Language Models API Reference
Purpose and Scope
LangChain language model APIs are designed to let application code talk to many providers through one set of runtime contracts. A language model in this reference is any runnable object that accepts prompt-like input and returns either text or a message object. The shared base layer defines that boundary, while chat-model and LLM modules specialize it for newer message-oriented models and older text-completion style models. This page focuses on the public contracts that provider integrations, agent builders, streaming clients, and tests should rely on instead of provider-specific implementation details.
Sources: libs/core/langchain_core/language_models/base.py, libs/core/langchain_core/language_models/chat_models.py, libs/core/langchain_core/language_models/llms.py
Official LangChain docs describe the same developer goal at the product level: install a provider package, choose a model identifier, and keep application logic stable while swapping OpenAI, Anthropic, Google, or another provider. In Python core, that promise is represented by base type aliases, runnable inheritance, callback and tracing metadata, and stream protocols. Provider packages can expose special capabilities, but the common surface is still the one application code should compose with prompts, tools, agents, retrievers, and evaluators.
Relevant Source Files
- libs/core/langchain_core/language_models/base.py - Defines shared language-model input and output aliases, LangSmith tracing parameters, tokenizer utilities, and the base model contract used by chat models and LLMs.
- libs/core/langchain_core/language_models/chat_models.py - Hosts the chat-model public API surface, including the message-oriented model abstraction used by modern provider integrations.
- libs/core/langchain_core/language_models/llms.py - Implements the traditional text LLM base interface, retry helper, callback integration, cache plumbing, and runnable configuration handling for completion-style models.
- libs/core/langchain_core/language_models/chat_model_stream.py - Defines per-message streaming objects for versioned chat model event streams, including synchronous and asynchronous projection APIs.
- libs/core/langchain_core/language_models/model_profile.py - Defines the model capability profile type exposed by chat models through a profile field.
Core Contracts
The most important shared types live in the base module. A model input can be a prompt value, a plain string, or a sequence of message-like representations. A model output can be a base message or a string. The type alias for a model-like object is a runnable from that input shape to that output shape, which means language models participate in the same composition system as prompts, parsers, retrievers, and other runnables. Test doubles and fake models should preserve that input-output behavior so they remain interchangeable with real provider-backed instances in chains and agents.
Sources: libs/core/langchain_core/language_models/base.py
The base module also defines LangSmith tracing metadata through a typed dictionary. These fields capture provider, model name, model type, temperature, maximum tokens, stop words, and integration name. The purpose is not to change model behavior; it is to make model calls understandable in traces and observability tooling. Implementations that know their provider or invocation settings can attach this metadata consistently, giving downstream debugging and evaluation tools a normalized view even when the underlying API payloads differ across providers.
Sources: libs/core/langchain_core/language_models/base.py
Token counting is another shared concern. The base module includes a cached tokenizer factory and a fallback token ID method based on a GPT-2 tokenizer. That fallback is useful as a generic counting mechanism, but the code warns that counts may be inaccurate for non-GPT-2 models and recommends model-specific methods when available. Application developers should treat the fallback as a convenience rather than a provider guarantee, especially when enforcing context-window budgets for multimodal, reasoning, or provider-specific tokenization schemes.
Sources: libs/core/langchain_core/language_models/base.py
Chat Models, LLMs, and Provider Interoperability
Chat models are the preferred abstraction for modern provider integrations because they operate over messages and can support capabilities such as tool calling, structured output, and richer streaming. The requested chat model module is the source location for that public API surface, while the shared base module supplies the common runnable and tracing contracts. The official provider guidance uses provider-prefixed model identifiers to explain how developers choose integrations, but the repository-level contract is more general: once initialized, a chat model should behave like the standard language model runnable that accepts prompt or message input.
Sources: libs/core/langchain_core/language_models/chat_models.py, libs/core/langchain_core/language_models/base.py
The LLM module covers traditional completion models. Its own module docstring frames these as older-style models, while noting that newer models are generally chat models. Even so, the LLM interface remains important for integrations and legacy chains that expect string-oriented completions. The module imports prompt values, message conversion utilities, output generation types, callback managers, runnable configuration helpers, cache access, and serialization support. That combination shows that completion models still participate in tracing, batching, configuration, caching, retry, and result normalization rather than existing as isolated provider wrappers.
Sources: libs/core/langchain_core/language_models/llms.py
The retry helper in the LLM module is a small but important implementation contract. It creates a Tenacity retry decorator from provider-specific error types, applies exponential waiting, and notifies callback managers when retries occur. It handles both synchronous and asynchronous callback managers, including the case where an event loop is already running. Provider implementations can use this pattern to expose resilient network behavior while preserving observability signals, so callers can see retries in callbacks instead of experiencing silent delays or unexplained final failures.
Sources: libs/core/langchain_core/language_models/llms.py
Streaming API
The streaming module documents a versioned event-stream surface for chat models. A synchronous stream object is returned by event streaming, and an asynchronous counterpart is returned by the async event streaming path. Both expose typed projections for text, reasoning, tool calls, usage, and final output. The projections accumulate protocol events as they arrive and can be iterated for deltas or drained for final values. This lets user interfaces, agent runtimes, and observability tools consume the same underlying stream at different levels of detail.
Sources: libs/core/langchain_core/language_models/chat_model_stream.py
A notable design choice is replay-buffer semantics for raw protocol events. Direct iteration over a stream object exposes the event feed, while multiple independent consumers can still read from the same stream. The helper functions in the module merge tool-call chunks, merge block deltas, tolerate older content-block field names, convert legacy block shapes into explicit deltas, and sweep accumulated chunk stores into finalized content. These details matter when rendering tool-call arguments incrementally or preserving compatibility across evolving streaming protocols.
Sources: libs/core/langchain_core/language_models/chat_model_stream.py
Model Profiles
A model profile is a typed capability description exposed through a chat model profile field. The profile type is explicitly marked as a beta surface and is a total-false typed dictionary, so every capability field must be treated as optional. The schema covers model metadata, input constraints, output constraints, and tool-calling capabilities. Examples include human-readable name, lifecycle status, release date, context window, supported input modalities, maximum output tokens, reasoning output, tool calling, tool choice, and whether structured tool-call chunks are returned during streaming.
Sources: libs/core/langchain_core/language_models/model_profile.py
Model profiles are best read as capability hints for routing, validation, UI affordances, and integration maintenance rather than as a substitute for invoking a model. Because extra fields are allowed and any field may be absent, robust code should use guarded access and conservative fallbacks. For example, an agent builder can prefer models with tool calling, a multimodal UI can check whether image inputs are supported, and a streaming interface can inspect whether tool-call streaming is expected before assuming incremental tool arguments will be structured.
Sources: libs/core/langchain_core/language_models/model_profile.py
Compact Reference
| API surface | Source module | Developer use |
|---|---|---|
| LanguageModelInput | libs/core/langchain_core/language_models/base.py | Accepted prompt, string, or message-like input shape for model runnables. |
| LanguageModelOutput | libs/core/langchain_core/language_models/base.py | Normalized output boundary of message or string. |
| LanguageModelLike | libs/core/langchain_core/language_models/base.py | Runnable contract for code that accepts any compatible model, including fakes. |
| LangSmithParams | libs/core/langchain_core/language_models/base.py | Optional tracing metadata for provider, model, model type, and invocation settings. |
| create_base_retry_decorator | libs/core/langchain_core/language_models/llms.py | Shared retry construction for provider error types with callback notification. |
| ChatModelStream and AsyncChatModelStream | libs/core/langchain_core/language_models/chat_model_stream.py | Event-stream wrappers with accumulated text, reasoning, tool call, usage, and output projections. |
| ModelProfile | libs/core/langchain_core/language_models/model_profile.py | Optional capability metadata for chat models, including modalities, token limits, and tool support. |
Implementation Guidance and Next Steps
When authoring a provider integration, start from the relevant chat model or LLM base class and keep the shared runnable contract intact. Add provider-specific configuration where needed, but normalize inputs, outputs, callbacks, retries, tracing fields, streaming projections, and profile metadata so higher-level LangChain components do not need provider branches. When writing tests, prefer fake models that exercise the same input and output types, including message conversion and streaming behavior when those features are part of the integration contract.
Sources: libs/core/langchain_core/language_models/base.py, libs/core/langchain_core/language_models/chat_models.py, libs/core/langchain_core/language_models/llms.py, libs/core/langchain_core/language_models/chat_model_stream.py, libs/core/langchain_core/language_models/model_profile.py
For related reading, use the broader language-model concepts page to understand how chat models fit into application design, the messages API reference for content and tool-message structures, the runnables API reference for composition semantics, and the callbacks and observability page for tracing behavior. If your immediate task is model selection, inspect the profile fields first, then validate behavior with real calls or evaluations because profile data is optional, evolving, and intentionally capability-oriented rather than a formal service-level guarantee.