langchain-ai__langchain-selected-20261004

Imported from 6tcbpvb4h7jszwz2/langchain-ai__langchain-selected-20261004 (AGENTS.md). Install upstream with npx skills add 6tcbpvb4h7jszwz2/langchain-ai__langchain-selected-20261004. Copyright stays with the author.

Global development guidelines for the LangChain monorepo

This document provides context to understand the LangChain Python project and assist with development.

Project architecture and context

Monorepo structure

This is a Python monorepo with multiple independently versioned packages that use uv.

langchain/
├── libs/
│   ├── core/             # `langchain-core` primitives and base abstractions
│   ├── langchain/        # `langchain-classic` (legacy, no new features)
│   ├── langchain_v1/     # Actively maintained `langchain` package
│   ├── partners/         # Third-party integrations
│   │   ├── openai/       # OpenAI models and embeddings
│   │   ├── anthropic/    # Anthropic (Claude) integration
│   │   ├── ollama/       # Local model support
│   │   └── ... (other integrations maintained by the LangChain team)
│   ├── text-splitters/   # Document chunking utilities
│   ├── standard-tests/   # Shared test suite for integrations
│   ├── model-profiles/   # Model configuration profiles
├── .github/              # CI/CD workflows and templates
├── .vscode/              # VSCode IDE standard settings and recommended extensions
└── README.md             # Information about LangChain

• Core layer (langchain-core): Base abstractions, interfaces, and protocols. Users should not need to know about this layer directly.
• Implementation layer (langchain): Concrete implementations and high-level public utilities
• 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.
• Testing layer (standard-tests/): Standardized integration tests for partner integrations

Development tools & commands

• uv – Fast Python package installer and resolver (replaces pip/poetry)
• make – Task runner for common development commands. Feel free to look at the Makefile for available commands and usage patterns.
• ruff – Fast Python linter and formatter
• mypy – Static type checking
• pytest – Testing framework

This monorepo uses uv for dependency management. Local development uses editable installs: [tool.uv.sources]

Each package in libs/ has its own pyproject.toml and uv.lock.

Before running your tests, set up all packages by running:

# For all groups
uv sync --all-groups

# or, to install a specific group only:
uv sync --group test

# Run unit tests (no network)
make test

# Run specific test file
uv run --group test pytest tests/unit_tests/test_specific.py

# Lint code
make lint

# Format code
make format

# Type checking
uv run --group lint mypy .

Environment and dependency management

Use uv for all environment and dependency operations in this monorepo. Do not invoke pip, poetry, or conda directly.

• 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.
• 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.
• Install dependencies explicitly through uv sync (optionally --group <name> / --all-groups); never let them install implicitly.
• 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).

Key config files

• pyproject.toml: Main workspace configuration with dependency groups
• uv.lock: Locked dependencies for reproducible builds
• Makefile: Development tasks

PR and commit titles

Follow 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.

• 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).
• Wrap named entities in backticks so they render as code. Proper nouns are left unadorned.
• Keep titles short and descriptive — save detail for the body.

Examples:

feat(langchain): add new chat completion feature
fix(core): resolve type hinting issue in vector store
chore(anthropic): update infrastructure dependencies
feat(langchain): `ls_agent_type` tag on `create_agent` calls
fix(openai): infer Azure chat profiles from model name

Branch naming

Branches should be prefixed <github-username>/<scope>/<short-description>:

• <github-username> — the author's GitHub login (e.g. mdrxy).
• <scope> — the same scope used in the Conventional Commit title (core, langchain, partner name, infra, docs, etc.).
• <short-description> — kebab-case, brief, no trailing slash.

Examples:

mdrxy/anthropic/normalize-tool-call-ids
mdrxy/core/vector-store-type-hints
mdrxy/infra/agents-md-branch

PR descriptions

The description is the summary — do not add a # Summary header.

• 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:

  Closes #123
  
  ---
  
  <rest of description>

  Only Closes, Fixes, and Resolves auto-close the referenced issue on merge. Related: or similar labels are informational and do not close anything.

• Explain the why: who benefits, what problem they had, and how this solves it. Prefer a simple user story over a long summary.

• 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.

• Do not cite line numbers; they go stale as soon as the file changes.

• Rarely include full file paths or filenames. Reference the affected symbol, class, or subsystem by name instead.

• Wrap class, function, method, parameter, and variable names in backticks.

• 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.

• Skip dedicated "Test plan" or "Testing" sections in most cases. Mention tests only when coverage is non-obvious, risky, or otherwise notable.

• Call out areas of the change that require careful review.

• Add a brief disclaimer noting AI-agent involvement in the contribution.

Core development principles

Maintain stable public interfaces

CRITICAL: Always attempt to preserve function signatures, argument positions, and names for exported/public methods. Do not make breaking changes. You should warn the developer for any function signature changes, regardless of whether they look breaking or not.

Before making ANY changes to public APIs:

• Check if the function/class is exported in __init__.py
• Look for existing usage patterns in tests and examples
• Use keyword-only arguments for new parameters: *, new_param: str = "default"
• Mark experimental features clearly with docstring warnings (using MkDocs Material admonitions, like !!! warning)

Ask: "Would this change break someone's code if they used it last week?"

Code quality standards

All Python code MUST include type hints and return types.

def filter_unknown_users(users: list[str], known_users: set[str]) -> list[str]:
    """Single line description of the function.

    Any additional context about the function can go here.

    Args:
        users: List of user identifiers to filter.
        known_users: Set of known/valid user identifiers.

    Returns:
        List of users that are not in the `known_users` set.
    """

• Use descriptive, self-explanatory variable names.
• Follow existing patterns in the codebase you're modifying
• Attempt to break up complex functions (>20 lines) into smaller, focused functions where it makes sense

Testing requirements

Every new feature or bugfix MUST be covered by unit tests.

• Unit tests: tests/unit_tests/ (no network calls allowed)
• Integration tests: tests/integration_tests/ (network calls permitted)
• We use pytest as the testing framework; if in doubt, check other existing tests for examples.
• The testing file structure should mirror the source code structure.

Checklist:

• Tests fail when your new logic is broken
• Happy path is covered
• Edge cases and error conditions are tested
• Use fixtures/mocks for external dependencies
• Tests are deterministic (no flaky tests)
• Does the test suite fail if your new logic is broken?

Security and risk assessment

• No eval(), exec(), or pickle on user-controlled input
• Proper exception handling (no bare except:) and use a msg variable for error messages
• Remove unreachable/commented code before committing
• Race conditions or resource leaks (file handles, sockets, threads).
• Ensure proper resource cleanup (file handles, connections)

Documentation standards

Use Google-style docstrings with Args section for all public functions.

def send_email(to: str, msg: str, *, priority: str = "normal") -> bool:
    """Send an email to a recipient with specified priority.

    Any additional context about the function can go here.

    Args:
        to: The email address of the recipient.
        msg: The message body to send.
        priority: Email priority level.

    Returns:
        `True` if email was sent successfully, `False` otherwise.

    Raises:
        InvalidEmailError: If the email address format is invalid.
        SMTPConnectionError: If unable to connect to email server.
    """

• Types go in function signatures, NOT in docstrings
  • If a default is present, DO NOT repeat it in the docstring unless there is post-processing or it is set conditionally.
• Focus on "why" rather than "what" in descriptions
• Document all parameters, return values, and exceptions
• Keep descriptions concise but clear
• Ensure American English spelling (e.g., "behavior", not "behaviour")
• Do NOT use Sphinx-style double backtick formatting (``code``). Use single backticks (`code`) for inline code references in docstrings and comments.

Model references in docs and examples

Always 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.

Before 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.

Changing 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.

For model profile data (capability flags, context windows), use the langchain-profiles CLI described below.

Model profiles

Model 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.

# Run from libs/model-profiles
cd libs/model-profiles

# Refresh profiles for a partner in this repo
uv run langchain-profiles refresh --provider openai --data-dir ../partners/openai/langchain_openai/data

# Refresh profiles for a partner in an external repo (requires echo y to confirm)
echo y | uv run langchain-profiles refresh --provider google --data-dir /path/to/langchain-google/libs/genai/langchain_google_genai/data

Example partners with profiles in this repo:

• libs/partners/openai/langchain_openai/data/ (provider: openai)
• libs/partners/anthropic/langchain_anthropic/data/ (provider: anthropic)
• libs/partners/perplexity/langchain_perplexity/data/ (provider: perplexity)

The echo y | pipe is required when --data-dir is outside the libs/model-profiles working directory.

CI/CD infrastructure

Release process

Each partner package is released independently. The full flow is:

1. Version bump PR. Create a PR that bumps three files by one line each:

   • langchain_<partner>/_version.py — __version__
   • pyproject.toml — version
   • 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

   Title follows Conventional Commits: release(<partner>): <version> (e.g. release(openrouter): 0.2.6). Use the branch name release/<partner>-<version>.

   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).

2. Merge the PR to master.

3. Trigger the release workflow. Run gh workflow run against the "🚀 Package Release" workflow (_release.yml, file ID 63880841):

   gh workflow run 63880841 --repo langchain-ai/langchain \
     -f working-directory=<partner> -f release-version=<version>

   working-directory is the short partner name from the workflow's dropdown (e.g. openrouter, not libs/partners/openrouter).

4. 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.

   Monitor the run:

   gh run view <run-id> --repo langchain-ai/langchain

   The full job chain is: build → release-notes → pre-release-checks → TestPyPI publish → PyPI publish → tag GitHub release.

PR labeling and linting

Title linting (.github/workflows/pr_lint.yml)

Auto-labeling:

• .github/workflows/pr_labeler.yml – Unified PR labeler (size, file, title, external/internal, contributor tier)
• .github/workflows/pr_labeler_backfill.yml – Manual backfill of PR labels on open PRs
• .github/workflows/auto-label-by-package.yml – Issue labeling by package
• .github/workflows/tag-external-issues.yml – Issue external/internal classification

Integration test tracing (LangSmith)

Scheduled 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.)

Env vars set by CI:

• LANGSMITH_API_KEY — authenticates to LangSmith (repo secret, scoped to the "Scheduled testing" GitHub environment in integration_tests.yml).
• LANGSMITH_TRACING: "true" — enables tracing for the test process.
• 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.
• 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.
• 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.

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.

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.

Adding a new partner to CI

When adding a new partner package, update these files:

• .github/ISSUE_TEMPLATE/*.yml – Add to package dropdown
• .github/dependabot.yml – Add dependency update entry
• .github/scripts/pr-labeler-config.json – Add file rule and scope-to-label mapping
• .github/workflows/_release.yml – Add API key secrets if needed
• .github/workflows/auto-label-by-package.yml – Add package label
• .github/workflows/check_diffs.yml – Add to change detection
• .github/workflows/integration_tests.yml – Add integration test config
• .github/workflows/pr_lint.yml – Add to allowed scopes

GitHub Actions & Workflows

This 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).

Additional resources

• 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.
• Contributing Guide: Contributing Guide