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

# Cast

> Convert data between types while preserving meaning

The `cast` function is your bridge between natural language and structured data types. It transforms `str → T` while preserving meaning, making it easy to convert:

* Natural numbers ("three point five" → 3.5)
* Casual responses ("sounds good" → True)
* Time expressions ("next Tuesday" → datetime)
* Rich descriptions ("John is 25" → Person(name="John", age=25))

For complex transformations, consider creating a custom task. The `cast` function is a convenient wrapper around Marvin's task system - see [Tasks](/concepts/tasks) for more details.

## Usage

Convert natural language descriptions of numbers into their numeric representation:

```python theme={null}
import marvin

# Convert text to a number
price = marvin.cast("three dollars and fifty cents", float)
print(price)
```

```python theme={null}
3.5
```

## Parameters

* `data`: The input data to convert (any type)
* `target`: The target type to convert to (defaults to `str`)
* `instructions`: Optional instructions to guide the conversion
* `agent`: Optional custom agent to use
* `thread`: Optional thread for conversation context
* `context`: Optional additional context

## Async Support

The function is also available in an async version:

```python theme={null}
import marvin
import asyncio

async def main():
    result = await marvin.cast_async(
        "three point five",
        float
    )
    print(result)  # 3.5

asyncio.run(main())
```

## Examples

### Converting Numbers

Convert natural language descriptions of quantities into numeric values:

```python theme={null}
import marvin

price = marvin.cast("three dollars and fifty cents", float)
print(price)
```

```python theme={null}
3.5
```

### Boolean Conversion

Interpret natural language expressions as boolean values:

```python theme={null}
import marvin

answer = marvin.cast("that sounds great!", bool)
print(answer)
```

```python theme={null}
True
```

### Structured Data

Extract structured information from natural language descriptions:

```python theme={null}
import marvin
from dataclasses import dataclass

@dataclass
class Address:
    street: str
    city: str
    country: str

address = marvin.cast(
    "123 Main St in New York, USA",
    Address
)
print(f"{address.street}, {address.city}, {address.country}")
```

```python theme={null}
"123 Main St", "New York", "USA"
```

### Custom Instructions

Use instructions to control how text is interpreted and formatted:

```python theme={null}
from typing import Annotated
import marvin
from pydantic import Field

phone = marvin.cast(
    "call me at 800-555-0123",
    Annotated[str, Field(pattern=r"\d{1}-\d{3}-\d{3}-\d{4}")],
    instructions="extract the phone number and assume the country code is 1"
)
print(phone)
```

```python theme={null}
"1-800-555-0123"
```