Fixes#36581
## Problem
`ChatOpenRouter` had no way to set custom HTTP headers on requests to
OpenRouter. Passing `default_headers` to the constructor silently
misfired: `build_extra` treated it as an unrecognized kwarg, emitted a
"transferred to model_kwargs" warning, and dumped the header into the
request body instead of the HTTP layer. This blocked any feature that
needs per-request header injection — for example xAI's `x-grok-conv-id`
for sticky-routing prompt cache hits.
## What changed
- `default_headers` is now a first-class field on `ChatOpenRouter`
(`Mapping[str, str] | None`). Because headers may carry credentials, the
field is excluded from serialization.
- User-supplied headers are merged with the built-in app-attribution
headers (`HTTP-Referer`, `X-Title`, `X-OpenRouter-Categories`). On
collision the user value wins; because HTTP header names are
case-insensitive, the merge drops any built-in whose name
case-insensitively matches a user header before applying, so
`http-referer` replaces `HTTP-Referer` rather than producing a doubled
header.
- Corrected the documented `session_id` length limit from 128 to 256
characters.
Example:
ChatOpenRouter(
model="x-ai/grok-4",
default_headers={"x-grok-conv-id": "session-abc123"},
)
---------
Co-authored-by: Mason Daugherty <github@mdrxy.com>
Closes#38226
---
OpenRouter can emit more than one terminal streaming chunk for a single
response. Before this change, LangChain treated each terminal chunk as
independent final metadata, so repeated string fields could be merged
into corrupted values like `stopstop`.
This updates `ChatOpenRouter` streaming so repeated terminal chunks are
interpreted as parts of the same response ending. Usage metadata is
still captured, later chunks can fill in terminal details that were
missing from earlier chunks, and already-seen terminal fields are not
duplicated.
The regression coverage exercises sync and async generation with
duplicate finish chunks, including the case where usage and additional
terminal metadata arrive on the later chunk.
Closes#37777
---
OpenRouter can return OpenAI Responses reasoning item IDs such as `rs_*`
in assistant reasoning details. Those IDs are not reliably resolvable on
a later OpenRouter turn, so replaying them can make otherwise-valid
multi-turn conversations fail with a provider 404.
This keeps the useful reasoning payload while removing only the
ephemeral Responses item IDs before serializing `reasoning_details` back
into request history. Non-Responses IDs and reasoning text are left
intact.
`ChatOpenRouter` users sending PDF/file content blocks previously relied
on a workaround: the OpenRouter Python SDK's `ChatContentItems`
discriminated union didn't include a `file` tag, so file parts failed
Pydantic validation. To work around it, `langchain-openrouter` wrapped
message dicts with `model_construct()` to bypass SDK validation while
still producing correct JSON.
The SDK fixed this in `openrouter` 0.9.2 by adding `file` to the
`ChatContentItems` union (verified against
OpenRouterTeam/python-sdk#38). This PR raises the dependency floor to
`openrouter>=0.9.2` and removes the now-unnecessary
`_wrap_messages_for_sdk` / `_has_file_content_blocks` helpers, passing
plain message dicts straight to the SDK so file parts go through the
normal validated path.
The old workaround's unit tests are replaced with a test asserting the
SDK now validates a `file` content part natively, guarding against a
regression if the floor is ever lowered. The existing `file`-block
conversion helpers and their tests are unchanged.
_This change was authored with the help of an AI agent._
Made by [Open
SWE](https://openswe.vercel.app/agents/9f95ffe6-2298-1045-9316-935f55d00fa7)
Co-authored-by: open-swe[bot] <open-swe@users.noreply.github.com>
The OpenRouter SDK preserves `cache_control` on tool definitions, and
`ChatOpenRouter` forwards full tool dicts unchanged. This adds a
regression test confirming a top-level `cache_control` on a tool dict
passed to `bind_tools` survives into the SDK request payload.
Made by [Open
SWE](https://openswe.vercel.app/agents/5059cee2-c2de-1ca4-200d-c3fdb8c5814e)
---------
Co-authored-by: open-swe[bot] <open-swe@users.noreply.github.com>
`ChatOpenRouter.bind_tools()` now accepts a `parallel_tool_calls`
argument to disable parallel tool use.
---
Users binding tools to `ChatOpenRouter` previously had to know that
arbitrary kwargs were forwarded to the OpenRouter SDK in order to
disable parallel tool use (e.g.
`model.bind(parallel_tool_calls=False)`). This made the option hard to
discover.
This exposes `parallel_tool_calls` as an explicit keyword-only argument
on `ChatOpenRouter.bind_tools()`, matching the ergonomics of
`langchain-openai`. When set, it is forwarded to the request exactly as
before; when left as `None` it is omitted, preserving existing behavior.
No change to the underlying request payload or SDK floor — purely an
API/discoverability improvement.
Made by [Open
SWE](https://openswe.vercel.app/agents/053b59c8-baf4-84e1-c003-425e349e014d)
Co-authored-by: open-swe[bot] <open-swe@users.noreply.github.com>
Automated refresh of model profile data for all in-monorepo partner
integrations via `langchain-profiles refresh`.
🤖 Generated by the `refresh_model_profiles` workflow.
Co-authored-by: mdrxy <61371264+mdrxy@users.noreply.github.com>
Automated refresh of model profile data for all in-monorepo partner
integrations via `langchain-profiles refresh`.
🤖 Generated by the `refresh_model_profiles` workflow.
Co-authored-by: mdrxy <61371264+mdrxy@users.noreply.github.com>
Automated refresh of model profile data for all in-monorepo partner
integrations via `langchain-profiles refresh`.
🤖 Generated by the `refresh_model_profiles` workflow.
Co-authored-by: mdrxy <61371264+mdrxy@users.noreply.github.com>
Automated refresh of model profile data for all in-monorepo partner
integrations via `langchain-profiles refresh`.
🤖 Generated by the `refresh_model_profiles` workflow.
Co-authored-by: mdrxy <61371264+mdrxy@users.noreply.github.com>
Automated refresh of model profile data for all in-monorepo partner
integrations via `langchain-profiles refresh`.
🤖 Generated by the `refresh_model_profiles` workflow.
Co-authored-by: mdrxy <61371264+mdrxy@users.noreply.github.com>
Automated refresh of model profile data for all in-monorepo partner
integrations via `langchain-profiles refresh`.
🤖 Generated by the `refresh_model_profiles` workflow.
Co-authored-by: mdrxy <61371264+mdrxy@users.noreply.github.com>
Automated refresh of model profile data for all in-monorepo partner
integrations via `langchain-profiles refresh`.
🤖 Generated by the `refresh_model_profiles` workflow.
Co-authored-by: mdrxy <61371264+mdrxy@users.noreply.github.com>
README installation examples now use `uv add` consistently, matching the
repo's `uv`-based Python workflow. The top-level README also gets a
cleaner quickstart and resource section with current links for docs,
community, learning, and contribution guidance.
## Changes
- Replaced `pip install` snippets with `uv add` across package quick
install docs, including the Hugging Face extras and
`sentence-transformers` upgrade examples.
- Updated the top-level quickstart to show only `uv add langchain` and
refreshed the example model to `openai:gpt-5.5`.
- Pointed the LangGraph orchestration link at the LangGraph GitHub
repository.
- Consolidated top-level documentation and additional-resource links
under a single `Resources` section covering docs, ecosystem overview,
API reference, discussions, Academy, contributing, and the Code of
Conduct.
- Added LangChain Academy and Code of Conduct links to package README
resource sections.
Bumps `langchain-core` to `1.4.7` for the next patch release and updates
downstream minimum `langchain-core` requirements so package locks
resolve against the new core version.
This also refreshes the runnable snapshots that embed `lc_versions`
metadata so the version consistency check continues to validate
checked-in artifacts.
Validated with `python libs/core/scripts/check_version.py`, `uv lock
--check` across package lockfiles, and the core runnable tests that own
the updated snapshots with local LangSmith tracing env disabled.
Package-version trace metadata now uses the LangChain-owned
`metadata["lc_versions"]` convention instead of the user-owned
`metadata["versions"]` key. Metadata merging is narrowed so only
`lc_versions` accumulates nested package-version entries, while generic
nested metadata keeps normal last-writer-wins behavior.
## Changes
- Renamed `BaseLanguageModel._add_version()` trace metadata from
`versions` to `lc_versions`, including docstrings and the non-dict
replacement warning.
- Scoped `_merge_metadata_dicts()` nested-map accumulation to only
`lc_versions`; duplicate package entries remain last-writer-wins and
`lc_versions` mappings are copied defensively.
- Preserved user-owned `metadata["versions"]` semantics by keeping it
out of package-version tracking and generic nested metadata merging.
- Updated runnable snapshots and partner package metadata assertions
across Anthropic, DeepSeek, Fireworks, Groq, Hugging Face, MistralAI,
Ollama, OpenAI, OpenRouter, Perplexity, and xAI to expect `lc_versions`.
## Testing
- Added/adjusted core tests for `lc_versions` accumulation, duplicate
package overwrite behavior, non-dict `lc_versions` replacement,
defensive copying, and `metadata["versions"]` last-writer-wins behavior.
- Ran focused core and partner metadata tests plus Ruff checks for
changed areas.
Automated refresh of model profile data for all in-monorepo partner
integrations via `langchain-profiles refresh`.
🤖 Generated by the `refresh_model_profiles` workflow.
Co-authored-by: mdrxy <61371264+mdrxy@users.noreply.github.com>
Standardizes inline code markup in Python docstrings and comments by
replacing Sphinx-style double backticks with single-backtick Markdown.
The cleanup keeps existing code fences intact while aligning inline
references with the repo's docstring convention.
## Changes
- Converted inline code references in core prompt-loading docs and
LangSmith tracer comments, including `..`, `allow_dangerous_paths`, and
inheritable metadata keys.
- Normalized agent-related docstrings and comments around
`wrap_model_call`, `ExtendedModelResponse`, `Command`,
`create_structured_chat_agent`, and `DockerExecutionPolicy`.
- Updated partner package docstrings for inline references such as
`json_schema`, `ToolCall`, `apply_patch_call_output`, OpenRouter content
block keys, and Perplexity tool-call serialization.
- Cleaned test and helper docstrings that referenced command separators,
fake `resource` modules, stream event names, and xdist rate-limit
environment variables.
Following on the heels of #35293
TODO:
- Packages outside of this repo (e.g. LiteLLM, Nvidia, Google, AWS)
---
## Summary
Surface partner package versions in `metadata.versions` on LangSmith
traces. Mirrors the JS SDK's `_addVersion()` pattern
([langchainjs#10106](https://github.com/langchain-ai/langchainjs/pull/10106)).
Each model constructor records its package version via `_add_version()`
on `BaseLanguageModel`. The version dict accumulates through the class
hierarchy — `langchain-core` is added in
`BaseLanguageModel.model_post_init`, `langchain-openai` in
`BaseChatOpenAI._set_openai_chat_version`, and each leaf partner in its
uniquely-named `model_validator`. Traces end up with:
```json
{
"metadata": {
"versions": {
"langchain-core": "1.4.5",
"langchain-openai": "1.3.0",
"langchain-xai": "1.2.2"
}
}
}
```
### Changes
- `BaseLanguageModel._add_version(pkg, version)` — appends to
`self.metadata["versions"]`; accepts any `Mapping` type; emits a warning
if a non-mapping value is found and replaced
- `BaseLanguageModel.model_post_init` — adds `langchain-core` version;
calls `super()` for MRO safety
- `_merge_metadata_dicts` — one-level-deep (non-recursive) merge for
nested dict metadata keys
- `CallbackManager.add_metadata` — uses `_merge_metadata_dicts` instead
of flat `dict.update()` so nested metadata dicts (like `versions`)
coexist rather than clobber
- `merge_configs` — uses `_merge_metadata_dicts` for config merging
**Partners:**
- Each now calls `self._add_version("langchain-<pkg>", __version__)`
### Design decisions
- **Constructor-based, not `_get_ls_params`-based** — versions flow
through `self.metadata` (local metadata on traces), not through
`LangSmithParams`. This matches JS and makes child-class version
inheritance automatic (no merge/clobber issues).
- **`versions` is local (non-inheritable) metadata** — `self.metadata`
is passed to `CallbackManager.configure` as `local_metadata`
(`add_metadata(..., inherit=False)`), so `versions` is attached **once
per chat-model run** and is **not** propagated to child runs or
duplicated onto every streaming chunk. This is intentionally the
opposite of the inheritable-per-chunk metadata that #36588 was reducing
for performance — `versions` does not regress that path.
- **`add_metadata` deep-merge is a correctness fix, not just for
versions** — previously `add_metadata`/`merge_configs` did a flat
top-level `dict.update`/spread, so any nested metadata dict baked into a
config (e.g. via `.with_config({"metadata": {...}})`) would be wholly
replaced when a caller also passed `metadata`. `_merge_metadata_dicts`
merges one level deep so user-provided `config.metadata.versions` and
model-set `versions` coexist instead of clobbering. The merge runs once
per `configure` (not per chunk), so it is off the streaming hot path.
- **One level deep only** — `_merge_metadata_dicts` is deliberately
*not* a recursive deep merge; values nested more than one level are
last-writer-wins. This covers the `versions` case without the
ambiguity/cost of arbitrary-depth merging.
- **Warn on non-dict `metadata["versions"]`** — if a user sets
`metadata={"versions": "some-string"}`, `_add_version` emits a warning
and replaces the value with the version dict rather than silently
discarding user data or crashing. This is a soft breaking change for
anyone who previously stored non-dict values at this key.
### Follow-ups (tracked separately, out of scope here)
- JS `mergeConfigs` still flat-spreads nested metadata, so
`metadata.versions` can still clobber on the JS side until an equivalent
deep-merge lands.
---
Made by [Open SWE](https://openswe.vercel.app)
---------
Co-authored-by: open-swe[bot] <open-swe@users.noreply.github.com>
Originally a narrow bump of mypy to `1.20` in four packages. Expanded to
get the whole monorepo onto a single, current mypy and a consistent
type-check configuration, so contributors no longer hit different mypy
versions and divergent behavior depending on which package they touch.
### What changed
- **Unified the mypy pin to `>=2.1.0,<2.2.0`** in every mypy-using
package (6 libs + 14 partners), replacing the previously scattered pins
(`1.10`/`1.17`/`1.18`/`1.19`/`1.20`, with assorted upper bounds).
- **Unified the `[tool.mypy]` base per tier:**
- libs: `plugins = ["pydantic.mypy"]`, `strict = true`,
`enable_error_code = "deprecated"`, `warn_unreachable = true`
- partners: `disallow_untyped_defs = true`
- Normalized style (`disallow_untyped_defs = "True"` string → bool,
quote/key consistency).
- **Fixed the 20 real errors** mypy 2.1 surfaces: `redundant-cast` from
improved narrowing (`core`, `langchain-classic`), a `var-annotated` for
`_LOGGED`, a return-type widening in `langchain-groq`'s
`_convert_from_v1_to_groq` (it can legitimately return a bare `str`),
and stale `type-arg`/`unused-ignore` in `langchain-model-profiles`
tests.
### Deliberate non-uniformity (documented inline in the relevant
`pyproject.toml`s)
Going fully byte-identical would surface ~196 additional errors that are
*not* real bugs, so two settings are kept package-appropriate:
- **`warn_unreachable`** is enabled on every strict lib **except
`core`**, where it false-flags intentional defensive code — including
the SSRF / IP-policy guards in `_security/` — as unreachable.
- **`pydantic.mypy` plugin** is used only on `anthropic` and
`perplexity` (their code is authored against it and reports ~99/~132
errors without it). It is *not* added to the other partners, where it
only flags the public alias constructor API (e.g. `ChatGroq(model=...)`)
in tests rather than finding bugs.
- **`ollama`** is left on its `ty` type checker; it does not use mypy.
---------
Co-authored-by: Mason Daugherty <github@mdrxy.com>
As a LangChain user streaming a tool-calling model, I expect each
streamed chunk to expose structured `tool_call_chunk` content blocks so
I can render or process tool calls live, instead of waiting for the
final aggregated message.
This adds `tool_call_streaming` to `ModelProfile` and uses it in the
standard chat-model tool-calling tests. When a model profile opts in,
`test_tool_calling` and `test_tool_calling_async` now validate that at
least one streamed chunk includes a `tool_call_chunk` block via
`content_blocks`, while preserving the existing final-message
validation.
This keeps the contract profile-gated so providers can opt in once their
streaming chunk shape is verified. This PR opts in the providers
verified by smoke testing with straightforward profile coverage: OpenAI,
Anthropic, Fireworks, HuggingFace, OpenRouter, DeepSeek, and xAI. The
generated profile artifacts are refreshed so runtime profiles expose the
new capability flag.
Perplexity Responses also passed the smoke test, but its current profile
data is for the `sonar` family while the Responses smoke path used a
routed model string. That profile strategy is left as follow-up.
MistralAI currently streams `.tool_call_chunks`, but its content-block
translator exposes a complete `tool_call` block instead of
`tool_call_chunk`, so it also stays out of this flag until that
integration is fixed.
Provider-native structured output fallback detection now uses bounded
model-name patterns instead of broad substring checks, reducing false
positives for unrelated model IDs. The model examples and test fixtures
across OpenAI/OpenRouter-facing code were refreshed around current
OpenAI model families while preserving shipped defaults.
## Changes
- Tightened `FALLBACK_MODELS_WITH_STRUCTURED_OUTPUT` from loose string
fragments to regex patterns, with `_supports_provider_strategy` matching
full model-name segments instead of arbitrary substrings.
- Expanded structured-output fallback coverage for newer OpenAI,
Anthropic, and xAI/Grok model families, including `gpt-5.x`, newer
Claude 4/5-style names, and `grok-build`.
- Reused `_attempt_infer_model_provider` in provider tool search routing
so `_provider_from_model_name` follows the same provider inference
behavior as `init_chat_model`.
- Suppressed irrelevant provider-inference deprecation warnings during
provider tool search registry lookup.
- Refreshed OpenAI, Azure OpenAI, OpenRouter, core metadata, and example
model references from older fixtures like `gpt-4`, `gpt-4o`, `o1`, and
`o4-mini` to current test/profile models such as `gpt-5.5`,
`gpt-5-nano`, and `gpt-4.1-mini`.
- Removed outdated OpenAI test assumptions around legacy `o1` behavior
and narrowed legacy structured-output checks to explicitly legacy model
names.
Partner unit tests now reflect the warning behavior emitted by updated
`langchain-core` serialization and model initialization paths.
Warning-strict runs can stay focused on the behavior under test rather
than expected framework warnings.
Automated refresh of model profile data for all in-monorepo partner
integrations via `langchain-profiles refresh`.
🤖 Generated by the `refresh_model_profiles` workflow.
Co-authored-by: mdrxy <61371264+mdrxy@users.noreply.github.com>
Automated refresh of model profile data for all in-monorepo partner
integrations via `langchain-profiles refresh`.
🤖 Generated by the `refresh_model_profiles` workflow.
Co-authored-by: mdrxy <61371264+mdrxy@users.noreply.github.com>
Automated refresh of model profile data for all in-monorepo partner
integrations via `langchain-profiles refresh`.
🤖 Generated by the `refresh_model_profiles` workflow.
Co-authored-by: mdrxy <61371264+mdrxy@users.noreply.github.com>
Automated refresh of model profile data for all in-monorepo partner
integrations via `langchain-profiles refresh`.
🤖 Generated by the `refresh_model_profiles` workflow.
Co-authored-by: mdrxy <61371264+mdrxy@users.noreply.github.com>
Automated refresh of model profile data for all in-monorepo partner
integrations via `langchain-profiles refresh`.
🤖 Generated by the `refresh_model_profiles` workflow.
Co-authored-by: mdrxy <61371264+mdrxy@users.noreply.github.com>
Test targets run with `-n auto`, which makes `pytest-benchmark` (present
via `langchain-tests`) auto-disable itself and emit a
`PytestBenchmarkWarning` once per xdist worker. Passing
`--benchmark-disable` turns the plugin off explicitly so the warning
never fires, matching what `core` and `langchain_v1` already do.
## Changes
- Add `--benchmark-disable` to the `-n auto` test targets across
`langchain` (unit) and 14 partner packages' integration targets:
`anthropic`, `chroma`, `deepseek`, `exa`, `fireworks`, `groq`,
`huggingface`, `mistralai`, `nomic`, `ollama`, `openai`, `openrouter`,
`qdrant`, `xai`.
- Deliberately excluded `text-splitters` and `model-profiles`: their
`test` group doesn't install `pytest-benchmark`, so the flag would fail
with `unrecognized arguments`. Verified by importing the plugin under
each package's actual dependency group before editing.
Automated refresh of model profile data for all in-monorepo partner
integrations via `langchain-profiles refresh`.
🤖 Generated by the `refresh_model_profiles` workflow.
Co-authored-by: mdrxy <61371264+mdrxy@users.noreply.github.com>
Automated refresh of model profile data for all in-monorepo partner
integrations via `langchain-profiles refresh`.
🤖 Generated by the `refresh_model_profiles` workflow.
Co-authored-by: mdrxy <61371264+mdrxy@users.noreply.github.com>
Automated refresh of model profile data for all in-monorepo partner
integrations via `langchain-profiles refresh`.
🤖 Generated by the `refresh_model_profiles` workflow.
Co-authored-by: mdrxy <61371264+mdrxy@users.noreply.github.com>
Automated refresh of model profile data for all in-monorepo partner
integrations via `langchain-profiles refresh`.
🤖 Generated by the `refresh_model_profiles` workflow.
Co-authored-by: mdrxy <61371264+mdrxy@users.noreply.github.com>
Automated refresh of model profile data for all in-monorepo partner
integrations via `langchain-profiles refresh`.
🤖 Generated by the `refresh_model_profiles` workflow.
Co-authored-by: mdrxy <61371264+mdrxy@users.noreply.github.com>
Automated refresh of model profile data for all in-monorepo partner
integrations via `langchain-profiles refresh`.
🤖 Generated by the `refresh_model_profiles` workflow.
Co-authored-by: mdrxy <61371264+mdrxy@users.noreply.github.com>
Automated refresh of model profile data for all in-monorepo partner
integrations via `langchain-profiles refresh`.
🤖 Generated by the `refresh_model_profiles` workflow.
Co-authored-by: mdrxy <61371264+mdrxy@users.noreply.github.com>
