Structured Output

Define the fields your analysis should return instead of parsing free text. Use the resulting batch to create a Studio with the same schema as its taxonomy.

Define and run

Install nomadic, pydantic, and pandas, then define your schema:

import os
from typing import Literal

from pydantic import BaseModel
from nomadic import NomadicAI

client = NomadicAI(api_key=os.environ["NOMADIC_API_KEY"])


class RoadScene(BaseModel):
    weather: Literal["clear", "rain", "snow", "fog"]
    lighting: Literal["day", "night", "twilight"]


batch = client.analyze(
    ["VIDEO_ID_1", "VIDEO_ID_2"],
    "Identify road scenes and classify their weather and lighting.",
    output_schema=RoadScene,
)

The SDK validates the schema locally before sending the request. Prompt analysis supports structured output in the default mode="thinking", not mode="fast".

Read results

Get typed objects or a pandas table:

for scene in batch.structured(as_model=RoadScene):
    print(scene.weather, scene.lighting)

frame = batch.to_dataframe(only_structured=True)
print(frame[["video_id", "event_id", "weather", "lighting"]])

structured() without as_model returns dictionaries. Both examples skip events without a structured payload. DataFrame rows include event metadata alongside your schema fields; only the DataFrame helper requires pandas. Fetch an existing batch with client.video.get_batch_analysis("BATCH_ID") to use the same helpers.

Other schema formats

Without Pydantic, pass a list of field definitions as output_schema:

schema = [
    {"name": "weather", "type": "enum", "values": ["clear", "rain", "snow", "fog"]},
    {"name": "lighting", "type": "enum", "values": ["day", "night", "twilight"]},
]

Supported types are enum, text, number, boolean, and time_range. Schemas support up to 12 fields; enums require 2–64 distinct values. Use unique snake_case names, required=False for optional fields, and repeated=True for multiple values. Next: Create a Studio.

​Define and run

​Read results

​Other schema formats

Define and run

Read results

Other schema formats