Marvin¶
Marvin turns one-line calls such as marvin.extract and marvin.classify into model calls. Point it at the gateway and
each of them is checked against your policies, charged to the right team and recorded in Request logs, whichever
provider's model answers.
What it is¶
Marvin 3 is a Python library of AI functions (cast, extract, classify, generate,
run, @marvin.fn) and agents. It reaches models through Pydantic AI, so its settings
are Pydantic AI's: a model string or a model object with a provider.
The two settings¶
| Setting | Environment variable | In code | Value |
|---|---|---|---|
| Base address | OPENAI_BASE_URL |
OpenAIProvider(base_url=…) |
https://<your-gateway>/v1 |
| Key | OPENAI_API_KEY |
OpenAIProvider(api_key=…) |
Your Vidai key (starts vk_), never a provider's key |
| Model | MARVIN_AGENT_MODEL |
marvin.defaults.model, or Agent(model=…) |
openai-chat:<model name>, for example openai-chat:claude-sonnet-4.5 |
Use the openai-chat: prefix, not openai:. In current Pydantic AI the bare openai: prefix picks the Responses API,
which the gateway sends to OpenAI models only; openai-chat: uses Chat Completions, which reaches every provider.
Marvin reads MARVIN_* settings when it's imported, so set the variables before import marvin. The gateway's
address is under Connect your app on the Keys page and in System › Settings › Gateway. You get the key from
Keys › Issue a key; its secret is shown once.
A minimal call¶
export OPENAI_BASE_URL="https://<your-gateway>/v1"
export OPENAI_API_KEY="vk_…"
export MARVIN_AGENT_MODEL="openai-chat:gpt-4o-mini"
import marvin
print(marvin.classify("The printer on floor 3 is on fire.", labels=["urgent", "normal", "low"]))
import marvin
from pydantic_ai.models.openai import OpenAIChatModel
from pydantic_ai.providers.openai import OpenAIProvider
gateway = OpenAIProvider(base_url="https://<your-gateway>/v1", api_key="vk_…")
marvin.defaults.model = OpenAIChatModel("claude-sonnet-4.5", provider=gateway)
print(marvin.classify("The printer on floor 3 is on fire.", labels=["urgent", "normal", "low"]))
For Claude or Gemini, change only the model name. The gateway translates the request and the answer.
Streaming¶
Marvin's functions return whole results. Agents built on Pydantic AI stream their model calls; a stream from Claude or Gemini arrives as OpenAI chunks, and Vidai records the tokens and the cost either way.
Tool calls¶
Marvin gets structured results (extract, cast, result_type=…) through tool calls, and agents call the tools you
give them. Tool calls work on every provider the gateway translates to.
from pydantic import BaseModel
class Contact(BaseModel):
name: str
email: str | None
print(marvin.extract("Write to Anouk at [email protected]", target=Contact))
Reading what the gateway did¶
Marvin doesn't show response headers. Look the calls up in Request logs: filter on Key, Model or Path
(/v1/chat/completions). One Marvin function can make more than one call (a retry after an answer fails validation,
or an agent's tool round trips); each has its own row. Cost is never in the answer.
Errors¶
The gateway writes its errors in the OpenAI format; Pydantic AI raises them as ModelHTTPError with the status code
and body. Common ones while setting up: 401 invalid_api_key, 403 model_not_allowed, 404 model_not_found, 400 when
the openai: prefix sends the Responses API to a non-OpenAI model (use openai-chat:). The full list is in
Headers and errors.
Model names¶
The name after openai-chat: is one your organisation approved under Models in the Control room.
GET https://<your-gateway>/v1/models with your key lists exactly the models it may call.
What goes through the gateway¶
| Feature | Through the gateway |
|---|---|
cast, extract, classify, generate, summarize, run, say, @marvin.fn, agents, teams, threads, with openai-chat: or OpenAIChatModel |
Yes, to OpenAI, Azure OpenAI, Anthropic, Gemini and Vertex AI models |
The openai: prefix (Responses API) |
OpenAI and Azure OpenAI models only; another provider gets a clear 400 |
Check it works in a minute¶
OPENAI_BASE_URL="https://<your-gateway>/v1" OPENAI_API_KEY="vk_…" MARVIN_AGENT_MODEL="openai-chat:gpt-4o-mini" \
python -c "import marvin; print(marvin.run('Reply with exactly: ok'))"
A short answer means the address and key are right. The call shows in Request logs within seconds.
Good to know¶
- An Anthropic model object works too:
AnthropicModel("claude-sonnet-4.5", provider=AnthropicProvider(base_url="https://<your-gateway>", api_key="vk_…"))sends the Messages format, which the gateway also translates to GPT and Gemini models. - The settings
MARVIN_OPENAI_BASE_URL,MARVIN_OPENAI_API_KEYandMARVIN_CHAT_COMPLETIONS_MODELbelong to Marvin 2; Marvin 3 doesn't read them. - Marvin's own docs: LLM models.