Marvin with Python: Automated Structured Data Extraction and Classification Using AI Functions

Artificial Intelligence tutorial - IT technology blog
Artificial Intelligence tutorial - IT technology blog

Background & Real-World Challenges

Handling unstructured, free-form text from users is never easy. Complaint emails, customer support messages, OCR-scanned invoices, and order notes are notoriously messy. You have to break those strings down into a standardized format to ingest into PostgreSQL. The traditional approach usually relies on regular expressions and endless tangled if-else conditions. All it takes is a single typo or a different phrasing from the customer, and the parser completely falls apart.

As LLMs became widespread, calling the OpenAI API with JSON mode felt like an obvious solution. However, manually crafting prompts with raw JSON Schemas often leads to frustrating debugging sessions. Models frequently add conversational pleasantries outside the JSON block, drop required fields, or return strings instead of integers. Meanwhile, LangChain is overly complex, introducing too many unnecessary layers of abstraction for straightforward data extraction tasks.

When our system traffic surged past 3,000 tickets a day, our team had to find a leaner, cleaner approach. The requirements were straightforward: it had to be type-safe, enforce strict application-level validation, and feel like idiomatic Python. That is why we chose Marvin as the core library for our extraction service over the past six months.

Developed by the Prefect team, Marvin turns large language models into standard Python functions (AI Functions) with deep Pydantic integration. Instead of wrestling with lengthy prompt templates, you simply define functions with clear type hints; Marvin takes care of the semantic reasoning and schema validation under the hood.

Environment Setup

Marvin works best on Python 3.10 and above. You should create a dedicated virtual environment to isolate dependencies:

# Initialize and activate virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Install Marvin, Pydantic v2, and python-dotenv
pip install marvin pydantic python-dotenv

By default, Marvin connects directly to OpenAI. If your internal infrastructure has strict security requirements, you can easily point it to Azure OpenAI, Claude, or a self-hosted Ollama cluster.

Connection Configuration

Create a .env file in the project root directory to store your API key and default model:

OPENAI_API_KEY="sk-proj-xxxxxxxxxxxxxxxxxxxxxxxx"
MARVIN_CHAT_COMPLETION_MODEL="gpt-4o-mini"

For classification and entity extraction tasks, gpt-4o-mini offers the best balance. Average response latency sits at just 250ms–400ms, accuracy exceeds 96%, and costs are 15 times cheaper than gpt-4o.

1. Instant Content Classification with marvin.classify

Consider the task of triaging customer support tickets by urgency. Instead of stuffing a two-page prompt with instructions for the LLM, you only need a standard Enum:

from enum import Enum
from dotenv import load_dotenv
import marvin

load_dotenv()

class Priority(Enum):
    LOW = "General inquiries, feature requests, business hours questions"
    MEDIUM = "Minor display issues, non-blocking payment flow"
    HIGH = "Double charge errors, security vulnerabilities, service outages"

customer_message = "My account was charged twice for 500k, but the order still shows canceled. Please resolve this immediately!"

# Classify directly into an Enum
result = marvin.classify(customer_message, Priority)
print(f"Priority: {result.name} | Definition: {result.value}")
# Output: Priority: HIGH | Definition: Double charge errors, security vulnerabilities, service outages

Marvin automatically leverages the Enum values and docstrings as context for classification. No manual prompting required. The output is a standard Enum instance, ready for immediate conditional routing.

2. Extracting Data to Pydantic Schemas with marvin.extract

Next scenario: a customer sends an unformatted hotel booking email. We need to extract their name, phone number, check-in date, and special requests into the database.

from typing import List, Optional
from datetime import date
from pydantic import BaseModel, Field
import marvin

class BookingRequest(BaseModel):
    customer_name: str = Field(description="Customer name")
    phone_number: Optional[str] = Field(None, description="10-digit phone number")
    checkin_date: Optional[date] = Field(None, description="Check-in date")
    room_count: int = Field(default=1, description="Number of rooms booked")
    special_notes: List[str] = Field(default_factory=list, description="Additional requests")

raw_email = """
Hello, I am Minh Tuan (0912345678).
Our team needs to book 3 rooms on November 25, 2026.
Please arrange high floors with ocean views and a workspace.
"""

# Extract data matching the Pydantic schema
bookings = marvin.extract(raw_email, target=BookingRequest)

for booking in bookings:
    print(booking.model_dump_json(indent=2))

The output is a fully validated Pydantic instance. The checkin_date field is automatically coerced into a datetime.date object, and the room count is parsed as an int. You can pass this object straight into an SQLAlchemy session without worrying about type mismatch errors.

3. Transforming Python Functions into AI Functions with @marvin.fn

This is arguably the most powerful feature of the library. The @marvin.fn decorator turns a function’s signature and docstring into the model’s execution logic:

from pydantic import BaseModel
import marvin

class NormalizedAddress(BaseModel):
    street: str
    ward: str
    district: str
    province: str

@marvin.fn
def parse_vietnamese_address(raw_text: str) -> NormalizedAddress:
    """
    Parse an abbreviated or non-standard shipping address in Vietnam
    into 4 administrative levels: house number/street, ward/commune, district, and province/city.
    """

address_input = "no 45 lane 120 tran duy hung, trung hoa, cau giay hn"
parsed = parse_vietnamese_address(address_input)

print(f"{parsed.street} | {parsed.ward} | {parsed.district} | {parsed.province}")
# Output: No. 45 Lane 120 Tran Duy Hung | Trung Hoa Ward | Cau Giay District | Hanoi

This function behaves just like native code in your codebase. The service layer invokes it without ever needing to know which model runs underneath.

Production Operations Insights

Integrating LLMs into your core application flow requires solid defensive engineering. You cannot leave system stability at the mercy of external network conditions.

1. Wrapping Fallbacks and Managing Timeouts

The OpenAI API can experience network congestion or rate limits. Proactively set timeouts and handle exceptions to return safe fallback values:

import logging
import marvin

marvin.settings.openai.chat.completions.timeout = 5.0

def safe_classify_ticket(ticket_content: str) -> Priority:
    try:
        return marvin.classify(ticket_content, Priority)
    except Exception as exc:
        logging.error(f"LLM classification failed: {exc}")
        # Fallback to default priority to avoid breaking the processing pipeline
        return Priority.MEDIUM

2. Slashing Costs by 45% with Caching

In practice, around 30% to 40% of requests share very similar content. Attaching a Redis cache or functools.lru_cache keyed on the input hash will save a substantial portion of your budget:

from functools import lru_cache

@lru_cache(maxsize=4096)
@marvin.fn
def standardize_brand_name(raw_name: str) -> str:
    """Normalize fashion brand names to their official format (e.g., nk -> Nike)."""

On our team, caching the 4,096 most common search queries reduced our monthly OpenAI bill from $420 down to $230.

3. Writing Automated Unit Tests for AI Functions

Never deploy AI functions without automated tests. Use pytest with set-membership assertions to verify output reliability:

# tests/test_address_parser.py
def test_parse_vietnamese_address():
    raw = "1 Dai Co Viet, Bach Khoa, Hai Ba Trung, Hanoi"
    res = parse_vietnamese_address(raw)
    
    assert res.province in ["Hanoi", "Hanoi City"]
    assert res.district in ["Hai Ba Trung", "Hai Ba Trung District"]
    assert "1 Dai Co Viet" in res.street

Marvin delivers a remarkably intuitive developer experience. Instead of cobbling together brittle prompt strings, you work directly with type hints and robust objects. It is the most pragmatic approach to bringing AI into modern backend architectures.

Share: