====== Marvin ======
**Marvin** is a Python framework by [[https://prefect.io|Prefect]] for producing [[structured_outputs|structured outputs]] from LLMs and building [[agentic_ai|agentic AI workflows]].(([[https://github.com/PrefectHQ/marvin|Marvin on GitHub]])) With 6.1K+ GitHub stars, it provides intuitive building blocks, cast, classify, extract, generate, that bridge AI unpredictability with type-safe, observable, composable software patterns. Version 3.0 introduces full agentic control flow with Tasks, Agents, and Threads.

===== Overview =====
Marvins philosophy treats AI capabilities as **engineering building blocks** rather than black-box magic. Each function enforces type safety via Pydantic, maintains observability, and composes naturally into larger workflows.(([[https://askmarvin.ai/|Marvin Documentation]])) The framework prioritizes making LLM interactions reliable and predictable while keeping the API minimal.

Core design principles:

  * **Type-safe results**, All outputs validated through Pydantic models
  * **Task-centric**, Discrete, observable units of work with clear objectives
  * **Composable**, Chain tasks into threads for complex multi-step workflows
  * **Flexible control**, Tune autonomy vs. determinism per task
  * **Multi-agent**, Assign specialized agents to specific tasks

===== Installation =====
<code bash>
pip install marvin
# or with uv
uv add marvin
</code>

Configure your LLM provider:

<code bash>
export OPENAI_API_KEY="your-api-key"
</code>

===== Core Functions =====
Marvin provides high-level functions for common LLM tasks:(([[https://pypi.org/project/marvin/|Marvin on PyPI]]))

<code python>
import marvin
from pydantic import BaseModel


#, cast: Convert unstructured text to typed objects ---
class Location(BaseModel):
    city: str
    state: str
    country: str

location = marvin.cast("The Big Apple", target=Location)
# Location(city=New York, state=NY, country=US)


#, classify: Categorize data into labels ---
sentiment = marvin.classify(
    "I absolutely love this product!",
    labels=["positive", "negative", "neutral"]
)
# "positive"


#, extract: Pull structured data from text ---
class Contact(BaseModel):
    name: str
    email: str

contacts = marvin.extract(
    "Reach out to Alice at alice@example.com or Bob at bob@test.io",
    target=Contact
)
# [Contact(name=Alice, email=alice@example.com),
#  Contact(name=Bob, email=bob@test.io)]


#, generate: Produce [[structured_outputs|structured outputs]] ---
colors = marvin.generate(
    target=str,
    instructions="Generate 5 creative color names for a cyberpunk palette",
    n=5
)


#, fn: AI-powered function decorator ---
@marvin.fn
def summarize(text: str, max_words: int = 50) -> str:
    "Summarize the given text in the specified number of words."

summary = summarize("Long article text here...", max_words=30)
</code>

===== Agentic Workflows (v3.0) =====
Marvin v3.0 introduces a full agentic control flow engine:(([[https://prefect.io/marvin|Marvin on Prefect.io]]))

<mermaid>
graph TD
    subgraph Thread["marvin.Thread: shared context"]
        A[Task 1: Research] --> B[Task 2: Write Article - agent=Writer]
        B --> C[Task 3: Review and Edit - agent=Editor]
    end
</mermaid>

<code python>
import marvin
from pydantic import BaseModel


class Article(BaseModel):
    title: str
    content: str
    key_points: liststr


# Define specialized agents
writer = marvin.Agent(
    name="Writer",
    instructions="Write clear, engaging content for a technical audience."
)

editor = marvin.Agent(
    name="Editor",
    instructions="Review and improve articles for clarity and accuracy."
)

# Orchestrate with a Thread (shared context)
with marvin.Thread() as thread:
    # Task 1: Research
    key_points = marvin.run(
        "Research the top 5 trends in AI agent frameworks for 2025",
        result_type=liststr
    )

    # Task 2: Write (assigned to writer agent)
    draft = marvin.run(
        "Write a technical article using the research",
        agent=writer,
        result_type=Article,
        context={"research": key_points}
    )

    # Task 3: Edit (assigned to editor agent)
    final = marvin.run(
        "Review and polish the article",
        agent=editor,
        result_type=Article,
        context={"draft": draft}
    )

print(f"Title: {final.title}")
print(final.content)
</code>

===== Planning and Teams =====
<code python>
import marvin

# AI-powered [[task_decomposition|task decomposition]]
tasks = marvin.plan("Create a comprehensive blog post about AI trends")
marvin.run_tasks(tasks)

# Team coordination
from marvin import Team, Swarm

# Structured team with delegation rules
research_team = Team(
    agents=[researcher, analyst],
    instructions="Collaborate on research tasks"
)

# Swarm: free-form delegation among agents
creative_swarm = Swarm(agents=[writer, designer, editor])
</code>

===== Integration with Prefect =====
Marvin integrates naturally with Prefect for production orchestration:

<code python>
from prefect import flow
import marvin

@flow
def process_github_issue(issue_payload: dict):
    summary = marvin.cast(
        issue_payload["body"],
        target=str,
        instructions="Summarize this [[github|GitHub]] issue in one sentence"
    )

    category = marvin.classify(
        summary,
        labels=["bug", "feature_request", "question", "documentation"]
    )

    response = marvin.generate(
        target=str,
        instructions=f"Write a helpful response to this {category} issue",
        context={"summary": summary}
    )

    return {"summary": summary, "category": category, "response": response}
</code>

===== Key Features in v3.0 =====
  * **Streaming responses**, Real-time output streaming for interactive applications
  * **Tool support**, Custom Python functions as agent tools
  * **Observability**, Built-in tracing and progress tracking
  * **Multimodal**, Image and audio input support
  * **Multiple LLM providers**, [[openai|OpenAI]] (default), [[claude|Claude]], and all Pydantic AI-supported models

===== See Also =====
  * [[hermes_agent|Hermes Agent]]
  * [[how_to_build_a_coding_agent|How to Build a Coding Agent]]
  * [[xagent|XAgent: Autonomous LLM Agent for Complex Tasks]]
  * [[langflow|Langflow]]
  * [[open_interpreter|Open Interpreter: Local AI Agent & Terminal AI Agent]]

===== References =====