Marvin (PrefectHQ)

3.2.7 · active · verified Tue Mar 24

AI functions and agentic workflow library by PrefectHQ. Provides decorator-based AI functions (marvin.fn, marvin.classify, marvin.extract, marvin.cast) and agent/task orchestration. v3.0 released 2024 — merged with ControlFlow, switched LLM backend from OpenAI-only to Pydantic AI (multi-provider). Current version: 3.2.7 (Mar 2026). WARNING: 'marvin' on PyPI is PrefectHQ's AI library — not the SDSS astronomy Marvin library (sdss-marvin on PyPI).

Warnings

breaking marvin v2 was OpenAI-only. v3 uses Pydantic AI as backend supporting all providers. marvin.settings.openai.api_key configuration pattern from v2 is gone.
Fix: Set OPENAI_API_KEY env var. Or configure other providers via pydantic-ai settings.
breaking ControlFlow's @flow decorator removed in v3. ControlFlow merged into marvin. Use marvin.Thread() context manager instead.
Fix: Replace @flow decorated functions with 'with marvin.Thread(): marvin.run(...)' pattern.
breaking Thread/message history storage changed to SQLite in v3. No database migrations available — expect data loss when updating during development.
Fix: Reset SQLite data after version updates during development. Production: handle migrations manually.
gotcha Name collision: 'marvin' PyPI package is PrefectHQ's AI library. 'sdss-marvin' is the SDSS astronomy toolkit. LLMs may conflate them. They are completely unrelated.
Fix: pip install marvin for AI functions. pip install sdss-marvin for astronomy. Never mix.
gotcha Marvin defaults to OpenAI gpt-4o. No model specified = OpenAI API call. Fails silently with AuthenticationError if OPENAI_API_KEY not set.
Fix: Set OPENAI_API_KEY or configure a different pydantic-ai provider explicitly.
gotcha ai_fn decorator from very old v1 docs still appears in many tutorials. Renamed to marvin.fn in v2+.
Fix: Use @marvin.fn not @ai_fn.

Install

pip install marvin Python

Imports

marvin.extract

import marvin

result = marvin.extract(
    'i found $30 on the ground and bought 5 bagels for $10',
    int,
    instructions='only USD amounts'
)
print(result)  # [30, 10]

marvin.settings.openai.api_key pattern from v2 is gone in v3. Set OPENAI_API_KEY env var or configure via pydantic-ai settings.

marvin.fn decorator

import marvin

@marvin.fn
def sentiment(text: str) -> float:
    """Returns sentiment score from -1.0 (negative) to 1.0 (positive)."""

score = sentiment('I love this product!')
print(score)  # ~0.9

ai_fn decorator from v1/old docs renamed to marvin.fn in v2+. Both may exist but marvin.fn is canonical.

marvin.Thread (v3)
```
import marvin

with marvin.Thread() as thread:
    marvin.run('What is quantum computing?')
    marvin.run('How does that relate to AI?')
```
ControlFlow's @flow decorator removed in v3. Use marvin.Thread() context manager instead. ControlFlow is now merged into marvin.

Quickstart

Core marvin 3.x structured output functions.

# pip install marvin
import marvin
import os

# Set OPENAI_API_KEY env var — marvin uses OpenAI by default

# Structured extraction
numbers = marvin.extract(
    'I paid $45 for lunch and $12 for coffee',
    int,
    instructions='USD amounts only'
)
print(numbers)  # [45, 12]

# Classification
category = marvin.classify(
    'The new iPhone has great camera features',
    labels=['tech', 'sports', 'politics']
)
print(category)  # 'tech'

# AI function
@marvin.fn
def translate(text: str, language: str) -> str:
    """Translates text to the given language."""

print(translate('Hello world', 'Spanish'))  # 'Hola mundo'

view raw JSON →