> ## Documentation Index
> Fetch the complete documentation index at: https://askmarvin.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```python theme={null}
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)
```

<Accordion title="Output">
  ```python theme={null}
  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']
  ```
</Accordion>

## 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:

```python theme={null}
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

```python theme={null}
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

```python theme={null}
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

```python theme={null}
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

```python theme={null}
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:

```python theme={null}
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

```python theme={null}
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())
```