Marvin

Marvin is a Python library for extracting structured data and running tasks with language models. It builds on Pydantic AI for model access and adds typed tasks, tools, and conversation history. Made by Prefect.

Install

Requires Python 3.10 or later and credentials for your model provider.

uv add marvin
export OPENAI_API_KEY="your-api-key"

Marvin uses OpenAI by default. See model configuration for other providers.

Use

import marvin
from pydantic import BaseModel

class Contact(BaseModel):
    name: str
    email: str

contacts = marvin.extract("Email Ada at ada@example.com", Contact)
print(contacts)

Use cast to produce one value, extract to find a list of values, classify to choose labels, and generate to create examples. Each has an async counterpart.

For work that needs instructions, context, or tools, use a task:

import marvin

def stock_level(product: str) -> int:
    """Return the number of units in stock."""
    return {"notebook": 12, "pen": 30}[product]

count = marvin.run(
    "Check how many notebooks are in stock",
    result_type=int,
    tools=[stock_level],
)

An Agent holds model settings, instructions, and tools you want to reuse. A Thread shares conversation history across calls and stores it in a database. See the quickstart and examples for both.

Develop

uv sync
uv run pytest tests/basic
uv run pre-commit run --all-files

Tests under tests/ai make model requests and require provider credentials. Keep test data separate from your local history by setting MARVIN_HOME_PATH to a temporary directory.

Docs

The documentation lives in docs/ and is published at askmarvin.ai. See releases for changes between versions.

License

Apache 2.0.