CLAUDE.md

1# Global development guidelines for the LangChain monorepo
2 
3This document provides context to understand the LangChain Python project and assist with development.
4 
5## Project architecture and context
6 
7### Monorepo structure
8 
9This is a Python monorepo with multiple independently versioned packages that use `uv`.
10 
11```txt
12langchain/
13├── libs/
14│   ├── core/             # `langchain-core` primitives and base abstractions
15│   ├── langchain/        # `langchain-classic` (legacy, no new features)
16│   ├── langchain_v1/     # Actively maintained `langchain` package
17│   ├── partners/         # Third-party integrations
18│   │   ├── openai/       # OpenAI models and embeddings
19│   │   ├── anthropic/    # Anthropic (Claude) integration
20│   │   ├── ollama/       # Local model support
21│   │   └── ... (other integrations maintained by the LangChain team)
22│   ├── text-splitters/   # Document chunking utilities
23│   ├── standard-tests/   # Shared test suite for integrations
24│   ├── model-profiles/   # Model configuration profiles
25├── .github/              # CI/CD workflows and templates
26├── .vscode/              # VSCode IDE standard settings and recommended extensions
27└── README.md             # Information about LangChain
28```
29 
30- **Core layer** (`langchain-core`): Base abstractions, interfaces, and protocols. Users should not need to know about this layer directly.
31- **Implementation layer** (`langchain`): Concrete implementations and high-level public utilities
32- **Integration layer** (`partners/`): Third-party service integrations. Note that this monorepo is not exhaustive of all LangChain integrations; some are maintained in separate repos, such as `langchain-ai/langchain-google` and `langchain-ai/langchain-aws`. Usually these repos are cloned at the same level as this monorepo, so if needed, you can refer to their code directly by navigating to `../langchain-google/` from this monorepo.
33- **Testing layer** (`standard-tests/`): Standardized integration tests for partner integrations
34 
35### Development tools & commands
36 
37- `uv` – Fast Python package installer and resolver (replaces pip/poetry)
38- `make` – Task runner for common development commands. Feel free to look at the `Makefile` for available commands and usage patterns.
39- `ruff` – Fast Python linter and formatter
40- `mypy` – Static type checking
41- `pytest` – Testing framework
42 
43This monorepo uses `uv` for dependency management. Local development uses editable installs: `[tool.uv.sources]`
44 
45Each package in `libs/` has its own `pyproject.toml` and `uv.lock`.
46 
47Before running your tests, set up all packages by running:
48 
49```bash
50# For all groups
51uv sync --all-groups
52 
53# or, to install a specific group only:
54uv sync --group test
55```
56 
57```bash
58# Run unit tests (no network)
59make test
60 
61# Run specific test file
62uv run --group test pytest tests/unit_tests/test_specific.py
63```
64 
65```bash
66# Lint code
67make lint
68 
69# Format code
70make format
71 
72# Type checking
73uv run --group lint mypy .
74```
75 
76#### Environment and dependency management
77 
78Use `uv` for all environment and dependency operations in this monorepo. Do not invoke `pip`, `poetry`, or `conda` directly.
79 
80- Let `uv` manage the interpreter and virtual environments — `uv sync` and `uv run` operate without manual `source .venv/bin/activate`. Do not create ad-hoc virtual environments outside the package directory.
81- Each package targets its own supported Python range via its `pyproject.toml`; do not pin a global Python version. If you need an interpreter explicitly, defer to the package's `requires-python` rather than assuming system Python.
82- Install dependencies explicitly through `uv sync` (optionally `--group <name>` / `--all-groups`); never let them install implicitly.
83- Don't mix environments within a session, and don't add new dependencies unless strictly required — when you do, justify them (recent releases/commits, adoption).
84 
85#### Key config files
86 
87- pyproject.toml: Main workspace configuration with dependency groups
88- uv.lock: Locked dependencies for reproducible builds
89- Makefile: Development tasks
90 
91#### PR and commit titles
92 
93Follow Conventional Commits. See `.github/workflows/pr_lint.yml` for allowed types and scopes. All titles must include a scope with no exceptions — even for the main `langchain` package.
94 
95- Start the text after `type(scope):` with a lowercase letter, unless the first word is a proper noun (e.g. `Azure`, `GitHub`, `OpenAI`) or a named entity (class, function, method, parameter, or variable name).
96- Wrap named entities in backticks so they render as code. Proper nouns are left unadorned.
97- Keep titles short and descriptive — save detail for the body.
98 
99Examples:
100 
101```txt
102feat(langchain): add new chat completion feature
103fix(core): resolve type hinting issue in vector store
104chore(anthropic): update infrastructure dependencies
105feat(langchain): `ls_agent_type` tag on `create_agent` calls
106fix(openai): infer Azure chat profiles from model name
107```
108 
109#### Branch naming
110 
111Branches should be prefixed `<github-username>/<scope>/<short-description>`:
112 
113- `<github-username>` — the author's GitHub login (e.g. `mdrxy`).
114- `<scope>` — the same scope used in the Conventional Commit title (`core`, `langchain`, partner name, `infra`, `docs`, etc.).
115- `<short-description>` — kebab-case, brief, no trailing slash.
116 
117Examples:
118 
119```txt
120mdrxy/anthropic/normalize-tool-call-ids
121mdrxy/core/vector-store-type-hints
122mdrxy/infra/agents-md-branch
123```
124 
125#### PR descriptions
126 
127The description *is* the summary — do not add a `# Summary` header.
128 
129- When the PR closes an issue, lead with the closing keyword on its own line at the very top, followed by a horizontal rule and then the body:
130 
131```txt
132  Closes #123
133 
134  ---
135 
136  <rest of description>
137```
138 
139  Only `Closes`, `Fixes`, and `Resolves` auto-close the referenced issue on merge. `Related:` or similar labels are informational and do not close anything.
140 
141- Explain the *why*: who benefits, what problem they had, and how this solves it. Prefer a simple user story over a long summary.
142- Write for readers who may be unfamiliar with this area of the codebase. Avoid insider shorthand and prefer language that is friendly to public viewers — this aids interpretability.
143- Do **not** cite line numbers; they go stale as soon as the file changes.
144- Rarely include full file paths or filenames. Reference the affected symbol, class, or subsystem by name instead.
145- Wrap class, function, method, parameter, and variable names in backticks.
146- For net new features or behavior-changing bugfixes, PR descriptions should include a `## Release note` section that states the user-visible change in release-note-ready language.
147- Skip dedicated "Test plan" or "Testing" sections in most cases. Mention tests only when coverage is non-obvious, risky, or otherwise notable.
148- Call out areas of the change that require careful review.
149- Add a brief disclaimer noting AI-agent involvement in the contribution.
150 
151## Core development principles
152 
153### Maintain stable public interfaces
154 
155CRITICAL: Always attempt to preserve function signatures, argument positions, and names for exported/public methods. Do not make breaking changes.
156You should warn the developer for any function signature changes, regardless of whether they look breaking or not.
157 
158**Before making ANY changes to public APIs:**
159 
160- Check if the function/class is exported in `__init__.py`
161- Look for existing usage patterns in tests and examples
162- Use keyword-only arguments for new parameters: `*, new_param: str = "default"`
163- Mark experimental features clearly with docstring warnings (using MkDocs Material admonitions, like `!!! warning`)
164 
165Ask: "Would this change break someone's code if they used it last week?"
166 
167### Code quality standards
168 
169All Python code MUST include type hints and return types.
170 
171```python title="Example"
172def filter_unknown_users(users: list[str], known_users: set[str]) -> list[str]:
173    """Single line description of the function.
174 
175    Any additional context about the function can go here.
176 
177    Args:
178        users: List of user identifiers to filter.
179        known_users: Set of known/valid user identifiers.
180 
181    Returns:
182        List of users that are not in the `known_users` set.
183    """
184```
185 
186- Use descriptive, self-explanatory variable names.
187- Follow existing patterns in the codebase you're modifying
188- Attempt to break up complex functions (>20 lines) into smaller, focused functions where it makes sense
189 
190### Testing requirements
191 
192Every new feature or bugfix MUST be covered by unit tests.
193 
194- Unit tests: `tests/unit_tests/` (no network calls allowed)
195- Integration tests: `tests/integration_tests/` (network calls permitted)
196- We use `pytest` as the testing framework; if in doubt, check other existing tests for examples.
197- The testing file structure should mirror the source code structure.
198 
199**Checklist:**
200 
201- [ ] Tests fail when your new logic is broken
202- [ ] Happy path is covered
203- [ ] Edge cases and error conditions are tested
204- [ ] Use fixtures/mocks for external dependencies
205- [ ] Tests are deterministic (no flaky tests)
206- [ ] Does the test suite fail if your new logic is broken?
207 
208### Security and risk assessment
209 
210- No `eval()`, `exec()`, or `pickle` on user-controlled input
211- Proper exception handling (no bare `except:`) and use a `msg` variable for error messages
212- Remove unreachable/commented code before committing
213- Race conditions or resource leaks (file handles, sockets, threads).
214- Ensure proper resource cleanup (file handles, connections)
215 
216### Documentation standards
217 
218Use Google-style docstrings with Args section for all public functions.
219 
220```python title="Example"
221def send_email(to: str, msg: str, *, priority: str = "normal") -> bool:
222    """Send an email to a recipient with specified priority.
223
224    Any additional context about the function can go here.
225
226    Args:
227        to: The email address of the recipient.
228        msg: The message body to send.
229        priority: Email priority level.
230
231    Returns:
232        `True` if email was sent successfully, `False` otherwise.
233 
234    Raises:
235        InvalidEmailError: If the email address format is invalid.
236        SMTPConnectionError: If unable to connect to email server.
237    """
238```
239 
240- Types go in function signatures, NOT in docstrings
241  - If a default is present, DO NOT repeat it in the docstring unless there is post-processing or it is set conditionally.
242- Focus on "why" rather than "what" in descriptions
243- Document all parameters, return values, and exceptions
244- Keep descriptions concise but clear
245- Ensure American English spelling (e.g., "behavior", not "behaviour")
246- Do NOT use Sphinx-style double backtick formatting (` ``code`` `). Use single backticks (`` `code` ``) for inline code references in docstrings and comments.
247 
248#### Model references in docs and examples
249 
250Always use the latest generally available (GA) models when referencing LLMs in docstrings and illustrative code snippets. Avoid preview or beta identifiers unless the model has no GA equivalent. Outdated model names signal stale code and confuse users.
251 
252Before writing or updating model references, verify current model IDs against the provider's official docs. Do not rely on memorized or cached model names — they go stale quickly.
253 
254Changing **shipped default parameter values** in code (e.g., a `model=` kwarg default in a class constructor) may constitute a breaking change — see "Maintain stable public interfaces" above. This guidance applies to documentation and examples, not code defaults.
255 
256For model *profile data* (capability flags, context windows), use the `langchain-profiles` CLI described below.
257 
258## Model profiles
259 
260Model profiles are generated using the `langchain-profiles` CLI in `libs/model-profiles`. The `--data-dir` must point to the directory containing `profile_augmentations.toml`, not the top-level package directory.
261 
262```bash
263# Run from libs/model-profiles
264cd libs/model-profiles
265 
266# Refresh profiles for a partner in this repo
267uv run langchain-profiles refresh --provider openai --data-dir ../partners/openai/langchain_openai/data
268 
269# Refresh profiles for a partner in an external repo (requires echo y to confirm)
270echo y | uv run langchain-profiles refresh --provider google --data-dir /path/to/langchain-google/libs/genai/langchain_google_genai/data
271```
272 
273Example partners with profiles in this repo:
274 
275- `libs/partners/openai/langchain_openai/data/` (provider: `openai`)
276- `libs/partners/anthropic/langchain_anthropic/data/` (provider: `anthropic`)
277- `libs/partners/perplexity/langchain_perplexity/data/` (provider: `perplexity`)
278 
279The `echo y |` pipe is required when `--data-dir` is outside the `libs/model-profiles` working directory.
280 
281## CI/CD infrastructure
282 
283### Release process
284 
285Each partner package is released independently. The full flow is:
286 
2871. **Version bump PR.** Create a PR that bumps three files by one line each:
288   - `langchain_<partner>/_version.py` — `__version__`
289   - `pyproject.toml` — `version`
290   - `uv.lock` — run `uv lock` from the package directory. If the diff includes unrelated changes (e.g. environment-dependent marker lines from a different local Python version), revert them and keep only the `version = "..."` line for the package being released
291 
292   Title follows Conventional Commits: `release(<partner>): <version>` (e.g. `release(openrouter): 0.2.6`). Use the branch name `release/<partner>-<version>`.
293 
294   Patch vs. minor bump follows in-repo precedent: within a `0.x` series, fixes and additive features get a patch bump (e.g. `session_id` field → 0.2.1→0.2.2, `parallel_tool_calls` → 0.2.3→0.2.4).
295 
2962. **Merge the PR** to `master`.
297 
2983. **Trigger the release workflow.** Run `gh workflow run` against the "🚀 Package Release" workflow (`_release.yml`, file ID `63880841`):
299 
300```bash
301   gh workflow run 63880841 --repo langchain-ai/langchain \
302     -f working-directory=&lt;partner&gt; -f release-version=&lt;version&gt;
303```
304 
305   `working-directory` is the short partner name from the workflow's dropdown (e.g. `openrouter`, not `libs/partners/openrouter`).
306 
3074. **The workflow handles everything else automatically** — do **not** create a GitHub release or tag manually. The `mark-release` job (using `ncipollo/release-action`) creates the GitHub release, tag, and release notes after PyPI publish succeeds. The release notes body is auto-generated from commit history between the previous tag and HEAD.
308 
309   Monitor the run:
310 
311```bash
312   gh run view &lt;run-id&gt; --repo langchain-ai/langchain
313```
314 
315   The full job chain is: build → release-notes → pre-release-checks → TestPyPI publish → PyPI publish → tag GitHub release.
316 
317### PR labeling and linting
318 
319**Title linting** (`.github/workflows/pr_lint.yml`)
320 
321**Auto-labeling:**
322 
323- `.github/workflows/pr_labeler.yml` – Unified PR labeler (size, file, title, external/internal, contributor tier)
324- `.github/workflows/pr_labeler_backfill.yml` – Manual backfill of PR labels on open PRs
325- `.github/workflows/auto-label-by-package.yml` – Issue labeling by package
326- `.github/workflows/tag-external-issues.yml` – Issue external/internal classification
327 
328### Integration test tracing (LangSmith)
329 
330Scheduled and manually dispatched integration tests (`integration_tests.yml`) trace every run to LangSmith so failures link back to the originating Actions run. (`_release.yml` runs integration tests too, but does not currently configure LangSmith tracing.)
331 
332**Env vars set by CI:**
333 
334- `LANGSMITH_API_KEY` — authenticates to LangSmith (repo secret, scoped to the "Scheduled testing" GitHub environment in `integration_tests.yml`).
335- `LANGSMITH_TRACING: "true"` — enables tracing for the test process.
336- `LANGSMITH_PROJECT` — the project traces are sent to. Defaults to `scheduled-testing-py` via a repo variable override: `${{ vars.LANGSMITH_PROJECT || 'scheduled-testing-py' }}`. To change the project, set the `LANGSMITH_PROJECT` repository variable in GitHub settings — do not hardcode it in the workflow.
337- `LANGSMITH_TAGS` — comma-separated tags identifying the run: `github-actions`, the matrix working directory (e.g. `libs/partners/openai`), the Python version, and the commit SHA.
338- `LANGSMITH_METADATA` — a JSON object built by the "Build LangSmith Metadata" step, containing `github_sha`, `github_run_id`, `github_run_attempt`, `github_run_url`, `github_workflow`, `github_event`, `github_ref`, `working_directory`, and `python_version`.
339 
340**The tracing bridge plugin:** The LangSmith SDK does not natively read `LANGSMITH_TAGS` or `LANGSMITH_METADATA` from the environment. The pytest plugin at `libs/standard-tests/langchain_tests/_langsmith_plugin.py` bridges that gap by entering `langsmith.run_helpers.tracing_context` for the duration of the test session. It only activates when `GITHUB_ACTIONS=true`, so local development is unaffected. Auto-discovered via the `pytest11` entry point in any package that depends on `langchain-tests`.
341 
342**Unit test isolation:** Unit tests must never make network calls or send traces. The `make test` target in the `libs/core` Makefile uses `env -u` to unset the tracing vars (`LANGCHAIN_TRACING_V2`, `LANGCHAIN_API_KEY`, `LANGSMITH_API_KEY`, `LANGSMITH_TRACING`, `LANGCHAIN_PROJECT`) before running pytest. Additionally, `libs/core/tests/unit_tests/runnables/conftest.py` has a session-scoped autouse fixture that explicitly disables tracing for runnable unit tests, restoring the original environment afterward.
343 
344### Adding a new partner to CI
345 
346When adding a new partner package, update these files:
347 
348- `.github/ISSUE_TEMPLATE/*.yml` – Add to package dropdown
349- `.github/dependabot.yml` – Add dependency update entry
350- `.github/scripts/pr-labeler-config.json` – Add file rule and scope-to-label mapping
351- `.github/workflows/_release.yml` – Add API key secrets if needed
352- `.github/workflows/auto-label-by-package.yml` – Add package label
353- `.github/workflows/check_diffs.yml` – Add to change detection
354- `.github/workflows/integration_tests.yml` – Add integration test config
355- `.github/workflows/pr_lint.yml` – Add to allowed scopes
356 
357## GitHub Actions & Workflows
358 
359This repository require actions to be pinned to a full-length commit SHA. Attempting to use a tag will fail. Use the `gh` cli to query. Verify tags are not annotated tag objects (which would need dereferencing).
360 
361## Additional resources
362 
363- **Documentation:** https://docs.langchain.com/oss/python/langchain/overview and source at https://github.com/langchain-ai/docs or `../docs/`. Prefer the local install and use file search tools for best results. If needed, use the docs MCP server as defined in `.mcp.json` for programmatic access.
364- **Contributing Guide:** [Contributing Guide](https://docs.langchain.com/oss/python/contributing/overview)
365