Add a taxonomy

Add a taxonomy when you want new fields on a Studio you created. Categorical and boolean fields use Studio search and deep reranking. Numeric fields use structured analysis so you can filter their values by threshold. Both run in the background. Use the Studio ID from its URL.

Adding a field does not prove that every physical occurrence was found or that every Studio event received a value. Search-based fields label matches found through retrieval and reranking. A missing value means not labeled here, not False and not proof that the condition was absent.

import os
from typing import Literal
from pydantic import BaseModel, Field
from nomadic import NomadicAI

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

class SceneConditions(BaseModel):
    weather: Literal["clear", "rain", "snow"] = Field(
        description="Weather visible in the scene"
    )
    lighting: Literal["day", "night"] = Field(
        description="Lighting conditions in the scene"
    )

run = client.studio.add_taxonomy(studio_id, SceneConditions)
print(run.id, run.status)  # A run ID and "processing"
run.wait(timeout=3600)

schema = client.studio.taxonomy_schema(studio_id)
results = client.studio.filter(studio_id, filters={"weather": "rain"})
print(results.total)

For categorical and boolean fields, the Studio publishes each field as it finishes. In the example, weather can appear in the filter rail while lighting is still processing. run.wait() prints which field is ready and returns once all fields finish. You can inspect run.completed_fields after run.refresh() or pass show_progress=False to silence updates. If a later field fails, earlier published fields remain available.

Run outcome	How to interpret it
`processing`	Some fields may already be visible; do not assume the taxonomy is complete.
`completed_fields`	Search-based fields published so far, not a count of events evaluated or a recall measure.
`done`	The run reached its terminal success state; it does not validate every label against source footage.
`failed` or `run.wait()` error	Inspect the run and retry or revise the failed field. Fields already published may remain.
`failed_videos`	Number of failed videos in a structured-analysis run; review this even if the run otherwise completed.

Check client.studio.taxonomy_schema(studio_id) for fields currently available to filters. client.studio.facet_rows(studio_id) exposes available, event_count, and truncated for the current event table. None is a count of all real-world occurrences in the source media. Each search-based field is classified into its own event bucket. Combined counts across fields use time overlap, so treat them as inferred combinations rather than direct observations from one event. Numeric fields use structured analysis and become available when that run completes. Field names already present on the Studio are rejected.

Fields and filters

Field type	Example definition	Example filter
Number	`speed_mps: float`	`{"speed_mps": "< 5"}` or `{"speed_mps": "> 20"}`
Boolean	`is_moving: bool`	`{"is_moving": True}` or `{"is_moving": False}`
Category	`weather: Literal["clear", "rain", "snow"]`	`{"weather": "rain"}`
Several values of one field	`weather` above	`{"weather": ["rain", "snow"]}` (OR)
Several fields	`speed_mps` and `is_moving`	`{"speed_mps": "< 5", "is_moving": True}` (AND)

To add numeric speed and a true/false field to an existing Studio:

class Motion(BaseModel):
    speed_mps: float = Field(description="Speed in metres per second")
    is_moving: bool = Field(description="Subject is visibly moving")

run = client.studio.add_taxonomy(studio_id, Motion)
run.wait()
print(run.failed_videos)  # Failed videos, if the structured run was partial

slow_motion = client.studio.filter(
    studio_id,
    filters={"speed_mps": "< 5", "is_moving": True},
)
fast_motion = client.studio.filter(studio_id, filters={"speed_mps": "> 20"})

Numeric filters accept <, =, or > followed by a finite number; they do not accept <= or >=. Numeric taxonomy fields run structured analysis, which can take longer than search-based labeling. Speed values are only as accurate as the source data and analysis allow. For numeric fields you already know at analysis time, you can also define them in Structured Output and create a Studio from that batch. Search-based labels may be absent when no matching event is retrieved. For a search-based boolean field, an absent label is not the same as False. Searches for different values are separate matching operations; do not assume every eligible event was assigned exactly one enum value or that competing matches were resolved as a mutually exclusive classifier. Review the resulting event values before using them as evaluation ground truth. speed_mps in this example is an inferred value, unless the source analysis has calibrated timing, geometry, or telemetry for metric speed. Units in the field name do not validate measurement accuracy. Check the data source and compare a sample against trusted measurements before applying thresholds such as < 5 or > 20 to a safety-critical dataset.

Overview

Getting Started

Dataset Studio

Deployment

Advanced

Legal

Fields and filters

​Fields and filters

Fields and filters