Models Provider

Models Provider gives applications one interface for selecting models, resolving provider access, creating chat models, and collecting usage. Model metadata is loaded privately from the public models.dev catalogue.

Installation

pip install models-provider

Public flow

Pass provider values directly to Models, then select a provider-qualified model:

from models_provider import Models

models = Models({
    "openai": "OPENAI_API_KEY",
})

model = models.chat(
    "openai/gpt-4.1-mini",
    temperature=0.2,
    top_p=0.9,
)

answer = model.invoke("Explain spaced repetition in two sentences.")

Models() fetches the fixed models.dev catalogue once during initialization and caches it internally. models.providers() and models.list() expose typed provider and model metadata, including friendly names. Applications do not load or construct a catalogue.

The model identifier describes the model publisher, not the authentication mechanism. The access implementation is selected internally from the provider and the supplied values. For example, openai/gpt-5 remains the model identifier when the available access is an API key or an OpenAI account session.

Provider values

The constructor accepts one ordinary dictionary. Values can be literal credentials, environment-variable names, or provider-specific mappings:

Models({"openai": "sk-proj-...7Qx2"})

Models({"openai": "OPENAI_API_KEY"})

An uppercase environment-variable name is resolved from the process environment. Persistence is owned by the embedding application; Models Provider does not expose a credential-store abstraction or load credential files.

OAuth

OAuth values use the same dictionary. The host controls how the authorization URL is displayed:

models = Models()

authorization = await models.sign_in("openai")
# The host uses authorization.url to open the authorization page for the user.
await authorization.complete()

model = models.chat("openai/gpt-5", authorization=authorization)

The login flow and token refresh are provider-owned. Each authorization is independent, so the same Models instance can serve different users. The host decides whether and how to persist a user's authorization values.

Model contract

models.chat(
    "provider/model",
    temperature=0.2,
    top_p=0.9,
    reasoning_effort="high",
    max_output_tokens=512,
) -> BaseChatModel

Request settings are ordinary keyword arguments. The selected access implementation validates and translates them to its transport. There is no public options object and no provider-specific access class required from the caller.

Use model.bind_tools(...) and model.astream(...) for typed incremental text, reasoning, and tool-call chunks. Streaming transports close when iteration ends or is cancelled; usage is reported when supplied by the provider.

Reuse the returned model across related calls. Account-backed transports keep private connection and cache affinity for that model's lifetime, while message history remains owned by the caller.

OpenAI account models pass LangChain image content blocks in user messages and tool results through to the Responses transport. Use an image-capable model and provide each image block with a MIME type and base64 data; text-only messages retain their existing wire format.

For OpenCode, pass an OpenCodeRequestContext(session_id=...) through opencode_request_context to reuse the conversation’s routing and cache identity. Explicit provider values take precedence over shared credential aliases.

For OpenAI account models, start_turn() resets the routing token at the start of a new user turn while retaining the connection and cache affinity. await aclose() closes the connection and clears incremental response state. A TransientProviderError means the host can retry the same model request; repeated WebSocket failures switch that turn to HTTP. Invalid requests and authentication errors are not classified as transient.

Usage values

Normalized usage is grouped by measurement type:

usage.tokens.input_tokens
usage.tokens.reasoning_tokens
usage.cache.cache_read_tokens
usage.audio.output_audio_tokens
usage.cost.cost_usd

UsageLedger owns accumulation when an application records multiple responses.

Ownership

Models Provider owns:

• the private models.dev catalogue and its built-in cache;
• provider and model selection;
• provider-specific authentication and transport;
• request-option normalization;
• usage normalization.

The embedding application owns:

• the provider-values dictionary;
• credential persistence, if needed;
• application workflows, sessions, tools, permissions, and files.