LangChain Core Reference

Purpose and Scope

LangChain Core is the Python package that defines the shared interfaces used across the LangChain ecosystem. The package README describes Core as the home for the base abstractions that power LangChain, and the package initializer narrows that description into a source-level contract: core components such as chat models, LLMs, vector stores, retrievers, and the universal invocation protocol are defined here. In practical terms, Core is the layer you depend on when you are building a component that should interoperate with the rest of LangChain rather than a complete application package with provider-specific integrations. Sources: libs/core/README.md, libs/core/langchain_core/init.py

The most important design constraint is separation. Core is intentionally modular, provider-neutral, and lightweight. The initializer explicitly states that no third-party integrations are defined in this package, which keeps the dependency surface small and helps integration authors implement standard contracts without inheriting unrelated provider code. That separation is why a chat model package, retriever implementation, vector store wrapper, or tool package can plug into higher-level LangChain flows through common interfaces. Users should think of Core as the stable vocabulary of LangChain: it names the component shapes, invocation behavior, and composition rules that other packages implement or consume. Sources: libs/core/README.md, libs/core/langchain_core/init.py

Use this page when you need a package-level reference rather than a tutorial. If you are building an agent with the main LangChain package, you usually interact with Core indirectly through prompts, models, messages, tools, retrievers, and runnables. If you are implementing an integration, writing middleware-like infrastructure, testing component compatibility, or debugging import-time warnings, you are closer to Core’s public and internal surfaces. The official documentation examples reinforce this role: runnable objects such as chat models, retrievers, and chains can be passed to evaluation and tracing workflows because they follow the common LangChain invocation protocol defined by Core-level abstractions.

Relevant Source Files

• libs/core/README.md — Package README for installation, positioning, benefits, documentation links, release policy links, contribution guidance, and resource links.
• libs/core/langchain_core/init.py — Package initializer that states the Core contract, exposes the package version, and turns on beta and deprecation warning surfacing at import time.
• libs/core/langchain_core/_api/init.py — Internal API helper module that lazily exposes beta, deprecation, and import-path utilities for LangChain developers.

Installation and Package Positioning

Install the package directly when your project needs the base interfaces without the application-level conveniences of the main LangChain package. The README’s quick install command is intentionally minimal: it installs the Core distribution by itself. That choice is useful for integration packages because their job is often to implement a provider-specific subclass while relying on the common abstractions supplied by Core. It is also useful for libraries that want to accept LangChain-compatible objects without forcing users to install a broad integration set. Sources: libs/core/README.md

uv add langchain-core

The README frames the package around three benefits: modularity, stability, and production usage. Modularity means Core abstractions are independent and not tied to a model provider. Stability means the project commits to versioning and advance communication for breaking changes. The battle-tested claim explains why these interfaces matter operationally: Core components have a large install base and are used in production by many companies. For a developer choosing a dependency boundary, those points imply that Core is the right target when you want the smallest LangChain layer that still gives your library the shared component contracts.

Core also sits beside documentation and platform resources rather than replacing them. The README points readers to the Python API reference for package details, the LangChain Docs for conceptual guides, tutorials, and examples, and Chat LangChain for interactive documentation help. It also points to release and versioning policies, which matters for library authors because Core-level changes can affect many downstream integrations. The README’s contribution section makes clear that Core is part of an open-source project that accepts feature, infrastructure, and documentation contributions, but the package itself remains focused on abstractions rather than end-user workflows. Sources: libs/core/README.md

Core Primitives and Public Contract

At the public package level, the initializer is concise but highly informative. It identifies chat models, LLMs, vector stores, retrievers, and more as Core component interfaces. It also names runnables as the universal invocation protocol and notes that Core defines a syntax for combining components. Those two ideas are central to how LangChain code composes: components are not only isolated classes, they can be invoked through a shared protocol and connected into larger pipelines. Official examples commonly show prompt templates, chat models, and output parsers joined into a chain, and that pattern works because the participating objects satisfy the same compositional expectations. Sources: libs/core/langchain_core/init.py

The phrase universal invocation protocol is important for readers comparing Core to individual integrations. A provider package might know how to call a specific API, format provider-specific payloads, or expose provider-specific options. Core defines the common interface that allows such a provider object to be invoked, streamed, batched, traced, evaluated, or composed in a predictable way by surrounding LangChain systems. That is also why the official LangSmith runnable documentation can treat chat models, retrievers, chains, and other runnable objects uniformly when evaluating a chain. The evaluation and tracing tools are downstream consumers of the contract; Core is where the common contract is declared.

The package also exposes version information through the initializer. It imports a version constant and assigns it to the conventional package attribute. This is a small but important reference point for diagnostics, reproducibility, and support. When debugging an integration issue, knowing the installed Core version is often more useful than only knowing the high-level application package version, because integration compatibility usually depends on the shared abstract interfaces and warning behavior. The initializer additionally calls functions that surface deprecation and beta warnings, so simply importing the package activates the project’s warning policy for consumers. Sources: libs/core/langchain_core/init.py

API Components Reference

The following names are visible from the supplied source and are the key reference points for this package page:

The internal helper module deserves careful handling. Its docstring explicitly says it is only relevant for LangChain developers, not users, and warns that the module and submodules are internal. The implementation still exposes a clear mechanism: a mapping connects public-looking helper names to submodules, the module-level lazy import hook resolves requested attributes through an import utility, and the resolved object is cached into the module globals. This design reduces initial import work and helps avoid circular dependency issues, but it is not a promise that application code can rely on those helpers as stable public API. Sources: libs/core/langchain_core/_api/init.py

For practical use, the distinction is simple. Application code and integration packages should import documented component base classes and utilities from their appropriate Core modules, following the API reference. LangChain maintainers and contributors may need the internal helper module when applying deprecation decorators, beta decorators, warning suppression, or import-path helpers across the codebase. The supplied file lists beta warning types and decorators, deprecation warning types and decorators, warning suppression helpers, a deprecation warning function, and path utilities. The list is useful for understanding how the project manages API lifecycle, but the warning in the module docstring should govern external usage. Sources: libs/core/langchain_core/_api/init.py

System-to-Code Mapping

The README provides the package-level promise: modular, stable abstractions for the ecosystem. The top-level initializer turns that promise into a concise import-time contract by documenting which families of components belong to Core, exporting version information, and activating warning surfacing. The internal API helper supports the same lifecycle story from the maintainer side by centralizing beta and deprecation utilities behind a lazy import layer. Together, these files show a package that is intentionally small at the entry point while still carrying important ecosystem responsibilities. Sources: libs/core/README.md, libs/core/langchain_core/init.py, libs/core/langchain_core/_api/init.py

That mapping helps decide where to look next. If you want to understand why Core exists, start with the README because it explains the package’s value and install path. If you want to understand what the root package promises at import time, read the initializer because it states the abstraction families and integration boundary. If you are contributing to LangChain internals and need to understand warning utilities, read the internal helper module and its warning carefully. Do not treat the internal helper module as a general extension point for applications merely because it is importable.

Operational Guidance and Next Steps

When building a provider or infrastructure package, depend on Core for shared contracts and keep provider-specific code outside it. That mirrors the package initializer’s statement that third-party integrations are not defined here and the README’s emphasis on provider-independent abstractions. When building an application, you can still benefit from Core through higher-level LangChain objects: prompts, models, output parsers, retrievers, and chains can participate in runnable flows, tracing, and evaluation because they align with the shared protocol. This lets teams switch providers or compose new pipelines without rewriting every surrounding system.

For compatibility work, treat Core versioning and warnings as first-class signals. Check the installed version when investigating behavior changes, and do not ignore beta or deprecation warnings surfaced during imports and execution. Those warnings are part of how the project communicates API lifecycle. If you are preparing a contribution, follow the README’s release, versioning, and contribution links before changing abstractions, because small Core-level changes can affect many packages. After this page, read the Runnables API Reference for invocation and composition details, the Language Models API Reference for model contracts, and the Messages and Content API Reference for the data structures exchanged by chat-oriented components.