langchain-openai

The OpenAI integration. Source: libs/partners/openai/langchain_openai/. PyPI: langchain-openai. Current version: 1.2.1. ~21 source modules, ~11,600 lines.

What it ships

Symbol	Purpose	File
ChatOpenAI	Chat-completions and Responses API client	libs/partners/openai/langchain_openai/chat_models/base.py
AzureChatOpenAI	Azure OpenAI deployment of ChatOpenAI	libs/partners/openai/langchain_openai/chat_models/azure.py
OpenAI, AzureOpenAI	Legacy completions endpoint (text-davinci-003 era)	libs/partners/openai/langchain_openai/llms/
OpenAIEmbeddings, AzureOpenAIEmbeddings	Embedding models	libs/partners/openai/langchain_openai/embeddings/
custom_tool	Decorator for OpenAI's function-calling tools with strict=True	libs/partners/openai/langchain_openai/tools/
StreamChunkTimeoutError	Raised when streaming stalls	libs/partners/openai/langchain_openai/chat_models/_client_utils.py

Directory layout

libs/partners/openai/langchain_openai/
├── __init__.py
├── chat_models/
│   ├── __init__.py
│   ├── _client_utils.py     # Retry, timeout, streaming buffer logic
│   ├── _compat.py           # Bridges old/new content-block shapes
│   ├── azure.py             # AzureChatOpenAI (~45 KB)
│   └── base.py              # ChatOpenAI itself (~197 KB)
├── data/                    # Model profiles (JSON + augmentations.toml)
├── embeddings/
├── llms/
└── tools/

base.py at ~5,000+ lines is by far the largest file in the partners directory. It handles:

• Both Chat Completions and the newer Responses API.
• Tool calling (tools=..., tool_choice=..., parallel tool calls, strict=True mode).
• Structured output via JSON mode and via function calling with a Pydantic schema.
• Vision and audio input via OpenAI's content-block format, translated to LangChain's ImageContentBlock / AudioContentBlock.
• Streaming with usage metadata accumulation (the stream_usage=True path).
• Reasoning content from o-series models, mapped to ReasoningContentBlock.
• Server-side tool calls (code interpreter, file search, web search) mapped to ServerToolCall / ServerToolResult.
• langsmith tracing hooks via the inherited callback machinery.

How ChatOpenAI is wired

from langchain_openai import ChatOpenAI

model = ChatOpenAI(
    model="gpt-5",
    temperature=0,
    max_tokens=1000,
    timeout=30,
    max_retries=2,
)
result = model.invoke([{"role": "user", "content": "Hello"}])
# result is an AIMessage with .content as list[ContentBlock] when modern features are used

Internally, ChatOpenAI:

1. Inherits from BaseChatModel (legacy contract; the v1 streaming-first contract is exposed through the _compat.py bridge).
2. Holds an openai.OpenAI client (sync) and openai.AsyncOpenAI client (async) — both httpx-based.
3. Translates LangChain messages and content blocks to OpenAI's input shape via helpers in _compat.py and _client_utils.py.
4. Calls the SDK with retry policy from tenacity.
5. Translates the OpenAI response back into an AIMessage with the appropriate content blocks.

Model profiles

libs/partners/openai/langchain_openai/data/ carries one JSON file per model family plus profile_augmentations.toml. Capability flags exposed via model.profile:

• context_window, max_output_tokens
• supports_tool_choice, supports_parallel_tool_calls
• supports_vision, supports_audio_input, supports_audio_output
• supports_strict_mode (function calling with JSON schema validation)
• supports_responses_api
• input_token_price, output_token_price

These are refreshed by langchain-profiles refresh --provider openai --data-dir libs/partners/openai/langchain_openai/data (see packages/model-profiles).

Azure variant

AzureChatOpenAI inherits from ChatOpenAI and overrides client construction to use Azure deployment names, API versions, and AAD token authentication. Most of azure.py is parameter shimming and inferring profile data from a deployment name (the _compat.py _infer_profile_from_model_name function).

Tests

• Unit tests (tests/unit_tests/) — no network. They mock the httpx transport and exercise content-block translation, tool call shaping, retry behavior, error classification.
• Integration tests (tests/integration_tests/) — hit the real OpenAI API. The tests/integration_tests/chat_models/test_standard.py file inherits from langchain_tests.integration_tests.ChatModelIntegrationTests and declares capability flags so the full standard suite runs.
• Cassette tests — VCR cassettes under tests/cassettes/ for deterministic replay.

Integration points

• Imports openai>=1.x, httpx, tiktoken.
• Inherits from langchain-core base classes.
• Tested via langchain-tests standard test suite.
• Used by the _BUILTIN_PROVIDERS registry in libs/langchain_v1/langchain/chat_models/base.py under the openai and azure_openai keys.

Entry points for modification

• For a new OpenAI feature (new content type, new tool kind), edit chat_models/base.py plus the translators in _compat.py.
• For an Azure-specific change, edit chat_models/azure.py.
• For streaming behavior, look at _client_utils.py — retry, timeout, and chunk buffering live there.
• For new model support, add to data/profile_augmentations.toml and run langchain-profiles refresh --provider openai.

Related

• partners/anthropic — the second-largest partner, similar shape
• partners/other-providers — the rest of the partner zoo
• primitives/messages — the content-block taxonomy translated here
• packages/standard-tests — the test suite this package inherits from