The run function is the simplest way to execute AI tasks in Marvin. It provides a clean, one-line interface for running tasks while handling all the complexity of task creation and execution under the hood.

​
Motivation

While Marvin provides powerful tools for complex AI workflows, many use cases are simple and don’t need all that complexity. The run function provides:

  • A simple, intuitive interface
  • Sensible defaults
  • Type safety through result types
  • Easy access to common parameters

​
Usage

import marvin

# Simple text generation
poem = marvin.run(
    "Write a haiku about coding",
    result_type=str
)
print(poem)

# Structured output
from pydantic import BaseModel

class Recipe(BaseModel):
    name: str
    ingredients: list[str]
    steps: list[str]

recipe = marvin.run(
    "Create a recipe for chocolate chip cookies",
    result_type=Recipe
)
print(recipe.name)
print(recipe.ingredients)

​
Parameters

  • instructions: What you want the AI to do
  • result_type: The expected type of the result (defaults to str)
  • tools: Optional list of functions the AI can use
  • thread: Optional thread for conversation context
  • agents: Optional list of agents to use
  • raise_on_failure: Whether to raise exceptions on failure (defaults to True)
  • handlers: Optional list of handlers for events
  • **kwargs: Additional context passed to the task

​
Async Support

The function is also available in an async version:

import marvin
import asyncio

async def main():
    # Run a task asynchronously
    result = await marvin.run_async(
        "Translate 'hello' to French",
        result_type=str
    )
    print(result)

asyncio.run(main()) # bonjour

​
Examples

​
Simple Text Tasks

import marvin

# Generate text
story = marvin.run(
    "Write a short story about a robot learning to paint"
)
print(story)

# Answer questions
answer = marvin.run(
    "What is the capital of France?",
    result_type=str
)
print(answer)  # "Paris"

​
Using Tools

import marvin
import random

def roll_die() -> int:
    return random.randint(1, 6)

# Let the AI use tools
result = marvin.run(
    "Roll a die and tell me if it's higher than 3",
    result_type=bool,
    tools=[roll_die]
)
print(result)  # True or False depending on the roll

​
Structured Output

import marvin
from pydantic import BaseModel, Field

class MovieReview(BaseModel):
    title: str
    rating: float = Field(gt=0, lt=5)
    pros: list[str]
    cons: list[str]

# Get structured review
review = marvin.run(
    "Review the movie 'The Matrix'",
    result_type=MovieReview
)
print(review.rating)  # 4.8
print(review.pros)    # ["Groundbreaking special effects", "Deep philosophical themes"]

​
Using Context

import marvin

# Provide additional context
summary = marvin.run(
    "Summarize this data in 2-3 sentences",
    context={
        "data": "Long text to summarize...",
        "style": "technical"
    }
)
print(summary)

​
Multiple Tasks

The run_tasks function allows you to run multiple tasks at once:

import marvin

# Create tasks
task1 = marvin.Task(
    instructions="Write a haiku",
    result_type=str
)
task2 = marvin.Task(
    instructions="Write a limerick",
    result_type=str
)

# Run them together
tasks = marvin.run_tasks([task1, task2])
print(tasks[0].result)  # Haiku
print(tasks[1].result)  # Limerick

​
Async Multiple Tasks

import marvin
import asyncio

async def main():
    # Run multiple tasks asynchronously
    tasks = await marvin.run_tasks_async(
        [
            marvin.Task("Write a haiku"),
            marvin.Task("Write a limerick")
        ]
    )
    for task in tasks:
        print(task.result)

asyncio.run(main())