langchain_classic — Internal Wiki

CompositionPydantic v1Pre-LCEL legacyProduction-critical

Project Philosophy

When LangChain split into langchain_core + integrations + classic, the design problem was how to keep four years of public API intact while migrating to LCEL. The answer was langchain_classic/: a library that re-implements (or thinly wraps) the historical surface — Chain, AgentExecutor, BaseLLM, BaseRetriever, BaseMemory, BaseTool — while internally bridging to the new Runnable protocol where possible. Every module here exists for one of three reasons: (1) a public class hierarchy users still subclass; (2) a factory function that builds an LCEL chain with the same shape as the legacy class; or (3) glue (callbacks, output parsers) where the legacy and modern stacks share infrastructure.

The unifying design choice across the codebase is Pydantic v1 BaseModel as the universal extension point. Every Chain, Tool, Retriever, Memory, and LLM is a BaseModel subclass. This gives free input validation, JSON serialisation, schema-driven UIs, and a discoverable __init__ contract — at the cost of locking the project to Pydantic v1 long after the ecosystem moved to v2.

Project-level Design Decisions

System Architecture

flowchart TD
  subgraph Orch["Orchestration"]
    CH["chains/"]
    AG["agents/"]
    RN["runnables/"]
  end
  subgraph MIO["Models I/O"]
    LL["llms/"]
    CM["chat_models/"]
    EM["embeddings/"]
    PR["prompts/"]
    OP["output_parsers/"]
  end
  subgraph RD["Retrieval & Data"]
    RE["retrievers/"]
    VS["vectorstores/"]
    DL["document_loaders/"]
    DT["document_transformers/"]
    IX["indexes/"]
  end
  subgraph ST["State & Tools"]
    TO["tools/"]
    ME["memory/"]
    SG["storage/"]
  end
  subgraph CC["Cross-cutting"]
    CB["callbacks/"]
    EV["evaluation/"]
    UT["utilities/"]
  end
  subgraph FN["Foundations (langchain_core)"]
    SC["schema/"]
    AD["adapters/"]
  end
  CH -->|"composes"| MIO
  AG -->|"calls"| TO
  AG -->|"streams"| CB
  CH -->|"emits"| CB
  RE --> VS
  RE --> EM
  DL --> DT
  DT --> VS
  IX --> VS
  ME --> SG
  TO --> UT
  Orch --> FN
  MIO --> FN
  RD --> FN

Modules

Orchestration

Models I/O

Retrieval & Data

State & Tools

Cross-cutting

Foundations

Cross-module Synthesis

End-to-end flows

Flow 1 — Conversational RAG with citations

User asks a question in a chat UI. The system retrieves relevant docs, answers with the LLM, and stores the turn for follow-up questions.

User input
   │
   ▼
chat history (memory.ChatMessageHistory)
   │
   ├──► history-aware rephrase  (chains.history_aware_retriever)
   │      └── prompt | LLM | StrOutputParser  ──► standalone question
   │
   ▼
retriever (retrievers.MultiQueryRetriever wrapping vectorstores.Chroma)
   │      └── LLM expands to N variants
   │      └── each variant → similarity_search → fuse via dedupe
   ▼
docs (list[Document])
   │
   ▼
contextual compression (retrievers.ContextualCompressionRetriever)
   │      └── EmbeddingsFilter → LLMChainExtractor
   ▼
answer chain (chains.create_stuff_documents_chain)
   │      └── prompt-with-{context} | LLM | StrOutputParser
   ▼
answer + cited docs
   │
   ├──► memory.save_context({"input": q}, {"output": a})  → updates ChatMessageHistory
   │
   ▼
response to user

Touched modules. memory/, chains/, retrievers/, vectorstores/, document_compressors/ (under retrievers/), output_parsers/, callbacks/ (instrumenting every step).

Total LLM calls. Typically 3 — rephrase, multi-query expand, answer. Plus optional compression LLM call.

Key insight. This entire flow is now expressible in LCEL: history_aware | retriever | compress | stuff. The classic Chain-class equivalents still exist for legacy code.

Flow 2 — Tool-calling agent answering "what's the weather in Paris and convert to F?"

input → AgentExecutor.invoke({"input": q})
          │
          ▼ (loop iteration 1)
       prompt = ChatPromptTemplate(system, MessagesPlaceholder("history"),
                                    HumanMessage(q),
                                    MessagesPlaceholder("agent_scratchpad"))
          │
          ▼
       prompt | llm.bind_tools(tools) | OpenAIToolsAgentOutputParser
          │      └── llm returns tool_calls=[get_weather(city="Paris")]
          ▼
       AgentAction("get_weather", {"city": "Paris"}, log=…)
          │
          ▼
       AgentExecutor calls tools["get_weather"].arun({"city":"Paris"})
          │      └── utilities.GoogleSearchAPIWrapper or open-meteo HTTP
          ▼
       observation = "21 °C, partly cloudy"
       intermediate_steps.append((action, observation))
          │
          ▼ (loop iteration 2)
       same prompt with new scratchpad
          │
          ▼
       LLM returns tool_calls=[convert_temperature(value=21, from="C", to="F")]
          │
          ▼ … observation = "69.8 °F"
          │
          ▼ (loop iteration 3)
       LLM returns AgentFinish(return_values={"output": "Paris is 21 °C / 69.8 °F"})
          │
          ▼
       AgentExecutor returns {"input": …, "output": …, "intermediate_steps": [...]}

Touched modules. agents/, tools/, chat_models/, prompts/ (MessagesPlaceholder), output_parsers/, callbacks/.

Key insight. All loop control lives in AgentExecutor. The agent itself is a stateless Runnable; the executor passes intermediate_steps back in on each iteration.

Flow 3 — Indexing a documentation site

loader = WebBaseLoader([...])           # document_loaders
docs = loader.lazy_load()
splits = RecursiveCharacterTextSplitter(...).split_documents(docs)   # text_splitter

embedder = CacheBackedEmbeddings.from_bytes_store(
    OpenAIEmbeddings(), LocalFileStore("./cache"), namespace="docs"
)                                                # embeddings + storage
vs = Chroma(embedding_function=embedder, persist_directory="./db")   # vectorstores

record_manager = SQLRecordManager("docs", db_url="sqlite:///rm.db")
record_manager.create_schema()                          # indexes

result = index(
    splits, record_manager, vs, cleanup="incremental", source_id_key="source"
)                                                       # indexes
# {"num_added": 142, "num_updated": 7, "num_deleted": 3, "num_skipped": 1820}

Touched modules. document_loaders, text_splitter, embeddings, storage, vectorstores, indexes.

Key insight. The record_manager + index() pair is what makes this idempotent. Without it, every run would re-embed every document.

Flow 4 — Evaluating an agent on a dataset

run_on_dataset(
    dataset_name="my-dataset",
    llm_or_chain_factory=lambda: AgentExecutor(...),
    evaluation=RunEvalConfig(evaluators=[
        RunEvalConfig.LabeledCriteria("correctness"),
        RunEvalConfig.AgentTrajectory(),
    ]),
)
   │
   ▼
LangSmith pulls dataset rows → for each, factory() builds a fresh chain
   │                          └── this isolation prevents memory leaks across rows
   ▼
chain.invoke(row.input) under tracing
   │
   ▼
LangChainTracer (callbacks) streams runs to LangSmith
   │
   ▼
For each evaluator: load_evaluator(...) → evaluate_strings/evaluate_run
   │      └── criteria evaluator: LLM judge with CoT
   │      └── trajectory evaluator: rates tool-use correctness
   ▼
Feedback rows stored against the run

Coupling analysis

Architectural philosophy

1. Composition over configuration. Chains compose; agents compose with tools; retrievers wrap retrievers. Configuration flags are reserved for orthogonal concerns (verbose, callbacks, max_iterations).
2. Pluggable strategies behind small ABCs. BaseTool, BaseRetriever, BaseMemory, BaseOutputParser, AgentOutputParser, BaseDocumentCompressor, BaseChatMessageHistory, ByteStore, RecordManager, Embeddings, BaseLLM, BaseChatModel. Every notable axis of variation is an ABC.
3. Evidence: Pydantic-typed I/O. Dict-based I/O at the chain boundary lets callers introspect; Pydantic models inside ABCs catch wiring mistakes at construction time.
4. Callbacks everywhere. No code is unobservable. Even tools have callbacks. This is a deliberate observability tax — you pay a tiny per-call overhead and get streaming + tracing + cost accounting for free.
5. Backward compatibility is a feature. Re-export shims (schema/, prompts/, tools/), lazy trampolines (llms/, chat_models/), @deprecated decorators, and side-by-side legacy + factory APIs (AgentType enum + create_*_agent factories; Chain subclassing + create_*_chain LCEL factories) all reflect a project that values stability for users on old code paths.
6. LCEL is the future, classic is the museum. Many newer constructors (create_retrieval_chain, create_history_aware_retriever, create_stuff_documents_chain, create_*_agent) return Runnables. The legacy Chain and Agent classes remain for compat but new code is encouraged toward LCEL.

Shared state inventory

• **Process-globals (globals.py):** verbose, debug, llm_cache. Set once at boot; consulted by every chain/agent. The convenience comes at the cost of test isolation — tests must reset.
• Inheritable callbacks: RunnableConfig.callbacks propagate through child runs, forming the run tree LangSmith renders.
• Memory: Owned by the chain; not shared between chains unless explicitly passed.
• Vectorstores / record managers: External, shared across processes; the indexing API treats them as ground truth.

System evolution

• Layer 1 — Core (Aug 2022): Chain, LLM, PromptTemplate. Single repo. Everything in one place.
• Layer 2 — Agents (Oct 2022): ZERO_SHOT_REACT_DESCRIPTION agent + Tool. The act-observe loop is invented.
• Layer 3 — Retrievers (early 2023): Vectorstore explosion + BaseRetriever ABC. RAG becomes a first-class pattern.
• Layer 4 — Memory (mid 2023): BaseMemory accumulates flavours: Buffer → Window → Summary → KG → VectorStore.
• Layer 5 — LCEL (late 2023): Runnable ABC, | composition, streaming as a first-class concern. Many Chains become wrappers over LCEL.
• Layer 6 — Package split (early 2024): Core / community / classic / provider packages. langchain_classic becomes the home of pre-LCEL code + classic-only constructors.
• Layer 7 — Modern factory APIs (2024–): create_*_agent, create_*_chain, init_chat_model, RunnableWithMessageHistory. The legacy classes persist; new code is steered to factories.

The "core" — most stable, most depended on — is langchain_core (not in this repo). Inside langchain_classic, the most stable layer is chains/base.py, agents/agent.py, BaseMemory, BaseRetriever. The most evolutionary churn is at the surface (factory functions, agent flavours).

Connection diagram

flowchart LR
  subgraph Core["langchain_core (external)"]
    R[Runnable]
    BM[BaseMessage]
    BT[BaseTool]
    BRet[BaseRetriever]
    BLLM[BaseLanguageModel]
    PT[BasePromptTemplate]
    DOC[Document]
  end

  subgraph Orch[Orchestration]
    CH[chains/]
    AG[agents/]
    RUN[runnables/]
  end

  subgraph IO[Models I/O]
    LL[llms/, chat_models/]
    EMB[embeddings/]
    OP[output_parsers/]
    PR[prompts/]
    CB[callbacks/]
  end

  subgraph Retrieve[Retrieval & Storage]
    RT[retrievers/]
    VS[vectorstores/]
    DL[document_loaders/]
    DT[document_transformers/]
    DS[docstore/]
    ST[storage/]
    IDX[indexes/]
  end

  subgraph Tools[Tools & I/O]
    TL[tools/]
    UT[utilities/]
    CL[chat_loaders/]
    GR[graphs/]
  end

  subgraph State[State]
    MM[memory/]
  end

  subgraph EvalSubgraph[Evaluation]
    EV[evaluation/]
    SM[smith/]
  end

  R --> Orch
  R --> IO
  R --> Retrieve
  R --> Tools
  BM --> IO
  BT --> AG
  BRet --> RT
  BLLM --> LL
  PT --> PR
  DOC --> Retrieve

  CH -.uses.-> PR
  CH -.uses.-> LL
  CH -.uses.-> OP
  CH -.uses.-> MM
  CH -.uses.-> RT

  AG -.uses.-> TL
  AG -.uses.-> CH
  AG -.uses.-> OP
  AG -.uses.-> CB

  RT -.uses.-> VS
  RT -.uses.-> EMB
  RT -.uses.-> DT
  IDX -.uses.-> VS
  IDX -.uses.-> ST
  DL -.feeds.-> DT
  DT -.feeds.-> VS

  TL -.uses.-> UT
  TL -.uses.-> GR
  EV -.uses.-> CH
  SM -.uses.-> EV

  CB -.observes.-> Orch
  CB -.observes.-> IO
  CB -.observes.-> Tools
  CB -.observes.-> Retrieve

Phase 1A — Broad Survey

langchain_classic/                 ← 28 functional sub-modules, 1321 .py files
├── chains/         (28 sub-dirs, 140 files)   ← L1+L2 candidate
├── agents/         (17 sub-dirs, 146 files)   ← L1+L2 candidate
├── tools/          (64 sub-dirs, 186 files)   ← L1, sub-dirs are integrations
├── document_loaders/ (2 sub-dirs, 166 files)  ← L1 flat (mostly re-exports)
├── llms/           (1 sub-dir,  83 files)
├── retrievers/     (2 sub-dirs, 78 files)
├── vectorstores/   (2 sub-dirs, 75 files)
├── utilities/      (0 sub-dirs, 58 files)
├── embeddings/     (0 sub-dirs, 51 files)
├── callbacks/      (2 sub-dirs, 45 files)
├── memory/         (1 sub-dir,  39 files)
├── chat_models/    (0 sub-dirs, 35 files)
├── evaluation/     (10 sub-dirs, 32 files)
├── output_parsers/ (0 sub-dirs, 23 files)
├── utils/          (0 sub-dirs, 15 files)
├── graphs/         (0 sub-dirs, 13 files)
├── prompts/        (1 sub-dir,  12 files)
├── document_transformers/ (1 sub-dir, 11 files)
├── chat_loaders/   (0 sub-dirs, 10 files)
├── indexes/        (1 sub-dir,   9 files)
├── storage/        (0 sub-dirs,  8 files)
├── smith/          (1 sub-dir,   7 files)
├── docstore/       (0 sub-dirs,  6 files)
├── _api/           (0 sub-dirs,  5 files)
├── load/           (0 sub-dirs,  4 files)
├── runnables/      (0 sub-dirs,  3 files)
├── adapters/       (0 sub-dirs,  2 files)
└── (single-file modules) cache.py · globals.py · hub.py · sql_database.py ·
                          requests.py · python.py · serpapi.py · text_splitter.py
                          · base_language.py · base_memory.py · model_laboratory.py

                         langchain_core
                       (Runnable, BaseMessage, BaseTool, BaseRetriever,
                        BasePromptTemplate, Document, BaseLanguageModel)
                              ▲           ▲          ▲           ▲
                              │           │          │           │
   ┌──────────────────────────┘           │          │           └────────────┐
   │                          ┌───────────┘          │                        │
   │                          │                      │                        │
chains/  ◄─── prompts/   ◄── llms/, chat_models/   tools/   ◄── output_parsers/
   ▲          ▲              embeddings/             ▲
   │          │              callbacks/              │
   │          └──────────────────┐                   │
   │                             │                   │
agents/  ─────────────────►  memory/  ◄── retrievers/  ◄── vectorstores/
   │                                                       ▲
   └─► utilities/  ─────► tools/integrations/              │
                                                  document_loaders/  ──► document_transformers/
                                                                              │
                                                                              ▼
                                                                          indexes/, storage/
   evaluation/  ─────► chains/  + criteria
   smith/       ─────► evaluation/  + LangSmith API

   graphs/      ─────► graph DB drivers (neo4j, networkx, kuzu)
   load/        ◄── used by every Serializable subclass
   _api/        ◄── used by every deprecated symbol

langchain_classic/
├── _api/                  ← deprecation infrastructure
├── adapters/              ← provider adapters (currently openai.py)
├── agents/                ← Agent loop, AgentExecutor, agent flavours
├── cache.py               ← LLM response cache
├── callbacks/             ← Observer pattern fan-out
├── chains/                ← Chain abstraction + 28 chain families
├── chat_loaders/          ← chat history → BaseMessage
├── chat_models/           ← lazy trampolines to community
├── docstore/              ← legacy in-memory document store
├── document_loaders/      ← 160+ file/web/cloud loaders
├── document_transformers/ ← splitters & filters
├── embeddings/            ← lazy trampolines + CacheBackedEmbeddings
├── env.py
├── evaluation/            ← QA, criteria, distance, comparison evals
├── example_generator.py
├── formatting.py
├── globals.py             ← process-wide toggles
├── graphs/                ← graph DB query wrappers
├── hub.py                 ← LangChain Hub pull/push
├── indexes/               ← record manager + index() upsert algorithm
├── input.py
├── llms/                  ← lazy trampolines to community
├── load/                  ← Serializable mixin
├── memory/                ← conversation state strategies
├── model_laboratory.py
├── output_parsers/        ← retry, fix, pydantic, structured parsers
├── prompts/               ← re-exports of langchain_core.prompts
├── python.py
├── requests.py
├── retrievers/            ← MultiQuery, ParentDoc, Ensemble, SelfQuery
├── runnables/             ← OpenAIAssistantRunnable + helpers
├── schema/                ← legacy type re-exports
├── serpapi.py
├── smith/                 ← LangSmith runner
├── sql_database.py
├── storage/               ← KV abstractions
├── text_splitter.py
├── tools/                 ← BaseTool + 60+ integration sub-dirs
├── utilities/             ← API wrappers
└── utils/                 ← misc helpers

Directory Map

/
├── __init__.py
├── _api/
├── adapters/
├── agents/
├── base_language.py
├── base_memory.py
├── cache.py
├── callbacks/
├── chains/
├── chat_loaders/
├── chat_models/
├── docstore/
├── document_loaders/
├── document_transformers/
├── embeddings/
├── env.py
├── evaluation/
├── example_generator.py
├── formatting.py
├── globals.py
├── graphs/
├── hub.py
├── indexes/
├── input.py
├── llms/
├── load/
├── memory/
├── model_laboratory.py
├── output_parsers/
├── prompts/
├── py.typed
├── python.py
├── requests.py
├── retrievers/
├── runnables/
├── schema/
├── serpapi.py
├── smith/
├── sql_database.py
├── storage/
├── text_splitter.py
├── tools/
├── utilities/
├── utils/
└── vectorstores/