langchain

The agent engineering platform.

144,108 stars Python Markdown Skills API Spec #agents#ai#ai-agents#anthropic
AI Prompts & Specs

Repository: langchain-ai/langchain


Stars: 133866

CLAUDE.md

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.

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

bash
For all groups

uv sync --all-groups
or, to install a specific group only:

uv sync --group test

bash
Run unit tests (no network)

make test
Run specific test file

uv run --group test pytest tests/unit_tests/test_specific.py

bash
Lint code

make lint
Format code

make format
Type checking

uv run --group lint mypy .

#### Key config files

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

#### Commit standards

Suggest PR titles that follow Conventional Commits format. Refer to .github/workflows/pr_lint for allowed types and scopes. Note that all commit/PR titles should be in lowercase with the exception of proper nouns/named entities. All PR titles should include a scope with no exceptions. For example:

txt
feat(langchain): add new chat completion feature
fix(core): resolve type hinting issue in vector store
chore(anthropic): update infrastructure dependencies

Note how feat(langchain) includes a scope even though it is the main package and name of the repo.

#### Pull request guidelines

- Always add a disclaimer to the PR description mentioning how AI agents are involved with the contribution.
- Describe the "why" of the changes, why the proposed solution is the right one. Limit prose.
- Highlight areas of the proposed changes that require careful review.

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.

``python title="Example"
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.
"""

text
- 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.
python title="Example"
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.
"""

text
- 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.
bash

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
text
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 
Releases are triggered manually via .github/workflows/_release.yml with working-directory and release-version inputs.
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
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

README.md 
<div align="center">
  <a href="https://docs.langchain.com/oss/python/langchain/overview">
    <picture>
      <source media="(prefers-color-scheme: dark)" srcset=".github/images/logo-dark.svg">
      <source media="(prefers-color-scheme: light)" srcset=".github/images/logo-light.svg">
      <img alt="LangChain Logo" src=".github/images/logo-dark.svg" width="50%">
    </picture>
  </a>
</div>
<div align="center">
  <h3>The agent engineering platform.</h3>
</div>
<div align="center">
  <a href="https://opensource.org/licenses/MIT" target="_blank"><img src="https://img.shields.io/pypi/l/langchain" alt="PyPI - License"></a>
  <a href="https://pypistats.org/packages/langchain" target="_blank"><img src="https://img.shields.io/pepy/dt/langchain" alt="PyPI - Downloads"></a>
  <a href="https://pypi.org/project/langchain/#history" target="_blank"><img src="https://img.shields.io/pypi/v/langchain?label=%20" alt="Version"></a>
  <a href="https://x.com/langchain" target="_blank"><img src="https://img.shields.io/twitter/url/https/twitter.com/langchain.svg?style=social&label=Follow%20%40LangChain" alt="Twitter / X"></a>
</div>
<br>
LangChain is a framework for building agents and LLM-powered applications. It helps you chain together interoperable components and third-party integrations to simplify AI application development — all while future-proofing decisions as the underlying technology evolves.
NOTE
Looking for the JS/TS library? Check out LangChain.js.
Quickstart
bash
pip install langchain

or


uv add langchain
text
python
from langchain.chat_models import init_chat_model

model = init_chat_model("openai:gpt-5.4")
result = model.invoke("Hello, world!")
``

If you're looking for more advanced customization or agent orchestration, check out LangGraph, our framework for building controllable agent workflows.

TIP

For developing, debugging, and deploying AI agents and LLM applications, see LangSmith.

LangChain ecosystem

While the LangChain framework can be used standalone, it also integrates seamlessly with any LangChain product, giving developers a full suite of tools when building LLM applications.

- Deep Agents — Build agents that can plan, use subagents, and leverage file systems for complex tasks
- LangGraph — Build agents that can reliably handle complex tasks with our low-level agent orchestration framework
- Integrations — Chat & embedding models, tools & toolkits, and more
- LangSmith — Agent evals, observability, and debugging for LLM apps
- LangSmith Deployment — Deploy and scale agents with a purpose-built platform for long-running, stateful workflows

Why use LangChain?

LangChain helps developers build applications powered by LLMs through a standard interface for models, embeddings, vector stores, and more.

- Real-time data augmentation — Easily connect LLMs to diverse data sources and external/internal systems, drawing from LangChain's vast library of integrations with model providers, tools, vector stores, retrievers, and more
- Model interoperability — Swap models in and out as your engineering team experiments to find the best choice for your application's needs. As the industry frontier evolves, adapt quickly — LangChain's abstractions keep you moving without losing momentum
- Rapid prototyping — Quickly build and iterate on LLM applications with LangChain's modular, component-based architecture. Test different approaches and workflows without rebuilding from scratch, accelerating your development cycle
- Production-ready features — Deploy reliable applications with built-in support for monitoring, evaluation, and debugging through integrations like LangSmith. Scale with confidence using battle-tested patterns and best practices
- Vibrant community and ecosystem — Leverage a rich ecosystem of integrations, templates, and community-contributed components. Benefit from continuous improvements and stay up-to-date with the latest AI developments through an active open-source community
- Flexible abstraction layers — Work at the level of abstraction that suits your needs — from high-level chains for quick starts to low-level components for fine-grained control. LangChain grows with your application's complexity

---

Documentation

- docs.langchain.com – Comprehensive documentation, including conceptual overviews and guides
- reference.langchain.com/python – API reference docs for LangChain packages
- Chat LangChain – Chat with the LangChain documentation and get answers to your questions

Discussions: Visit the LangChain Forum to connect with the community and share all of your technical questions, ideas, and feedback.

Additional resources

- Contributing Guide – Learn how to contribute to LangChain projects and find good first issues.
- Code of Conduct – Our community guidelines and standards for participation.
- LangChain Academy – Comprehensive, free courses on LangChain libraries and products, made by the LangChain team.