Add OpenRouterModel as OpenAIChatModel subclass

[ajac-zero]

Hi! This pull request takes a shot at implementing a dedicated OpenRouterModel model. Closes #2936.

The differentiator for this PR is that this implementation minimizes code duplication as much as possible by delegating the main logic to OpenAIChatModel, such that the new model class serves as a convenience layer for OpenRouter specific features.

The main thinking behind this solution is that as long as the OpenRouter API is still fully accessible via the openai package, it would be inefficient to reimplement the internal logic using this same package again. We can instead use hooks to achieve the requested features.

I would like to get some thoughts on this implementation before starting to update the docs.

Addressed issues

1. Closes Store OpenRouter provider metadata in ModelResponse vendor details #1849

Provider metadata can now be accessed via the 'downstream_provider' key in ModelMessage.provider_details:

from pydantic_ai import ModelRequest
from pydantic_ai.direct import model_request_sync
from pydantic_ai.models.openrouter import OpenRouterModel

model = OpenRouterModel('moonshotai/kimi-k2-0905')

response = model_request_sync(model, [ModelRequest.user_text_prompt('Who are you')])

assert response.provider_details is not None
print(response.provider_details['downstream_provider'])  # <-- Final provider that was routed to
# Output: AtlasCloud

2. Closes Can I get thinking part from openrouter provider using google/gemini-2.5-pro? #2999

The new OpenRouterModelSettings allows for the reasoning parameter by OpenRouter, the thinking can then be accessed as a ThinkingPart in the model response:

from pydantic_ai import ModelRequest
from pydantic_ai.direct import model_request_sync
from pydantic_ai.models.openrouter import OpenRouterModel, OpenRouterModelSettings

model = OpenRouterModel('google/gemini-2.5-pro')

settings = OpenRouterModelSettings(openrouter_reasoning={'effort': 'high'})

response = model_request_sync(model, [ModelRequest.user_text_prompt('Who are you')], model_settings=settings)

print(response.parts[0])
# Output: ThinkingPart(content='**Identifying the Core Inquiry**\n\nI\'m grappling with the core question: "Who am I?" Initially, I\'m identifying the root of the query. The user wants a fundamental identity explained, and I\'ve begun by pinpointing the key words and associations. AI, specifically. Next step, I\'ll move onto broadening this.\n\n\n**Clarifying My Nature**\n\nI\'m now dissecting the definition of "language model," focusing on what that *means* in practical terms. I\'ve moved past simply stating the term and am now delving into how my functions—answering, generating, translating—are executed. This requires explaining my training on vast datasets and my lack of personal experience, which is key to the identity question. I am trying to find the right framing for this complex process.\n\n\n**Formulating a Direct Response**\n\nI\'m now trying to directly answer the question, avoiding technical jargon where possible. I\'m organizing my response. The essential elements have been identified: My nature, my capabilities, and what I *cannot* do. I\'m thinking of ways to explain these facts in a concise, accessible format, focusing on clarity for the user.\n\n\n**Constructing a Detailed Answer**\n\nI\'m now translating the structured plan into actual sentences. I\'m working on the opening, the "I am..." statement, and aiming for a direct, clear tone. Then, I am carefully crafting the explanation of my capabilities and limitations to avoid misunderstandings. I\'m actively searching for concise and impactful language.\n\n\n**Drafting the Final Response**\n\n\\n\\n\n\nI\'m now integrating all the elements I\'ve identified. I\'m beginning the final draft. I\'m focusing on flow and readability, weaving the key points—my nature, my origin, my abilities, and my constraints—into a cohesive narrative. The goal is a concise and informative self-description, tailored to the user\'s inquiry.\n\n\n', id='reasoning', provider_name='openrouter')

3. Closes Handle error response from OpenRouter as exception instead of validation failure #2323. Closes OpenRouter uses non-compatible finish reason #2844

These are dependent on some downstream logic from OpenRouter or their own downstream providers (that a response of type 'error' will have a >= 400 status code), but for most cases I would say it works as one would expect:

from pydantic_ai import ModelHTTPError, ModelRequest
from pydantic_ai.direct import model_request_sync
from pydantic_ai.models.openrouter import OpenRouterModel, OpenRouterModelSettings

model = OpenRouterModel('google/gemini-2.5-pro')

settings = OpenRouterModelSettings(
    openrouter_preferences={'only': ['azure']}  # Gemini is not available in Azure; Guaranteed failure.
)

try:
    response = model_request_sync(model, [ModelRequest.user_text_prompt('Who are you')], model_settings=settings)
except ModelHTTPError as e:
    print(e)
# status_code: 404, model_name: google/gemini-2.5-pro, body: {'message': 'No allowed providers are available for the selected model.', 'code': 404}

4. Add OpenRouterModel #1870 (comment)

Add some additional type support to set the provider routing options from OpenRouter:

from pydantic_ai import ModelRequest
from pydantic_ai.direct import model_request_sync
from pydantic_ai.models.openrouter import OpenRouterModel, OpenRouterModelSettings

model = OpenRouterModel('moonshotai/kimi-k2-0905')

settings = OpenRouterModelSettings(
    openrouter_preferences={
        'order': ['moonshotai', 'deepinfra', 'fireworks', 'novita'],
        'allow_fallbacks': True,
        'require_parameters': True,
        'data_collection': 'allow',
        'zdr': True,
        'only': ['moonshotai', 'fireworks'],
        'ignore': ['deepinfra'],
        'quantizations': ['fp8'],
        'sort': 'throughput',
        'max_price': {'prompt': 1},
    }
)

response = model_request_sync(model, [ModelRequest.user_text_prompt('Who are you')], model_settings=settings)
assert response.provider_details is not None
print(response.provider_details['downstream_provider'])
# Output: Fireworks

[DouweM]

@ajac-zero Muchas gracias Anibal!

[ajac-zero]

Buen día @DouweM, can you take a look when you get the chance?

[DouweM]

Gracias!

It'd be interesting to add support for the WebSearchTool built-in tool as well, shouldn't be too complicated I think: https://openrouter.ai/docs/features/web-search

[DouweM]

@ajac-zero We can also remove this comment from openai.py:

pydantic-ai/pydantic_ai_slim/pydantic_ai/models/openai.py

Lines 558 to 560 in c5b1495

	# NOTE: We don't currently handle OpenRouter `reasoning_details`:
	# - https://openrouter.ai/docs/use-cases/reasoning-tokens#preserving-reasoning-blocks
	# If you need this, please file an issue.

[xcpky]

Hi, just found this useful pr and I think top_k and other missing model config should be added to align with the Request Schema documented here https://openrouter.ai/docs/api-reference/overview.

[DouweM]

It's a small thing, but since these map to headers and are documented in https://openrouter.ai/docs/app-attribution as being headers, would it make sense to expose the entire headers option, or document how to set headers via a custom client? That's the route we've taken in other providers -- I don't think we've exposed specific headers as arguments, except for auth etc.

I could see these making sense if we name them for the purpose, rather than the specific header they map to, e.g. app_url and app_title, matching how they're described in the docs. If they're not just headers but an "OpenRouter feature" to configure, dedicated args feel more natural. That'd also warrant an App Attribution section here.

[ajac-zero]

I prefer the second option, I would consider it a proper feature that should be supported.

[DouweM]

Nice, I like it, this is a bit similar to the recently introduced EventStream and I think it'd be a great direction to move these model classes into, if we can find something that's expressive enough for all of the crazy stuff that's happening in model message mapping...

[DouweM]

Could we pass this into a method on the new context object?

[DouweM]

Typo: respose -> response

[DouweM]

Now that we're in BaseModel land, we can use type as a union discriminator: https://docs.pydantic.dev/latest/concepts/unions/#discriminated-unions, and have TypeAdapter(A | B | C).validate_json() automatically deserialize as the correct subclass.

Looking at the code though, I'm feeling a little bad about abusing the id field like this. (I felt less bad about it when I suggested basically type|id|etc|etc, but I agree that's gonna be a mess with so many fields and potentially more in the future.)

Adding an arbitrary-provider-metadata field to parts has come up a couple of times recently (#3453, #3474), so it may be time to bite the bullet and do it. provider_details: dict[str, Any] | None = None (like the same field on ModelResponse) seems reasonable to me. Would you be up for adding it to the PR? (I'd also understand if you'd rather get this PR over with, in which case you can do it the id way and I/you/someone can do the other thing in a followup, as it can be backward compatible)

[DouweM]

Can these be dataclasses? Pydantic supports those as well, and they're more light weight than BaseModels.

[DouweM]

Our provider_details['finish_reason'] is essentially the same thing as OpenRouter's native_finish_reason, as in the original value before being mapped to some abstraction layer. So it feels natural to me to call it finish_reason here. We'd "lose" OpenRouter's own intermediate value, but not really because that maps to the response.finish_reason values (I think).

I'm just thinking about code somewhere that may look for provider_details['finish_reason'] and expect it to the the ultimate original value