The agent engineering platform.
Python agentsaiai-agentsanthropicchatgptdeepagentsenterpriseframeworkgeminigenerative-ailangchainlanggraphllmmultiagentopen-sourceopenaipydanticpythonragtypescript
feat(openrouter): add `app_categories` field for marketplace attribution (#36205)
Mason Daugherty2a16ee9b7301
diff --git a/libs/partners/openrouter/langchain_openrouter/chat_models.py b/libs/partners/openrouter/langchain_openrouter/chat_models.pyindex 357cc70f27..7438bd9815 100644--- a/libs/partners/openrouter/langchain_openrouter/chat_models.py+++ b/libs/partners/openrouter/langchain_openrouter/chat_models.py@@ -118,6 +118,7 @@ class ChatOpenRouter(BaseChatModel):| `timeout` | `int | None` | Timeout in milliseconds. || `app_url` | `str | None` | App URL for attribution. || `app_title` | `str | None` | App title for attribution. |+ | `app_categories` | `list[str] | None` | Marketplace attribution categories. || `max_retries` | `int` | Max retries (default `2`). Set to `0` to disable. |??? info "Instantiate"@@ -174,12 +175,27 @@ class ChatOpenRouter(BaseChatModel):Maps to `X-Title` header.- Defaults to `'LangChain'`. Set this to your app's URL to get attribution for- API usage in the OpenRouter dashboard.+ Defaults to `'LangChain'`. Set this to your app's name to get attribution+ for API usage in the OpenRouter dashboard.See https://openrouter.ai/docs/app-attribution for details."""+ app_categories: list[str] | None = Field(+ default=None,+ )+ """Marketplace categories for OpenRouter attribution.++ Maps to `X-OpenRouter-Categories` header. Pass a list of lowercase,+ hyphen-separated category strings (max 30 characters each),+ e.g. `['cli-agent', 'programming-app']`.++ Only recognized categories are accepted (unrecognized values are silently+ dropped by OpenRouter).++ See https://openrouter.ai/docs/app-attribution for recognized categories.+ """+request_timeout: int | None = Field(default=None, alias="timeout")"""Timeout for requests in milliseconds. Maps to SDK `timeout_ms`."""@@ -307,6 +323,59 @@ class ChatOpenRouter(BaseChatModel):values["model_kwargs"] = extrareturn values+ def _build_client(self) -> Any:+ """Build and return an `openrouter.OpenRouter` SDK client.++ Returns:+ An `openrouter.OpenRouter` SDK client instance.+ """+ import openrouter # noqa: PLC0415+ from openrouter.utils import ( # noqa: PLC0415+ BackoffStrategy,+ RetryConfig,+ )++ client_kwargs: dict[str, Any] = {+ "api_key": self.openrouter_api_key.get_secret_value(), # type: ignore[union-attr]+ }+ if self.openrouter_api_base:+ client_kwargs["server_url"] = self.openrouter_api_base+ if self.app_url:+ client_kwargs["http_referer"] = self.app_url+ if self.app_title:+ client_kwargs["x_title"] = self.app_title+ if self.app_categories:+ # The SDK lacks a native constructor param for X-OpenRouter-Categories,+ # so inject the header via custom httpx clients. The SDK sets its own+ # headers (Authorization, HTTP-Referer, X-Title) per-request, and httpx+ # merges client-default headers with per-request headers, so nothing is+ # lost.+ import httpx # noqa: PLC0415++ extra_headers = {+ "X-OpenRouter-Categories": ",".join(self.app_categories),+ }+ client_kwargs["client"] = httpx.Client(+ headers=extra_headers, follow_redirects=True+ )+ client_kwargs["async_client"] = httpx.AsyncClient(+ headers=extra_headers, follow_redirects=True+ )+ if self.request_timeout is not None:+ client_kwargs["timeout_ms"] = self.request_timeout+ if self.max_retries > 0:+ client_kwargs["retry_config"] = RetryConfig(+ strategy="backoff",+ backoff=BackoffStrategy(+ initial_interval=500,+ max_interval=60000,+ exponent=1.5,+ max_elapsed_time=self.max_retries * 150_000,+ ),+ retry_connection_errors=True,+ )+ return openrouter.OpenRouter(**client_kwargs)+@model_validator(mode="after")def validate_environment(self) -> Self:"""Validate configuration and build the SDK client."""@@ -319,41 +388,14 @@ class ChatOpenRouter(BaseChatModel):if not self.client:try:- import openrouter # noqa: PLC0415- from openrouter.utils import ( # noqa: PLC0415- BackoffStrategy,- RetryConfig,- )+ import openrouter # noqa: PLC0415, F401except ImportError as e:msg = ("Could not import the `openrouter` Python SDK. ""Please install it with: pip install openrouter")raise ImportError(msg) from e-- client_kwargs: dict[str, Any] = {- "api_key": self.openrouter_api_key.get_secret_value(),- }- if self.openrouter_api_base:- client_kwargs["server_url"] = self.openrouter_api_base- if self.app_url:- client_kwargs["http_referer"] = self.app_url- if self.app_title:- client_kwargs["x_title"] = self.app_title- if self.request_timeout is not None:- client_kwargs["timeout_ms"] = self.request_timeout- if self.max_retries > 0:- client_kwargs["retry_config"] = RetryConfig(- strategy="backoff",- backoff=BackoffStrategy(- initial_interval=500,- max_interval=60000,- exponent=1.5,- max_elapsed_time=self.max_retries * 150_000,- ),- retry_connection_errors=True,- )- self.client = openrouter.OpenRouter(**client_kwargs)+ self.client = self._build_client()return selfdef _resolve_model_profile(self) -> ModelProfile | None:diff --git a/libs/partners/openrouter/tests/unit_tests/test_chat_models.py b/libs/partners/openrouter/tests/unit_tests/test_chat_models.pyindex fc352da330..58bd605e56 100644--- a/libs/partners/openrouter/tests/unit_tests/test_chat_models.py+++ b/libs/partners/openrouter/tests/unit_tests/test_chat_models.py@@ -337,6 +337,72 @@ class TestChatOpenRouterInstantiation:assert call_kwargs["http_referer"] == "https://my-custom-app.com"assert call_kwargs["x_title"] == "My Custom App"+ def test_app_categories_passed_to_client(self) -> None:+ """Test that app_categories injects custom httpx clients with header."""+ with patch("openrouter.OpenRouter") as mock_cls:+ mock_cls.return_value = MagicMock()+ ChatOpenRouter(+ model=MODEL_NAME,+ api_key=SecretStr("test-key"),+ app_categories=["cli-agent", "programming-app"],+ )+ call_kwargs = mock_cls.call_args[1]+ # Custom httpx clients should be created+ assert "client" in call_kwargs+ assert "async_client" in call_kwargs+ # Verify the header value is comma-joined+ sync_headers = call_kwargs["client"].headers+ assert sync_headers["X-OpenRouter-Categories"] == (+ "cli-agent,programming-app"+ )+ async_headers = call_kwargs["async_client"].headers+ assert async_headers["X-OpenRouter-Categories"] == (+ "cli-agent,programming-app"+ )++ def test_app_categories_none_no_custom_clients(self) -> None:+ """Test that no custom httpx clients are created when categories unset."""+ with patch("openrouter.OpenRouter") as mock_cls:+ mock_cls.return_value = MagicMock()+ ChatOpenRouter(+ model=MODEL_NAME,+ api_key=SecretStr("test-key"),+ )+ call_kwargs = mock_cls.call_args[1]+ assert "client" not in call_kwargs+ assert "async_client" not in call_kwargs++ def test_app_categories_empty_list_no_custom_clients(self) -> None:+ """Test that an empty list does not inject custom httpx clients."""+ with patch("openrouter.OpenRouter") as mock_cls:+ mock_cls.return_value = MagicMock()+ ChatOpenRouter(+ model=MODEL_NAME,+ api_key=SecretStr("test-key"),+ app_categories=[],+ )+ call_kwargs = mock_cls.call_args[1]+ assert "client" not in call_kwargs+ assert "async_client" not in call_kwargs++ def test_app_categories_with_other_attribution(self) -> None:+ """Test that app_categories coexists with app_url and app_title."""+ with patch("openrouter.OpenRouter") as mock_cls:+ mock_cls.return_value = MagicMock()+ ChatOpenRouter(+ model=MODEL_NAME,+ api_key=SecretStr("test-key"),+ app_url="https://myapp.com",+ app_title="My App",+ app_categories=["cli-agent"],+ )+ call_kwargs = mock_cls.call_args[1]+ assert call_kwargs["http_referer"] == "https://myapp.com"+ assert call_kwargs["x_title"] == "My App"+ assert "client" in call_kwargs+ sync_headers = call_kwargs["client"].headers+ assert sync_headers["X-OpenRouter-Categories"] == "cli-agent"+def test_reasoning_in_params(self) -> None:"""Test that `reasoning` is included in default params."""model = _make_model(reasoning={"effort": "high"})