Cast

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 for more details.

​

Usage

Convert natural language descriptions of numbers into their numeric representation:

import marvin

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

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:

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:

import marvin

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

3.5

​

Boolean Conversion

Interpret natural language expressions as boolean values:

import marvin

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

True

​

Structured Data

Extract structured information from natural language descriptions:

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}")

"123 Main St", "New York", "USA"

​

Custom Instructions

Use instructions to control how text is interpreted and formatted:

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)

"1-800-555-0123"