langchain-core

Base abstractions for the entire LangChain ecosystem. langchain-core defines the protocols that every other package implements. It is intentionally lightweight — its only runtime dependencies are pydantic, langsmith, tenacity, jsonpatch, PyYAML, typing-extensions, packaging, uuid-utils, and langchain-protocol.

• Source root: libs/core/langchain_core/
• PyPI: langchain-core
• Current version: 1.3.2
• Files: ~183 source modules

Purpose

If langchain is the framework, langchain-core is the framework's contract. It contains:

• The Runnable protocol and LCEL composition operators.
• The message type system (HumanMessage, AIMessage, …) and the v1 content-block taxonomy (TextContentBlock, ImageContentBlock, ReasoningContentBlock, Citation, …).
• Language model base classes: BaseLanguageModel, BaseChatModel, BaseLLM, plus the streaming-first v1 protocol BaseChatModelV1.
• Tool abstractions: BaseTool, StructuredTool, the @tool decorator.
• Prompt templates: PromptTemplate, ChatPromptTemplate, few-shot variants.
• Output parsers: string, JSON, Pydantic, OpenAI-tools, XML, transform.
• Callbacks and tracers that emit LangSmith run trees.
• Vector store and retriever interfaces.
• Document types (Document, Blob) and indexing helpers.
• Caches, chat histories, stores, rate limiters, example selectors.

Almost every other package imports from langchain_core.

Directory layout

libs/core/langchain_core/
├── _api/                  # Deprecation/beta machinery
├── _security/             # Sandboxed transports, policy hooks
├── agents.py              # AgentAction / AgentFinish base types
├── caches.py              # BaseCache and in-memory cache
├── callbacks/             # CallbackHandler, CallbackManager (sync & async)
├── chat_history.py        # BaseChatMessageHistory
├── document_loaders/      # Base loader/blob loader interfaces
├── documents/             # Document, Blob
├── embeddings/            # Embeddings interface
├── example_selectors/     # Few-shot selectors (similarity, length-based)
├── exceptions.py          # OutputParserException, TracerException, ...
├── globals.py             # debug/verbose/cache globals
├── indexing/              # Index API for vector stores
├── language_models/       # BaseLanguageModel, BaseChatModel, BaseLLM, BaseChatModelV1
├── load/                  # Serializable + serialization helpers
├── messages/              # Message types and content blocks
├── output_parsers/        # String, JSON, Pydantic, OpenAI-tools, XML parsers
├── outputs/               # Generation, ChatGeneration, LLMResult
├── prompt_values.py       # PromptValue base
├── prompts/               # PromptTemplate, ChatPromptTemplate, few-shot
├── rate_limiters.py       # InMemoryRateLimiter
├── retrievers.py          # BaseRetriever
├── runnables/             # The Runnable protocol and LCEL operators
├── stores.py              # BaseStore (key-value)
├── structured_query.py    # Filter expression language
├── sys_info.py            # Diagnostic dump for issue templates
├── tools/                 # BaseTool, StructuredTool, @tool decorator
├── tracers/               # LangSmith and run-log tracers
├── utils/                 # General utilities (pydantic, JSON, async)
├── vectorstores/          # VectorStore base
└── version.py             # __version__

Key abstractions

Symbol	File	Description
Runnable	libs/core/langchain_core/runnables/base.py	Universal invoke/batch/stream protocol that everything implements
RunnableSequence	libs/core/langchain_core/runnables/base.py	The | operator's runtime; chains runnables
RunnableParallel, RunnableMap	libs/core/langchain_core/runnables/base.py	Run runnables in parallel and combine outputs
RunnableLambda	libs/core/langchain_core/runnables/base.py	Wrap a plain function as a Runnable
RunnableConfig	libs/core/langchain_core/runnables/config.py	Config object that carries callbacks, tags, metadata
BaseChatModel	libs/core/langchain_core/language_models/chat_models.py	Legacy chat-model contract; partners still subclass it
BaseChatModelV1	libs/core/langchain_core/language_models/chat_model_stream.py	Streaming-first v1 contract for new partners
BaseLLM	libs/core/langchain_core/language_models/llms.py	Completion-style model contract
BaseTool, @tool	libs/core/langchain_core/tools/base.py	Tool definition with input schema and async support
BaseMessage, AIMessage, HumanMessage, ToolMessage	libs/core/langchain_core/messages/	Conversation turn types
ContentBlock and friends	libs/core/langchain_core/messages/content.py	Typed message-content taxonomy (text, image, audio, video, reasoning, …)
BaseCallbackHandler, CallbackManager	libs/core/langchain_core/callbacks/base.py, manager.py	Observability protocol and dispatch
BaseTracer	libs/core/langchain_core/tracers/base.py	Tree-of-runs tracer that feeds LangSmith
BasePromptTemplate, ChatPromptTemplate	libs/core/langchain_core/prompts/base.py, chat.py	Prompt templating
BaseOutputParser	libs/core/langchain_core/output_parsers/base.py	Output parser protocol
VectorStore, BaseRetriever	libs/core/langchain_core/vectorstores/, retrievers.py	RAG primitives

How it works

Almost everything in langchain-core is a Runnable. A Runnable[Input, Output] exposes:

• invoke(input, config=...) -> Output
• ainvoke(input, config=...) -> Awaitable[Output]
• batch(inputs, config=...) -> list[Output] (and abatch)
• stream(input, config=...) -> Iterator[Output] (and astream)
• astream_events(input, config=...) -> AsyncIterator[StreamEvent]

The pipe operator constructs a RunnableSequence:

from langchain_core.prompts import ChatPromptTemplate
from langchain_core.output_parsers import StrOutputParser

prompt = ChatPromptTemplate.from_messages([("user", "{question}")])
chain = prompt | model | StrOutputParser()  # RunnableSequence
result = chain.invoke({"question": "What is LCEL?"})

RunnableConfig flows through every nested call and carries:

• callbacks — a list of BaseCallbackHandler instances
• tags and metadata — for filtering in LangSmith
• run_name — display name for the trace
• max_concurrency — parallelism cap for RunnableParallel
• recursion_limit — for nested invocations
• configurable — overrides for ConfigurableFields declared on Runnables

Integration points

• Partner packages subclass BaseChatModel (or BaseChatModelV1) to plug a provider in.
• langchain (v1) builds langgraph graphs whose nodes wrap Runnables.
• langchain-classic layers chains and agents on top of LCEL.
• LangSmith receives runs from the BaseTracer subclass LangChainTracer.
• langgraph uses RunnableConfig and BaseCallbackHandler so that traces span both libraries.
• langchain-protocol defines the wire protocol langchain-core uses for serialized messages and runs.

Entry points for modification

• To add a new content-block type, edit libs/core/langchain_core/messages/content.py, add a translator in messages/block_translators/, and update messages/__init__.py's __all__. Every partner package will need a corresponding update.
• To add a new Runnable operator, prefer composing existing ones. If you must add a new class, place it in libs/core/langchain_core/runnables/ and re-export it from runnables/__init__.py.
• To add a new output parser, subclass BaseOutputParser (or BaseTransformOutputParser for streaming) in libs/core/langchain_core/output_parsers/ and re-export from __init__.py.

Related

• Primitives — deeper dives into runnables, messages, language models, tools, prompts, output parsers, callbacks
• packages/langchain — the consumer of langchain-core that ships agents and middleware
• packages/langchain-classic — the legacy implementations layered on top of core