langchain-ai/langchain
github.com/langchain-ai/langchain ↗ · 3001 files · 16.1 MB
The agent engineering platform. LangChain is a framework for building agents and LLM-powered applications.
Overview
LangChain is a Python monorepo for building LLM-powered agents and applications. The actively maintained `langchain` package (libs/langchain_v1) is a thin orchestration layer over LangGraph: `create_agent()` compiles a tool-calling agent loop into a `CompiledStateGraph`, `init_chat_model()` lazily instantiates provider chat models from a registry, and a middleware system lets users hook every stage of the agent loop. `langchain-core` owns the stable abstractions (Runnable, BaseChatModel, BaseTool, messages, callbacks), `libs/partners/` holds ~17 independently released provider integrations, and `langchain-classic` preserves the legacy chains/agents API without new features.
System map
A uv-managed Python monorepo of independently versioned packages under libs/. langchain-core defines provider-agnostic abstractions; langchain (langchain_v1) is the user-facing orchestration layer built on LangGraph's StateGraph; langchain-classic is a frozen legacy package; libs/partners/ contains per-provider integrations released individually. There is no server or CLI entrypoint — the 'entrypoints' are library factories (create_agent, init_chat_model, init_embeddings) plus the langchain-profiles CLI. Build is hatchling, tests are pytest, and CI is a set of reusable GitHub Actions workflows.
- The repo is a monorepo of independently versioned packages: langchain-core v1.6.4 (libs/core), langchain v1.4.2 (libs/langchain_v1), langchain-classic v1.0.8 (libs/langchain), plus text-splitters, standard-tests (langchain-tests), and model-profiles.
- The actively maintained `langchain` package depends only on langchain-core>=1.6.3, langgraph>=1.2.11, and pydantic>=2.7.4; all provider integrations (openai, anthropic, mcp/fastmcp, etc.) are optional extras.
- langchain-core is the abstraction layer housing runnables, language_models, messages, tools, callbacks, vectorstores, output_parsers, prompts, tracers, and a _security subpackage; its own deps are langsmith, httpx, tenacity, pydantic, jsonpatch, PyYAML.
- The primary public entrypoint is `create_agent`, re-exported from `langchain.agents`, which builds and compiles a LangGraph `StateGraph` into a `CompiledStateGraph`.
- `init_chat_model` resolves provider strings like 'openai:gpt-5.5' through the `_BUILTIN_PROVIDERS` registry (~28 entries mapping provider key -> (module_path, class_name, creator_func)) and lazily imports the partner package.
- Provider integrations live in libs/partners/ (anthropic, chroma, deepseek, exa, fireworks, groq, huggingface, mistralai, nomic, ollama, openai, openrouter, perplexity, qdrant, xai) each with its own pyproject.toml and uv.lock, and each implementing langchain-core abstractions (e.g. ChatOpenAI in langchain_openai/chat_models/base.py).
- langchain-classic is the legacy package: `initialize_agent` is decorated @deprecated since 0.1.0 pointing users to `create_agent`, and its chains/agents tree (AgentExecutor, chains/*) is maintained for backward compatibility only.
- All packages build with hatchling and are developed via uv; local cross-package deps use editable `[tool.uv.sources]` path references (e.g. langchain-core -> ../core).
- Per-package Makefiles define the dev surface: `make test` (pytest with docker compose postgres+redis services), `make lint` (ruff check + ruff format --diff + mypy), `make format`, `make benchmark`.
- CI is organized as reusable workflows: `_test.yml` runs unit tests then re-runs them against computed minimum dependency versions via `.github/scripts/get_min_versions.py`.
- Releases are per-package and manually dispatched through `_release.yml` (workflow_call/workflow_dispatch), which resolves a working-directory dropdown value to a PyPI package name (langchain->langchain-classic, langchain_v1->langchain).
- The `langchain.mcp` namespace is beta-gated (importing it emits LangChainBetaWarning) and adapts MCP servers via the optional `fastmcp` extra.
Feature catalog
User-facing surface: agent construction (create_agent with middleware, structured output, persistence, interrupts), model/embeddings factories (init_chat_model, init_embeddings), tool authoring (@tool, BaseTool, ToolRuntime injection), a large built-in middleware catalog (HITL, summarization, PII, retries, limits, shell tool, file search, todo lists, tool selection/emulation), MCP server tool adaptation, and message/rate-limiter re-exports. langchain-classic preserves the legacy chains/agents API. langchain-tests ships a conformance suite for partner authors; langchain-profiles ships a CLI for model capability data.
- `create_agent(model, tools, system_prompt, middleware, response_format, state_schema, context_schema, checkpointer, store, interrupt_before, interrupt_after, debug, name, cache, transformers)` returns a `CompiledStateGraph` implementing the model->tools loop until no tool_calls remain.
- `init_chat_model` supports string specs ('provider:model'), explicit model_provider, configurable_fields producing a deferred `_ConfigurableModel`, and a special 'langsmith' provider that routes ChatOpenAI through the LangSmith gateway (LANGSMITH_GATEWAY_API_KEY / gateway.smith.langchain.com).
- `init_embeddings` provides the same lazy provider-registry pattern for ~10 embeddings providers (azure_openai, bedrock, cohere, google_genai, huggingface, mistralai, ollama, openai, ...).
- Tools are authored via the `@tool` decorator (langchain_core.tools.convert) or BaseTool subclasses; langchain.tools re-exports these plus ToolRuntime, InjectedState, and InjectedStore for runtime/state injection into tool functions.
- The built-in middleware catalog includes: SummarizationMiddleware, HumanInTheLoopMiddleware, PIIMiddleware, TodoListMiddleware, ModelRetryMiddleware, ModelFallbackMiddleware, ModelCallLimitMiddleware, ToolRetryMiddleware, ToolCallLimitMiddleware, ToolErrorMiddleware, LLMToolSelectorMiddleware, LLMToolEmulator, ContextEditingMiddleware, FilesystemFileSearchMiddleware, ProviderToolSearchMiddleware, and ShellToolMiddleware.
- Structured output is configured via `response_format` accepting a raw Pydantic/dataclass/TypedDict/JSON-schema or explicit ToolStrategy/ProviderStrategy/AutoStrategy; AutoStrategy picks provider-native output when `_supports_provider_strategy` says the model supports it.
- HumanInTheLoopMiddleware pauses tool calls via langgraph `interrupt()` with ReviewConfig policies allowing approve/edit/reject/respond decisions, and annotates edited calls with an `_EDIT_NOTICE` so the model knows the call was replaced.
- ShellToolMiddleware exposes a persistent `shell` tool executing commands under pluggable policies: HostExecutionPolicy (direct subprocess), DockerExecutionPolicy, and CodexSandboxExecutionPolicy, with output redaction via RedactionRule.
- PIIMiddleware detects emails/credit cards/IPs/MACs/URLs via `_redaction` helpers and can mutate streaming deltas in flight through `_PIIStreamTransformer` (a 128-char lookback buffer catches patterns straddling token boundaries).
- `MCPAdapter` converts FastMCP targets (URL, Path, transport, MCPConfig, in-process server, client/group) into LangChain tools via `list_tools()`, and arms clients so server elicitation requests become LangGraph interrupts answered by humans.
- langchain.messages re-exports the canonical message model (AIMessage, ToolMessage, HumanMessage, SystemMessage, content-block types, ToolCall, trim_messages) from langchain-core.
- BaseRateLimiter/InMemoryRateLimiter are re-exported from langchain.rate_limiters and are honored by BaseChatModel._generate_with_cache which acquires the limiter before hitting the provider API (but after cache lookup).
Data flow
Agents are LangGraph state machines: input is a messages list merged into a resolved state schema (middleware schemas + AgentState, base last so caller schema wins conflicts). Each loop iteration builds a ModelRequest carried through the wrap_model_call middleware stack to a bound model; the AIMessage is post-processed for structured output and packed into Command state updates. Tool calls route to ToolNode, whose ToolMessages append via the add_messages reducer. Tool calls go through a wrap_tool_call stack. Streaming is reshaped by TransformerFactory instances registered at compile time. Outside agents, init_chat_model resolves provider strings to lazily imported classes, and BaseChatModel.invoke routes through callbacks, an LLM cache, and a rate limiter before _generate/_stream.
- Agent input boundary is `{"messages": [...]}`: `_resolve_schemas` merges each middleware's `state_schema` (in registration order) with the base schema last, producing resolved_state_schema, input_schema, output_schema for the StateGraph.
- ModelRequest is the data unit flowing through wrap_model_call middleware: it carries model, messages (excluding system message), system_message, tool_choice, tools, response_format, state, runtime, and model_settings, with an `override()` API (direct attribute assignment is deprecated).
- The model node builds a ModelRequest, runs it through the composed `wrap_model_call_handler` (or calls `_execute_model` directly), then `_build_commands` converts the ModelResponse into Command objects updating `messages` and `structured_response` state.
- `_get_bound_model` validates middleware-added client-side tools against `tool_node.tools_by_name` (skipped when wrap_tool_call middleware can handle dynamic tools), normalizes raw schemas to AutoStrategy, and picks ProviderStrategy vs ToolStrategy by model capability.
- Structured output is marshaled inside `_handle_model_output`: ProviderStrategy parses the AIMessage via `ProviderStrategyBinding.parse`, ToolStrategy intercepts tool_calls matching `structured_output_tools` names and validates args into `structured_response` state.
- Tool execution reuses LangGraph's ToolNode — langchain's tools/tool_node.py is a backwards-compat shim re-exporting ToolNode, ToolCallRequest, ToolCallWrapper, InjectedState, InjectedStore, ToolRuntime from langgraph.prebuilt.
- Conversation history accumulates in the `messages` channel via langgraph's `add_messages` reducer imported in middleware types; agent state also carries ephemeral routing via JumpTo ('tools'|'model'|'end').
- Stream output is post-processed by transformers registered at compile: ToolCallTransformer and SubagentTransformer always run first, then per-middleware `transformers` (e.g. InternalCallTransformer for SummarizationMiddleware's internal calls), then user-supplied factories, deduped.
- Tracing flows through LangSmith: middleware wrap hooks are wrapped in `traceable` with `_scrub_inputs` stripping unserializable handler/runtime, per-middleware TracePolicy via `_node_trace_policy`, and the compiled graph gets metadata `ls_integration: langchain_create_agent`.
- init_chat_model data flow: provider key lookup in `_BUILTIN_PROVIDERS` -> `_import_module` (importlib with 'pip install <pkg>' hint on failure) -> getattr class -> functools.partial creator; provider inference from model name uses the registry keys.
- BaseChatModel.invoke pipelines through callback_manager.on_chat_model_start -> `_generate_with_cache` (llm cache lookup via `dumps(messages)` key, then rate_limiter.acquire) -> either protocol v2 streaming, implicit `_stream` chunk accumulation with on_llm_new_token, or `_generate` -> on_llm_end with LLMResult.
- BaseTool.run wraps execution in on_tool_start/on_tool_end callbacks and converts ToolException into tool output content per the tool's `handle_tool_error` flag (bool, str template, or callable) via `_handle_tool_error`.
Behavior traces
Key flows traced end-to-end: (1) model initialization via init_chat_model; (2) agent construction via create_agent — middleware classification, schema merge, node/edge wiring, compile; (3) the agent loop — before_agent/before_model hooks, model call through the wrap_model_call stack, tool dispatch, loop-back or exit through after_model/after_agent; (4) single chat-model invocation through cache/rate-limiter/streaming; (5) MCP tool adoption; (6) CI test and release flows.
- Import/startup: `import langchain` sets only __version__; `from langchain.agents import create_agent` pulls factory.py which imports langgraph (StateGraph, ToolNode, Command, Send), langsmith.traceable, and init_chat_model; `import langchain.mcp` emits a LangChainBetaWarning.
- init_chat_model('openai:gpt-5.5'): parse provider prefix -> `_get_chat_model_creator` (lru_cached) -> `_import_module('langchain_openai')` -> getattr ChatOpenAI -> functools.partial(_call, cls) -> cls(**kwargs); ollama falls back to langchain_community.chat_models for backwards compat.
- create_agent construction order: str model -> init_chat_model; system_prompt -> SystemMessage; middleware partitioned by which hooks each subclass overrides (before_agent/before_model/after_model/after_agent/wrap_model_call/wrap_tool_call); sync and async wrap handlers composed via `_chain_model_call_handlers`/`_chain_async_model_call_handlers`.
- Graph wiring: nodes added — 'model' (RunnableCallable(model_node, amodel_node)), 'tools' (ToolNode, only if tools exist), and '<middleware_name>.<hook>' RunnableCallables; START->entry_node; conditional edges route tools->loop_entry|exit and model->tools|exit|loop_entry; middleware chains wired via `_add_middleware_edge` with can_jump_to.
- Compile step: graph.compile(checkpointer, store, interrupt_before, interrupt_after, debug, name, cache, transformers=[ToolCallTransformer, SubagentTransformer, middleware+user transformers]) then `.with_config({recursion_limit: 9999, metadata: {ls_integration: langchain_create_agent}})`.
- Runtime loop order on agent.invoke: START -> first before_agent middleware -> before_model chain -> 'model' -> after_model chain (reverse order) -> conditional edge: tool_calls present -> 'tools' -> back to loop_entry_node (first before_model or 'model'); no tool_calls -> exit_node -> after_agent chain -> END.
- Inside the model node (sync path mirrored by amodel_node): ModelRequest assembled -> awrap_model_call_handler(request, _execute_model_async) -> _get_bound_model binds tools and resolves response format -> model.ainvoke(messages) -> _handle_model_output -> ModelResponse -> _build_commands (rejecting Command.goto from wrap_model_call with NotImplementedError).
- Structured-output error recovery: StructuredOutputValidationError or MultipleStructuredOutputsError goes through `_handle_structured_output_error`; if retryable, an error ToolMessage (STRUCTURED_OUTPUT_ERROR_TEMPLATE 'Please fix your mistakes.') is appended and the loop continues.
- Single chat-model call: BaseChatModel.invoke -> generate -> callback_manager.on_chat_model_start -> _generate_with_cache -> cache.lookup(prompt, llm_string) short-circuits on hit -> rate_limiter.acquire -> protocol-v2 streaming / implicit _stream (on_llm_new_token per chunk) / _generate -> run_manager.on_llm_end(LLMResult).
- Tool invocation inside ToolNode delegates to BaseTool.run: callback_manager.on_tool_start -> _run -> on ToolException, `_handle_tool_error` renders handled content per handle_tool_error -> on_tool_end(output).
- MCP adoption flow: MCPAdapter(target) -> str targets pass `_validate_url_target` -> FastMCPClient(target) -> `_arm_for_interrupts` (clones pre-built clients that lack an elicitation handler) -> `async with adapter` connects -> list_tools -> as_langchain_tool -> tools passed to create_agent.
- CI unit-test flow: _test.yml -> uv_setup action -> `uv sync --group test --dev` -> `make test` (docker compose postgres+redis up, pytest -n auto --disable-socket --allow-unix-socket) -> get_min_versions.py -> `uv pip install $MIN_VERSIONS` -> `make tests` again -> git-clean check.
Testing signals
pytest is the framework everywhere, configured per-package with strict markers/config, asyncio auto mode, syrupy snapshots, and pytest-socket to forbid network in unit tests. langchain_v1 has ~85 unit-test files (heavy agents/middleware coverage, plus chat_models, embeddings, mcp, tools), integration tests with VCR cassettes, and a benchmark suite for create_agent. CI runs tests twice — current and minimum dependency versions — and scheduled integration tests trace to LangSmith. langchain-tests packages the conformance suite partners must pass. Gaps: unit tests need docker postgres/redis for checkpointer paths, and langchain-classic's huge legacy surface relies on older coverage.
- pytest config: `--strict-markers --strict-config --durations=5 --snapshot-warn-unused -vv`, asyncio_mode=auto, custom markers (requires, scheduled, compile, benchmark), syrupy snapshots under tests/**/__snapshots__.
- Unit tests live in tests/unit_tests mirroring source layout; langchain_v1's agents suite includes test_react_agent.py, test_response_format*.py, test_return_direct*.py, test_subagent_*.py, middleware/ and middleware_typing/ dirs, plus specifications/ and cassettes/ for VCR replay.
- Network isolation is enforced: `make test` runs pytest with `--disable-socket --allow-unix-socket` (pytest-socket), and unit tests must not hit the network per AGENTS.md.
- Persistence tests are not hermetic: `make test`/`extended_tests`/`test_watch` spin up postgres and redis via `tests/unit_tests/agents/compose-postgres.yml` and `compose-redis.yml` before running, then tear them down.
- Async correctness is checked with blockbuster (blocking-call detection) in the test group; freezegun and responses are used in core tests.
- Benchmarks exist for agent creation: `make benchmark` runs tests/benchmarks/test_create_agent.py with -m benchmark; a codspeed workflow exists for perf tracking.
- CI runs the unit suite twice — once on current deps and once after installing computed minimum versions via `.github/scripts/get_min_versions.py` — catching lower-bound regressions.
- Scheduled integration tests (integration_tests.yml) trace runs to LangSmith using LANGSMITH_TRACING/API_KEY/PROJECT/TAGS env vars and authenticate to cloud providers via workload identity (google-github-actions/auth, configure-aws-credentials).
- langchain-tests is a published package exposing standard unit+integration test classes (chat_models, embeddings, tools, vectorstores, retrievers, indexers, caches, sandboxes) that partner packages subclass for conformance.
- Static checks are strict: ruff with `select = ["ALL"]` (google docstring convention, banned relative imports) and mypy strict mode with pydantic plugin; `check_imports` script verifies every module imports cleanly in CI.
- Coverage is gated by make targets `coverage` and `coverage_agents` (term-missing + xml/html reports scoped to langchain.agents); test_react_agent.py is exempted from all lint rules, suggesting it is a large legacy-style test file.
Risk map
The highest blast radius sits in places that execute or reach out: ShellToolMiddleware spawns real subprocesses (host/docker/codex policies), MCPAdapter intentionally blocks non-http(s) string targets because FastMCP would otherwise exec local files, and core's _security module provides SSRF validation with a test-only bypass env var. Fragile spots: regex-based model capability fallbacks that must track provider releases, a 9_999 recursion limit, deferred import errors from lazy provider loading, validation gaps when wrap_tool_call middleware exists, and the still-shipped langchain-classic legacy surface.
- ShellToolMiddleware executes model-generated shell commands via subprocess.Popen (n noqa'd S603); HostExecutionPolicy runs commands directly on the host — DockerExecutionPolicy/CodexSandboxExecutionPolicy exist precisely because host execution is dangerous. Agents given this middleware have arbitrary-code-execution capability.
- MCPAdapter._validate_url_target rejects any str target that is not http/https because fastmcp.Client tests strings as filesystem paths first and would launch a matching .py/.js file as a subprocess — a deliberate guard against config/model-supplied strings becoming local code execution.
- core._security provides SSRF protection (validate_safe_url) blocking private IPs, localhost, cloud metadata, and k8s-internal addresses — but a `LANGCHAIN_ENV=local_test` env var bypasses validation for hostnames starting with 'test' containing 'server', a foot-gun if set in production.
- FALLBACK_MODELS_WITH_STRUCTURED_OUTPUT is a hand-maintained regex list of model names assumed to support provider-native structured output when profile data is missing — it will silently mispredict capabilities for new models until updated.
- The compiled agent gets `recursion_limit: 9_999` (working around a langgraph issue), so a model stuck in a tool-call loop can iterate ~10k times before stopping — cost/runaway risk mitigated only by opt-in ModelCallLimitMiddleware/ToolCallLimitMiddleware.
- Lazy provider loading means ImportError surfaces at first use, not import time: `_import_module` rewrites failures into 'pip install <pkg>' messages, and ollama has a langchain_community fallback that can mask which package is actually missing.
- Client-side tool validation in `_get_bound_model` is skipped entirely when any middleware defines wrap_tool_call, so a typo'd dynamic tool name fails only when the middleware's own handler misses it — validation coverage depends on middleware correctness.
- wrap_model_call middleware cannot return Command.goto (raises NotImplementedError pointing users at jump_to), and commands accumulate inner-first through the composed stack — ordering/return-shape mistakes produce runtime errors deep in the loop.
- langchain-classic remains a large shipped legacy surface (chains/, agents/, retrievers/, utilities/ including many network-calling API wrappers); the dangerous LLMBashChain was removed — its module is now a stub raising AttributeError redirecting to langchain-experimental.
- PIIMiddleware mutates streamed content in flight via _PIIStreamTransformer — silent redaction means downstream consumers (logs, users) see altered text; a false-positive detection corrupts model output with no record unless tracing is on. (inferred)
- Unit tests for persistence require live postgres/redis containers — a contributor running plain pytest without `make test`'s docker compose step will hit connection failures, not skips. (inferred)
- init_chat_model's 'langsmith' provider silently rewrites kwargs (openai_api_base -> gateway.smith.langchain.com, api key from LANGSMITH_GATEWAY_API_KEY/LANGSMITH_API_KEY, use_responses_api=True) — credentials and traffic routing change based on env vars.
Extension points
The framework is built around extension. Agents are extended via AgentMiddleware subclasses (six hook points + state_schema + transformers), custom tools (BaseTool/@tool/dict provider tools), custom state/context schemas, structured-output strategies, checkpointers/stores/caches from LangGraph, and stream transformers. Models and embeddings plug in through partner packages implementing core abstractions plus registry entries in _BUILTIN_PROVIDERS, validated by the langchain-tests conformance suite. Shell execution is extensible via BaseExecutionPolicy.
- AgentMiddleware is the primary extension point: subclasses override any of before_agent/before_model/after_model/after_agent/wrap_model_call/wrap_tool_call (sync and/or async variants); decorators @before_agent/@before_model/@after_agent/@after_model/@dynamic_prompt/@wrap_model_call/@wrap_tool_call offer a functional alternative.
- Middleware can declare `state_schema` (merged into agent state), `tools` (registered on the agent), `transformers` (stream post-processors), `trace_policy`, and `can_jump_to` per hook — factory.py inspects which hooks are overridden to decide which graph nodes to add.
- New chat-model providers are added by implementing BaseChatModel in a partner package and adding a (module_path, class_name, creator_func) entry to `_BUILTIN_PROVIDERS`; custom creator lambdas handle non-standard constructors (e.g. huggingface's from_model_id, ibm's model_id kwarg).
- New embeddings providers follow the identical registry pattern in embeddings/base.py `_BUILTIN_PROVIDERS`.
- Partner packages prove conformance by subclassing langchain-tests suites (unit_tests/chat_models.py, integration_tests/vectorstores.py, etc.) rather than writing their own contract tests.
- Tools plug in as BaseTool subclasses, @tool-decorated callables, or raw dicts (provider built-in tools); tools can inject runtime/state/store via ToolRuntime/InjectedState/InjectedStore annotations.
- Agent state is extensible two ways: a custom `state_schema` TypedDict passed to create_agent (wins field conflicts over middleware schemas since it's merged last), or middleware-declared state_schema attributes.
- Structured output strategies are pluggable ResponseFormat implementations (ToolStrategy, ProviderStrategy, AutoStrategy); callers can also pass raw Pydantic/dataclass/TypedDict/JSON-schema which get wrapped in AutoStrategy.
- Persistence/streaming extension points come straight from LangGraph: create_agent accepts checkpointer (Checkpointer), store (BaseStore), cache (BaseCache), interrupt_before/after node names, and user `transformers` factories appended to the default pipeline.
- Shell execution policy is pluggable via BaseExecutionPolicy subclasses — built-ins are HostExecutionPolicy, DockerExecutionPolicy, CodexSandboxExecutionPolicy, each implementing process launch and post-spawn limits.
- Multi-agent composition is supported by naming an agent (`name=` becomes a subgraph node name) and by SubagentTransformer, which is always registered on the compiled graph to reshape nested-agent stream events.
- Observability is extensible per-middleware via TracePolicy and process-wide via configure_trace_policy; all wrap_* hooks are traced through LangSmith `traceable` with scrubbed inputs.
Contributor handoff
Read AGENTS.md/CLAUDE.md first — they encode the real conventions (uv-only, Conventional Commits with mandatory scope, Google docstrings, mypy strict + ruff ALL, no breaking signature changes). Work in libs/langchain_v1 for new features; libs/langchain (langchain-classic) is frozen. Re-export shims point at canonical homes: edit langchain_core or langgraph.prebuilt, not the shim. Tests must be hermetic unit tests under tests/unit_tests unless they need the docker services. Watch for: the manual structured-output model regexes, validation gaps around wrap_tool_call, and checkpointer tests that need containers.
- AGENTS.md and CLAUDE.md at repo root are the canonical contributor contract: uv for all env/dep ops (never pip/poetry), `uv sync --all-groups` before tests, make test/lint/format per package, Conventional Commits with mandatory scope, branch naming `<user>/<scope>/<desc>`.
- New features go in libs/langchain_v1 (package `langchain`); libs/langchain ships `langchain-classic` and is explicitly 'legacy, no new features' per AGENTS.md — don't add capabilities there.
- Public API stability is a hard rule: preserve signatures/positions/names, add new params keyword-only, mark experimental features with `!!! warning` docstring admonitions, and check `__init__.py` exports before touching anything public.
- Several langchain_v1 modules are backwards-compat re-export shims — e.g. langchain/tools/tool_node.py re-exports langgraph.prebuilt ToolNode/ToolCallRequest, langchain/tools/__init__.py re-exports langchain_core.tools — so edit the canonical implementation, not the shim.
- Before writing agent-loop code, read factory.py end-to-end: node names are '<middleware_name>.<hook>', edges must go through `_add_middleware_edge`/`_get_can_jump_to`, wrap handlers compose via `_chain_model_call_handlers`, and Command.goto inside wrap_model_call is unsupported.
- Test conventions: mirror source layout under tests/unit_tests, no network (pytest-socket enforced), use fixtures/mocks, determinism required; persistence tests need `make start_services` (postgres+redis) first.
- Lint bar is high: ruff `select = ["ALL"]` with google pydocstyle, single-backtick docstring code refs, banned relative imports, mypy strict with pydantic plugin and warn_unreachable; run `make lint` and `uv run --all-groups mypy .` before submitting.
- Releasing a package = bump `_version.py` + pyproject version + `uv lock`, merge, then trigger _release.yml via `gh workflow run 63880841` — never tag or create GitHub releases manually.
- Known traps: FALLBACK_MODELS_WITH_STRUCTURED_OUTPUT regexes must be updated for new model families; middleware-added tools bypass validation when wrap_tool_call exists; ModelRequest attribute mutation is deprecated (use override()); system_prompt param deprecated in favor of SystemMessage.
- Model profile data (capabilities/context windows) is generated, not hand-edited: use `uv run langchain-profiles refresh --provider <p> --data-dir <partner>/langchain_<p>/data` from libs/model-profiles.
- Every public module/function needs Google-style docstrings with Args/Returns/Raises, full type hints, and American English; tests get relaxed lint rules but still require the strict pytest config (no bare markers).
Languages
| Language | Files | Share of source |
|---|---|---|
| Python | 2610 | 98% |
| JSON | 71 | docs/config |
| Markdown | 56 | docs/config |
| YAML | 48 | docs/config |
| TOML | 30 | 1% |
| Shell | 22 | 1% |
| HTML | 2 | docs/config |
| JavaScript | 2 | 0% |
Start reading here
Probable source entrypoint: libs/ — inferred from the directory tree and manifest, not the upstream docs.
Source roots
libs/ (2888 files) openwiki/ (50 files)
Source layout — libs/
| Path | Files |
|---|---|
libs/core/ | 303 |
libs/text-splitters/ | 32 |
Repository structure
| Top-level path | Files |
|---|---|
libs/ | 2888 |
openwiki/ | 50 |
.github/ | 48 |
.devcontainer/ | 3 |
Docs found: AGENTS.mdCLAUDE.mdREADME.md
Package
libs/core/pyproject.toml — langchain-core v1.6.4, 0 declared dependencies.
CI & config entrypoints
README.md— Repository readmeAGENTS.md— Agent instructionsCLAUDE.md— Claude instructions.github/workflows/pr_labeler_backfill.yml— GitHub Actions workflow.github/workflows/pr_labeler.yml— GitHub Actions workflow.github/workflows/_test.yml— GitHub Actions workflow.github/workflows/_release.yml— GitHub Actions workflow.github/workflows/_test_vcr.yml— GitHub Actions workflow.github/workflows/check_extras_sync.yml— GitHub Actions workflow.github/workflows/_lint.yml— GitHub Actions workflow
Structural health signals
Average score 6.1/10 across 96 analyzed source files; 81 hotspots surfaced.
libs/partners/openai/langchain_openai/chatgpt_oauth.py— 1063 lines, score 4.7 (Large file, Deep nesting)libs/langchain_v1/langchain/agents/middleware/shell_tool.py— 949 lines, score 4.7 (Large file, Deep nesting)libs/langchain_v1/langchain/agents/middleware/tool_selection.py— 515 lines, score 5.2 (Large file, Deep nesting)
These are deterministic review leads — size, churn, and structural signals — not proof of a bug in this project.
Recent history
9e4ea7a349592026-09-22 — fix(fireworks): use current completions model in LLM tests (#40740)219b372051b62026-09-22 — fix(deepseek,infra): resolve compatible minimum OpenAI dependencies, bump min ver (#40738)b976c82c587a2026-09-22 — hotfix(fireworks): use available model in LLM tests (#40737)e2eab823c7282026-09-22 — release(deepseek): 1.1.1 (#40734)0683934fb2112026-09-22 — release(fireworks): 1.6.2 (#40735)