Quickstart - Marvin

Install Marvin and configure a provider before running these examples.

Extract structured data

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)

extract returns a list of Contact objects. Use cast when you want one value, or run for instructions with an explicit result_type.

Give an agent a tool

import marvin

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

agent = marvin.Agent(
    name="Inventory",
    instructions="Use stock_level to answer inventory questions.",
    tools=[stock_level],
)
count = agent.run("How many notebooks are in stock?", result_type=int)
print(count)

The model chooses when to call a tool. Marvin validates its arguments and returns the tool’s result to the model.

import marvin

with marvin.Thread() as thread:
    marvin.say("My order number is 12345.")
    order_number = marvin.run("What is my order number?", result_type=int)

print(order_number)
print(thread.id)

Save the thread ID to resume the same history later. See threads for persistence and tasks for explicit task objects and dependencies. In async code, use functions such as await marvin.extract_async(...) or await agent.run_async(...).

⌘I