The agent engineering platform.
type: "Reference" title: "Source Map: Repository File Organization" description: "Quick reference for locating code by topic, mapping LangChain concepts to their implementation paths across the monorepo including core abstractions, agents, middleware, partners, and configuration files." tags: [reference, file-organization, monorepo, codebase-map, pathfinding] sources:
- id: openwiki-source-4d1645cb6317345817452838 resource: repo://.pre-commit-config.yaml
- id: openwiki-source-1c233fccf5a66b84d0045366 resource: repo://libs/core/langchain_core/callbacks/manager.py
- id: openwiki-source-c52037e7b642f7ac5a7642a8 resource: repo://libs/core/langchain_core/language_models/chat_models.py
- id: openwiki-source-b32b84365d17276620c41ebc resource: repo://libs/core/langchain_core/messages/base.py
- id: openwiki-source-03d7415879ed05a392edd62d resource: repo://libs/core/langchain_core/prompts/base.py
- id: openwiki-source-a1981e868973f6fd7f71e12e resource: repo://libs/core/langchain_core/runnables/base.py
- id: openwiki-source-4ff475d7b00540f962384251 resource: repo://libs/core/langchain_core/tools/base.py
- id: openwiki-source-3486a94e6eb23a78271a5bfb resource: repo://libs/core/pyproject.toml
- id: openwiki-source-a690cf632a02205e3f555be8 resource: repo://libs/core/tests/unit_tests/test_tools.py
- id: openwiki-source-71e882e1ac9757ea8e959a7c resource: repo://libs/langchain_v1/langchain/agents/factory.py
- id: openwiki-source-03e8ca0eebe37feda8566793 resource: repo://libs/langchain_v1/langchain/agents/middleware/types.py
- id: openwiki-source-ec30ab6256dd50cc670919f6 resource: repo://libs/langchain_v1/langchain/agents/structured_output.py
- id: openwiki-source-c479d4fffee5cf62576699e4 resource: repo://libs/langchain_v1/langchain/chat_models/base.py
- id: openwiki-source-0a3228970b0eadc4bcadbb5d resource: repo://libs/langchain_v1/langchain/mcp/adapter.py
- id: openwiki-source-ba4876d385d4d18ed4fa0342 resource: repo://libs/langchain_v1/pyproject.toml
- id: openwiki-source-94d5218d78dfd52679adc96b resource: repo://libs/langchain_v1/tests/unit_tests/test_imports.py
- id: openwiki-source-49fbcc45434b619b68220bf9 resource: repo://libs/Makefile
- id: openwiki-source-77f5d6298c73161b4d4f697e resource: repo://libs/model-profiles/langchain_model_profiles/init.py
- id: openwiki-source-738512768ef81ae009b097ac resource: repo://libs/partners/openai/langchain_openai/chat_models/base.py
- id: openwiki-source-b65307f1d05bd74532af2eee resource: repo://libs/partners/openai/langchain_openai/decisions/base.py
- id: openwiki-source-bd29e79613d5f366a00068f5 resource: repo://libs/standard-tests/langchain_tests/base.py generated: { by: "openwiki/0.5.0", at: "2026-10-22T08:26:56.662Z" } verified:
- by: openwiki/0.5.0 at: 2026-10-22T08:26:56.662Z
Overview
This page provides a quick reference for locating code by topic in the LangChain monorepo. The repository is organized as a multi-package workspace with a three-layer architecture:
- langchain-core (v1.6.13): Base abstractions for messages, runnables, tools, prompts, language models, and callbacks
- langchain (v1.4.7): Orchestration, agent factory, middleware composition, and model initialization
- langchain-classic (v1.0.8): Legacy chains, memory, retrieval abstractions, and backward compatibility
- partners (
langchain-*packages): Provider-specific implementations (OpenAI, Anthropic, Ollama, etc.) - text-splitters (v1.x): Text splitting and chunking utilities
- model-profiles (v0.0.6): LLM metadata and capability profiles
- standard-tests (shared): Ecosystem test contracts and conformance suites
Use this map to navigate directly to the code responsible for a given concept, understand architectural layering, and locate integration points.
Concept-to-Path Mapping
| Concept | Primary Path | Purpose |
|---|---|---|
| Agent Factory | repo://libs/langchain_v1/langchain/agents/factory.py |
Constructs compiled LangGraph state machines for agentic loops with model binding, tool execution, and middleware composition |
| Agent Middleware | repo://libs/langchain_v1/langchain/agents/middleware/ |
Pluggable hooks for model calls, tool invocation, and lifecycle events (retries, human-in-loop, redaction, etc.); 20+ middleware implementations |
| Caches & Prompt Caching | repo://libs/core/langchain_core/caches.py |
Optional caching layer for LLM results (distinct from provider prompt caching); in-memory and custom cache backends |
| Chat Models (Core) | repo://libs/core/langchain_core/language_models/chat_models.py |
BaseChatModel abstract base and unified provider interface for streaming, batching, token counting, and structured outputs |
| Chat Models (Discovery) | repo://libs/langchain_v1/langchain/chat_models/base.py |
init_chat_model() factory for dynamic model discovery and loading by provider:model identifier |
| Chat Models (Implementations) | repo://libs/partners/*/langchain_*/chat_models/ (e.g., openai/) |
Provider-specific implementations: ChatOpenAI, ChatAnthropic, ChatOllama, ChatGroq, etc. |
| Callbacks & Tracing | repo://libs/core/langchain_core/callbacks/ |
Callback manager, base handlers, streaming output, LangSmith integration, and event instrumentation |
| Decisions (OpenAI) | repo://libs/partners/openai/langchain_openai/decisions/ |
OpenAI structured outputs API integration for deterministic response marshaling and routing |
| Document Loaders | repo://libs/core/langchain_core/document_loaders/ |
Base loaders for ingesting documents from files, URLs, LangSmith, and blob storage |
| Documents & Metadata | repo://libs/core/langchain_core/documents/base.py |
Document type, compression, and transformation utilities |
| Embeddings | repo://libs/core/langchain_core/embeddings/embeddings.py |
Base embedding interface and fake embeddings for testing |
| Example Selectors | repo://libs/core/langchain_core/example_selectors/ |
Selection strategies for few-shot examples (LLM, max marginal relevance, etc.) |
| Messages | repo://libs/core/langchain_core/messages/ |
Message types (AIMessage, HumanMessage, SystemMessage, ToolMessage) and content blocks (text, images, tool use, etc.) |
| Model Profiles | repo://libs/model-profiles/langchain_model_profiles/ |
Metadata registry and CLI tools for LLM behavior, capabilities, and configuration |
| MCP (Model Context Protocol) | repo://libs/langchain_v1/langchain/mcp/ |
Adapter and tools for MCP-based model integrations and protocol compatibility |
| Output Parsers | repo://libs/core/langchain_core/output_parsers/ |
Structured output parsing (JSON, XML, Pydantic, OpenAI tools), format instructions, and validation |
| Prompts | repo://libs/core/langchain_core/prompts/ |
Chat and string prompt templates, few-shot examples, image prompts, and prompt composition |
| Rate Limiters | repo://libs/core/langchain_core/rate_limiters.py |
Base rate limiter interface and in-memory rate limiting implementations |
| Retrievers | repo://libs/core/langchain_core/retrievers.py |
Retriever abstraction for document retrieval, vector store integration, and composition |
| Runnables (LCEL) | repo://libs/core/langchain_core/runnables/ |
Foundational Runnable[Input, Output] protocol, composition operators (piping, branching, fallback, retry), and execution utilities |
| Structured Output | repo://libs/langchain_v1/langchain/agents/structured_output.py |
Schema definition and response marshaling for typed agent outputs (Pydantic, dataclass, TypedDict, JSON schema) |
| Tools | repo://libs/core/langchain_core/tools/ |
BaseTool abstraction, tool conversion from functions/Pydantic, schema generation, and tool rendering |
| Vector Stores | repo://libs/core/langchain_core/vectorstores/base.py |
Base vector store interface with in-memory implementation; persistence and async support |
| Legacy Chains | repo://libs/langchain/langchain_classic/chains/ |
Legacy chain abstractions (LLMChain, SequentialChain, etc.) for backward compatibility |
| Legacy Memory | repo://libs/langchain/langchain_classic/memory/ |
Conversation memory implementations (BufferMemory, EntityMemory, summary-based) |
| Text Splitters | repo://libs/text-splitters/langchain_text_splitters/ |
Character, token, semantic, and language-specific text chunking algorithms |
| Tests (Core Unit) | repo://libs/core/tests/unit_tests/ |
Unit tests for abstractions: runnables, messages, prompts, tools, callbacks, output parsers |
| Tests (Core Integration) | repo://libs/core/tests/integration_tests/ |
Integration tests with live providers and external services |
| Tests (LangChain Unit) | repo://libs/langchain_v1/tests/unit_tests/ |
Unit tests for agent factory, middleware, chat models, orchestration, and initialization |
| Tests (LangChain Integration) | repo://libs/langchain_v1/tests/integration_tests/ |
Integration tests for agent execution, tool binding, and provider fallback |
| Tests (Partner Unit) | repo://libs/partners/*/tests/unit_tests/ |
Provider-specific unit tests for chat models and integrations |
| Tests (Partner Integration) | repo://libs/partners/*/tests/integration_tests/ |
Provider-specific integration tests using live APIs (with cassettes for replay) |
| Standard Tests | repo://libs/standard-tests/langchain_tests/ |
Shared test suites and contracts for component conformance across the ecosystem |
| Configuration (Core) | repo://libs/core/pyproject.toml |
langchain-core package metadata, dependencies (langsmith, httpx, tenacity, pydantic), and build config |
| Configuration (LangChain v1) | repo://libs/langchain_v1/pyproject.toml |
langchain v1 package metadata, core dependencies, and optional provider groups |
| Configuration (Classic) | repo://libs/langchain/pyproject.toml |
langchain-classic package metadata (legacy chains, memory, retrieval) |
| Configuration (Text Splitters) | repo://libs/text-splitters/pyproject.toml |
langchain-text-splitters package metadata and dependencies |
| Configuration (Repo-Wide) | repo://.pre-commit-config.yaml |
Git hooks for formatting, linting, and validation across all packages |
| Build System (Libs) | repo://libs/Makefile |
Multi-package lockfile coordination, build targets, and cross-package tasks |
Key Directory Structure
/libs/
├── core/ # langchain-core: Base abstractions (v1.6.13)
│ ├── langchain_core/
│ │ ├── language_models/ # BaseChatModel and language model abstractions
│ │ │ ├── chat_models.py # Core chat model interface
│ │ │ ├── base.py # BaseLanguageModel and registry
│ │ │ └── model_profile.py # Profile metadata integration
│ │ ├── messages/ # Message types and content blocks
│ │ │ ├── base.py # BaseMessage and AIMessage
│ │ │ ├── content.py # Content block types (text, images, tool use)
│ │ │ ├── ai.py # AIMessage, AIMessageChunk
│ │ │ ├── tool.py # ToolMessage, ToolCall handling
│ │ │ └── utils.py # Message utilities and converters
│ │ ├── runnables/ # Runnable protocol and composition
│ │ │ ├── base.py # Runnable[Input, Output] protocol
│ │ │ ├── config.py # RunnableConfig and context management
│ │ │ ├── router.py # Routing and branching logic
│ │ │ └── utils.py # Composition utilities
│ │ ├── tools/ # BaseTool and tool conversion
│ │ │ ├── base.py # BaseTool abstract base
│ │ │ ├── convert.py # Function/Pydantic to tool conversion
│ │ │ ├── structured.py # StructuredTool with schema
│ │ │ └── render.py # Tool rendering for models
│ │ ├── prompts/ # Prompt templates and composition
│ │ │ ├── base.py # BasePrompt and PromptTemplate
│ │ │ ├── chat.py # ChatPromptTemplate, message composition
│ │ │ ├── few_shot.py # Few-shot example selection
│ │ │ └── image.py # Image prompt support
│ │ ├── output_parsers/ # Output parsing and validation
│ │ │ ├── base.py # BaseOutputParser interface
│ │ │ ├── pydantic.py # Pydantic model parsing
│ │ │ ├── openai_tools.py # OpenAI tool/function call parsing
│ │ │ ├── json.py # JSON output parsing
│ │ │ └── xml.py # XML structured output parsing
│ │ ├── callbacks/ # Callback manager and handlers
│ │ │ ├── manager.py # CallbackManager, async variants, event coordination
│ │ │ ├── base.py # BaseCallbackHandler interface
│ │ │ ├── streaming_stdout.py # Streaming output callback
│ │ │ └── file.py # File-based logging
│ │ ├── language_models/ # Additional model utilities
│ │ ├── caches.py # Cache interface for LLM results
│ │ ├── rate_limiters.py # Rate limiter base and in-memory impl
│ │ ├── retrievers.py # Retriever abstraction
│ │ ├── vectorstores/ # Vector store interface and in-memory impl
│ │ ├── documents/ # Document type and utilities
│ │ ├── embeddings/ # Embedding interface and fake impl
│ │ ├── document_loaders/ # Document loader abstractions
│ │ ├── example_selectors/ # Few-shot example selector strategies
│ │ └── ... (other utilities)
│ ├── tests/
│ │ ├── unit_tests/
│ │ ├── integration_tests/
│ │ └── benchmarks/
│ ├── Makefile
│ └── pyproject.toml
│
├── langchain_v1/ # langchain: Orchestration and agents (v1.4.7)
│ ├── langchain/
│ │ ├── agents/
│ │ │ ├── factory.py # Agent factory: graph construction, node orchestration
│ │ │ ├── middleware/ # Pluggable middleware system (20+ impls)
│ │ │ │ ├── types.py # AgentMiddleware, AgentState, callbacks
│ │ │ │ ├── _retry.py # Retry coordination
│ │ │ │ ├── _execution.py # Execution lifecycle
│ │ │ │ ├── model_retry.py # Model invocation retry
│ │ │ │ ├── tool_retry.py # Tool call retry
│ │ │ │ ├── tool_call_limit.py # Tool invocation limits
│ │ │ │ ├── model_fallback.py # Model fallback chains
│ │ │ │ ├── human_in_the_loop.py # Human approval loops
│ │ │ │ ├── pii.py # PII detection and redaction
│ │ │ │ ├── shell_tool.py # Shell command execution
│ │ │ │ ├── file_search.py # File system search and indexing
│ │ │ │ ├── tool_selection.py # LLM-based tool selection
│ │ │ │ ├── context_editing.py # Message context manipulation
│ │ │ │ ├── summarization.py # Conversation summarization
│ │ │ │ └── ... (other middleware)
│ │ │ ├── structured_output.py # Response schema marshaling
│ │ │ └── _subagent_transformer.py # Sub-agent graph composition
│ │ ├── chat_models/
│ │ │ └── base.py # init_chat_model factory and registry
│ │ ├── mcp/ # Model Context Protocol adapter
│ │ ├── messages/ # v1-specific message utilities
│ │ ├── embeddings/ # Embedding utilities
│ │ ├── tools/ # v1-specific tool utilities
│ │ └── rate_limiters/ # Rate limiting implementations
│ ├── tests/
│ │ ├── unit_tests/
│ │ ├── integration_tests/
│ │ ├── benchmarks/
│ │ └── cassettes/ # VCR cassettes for HTTP mocking
│ ├── Makefile
│ └── pyproject.toml
│
├── langchain/ # langchain-classic: Legacy code (v1.0.8)
│ ├── langchain_classic/
│ │ ├── chains/ # Legacy chain abstractions
│ │ ├── memory/ # Conversation memory implementations
│ │ ├── llms/ # Legacy LLM abstractions
│ │ ├── retrievers/ # Legacy retrieval abstractions
│ │ ├── document_loaders/ # Legacy document loading
│ │ └── ... (other legacy modules)
│ ├── tests/
│ ├── Makefile
│ └── pyproject.toml
│
├── partners/ # Provider-specific integrations
│ ├── openai/ # ChatOpenAI, embeddings, decisions API
│ │ ├── langchain_openai/
│ │ │ ├── chat_models/base.py # ChatOpenAI implementation
│ │ │ ├── decisions/ # Structured outputs integration
│ │ │ ├── embeddings/ # OpenAI embedding models
│ │ │ ├── llms/ # Legacy LLM compatibility
│ │ │ ├── output_parsers/ # Tool/function call parsing
│ │ │ ├── middleware/ # OpenAI-specific middleware
│ │ │ └── tools/ # OpenAI-specific tool integrations
│ │ ├── tests/
│ │ ├── Makefile
│ │ └── pyproject.toml
│ │
│ ├── anthropic/ # ChatAnthropic (Claude)
│ ├── ollama/ # ChatOllama (local models)
│ ├── groq/ # ChatGroq
│ ├── mistralai/ # ChatMistralAI
│ ├── huggingface/ # HuggingFace embeddings and models
│ ├── deepseek/ # ChatDeepSeek
│ ├── xai/ # XAI (Grok)
│ ├── perplexity/ # Perplexity models
│ ├── fireworks/ # Fireworks inference
│ ├── openrouter/ # OpenRouter aggregator
│ ├── together/ # Together AI models
│ ├── google-vertexai/ # Google Vertex AI
│ ├── google-genai/ # Google Generative AI
│ ├── azure-ai/ # Azure OpenAI and AI services
│ ├── aws/ # AWS Bedrock and SageMaker
│ ├── chroma/ # Chroma vector store
│ ├── qdrant/ # Qdrant vector store
│ ├── exa/ # Exa search
│ ├── nomic/ # Nomic embeddings
│ ├── typesafe/ # Typesafe schema generation
│ ├── cohere/ # Cohere models
│ └── Makefile
│
├── text-splitters/ # Text splitting utilities (v1.x)
│ ├── langchain_text_splitters/
│ │ ├── base.py # TextSplitter base class
│ │ ├── character.py # Character-based splitting
│ │ ├── token_based.py # Token count aware splitting
│ │ ├── semantic.py # Semantic (embedding-based) splitting
│ │ └── language_specific.py # Language-specific algorithms
│ ├── tests/
│ ├── Makefile
│ └── pyproject.toml
│
├── model-profiles/ # LLM behavior and capability profiles (v0.0.6)
│ ├── langchain_model_profiles/
│ │ ├── cli.py # CLI for updating profiles
│ │ └── _summary.py # Profile metadata aggregation
│ ├── tests/
│ ├── Makefile
│ └── pyproject.toml
│
├── standard-tests/ # Cross-ecosystem test contracts
│ ├── langchain_tests/
│ │ ├── base.py # BaseStandardTests class
│ │ ├── unit_tests/ # Standard unit test suites
│ │ ├── integration_tests/ # Standard integration test suites
│ │ ├── conftest.py # Pytest configuration
│ │ └── utils/ # Test utilities
│ ├── tests/
│ ├── Makefile
│ └── pyproject.toml
│
├── Makefile # Multi-package build coordination
└── README.md
Architecture Layers
Layer 1: langchain-core (Base Abstractions)
Core interfaces and implementations used by all other packages:
- Message protocol: AIMessage, HumanMessage, SystemMessage, ToolMessage with rich content blocks
- Runnable protocol: Composable units with
invoke(),stream(),batch()and async variants - LLM interface: BaseChatModel for unified provider integration
- Tool system: BaseTool with schema generation and conversion utilities
- Prompt templates: ChatPromptTemplate and PromptTemplate for composition
- Output parsing: Structured output extraction (JSON, XML, Pydantic, OpenAI tools)
- Callbacks: Event instrumentation and LangSmith integration
- Retrieval: Document loaders, vectorstores, retrievers
- Utilities: Embeddings, caches, rate limiters, example selectors
Layer 2: langchain (Orchestration & Agents)
High-level abstractions for agentic loops and orchestration:
- Agent Factory (
factory.py): Constructs LangGraph state machines with 7 node types (entry, loop entry, model, after-model, tools, exit) orchestrated by middleware - Middleware System: Pluggable hooks for model boundaries, tool boundaries, and lifecycle events (before_agent, before_model, after_model, after_tool, after_agent)
- Model Initialization:
init_chat_model()factory for provider:model discovery and dynamic loading - Structured Output: Schema marshaling for typed agent responses (Pydantic, dataclass, TypedDict, JSON schema)
- MCP Integration: Model Context Protocol adapter for tool discovery
Layer 3: langchain-classic (Legacy Code)
Backward-compatible implementations for v0.x users:
- Chains: LLMChain, SequentialChain, and other legacy composition patterns
- Memory: BufferMemory, EntityMemory, summary-based memory implementations
- Retrievers: Legacy retriever abstractions
- Loaders: Legacy document loader patterns
Layer 4: Partners (Provider Integrations)
Provider-specific implementations as independent packages:
- Each partner follows the partner pattern: extends core abstractions, released independently, dependencies pinned to core versions
- ChatOpenAI, ChatAnthropic, ChatOllama, etc.: Each implements BaseChatModel
- Decisions API: OpenAI-specific structured outputs integration
- Vector Stores: Chroma, Qdrant implementations of BaseVectorStore
- Embeddings: Provider-specific embedding models
Common Workflows
Finding Agent-Related Code
- Agent construction:
repo://libs/langchain_v1/langchain/agents/factory.py(graph nodes, middleware orchestration) - Middleware hooks:
repo://libs/langchain_v1/langchain/agents/middleware/types.py(type definitions); individual middleware inrepo://libs/langchain_v1/langchain/agents/middleware/subdirectory (20+ implementations) - Structured output:
repo://libs/langchain_v1/langchain/agents/structured_output.py(schema marshaling, response validation) - Tests:
repo://libs/langchain_v1/tests/unit_tests/andrepo://libs/langchain_v1/tests/integration_tests/
Finding LLM Integration Code
- Provider implementations:
repo://libs/partners/<provider>/(e.g.,repo://libs/partners/openai/)- Chat models:
langchain_*/chat_models/base.py - Embeddings:
langchain_*/embeddings/ - Provider-specific middleware:
langchain_*/middleware/
- Chat models:
- Model discovery:
repo://libs/langchain_v1/langchain/chat_models/base.py(init_chat_model()factory, registry) - Base interface:
repo://libs/core/langchain_core/language_models/chat_models.py(BaseChatModel protocol) - Model profiles:
repo://libs/model-profiles/langchain_model_profiles/(metadata registry and CLI)
Finding Core Abstractions
- Runnable protocol:
repo://libs/core/langchain_core/runnables/base.py(composition, streaming, batching) - Messages:
repo://libs/core/langchain_core/messages/(types, content blocks, utilities) - Tools:
repo://libs/core/langchain_core/tools/base.py(tool definition, schema, rendering) - Prompts:
repo://libs/core/langchain_core/prompts/(templates, composition, few-shot) - Callbacks:
repo://libs/core/langchain_core/callbacks/(event system, LangSmith integration) - Output parsing:
repo://libs/core/langchain_core/output_parsers/(structured extraction, validation) - Vector stores:
repo://libs/core/langchain_core/vectorstores/base.py(interface and in-memory impl) - Retrievers:
repo://libs/core/langchain_core/retrievers.py(document retrieval abstraction)
Finding Tests
- Core abstractions:
repo://libs/core/tests/(unit and integration tests for runnables, messages, tools, etc.) - Agent and orchestration:
repo://libs/langchain_v1/tests/(agent factory, middleware, initialization tests) - Provider-specific:
repo://libs/partners/<provider>/tests/(provider-specific unit and integration tests) - Shared test contracts:
repo://libs/standard-tests/(conformance tests for components across ecosystem) - Integration test data:
repo://libs/langchain_v1/tests/cassettes/(VCR cassettes for replaying HTTP interactions)
Configuration and Build
- Lint and format:
.pre-commit-config.yamlat repo root (ruff, black, mypy config) - Core dependencies:
repo://libs/core/pyproject.toml(langsmith, httpx, tenacity, pydantic) - LangChain dependencies:
repo://libs/langchain_v1/pyproject.toml(core, langgraph, optional provider groups) - Multi-package tasks:
repo://libs/Makefile(lock, check-lock targets for all packages)
Adding a New Provider Integration
- Create
repo://libs/partners/<provider>/directory - Implement
langchain_<provider>/chat_models/base.pyextendingBaseChatModel - Follow partner pattern: independent dependencies, core pinning, standard test suite
- Add to
repo://libs/langchain_v1/langchain/chat_models/base.pyregistry in_BUILTIN_PROVIDERS - Organize tests in
tests/unit_tests/andtests/integration_tests/
Adding a Middleware Implementation
- Create new file in
repo://libs/langchain_v1/langchain/agents/middleware/ - Extend
AgentMiddlewarefromrepo://libs/langchain_v1/langchain/agents/middleware/types.py - Implement hook methods:
before_agent(),before_model(),after_model(),after_tool_call(),after_agent() - Register in middleware composition chain via
factory.pybuilder
Build and Development Commands
All package directories (libs/core/, libs/langchain_v1/, libs/partners/<provider>/, etc.) include a local Makefile with standard targets:
# Format code (ruff)
make -C <package> format
# Lint code (ruff)
make -C libs/core lint
# Type check (mypy)
make -C libs/core type
# Run all tests
make -C libs/langchain_v1 test
# Run specific test file
make -C libs/core TEST_FILE=tests/unit_tests/test_runnables.py test
# Lock dependencies
make -C libs/core lock
# Check lockfile consistency
make -C libs/core check-lock
# Extended tests (marked with @pytest.mark.extended)
make -C libs/core extended_tests
The root repo://libs/Makefile coordinates multi-package operations:
# Lock all packages at once
make -C libs lock
# Check all lockfiles
make -C libs check-lock
Key Implementation Details
Agent Factory & Middleware Orchestration
The agent construction pipeline in repo://libs/langchain_v1/langchain/agents/factory.py builds a LangGraph state machine with these node types:
- Entry: Runs
before_agentmiddleware once at start - Loop Entry: Begins each model iteration, runs
before_modelhooks - Model: Invokes language model with accumulated message history and tool bindings
- After Model: Runs
after_modelhooks for response processing, tool call extraction - Tools: Executes tool calls in parallel when present
- Exit: Runs
after_agenthooks once at completion
Middleware hooks are composable and execute in order:
before_agent(state, config)→ single entry pointbefore_model(state, config)→ per-iteration, before model callafter_model(response, state, config)→ after model call, can transform responseafter_tool_call(tool_call, tool_result, state, config)→ per tool executionafter_agent(state, config)→ single exit point
Each middleware can inject commands to jump to different nodes, modify state, or abort execution.
Middleware Implementations (20+ in /agents/middleware/)
- Model-level:
ModelRetryMiddleware,ModelCallLimitMiddleware,ModelFallbackMiddleware - Tool-level:
ToolRetryMiddleware,ToolCallLimitMiddleware,ToolErrorMiddleware,ToolEmulator - Context:
HumanInTheLoopMiddleware,ContextEditingMiddleware,FilesystemFileSearchMiddleware - Safety/Redaction:
PIIMiddleware,RedactionMiddleware,ShellToolMiddleware - Execution Control:
ProviderToolSearchMiddleware - Optimization:
SummarizationMiddleware,TodoListMiddleware - Selection:
LLMToolSelectorMiddleware - Lifecycle:
TracePolicyconfiguration and execution tracing
Each middleware is independently configurable and composable into agent construction chains.
Runnable Composition Protocol
The Runnable protocol in repo://libs/core/langchain_core/runnables/base.py enables declarative chaining via operators:
- Piping (
|): Sequential composition, threads output to next input - Parallel (
+): Parallel execution of branches, collects results - Branching (
.pipe()with routing): Conditional execution paths based on state - Fallback (
.with_fallback()): Error recovery with alternative runnables - Retry (
.with_retry()): Automatic retry with exponential backoff
All compositions automatically support:
invoke(input, config=None)→ sync executionainvoke(input, config=None)→ async executionbatch(inputs, config=None, ...)→ parallel batch processingstream(input, config=None)→ streaming output chunksastream(),batch_as_completed(), and other variants
Message Protocol & Content Blocks
The message abstraction in repo://libs/core/langchain_core/messages/ defines:
- Message types:
AIMessage,HumanMessage,SystemMessage,ToolMessage,FunctionMessage - Content representation: Messages store
contentas either:strfor simple textlist[ContentBlock]for mixed content (text, images, tool use, etc.)
- Content blocks:
TextBlock,ImageBlock,ToolUseBlock,ToolResultBlock, custom blocks - Message utilities:
- Serialization/deserialization via
dumps(),loads() - Message merging and deduplication
- Role mapping for different model APIs
- Model-specific translation (e.g., OpenAI format conversion)
- Serialization/deserialization via
Tool Abstraction & Binding
The BaseTool in repo://libs/core/langchain_core/tools/base.py provides:
- Tool protocol:
- Sync/async invoke methods
- Schema generation from docstrings and Pydantic models
- Argument validation and type coercion
- Tool conversion (via
convert.py):tool()decorator for functions → StructuredTool- Pydantic model → Tool with JSON schema
- Custom tool builders
- Tool rendering (via
render.py):- Format tools for model context
- Description-only for prompt inclusion
- Structured schemas for function calling
Tool binding in chat models:
model.bind_tools([tool1, tool2]) # Binds tools via provider API
Output Parser Hierarchy
- BaseOutputParser: Abstract base for all parsers
- PydanticOutputParser: Validates against Pydantic model
- JsonOutputParser: Parses JSON text into dict
- XmlOutputParser: Parses XML structured output
- OpenAI tool/function parsers: Handle tool call and function call formats
- Custom parsers: User-defined parsing logic
Dependency Flow
User Applications
├─→ langchain (v1.4.6)
│ ├─→ langchain-core (v1.6.12)
│ └─→ LangGraph (state machines, runtime)
│
├─→ langchain-core (direct use)
│ └─→ LangSmith (tracing), httpx (HTTP), tenacity (retry), pydantic
│
├─→ langchain-classic (v1.0.8) [backward compat]
│ └─→ langchain-core, SQLAlchemy, LangSmith
│
└─→ Partner Packages (langchain-openai, langchain-anthropic, etc.)
├─→ langchain-core (pinned versions)
└─→ Provider SDKs (openai, anthropic, etc.)
Versioning Model:
- Core is released independently with strict semantic versioning
- LangChain and partners pin core versions with lower bounds
- Partner packages are released independently per provider
- Standard-tests library contains shared conformance contracts
Extension Points
Adding Custom Chat Model
- Extend
BaseChatModelfromlangchain_core.language_models.chat_models - Implement:
_generate(),_stream(),_invoke()methods - Register in
init_chat_model()via_BUILTIN_PROVIDERSdict - Inherit callback support, streaming, token counting, structured output from base
Adding Custom Retriever
- Extend
BaseRetrieverfromlangchain_core.retrievers - Implement:
_get_relevant_documents(),_aget_relevant_documents() - Automatic integration with callback system and streaming
Adding Custom Output Parser
- Extend
BaseOutputParserfromlangchain_core.output_parsers - Implement:
parse()method (andaparse()for async) - Optionally implement
get_format_instructions()for prompt injection
Adding Custom Tool
- Extend
BaseToolor use@tooldecorator - Implement
_run()(and_arun()for async) - Schema automatically generated from docstrings and Pydantic annotations
Adding Custom Runnable
- Extend
Runnable[Input, Output]orRunnableSerializable - Implement:
invoke(),stream(),batch()(async variants optional) - Automatically compose with operators:
|,+,.with_fallback(), etc.