Skip to content

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_KEY and MARVIN_CHAT_COMPLETIONS_MODEL belong to Marvin 2; Marvin 3 doesn't read them.
  • Marvin's own docs: LLM models.