Models API Reference¶

Bring your own model: promptise.models is the one place that turns a model description into a LangChain chat model. Every entry point that accepts a model -- build_agent(model=...), .superagent and .agent files, promptise mcpcast --model, the CLI's --model-id -- goes through resolve_model(), so the friendly provider names (azure, foundry, gemini, vertex, bedrock, mistral, grok, hf, ...) and the same actionable errors apply everywhere. The promptise models CLI and the provider table in the docs are generated from the same registry, so the code, the CLI and the pages cannot disagree.

Nothing to install per provider. OpenAI, Azure OpenAI and Anthropic use their native integrations, which are part of the core install; every other provider is reached through its OpenAI-compatible endpoint with langchain-openai, also core. Model(..., native=True) opts into a provider's own LangChain package when you have installed it yourself.

There are three ways to say which model and how to reach it, and they share one vocabulary:

A string -- "provider:model"; credentials come from the environment or a .env file: build_agent(model="azure:chat-prod").
A Model -- provider, model and credentials in code, in the shape of LangChain's init_chat_model: Model("gpt-4o", provider="azure", deployment="chat-prod", endpoint=..., api_key=..., api_version=...). The words are the same for every provider.
A config file -- the same fields under model: in a .superagent file.

Any LangChain BaseChatModel instance is accepted too, for full control.

import asyncio
from promptise import Model, build_agent, check_model, resolve_model, ModelSetupError

# Diagnose without calling anything
result = check_model("azure:chat-prod")
if not result.ok:
    print("\n".join(result.problems))   # each problem names its fix

# Or let resolution raise a ModelSetupError with the same text
try:
    llm = resolve_model("groq:llama-3.3-70b-versatile")
except ModelSetupError as exc:
    print(exc)   # GROQ_API_KEY is not set — console.groq.com → API Keys ... put it in .env, export it, or pass api_key=

async def main():
    # A string: build_agent() calls resolve_model() for you; .env or env vars supply the credentials
    agent = await build_agent(model="azure:chat-prod", instructions="Be concise.")
    await agent.shutdown()

    # A Model: provider, model and credentials in code
    agent = await build_agent(
        model=Model(
            "gpt-4o",
            provider="azure",
            deployment="chat-prod",
            endpoint="https://my-resource.openai.azure.com/",
            api_key="...",
            api_version="2024-10-21",
            temperature=0,
        ),
        instructions="Be concise.",
    )
    await agent.shutdown()

asyncio.run(main())

For the walkthrough -- Azure AI Foundry in depth, every provider, custom and self-hosted endpoints -- see Model Setup; for where keys live, Configuration & Secrets.

Resolution¶

resolve_model¶

`promptise.models.resolve_model(spec, **kwargs)` ¶

Turn a "provider:model" string (plus optional words) into a chat model.

Keyword arguments are the :class:Model words (api_key, endpoint, deployment, api_version, region, project), the settings (temperature, max_tokens, timeout), native=True, and any provider-specific extras, which are passed through. A word that is None or a blank string counts as not given, so the environment (or .env) supplies it — api_key="" never shadows the credential check.

Raises:

Type	Description
`ModelSetupError`	Naming each missing variable and where to find it, the word that does not apply to the provider, or a `.env` file that cannot be read.

Model¶

`promptise.models.Model` `dataclass` ¶

Provider, model and credentials in code — the LangChain shape.

Positional model is what the model is ("gpt-4o"); provider is where it runs ("azure", "openai", "foundry", "bedrock"… — any prefix or alias from :data:PROVIDERS, inferred from the model name like LangChain does when omitted); deployment is what you named it there (Azure OpenAI). The remaining words are the same for every provider. Anything else goes in extra verbatim. A value given here counts as provided, so the matching environment variable is not required; None or a blank string (api_key="" — what ${OPENAI_API_KEY} yields for a variable exported but empty) counts as not given, and the environment or .env supplies it.

Model("azure:chat-prod") — the string form inside Model — means Model("chat-prod", provider="azure").

repr() and str() never include api_key or extra, so a Model is safe to log and to name in error messages.

Parameters:

Name	Type	Description	Default
`model`	`str`	The model name (Azure OpenAI: the underlying model, e.g. `"gpt-4o"`; the request goes to `deployment`).	required
`provider`	`str \| None`	Provider prefix or alias. Omit it to let LangChain infer the provider from the model name (`gpt-…` → OpenAI).	`None`
`deployment`	`str \| None`	Azure OpenAI deployment name — what you called the model when you deployed it in Azure AI Foundry. Defaults to model.	`None`
`api_key`	`str \| None`	The provider's key (Bedrock: a Bedrock API key; Vertex AI: an OAuth access token; not applicable to a local Ollama).	`None`
`endpoint`	`str \| None`	Where to send requests — an Azure OpenAI resource endpoint, an Azure AI Foundry inference endpoint, or the `/v1` URL of any OpenAI-compatible server (vLLM, LM Studio, a proxy, a NIM…). For providers with a public API this overrides the default URL.	`None`
`api_version`	`str \| None`	Azure OpenAI REST API version (`"2024-10-21"`), or the Azure AI Foundry inference `api-version`.	`None`
`region`	`str \| None`	Bedrock region or Vertex AI location.	`None`
`project`	`str \| None`	Google Cloud project id (Vertex AI).	`None`
`temperature`	`float \| None`	Sampling temperature.	`None`
`max_tokens`	`int \| None`	Completion token limit.	`None`
`timeout`	`float \| None`	Request timeout in seconds.	`None`
`native`	`bool`	Use the provider's native LangChain integration instead of its OpenAI-compatible endpoint (`langchain-aws` for IAM auth on Bedrock, `langchain-google-genai` for Gemini-only features…). The package must be installed; nothing is installed for you.	`False`
`extra`	`dict[str, Any]`	Provider-specific keyword arguments passed through untouched (`{"azure_ad_token_provider": ...}`, `{"default_headers": {...}}`).	`dict()`

Model("gpt-5-mini", provider="openai", api_key="sk-...")
Model("gpt-4o", provider="azure", deployment="chat-prod",
      endpoint="https://r.openai.azure.com/", api_key="...", api_version="2024-10-21")
Model("Llama-3.3-70B-Instruct", provider="foundry",
      endpoint="https://r.services.ai.azure.com/models", api_key="...")
Model("anthropic.claude-sonnet-4-20250514-v1:0", provider="bedrock",
      region="us-east-1", api_key="ABSK...")
Model("qwen2.5", provider="openai", endpoint="http://localhost:8000/v1", api_key="none")

`provider_info` `property` ¶

The registry entry for provider (None when left to inference).

`spec` `property` ¶

The canonical "provider:model" string (or the bare model name).

`kwargs()` ¶

Everything but the spec, as keyword arguments for :func:resolve_model.

Words left None or blank are omitted, so the environment (or .env) supplies them.

`resolve()` ¶

The LangChain chat model for this configuration.

How the words reach a provider: for the three native integrations they map to that class's own arguments (endpoint → azure_endpoint= on Azure OpenAI, base_url= on OpenAI and Anthropic; deployment → azure_deployment=). For every other provider the words build the OpenAI-compatible request: endpoint overrides the provider's default URL (or is the URL for Azure AI Foundry and Ollama), region and project fill the URL template for Bedrock and Vertex AI, api_version sets Azure AI Foundry's api-version query parameter, and api_key becomes the bearer token (Bedrock: a Bedrock API key; Vertex AI: an OAuth access token — minted for you when google-auth and Application Default Credentials are available, as a token provider the client calls before every request, so the ~1 h token is refreshed before it expires; a token given by hand is used as given and expires). A word a provider has no setting for raises ModelSetupError with what to use instead; a word that is None or a blank string counts as not given (an empty api_key="" never shadows the environment check). extra is merged in last, verbatim -- a keyless Azure OpenAI setup is Model("gpt-4o", provider="azure", deployment=..., endpoint=..., api_version=..., extra={"azure_ad_token_provider": provider}).

>>> Model("m", provider="groq", deployment="d").resolve()
ModelSetupError: Groq has no 'deployment' setting: only Azure OpenAI addresses models by deployment name — put the name in model=.

check_model¶

`promptise.models.check_model(spec, provided=None, *, native=False)` ¶

Diagnose a model string without calling anything.

provided names the words the caller supplies in code ({"api_key"}); they count as satisfying the corresponding variables.

ModelCheck¶

`promptise.models.ModelCheck` `dataclass` ¶

The result of :func:check_model.

`ok` `property` ¶

True when nothing stands in the way of building this model.

A spec with no known prefix is always usable (LangChain infers the provider). Otherwise every required variable is set or covered by a word given in code (:attr:missing_env is empty) and, when the native route was requested, its integration is installed. When this is False, :attr:problems says what to fix.

`problems` `property` ¶

Human-readable problems, each with its fix.

ModelSetupError¶

`promptise.models.ModelSetupError` ¶

Bases: RuntimeError

A model cannot be used yet — the message says exactly what to do.

The message always says what to do. Missing credentials, nothing set:

Cannot use model azure:'chat-prod' (Azure OpenAI (OpenAI models deployed in Azure AI Foundry)) yet:
  - AZURE_OPENAI_ENDPOINT is not set — Azure AI Foundry portal → your resource → Overview → Endpoint (https://<resource>.openai.azure.com/, no path) (e.g. https://my-resource.openai.azure.com/)
  - AZURE_OPENAI_API_KEY is not set — Azure AI Foundry portal → your resource → Keys and Endpoint → KEY 1 (or Entra ID: pass extra={'azure_ad_token_provider': ...})
  - OPENAI_API_VERSION is not set — the REST API version your deployment supports, e.g. 2024-10-21 (Azure docs → 'API version lifecycle') (e.g. 2024-10-21)
  - put AZURE_OPENAI_ENDPOINT, AZURE_OPENAI_API_KEY, OPENAI_API_VERSION in a .env file next to your script (loaded automatically, never overrides a set variable), export it, or pass it in code: Model(..., endpoint=, api_key=, api_version=) — see promptise models env azure
  Model part means: in the string form, your DEPLOYMENT name (Foundry → Deployments → Name); with Model(...), the model name (gpt-4o) — the deployment goes in deployment=.
  Example: azure:chat-prod
  Diagnose any model string with: promptise models check azure:chat-prod

load_dotenv_if_present¶

`promptise.models.load_dotenv_if_present(*, cwd=None)` ¶

Load the nearest safe .env file from cwd (default: the working directory) upward.

The search walks from cwd through its parents and stops after the project root — the first directory holding pyproject.toml or .git — so a file above the project (/tmp/.env on a shared host, another user's home) is never consulted. A candidate is loaded only when it is a regular file and, on POSIX, owned by you and not world-writable; anything else is skipped with a :class:UserWarning naming the file (once per process) and the search continues upward.

A variable that is already set to a non-empty value is never overwritten. A variable exported as an empty string (export OPENAI_API_KEY= left in a shell profile) counts as unset everywhere in this module, so the file's non-empty value fills it — python-dotenv alone would skip it and the key would look "not set" although it is in the file. Empty values in the file set nothing. :func:dotenv_origin reports which file filled a variable.

Returns the path that was loaded, or None. Set PROMPTISE_NO_DOTENV=1 to disable (tests and hermetic deployments). Loading happens once per process per file; call again after os.chdir to pick up another one.

Raises:

Type	Description
`ModelSetupError`	When the file that would be loaded cannot be read or is not UTF-8 — the message names it and says what to do.

The search is bounded and the file is checked before it is read: the walk from the working directory stops after the project root (the first ancestor holding pyproject.toml or .git), and a candidate that is not a regular file or -- on POSIX -- is owned by another user or world-writable is skipped with a UserWarning that names it. A file that cannot be read or is not UTF-8 raises ModelSetupError naming the path (cannot read /path/.env: ... — fix its permissions/encoding, move it, or set PROMPTISE_NO_DOTENV=1) — the same error resolve_model(), build_agent() and the CLI surface, never a raw PermissionError. The promptise CLI loads the file once, in its global callback, and prints .env loaded from <path> on stderr.

dotenv_origin¶

`promptise.models.dotenv_origin(name)` ¶

The .env file that supplied the current value of variable name, or None.

None means the variable came from the environment itself (or is not set at all): :func:load_dotenv_if_present records a file only for the variables it filled.

from promptise.models import dotenv_origin, load_dotenv_if_present

load_dotenv_if_present()
dotenv_origin("OPENAI_API_KEY")   # '/home/me/project/.env' — or None when the shell set it

promptise models check uses it to print set (from /home/me/project/.env) next to every variable the file filled.

Parsing¶

parse_model¶

`promptise.models.parse_model(spec)` ¶

Split "prefix:model" into (provider, canonical_spec, model).

A spec without a known prefix is returned with provider=None and left for LangChain to infer ("gpt-5-mini" still works).

find_provider¶

`promptise.models.find_provider(prefix)` ¶

The provider for a prefix or alias ("azure" → Azure OpenAI), or None.

env_template¶

`promptise.models.env_template(prefix)` ¶

Shell export lines for a provider, with placeholders and hints.

$ promptise models env azure
# Azure OpenAI (OpenAI models deployed in Azure AI Foundry) — model string example: azure:chat-prod
export AZURE_OPENAI_ENDPOINT=https://my-resource.openai.azure.com/
#   ↳ Azure AI Foundry portal → your resource → Overview → Endpoint (https://<resource>.openai.azure.com/, no path)
export AZURE_OPENAI_API_KEY=...
#   ↳ Azure AI Foundry portal → your resource → Keys and Endpoint → KEY 1 (or Entra ID: pass extra={'azure_ad_token_provider': ...})
export OPENAI_API_VERSION=2024-10-21
#   ↳ the REST API version your deployment supports, e.g. 2024-10-21 (Azure docs → 'API version lifecycle')

Registry¶

Provider¶

`promptise.models.Provider` `dataclass` ¶

How to reach one model provider.

`aliases` `instance-attribute` ¶

Friendly prefixes users may type instead of key (azure).

`base_url = None` `class-attribute` `instance-attribute` ¶

OpenAI-compatible endpoint, with {endpoint}, {region} and {project} placeholders filled from the words. None for the three providers reached through their native core integration.

`display` `property` ¶

The prefix shown in docs and messages (a friendly alias for the LangChain-style keys, else the key itself).

`example = ''` `class-attribute` `instance-attribute` ¶

A complete example model string.

`key` `instance-attribute` ¶

The canonical prefix (azure_openai).

`key_optional = False` `class-attribute` `instance-attribute` ¶

The endpoint works without a key (a local Ollama).

`model_hint = ''` `class-attribute` `instance-attribute` ¶

What the model part means for this provider.

`native = None` `class-attribute` `instance-attribute` ¶

LangChain init_chat_model provider key of the native integration.

`native_installed` `property` ¶

Whether the native LangChain integration can be imported right now.

True when the integration ships with the core install (:attr:native_package is None); otherwise whether that package (langchain_groq…) is installed — checked without importing it.

`native_kwargs = field(default_factory=dict)` `class-attribute` `instance-attribute` ¶

How the words map onto the native integration's keyword arguments.

`native_package = None` `class-attribute` `instance-attribute` ¶

Importable module of that integration (langchain_groq); None when it is part of the core install.

`prefixes` `property` ¶

Every prefix that selects this provider in a model string.

:attr:key first, then :attr:aliases — the strings :func:find_provider matches a prefix:model spec against.

`query = field(default_factory=dict)` `class-attribute` `instance-attribute` ¶

Query parameters every request carries (Azure AI Foundry's api-version).

`route` `property` ¶

"native" (core integration) or "openai-compatible".

`missing(provided)` ¶

Required variables that are neither set nor covered by a provided word.

`words()` ¶

The words this provider understands.

EnvVar¶

`promptise.models.EnvVar` `dataclass` ¶

One environment variable a provider reads.

`aliases = ()` `class-attribute` `instance-attribute` ¶

Other variable names accepted for the same value (GEMINI_API_KEY).

`where` `instance-attribute` ¶

Where to find the value (the provider's console page, a CLI command…).

`word` `instance-attribute` ¶

The :class:Model word this variable feeds (api_key, endpoint…); a value given in code for that word makes the variable unnecessary.

`value()` ¶

The value the environment currently holds for this variable, or None.

The first of :attr:name and :attr:aliases set to a non-empty string wins; a variable exported but empty counts as not set (which is why :func:load_dotenv_if_present fills empty ones from a .env file).

PROVIDERS¶

PROVIDERS is the tuple of every Provider Promptise knows, in the order the CLI lists them. The table below is generated from it (and a test asserts it stays exact):

Provider	`provider=`	Environment variables (exact names)	`Model(...)` words	Route
OpenAI	`openai` also `gpt`	`OPENAI_API_KEY` `OPENAI_BASE_URL` (optional)	`api_key=`, `endpoint=`	native (core)
Azure OpenAI	`azure` also `azure_openai`, `azure-openai`, `azureopenai`, `aoai`	`AZURE_OPENAI_ENDPOINT` `AZURE_OPENAI_API_KEY` `OPENAI_API_VERSION`	`deployment=`, `api_key=`, `endpoint=`, `api_version=`	native (core)
Azure AI Foundry model catalog	`foundry` also `azure_ai`, `azure-ai`, `azureai`, `ai-foundry`	`AZURE_INFERENCE_ENDPOINT` `AZURE_INFERENCE_CREDENTIAL`	`api_key=`, `endpoint=`, `api_version=`	OpenAI-compatible, URL built from the words
Anthropic Claude	`anthropic` also `claude`	`ANTHROPIC_API_KEY`	`api_key=`, `endpoint=`	native (core)
Google Gemini	`gemini` also `google_genai`, `google`, `google-genai`, `genai`	`GOOGLE_API_KEY` / `GEMINI_API_KEY`	`api_key=`, `endpoint=`	OpenAI-compatible: `https://generativelanguage.googleapis.com/v1beta/openai/`
Google Vertex AI	`vertex` also `google_vertexai`, `vertexai`, `google-vertex`, `gcp`	`GOOGLE_CLOUD_PROJECT` `GOOGLE_CLOUD_LOCATION` (optional) `GOOGLE_OAUTH_ACCESS_TOKEN` (optional)	`api_key=`, `endpoint=`, `region=`, `project=`	OpenAI-compatible, URL built from the words
Amazon Bedrock	`bedrock` also `aws`, `amazon`	`AWS_DEFAULT_REGION` / `AWS_REGION` `AWS_BEARER_TOKEN_BEDROCK`	`api_key=`, `endpoint=`, `region=`	OpenAI-compatible, URL built from the words
Ollama	`ollama` also `local`	`OLLAMA_HOST` (optional)	`endpoint=`	OpenAI-compatible, URL built from the words
Cohere	`cohere`	`COHERE_API_KEY`	`api_key=`, `endpoint=`	OpenAI-compatible: `https://api.cohere.ai/compatibility/v1`
DeepSeek	`deepseek`	`DEEPSEEK_API_KEY`	`api_key=`, `endpoint=`	OpenAI-compatible: `https://api.deepseek.com/v1`
Fireworks AI	`fireworks`	`FIREWORKS_API_KEY`	`api_key=`, `endpoint=`	OpenAI-compatible: `https://api.fireworks.ai/inference/v1`
Groq	`groq`	`GROQ_API_KEY`	`api_key=`, `endpoint=`	OpenAI-compatible: `https://api.groq.com/openai/v1`
Hugging Face Inference Providers	`huggingface` also `hf`	`HF_TOKEN` / `HUGGINGFACEHUB_API_TOKEN`	`api_key=`, `endpoint=`	OpenAI-compatible: `https://router.huggingface.co/v1`
Mistral AI	`mistral` also `mistralai`	`MISTRAL_API_KEY`	`api_key=`, `endpoint=`	OpenAI-compatible: `https://api.mistral.ai/v1`
NVIDIA NIM	`nvidia` also `nim`	`NVIDIA_API_KEY`	`api_key=`, `endpoint=`	OpenAI-compatible: `https://integrate.api.nvidia.com/v1`
OpenRouter	`openrouter`	`OPENROUTER_API_KEY`	`api_key=`, `endpoint=`	OpenAI-compatible: `https://openrouter.ai/api/v1`
Perplexity	`perplexity`	`PPLX_API_KEY`	`api_key=`, `endpoint=`	OpenAI-compatible: `https://api.perplexity.ai`
Together AI	`together`	`TOGETHER_API_KEY`	`api_key=`, `endpoint=`	OpenAI-compatible: `https://api.together.xyz/v1`
xAI Grok	`xai` also `grok`	`XAI_API_KEY`	`api_key=`, `endpoint=`	OpenAI-compatible: `https://api.x.ai/v1`

Nothing to install for any row: pip install promptise covers every provider. native=True opts into a provider's own LangChain integration when you have it installed.

CLI module¶

promptise.models_cli¶

The promptise models command group (list, check [--ping], env) lives in promptise.models_cli and reads only PROVIDERS, check_model(), resolve_model() and env_template() -- see the CLI reference.

Models API Reference¶

Resolution¶

resolve_model¶

promptise.models.resolve_model(spec, **kwargs) ¶

Model¶

promptise.models.Model dataclass ¶

provider_info property ¶

spec property ¶

kwargs() ¶

resolve() ¶

check_model¶

promptise.models.check_model(spec, provided=None, *, native=False) ¶

ModelCheck¶

promptise.models.ModelCheck dataclass ¶

ok property ¶

problems property ¶

ModelSetupError¶

promptise.models.ModelSetupError ¶

load_dotenv_if_present¶

promptise.models.load_dotenv_if_present(*, cwd=None) ¶

dotenv_origin¶

promptise.models.dotenv_origin(name) ¶

Parsing¶

parse_model¶

promptise.models.parse_model(spec) ¶

find_provider¶

promptise.models.find_provider(prefix) ¶

env_template¶

promptise.models.env_template(prefix) ¶

Registry¶

Provider¶

promptise.models.Provider dataclass ¶

aliases instance-attribute ¶

base_url = None class-attribute instance-attribute ¶

display property ¶

example = '' class-attribute instance-attribute ¶

key instance-attribute ¶

key_optional = False class-attribute instance-attribute ¶

model_hint = '' class-attribute instance-attribute ¶

native = None class-attribute instance-attribute ¶

native_installed property ¶

native_kwargs = field(default_factory=dict) class-attribute instance-attribute ¶

native_package = None class-attribute instance-attribute ¶

prefixes property ¶

query = field(default_factory=dict) class-attribute instance-attribute ¶

route property ¶

missing(provided) ¶

words() ¶