Run

Execute AI tasks with a single line of code

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)

Output

Keys tap in silence,
Ideas flow through the night air,
Code becomes my art.

Chocolate Chip Cookies
['1 cup unsalted butter, softened', '1 cup white sugar', '1 cup packed brown sugar', '2 large eggs', '2 teaspoons vanilla extract', '3 cups all-purpose flour', '1 teaspoon baking soda', '1/2 teaspoon baking powder', '1/2 teaspoon salt', '2 cups semisweet chocolate chips']

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())