« Phase 29 README · Warmup · Hitchhiker's · Deep Dive · Principal Deep Dive · Staff Notes

Phase 29 — Core Contributor Notes: LangChain Core

This is the view from inside the langchain-core source tree — how the real framework implements the abstractions our miniature imitates, the decisions that aren't obvious from the public API, and the scar tissue from the framework's own migrations. If you maintain LCEL in anger, these are the things you learn.

Runnable is an abstract base class with a lot of default machinery

In the real codebase Runnable lives in langchain_core.runnables.base. A concrete Runnable is only required to implement invoke (or ainvoke). Everything else is a default:

• batch defaults to running invoke over a ThreadPoolExecutor bounded by config["max_concurrency"]; abatch uses asyncio.gather with a semaphore. Override them only when the provider has a genuine bulk endpoint.
• stream defaults to yield self.invoke(...) — a single chunk. That is a legal, non-streaming implementation. A model overrides it to yield token chunks.
• astream defaults to wrapping stream in a thread; ainvoke defaults to running invoke in a thread pool. This is why a sync-only RunnableLambda still works in an async chain — the framework bridges it — and also why a blocking call inside a "lambda" can stall the event loop under load. A committer knows to provide a real afunc for hot async paths rather than leaning on the thread bridge.

Most Runnables actually subclass RunnableSerializable (Runnable + Serializable), which is what makes chains dumpable to JSON for LangServe playgrounds and LangSmith. Our stdlib miniature skips serialization entirely; the real one carries lc_secrets/lc_attributes plumbing so secrets are stripped on dump.

__or__, coercion, and the RunnableSequence shape

a | b calls a.__or__(b), which routes through coerce_to_runnable and builds (or extends) a RunnableSequence. coerce_to_runnable is the small, load-bearing function that makes LCEL ergonomic: a dict becomes RunnableParallel, a callable becomes RunnableLambda, an existing Runnable passes through. RunnableSequence deliberately flattens — (a | b) | c yields one sequence with three steps, not nested pairs — so the run tree and streaming are linear. RunnableParallel runs its branches on a thread pool and, crucially, copies the config per branch so callbacks/run-ids nest correctly; getting that wrong is a classic source of tangled traces.

RunnableLambda has a sharp edge worth internalising: it inspects your function's signature. A one-arg function gets the input; a function that also accepts config/run_manager gets them injected. And a RunnableLambda may itself return a Runnable, which the framework then invokes — that is how dynamic routing (return a different chain based on input) works without RunnableBranch.

Streaming, transform, and astream_events

The Deep Dive's streaming mechanism — sequences thread iterators via transform/atransform, and the default transform buffers — is exactly the real implementation. The non-obvious contributor-level piece is astream_events (the v2 event API). Because raw stream only surfaces the final step's chunks, you cannot see "the retriever returned these docs, then the model started generating" from stream alone. astream_events walks the callback/run-tree and emits typed events (on_retriever_end, on_chat_model_stream, on_chain_end) for every nested step. It exists because production UIs need to render intermediate progress ("Searching..." then tokens), and the v1→v2 rewrite happened because v1's event schema couldn't cleanly express nested/parallel runs. If you build a streaming agent UI on real LangChain, this is the API you actually use.

Config propagation via contextvars — the subtle correctness bug

RunnableConfig (callbacks, tags, metadata, run_id, max_concurrency) must reach every nested step so traces form one tree. Modern langchain-core propagates it through Python contextvars, which means it flows automatically through await boundaries — but not always across manually spawned threads. The well-known gotcha: if you asyncio.create_task or hand work to your own executor inside a Runnable without copying the context, the child loses the parent run-id and your LangSmith trace splits into orphans. Contributors learn to thread config explicitly (or use the provided helpers) exactly at those boundaries.

The great reorganization — and why the API looks the way it does

The single most important thing to know about real LangChain is its migration history, because half of what you'll inherit is pre-migration:

• Era one (0.0.x): one monolithic langchain package, LLMChain, RetrievalQA, ConversationChain, initialize_agent. Powerful, tightly coupled, hard to test, and the source of the framework's reputation.
• The split (0.1 → 0.2 → 0.3): the primitives were extracted into langchain-core; provider integrations moved to thin partner packages (langchain-openai, langchain-anthropic, …); the long tail moved to langchain-community. The point was to stabilise the core interface while providers churn, and to shrink the dependency footprint of a production install.
• LCEL replaced the *Chain classes. RetrievalQA → an LCEL RAG chain; LLMChain → prompt | model | parser; ConversationChain → RunnableWithMessageHistory. The old classes still import (with deprecation warnings) precisely because so much production code depends on them.
• Pydantic v1 → v2. Core moved to Pydantic v2; the interop shims and the .model_dump vs .dict divergence are a real source of bugs in mixed codebases.

When you see from langchain.chains import RetrievalQA in a repo, you are reading era-one code, and the maintainer-correct move is "this still runs, here's the LCEL rewrite, migrate on the next touch — don't start new work on it."

with_structured_output and bind_tools are provider-specific under one signature

model.with_structured_output(Schema) presents a uniform API, but underneath it dispatches per provider: OpenAI-style tool/function calling, a JSON-mode, or (fallback) a parser over free text. That is why the same call has different failure characteristics on different models — the "translation layer has a ceiling" pattern. bind_tools similarly normalises wildly different provider tool schemas into AIMessage.tool_calls. Contributors treat these as adapters, and the sharp edge is that a model which doesn't natively support tool calling silently routes to the weakest fallback.

AgentExecutor lives in legacy-land; LangGraph is the successor

AgentExecutor sits in the langchain package, not core, and is in maintenance mode. Its loop is exactly the Deep Dive's trace, and its inability to pause/checkpoint/edit mid-loop is why the team built LangGraph and create_react_agent. The two share langchain-core: a compiled LangGraph graph implements Runnable, so it drops into an LCEL pipeline unchanged, and graph nodes call LCEL chains inside them. The evolution is honest — the maintainers deprecated their own most-used feature because a hidden while-loop was the wrong shape for durable agents.

What our miniature simplifies

Our stdlib version keeps the shape and drops the industrial plumbing: no callbacks/tracing/run-tree, no serialization, no contextvar config propagation, single-threaded batch, no astream_events, and a stream that may not implement full transform-based end-to-end incrementality. Those omissions are the difference between "I understand the Runnable algebra" and "I can operate the real framework" — and knowing precisely which corners were cut is itself the contributor-level signal.