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"