Python reference¶

The seams worth programming against, not every module. LabeloxAV has roughly 600 Python modules; auto-dumping all of them produces a reference nobody can navigate and that goes stale the moment an internal helper moves. What follows is the surface that is deliberately stable: the domain-pack contract, the engine's bridge to it, and the measurement primitives.

The domain pack contract¶

A pack is how one engine serves two domains. packs/av is autonomous driving; packs/sec is physical security. The engine never imports either: .importlinter forbids core, services and db from importing packs.av or packs.sec, and everything goes through the registry.

packs.base.DomainPack ¶

Bases: Protocol

The contract a concrete pack satisfies. Attribute-only Protocol: any object exposing these fields is a DomainPack (runtime_checkable checks presence). scene_model / ingestion_adapters are Optional / empty until SEC-M2 wires the scene-model fork; every other surface is real in SEC-M1.

Source code in packs/base.py

@runtime_checkable
class DomainPack(Protocol):
    """The contract a concrete pack satisfies. Attribute-only Protocol: any object exposing these fields is a
    DomainPack (runtime_checkable checks presence). scene_model / ingestion_adapters are Optional / empty until
    SEC-M2 wires the scene-model fork; every other surface is real in SEC-M1.
    """
    manifest: PackManifest
    ontology: OntologySpec
    safety_policy: SafetyPolicy
    autolabel_profile: AutoLabelProfile
    eval_strata: EvalStrataSpec
    quality_profile: QualityProfile
    forge_targets: Sequence[ForgeTarget]
    privacy: PrivacyPlaneSpec
    relations: RelationSpec | None
    cliques: CliqueSpec | None
    class_tree: ClassTree | None
    motion_models: MotionModelSpec | None
    scene_model: SceneModelFactory | None
    ingestion_adapters: Sequence[IngestionAdapter]
    # Optional: the frame-level vocabulary a person may set on Frame.scene. Empty means the domain has
    # nothing to say about the scene as a whole.
    context: ContextSpec | None
    track_events: TrackEventSpec | None
    # Optional because they are genuinely domain-specific rather than merely unfinished: an AV pack has no
    # fixed zones to police and no camera to open. A pack that does not fill them is complete, and the engine
    # refuses the corresponding route rather than pretending the capability exists.
    zone_policy: ZonePolicy | None
    stream_source: StreamSource | None

packs.base.OntologySpec `dataclass` ¶

The taxonomy plus the ontology facts the audit found in code rather than in the governed YAML.

yaml_path is the governed, versioned artifact (unchanged for AV). stuff_names / stuff_l0 externalise the panoptic split that was a frozenset in services/autolabel/ontology.py:31. supported_core externalises core/config.py:396. superclass_map / size_priors are consumed when the quality reviewer moves behind the pack in SEC-M5; they are None until then (honest incremental fill, not a stub).

Source code in packs/base.py

@dataclass(frozen=True)
class OntologySpec:
    """The taxonomy plus the ontology facts the audit found in code rather than in the governed YAML.

    yaml_path is the governed, versioned artifact (unchanged for AV). stuff_names / stuff_l0 externalise the
    panoptic split that was a frozenset in services/autolabel/ontology.py:31. supported_core externalises
    core/config.py:396. superclass_map / size_priors are consumed when the quality reviewer moves behind the
    pack in SEC-M5; they are None until then (honest incremental fill, not a stub).
    """
    yaml_path: str
    stuff_names: frozenset[str]
    stuff_l0: frozenset[str]
    supported_core: frozenset[str]
    custom_id_base: int
    superclass_map: Mapping[str, str] | None = None       # SEC-M5
    size_priors: Mapping[str, SizeBound] | None = None     # SEC-M5

packs.base.CliqueSpec `dataclass` ¶

The confusion cliques of a domain, and the cost of confusing classes across them.

Held by the pack because which classes a model confuses is a fact about the world it works in: a scooter and a motorcycle are one decision on an Indian road and two unrelated objects in a warehouse.

Source code in packs/base.py

@dataclass(frozen=True)
class CliqueSpec:
    """The confusion cliques of a domain, and the cost of confusing classes across them.

    Held by the pack because which classes a model confuses is a fact about the world it works in: a
    scooter and a motorcycle are one decision on an Indian road and two unrelated objects in a warehouse.
    """
    cliques: tuple[ConfusionClique, ...]
    # Cost of confusing two classes that are not in a clique together. Higher than any within-clique cost
    # by construction: a confusion the ontology did not anticipate is worse than one it did.
    cross_clique_cost: float = 1.0

    def by_name(self, name: str) -> ConfusionClique | None:
        for c in self.cliques:
            if c.name == name:
                return c
        return None

    def clique_of(self, class_name: str) -> ConfusionClique | None:
        for c in self.cliques:
            if class_name in c.class_names:
                return c
        return None

    def pair_cost(self, a: str, b: str) -> float:
        """Cost of confusing a for b. Zero for a class with itself, the clique cost within one, else cross."""
        if a == b:
            return 0.0
        ca, cb = self.clique_of(a), self.clique_of(b)
        if ca is not None and ca is cb:
            return ca.cost
        return self.cross_clique_cost

pair_cost ¶

pair_cost(a, b)

Cost of confusing a for b. Zero for a class with itself, the clique cost within one, else cross.

Source code in packs/base.py

def pair_cost(self, a: str, b: str) -> float:
    """Cost of confusing a for b. Zero for a class with itself, the clique cost within one, else cross."""
    if a == b:
        return 0.0
    ca, cb = self.clique_of(a), self.clique_of(b)
    if ca is not None and ca is cb:
        return ca.cost
    return self.cross_clique_cost

packs.base.RelationSpec `dataclass` ¶

The relationship vocabulary, and which ordered class pairs can stand in which relation.

Two disjoint vocabularies are live in the engine today and neither knows about the other: services/api/routers/objects.py validates {rider_of, towed_by, part_of, member_of, occludes} on the editor path, while services/intelligence/scene_graph.py inserts {occluded_by, following, crossing_in_front_of, parked_near} directly and never passes that validation. occludes and occluded_by are the same fact in opposite directions and both are stored, so a query for one silently misses half the corpus.

kinds is the union any writer may use. overlap_pairs maps an ordered (subject l1, object l1) pair to the relation an overlapping pair of those superclasses probably stands in, which is what lets relationship-aware NMS keep a rider and their motorcycle apart and say why. inverse records the pairs that are one fact in two directions, so a reader can normalise rather than guess.

Source code in packs/base.py

@dataclass(frozen=True)
class RelationSpec:
    """The relationship vocabulary, and which ordered class pairs can stand in which relation.

    Two disjoint vocabularies are live in the engine today and neither knows about the other:
    services/api/routers/objects.py validates {rider_of, towed_by, part_of, member_of, occludes} on the
    editor path, while services/intelligence/scene_graph.py inserts {occluded_by, following,
    crossing_in_front_of, parked_near} directly and never passes that validation. `occludes` and
    `occluded_by` are the same fact in opposite directions and both are stored, so a query for one silently
    misses half the corpus.

    `kinds` is the union any writer may use. `overlap_pairs` maps an ordered (subject l1, object l1) pair
    to the relation an overlapping pair of those superclasses probably stands in, which is what lets
    relationship-aware NMS keep a rider and their motorcycle apart and say why. `inverse` records the pairs
    that are one fact in two directions, so a reader can normalise rather than guess.
    """
    kinds: frozenset[str]
    overlap_pairs: Mapping[tuple[str, str], str]
    inverse: Mapping[str, str] = field(default_factory=dict)

    def relation_for_l1(self, subject_l1: str, object_l1: str) -> str | None:
        return self.overlap_pairs.get((subject_l1, object_l1))

    def canonical(self, kind: str) -> str:
        """The direction this engine stores. An inverse maps to its canonical form; anything else is itself."""
        return self.inverse.get(kind, kind)

canonical ¶

canonical(kind)

The direction this engine stores. An inverse maps to its canonical form; anything else is itself.

Source code in packs/base.py

def canonical(self, kind: str) -> str:
    """The direction this engine stores. An inverse maps to its canonical form; anything else is itself."""
    return self.inverse.get(kind, kind)

packs.base.TrackEventSpec `dataclass` ¶

The track-event vocabulary of a domain.

Source code in packs/base.py

@dataclass(frozen=True)
class TrackEventSpec:
    """The track-event vocabulary of a domain."""

    types: tuple[TrackEventType, ...]

    def names(self) -> frozenset[str]:
        return frozenset(t.name for t in self.types)

    def get(self, name: str) -> TrackEventType | None:
        return next((t for t in self.types if t.name == name), None)

packs.base.ContextSpec `dataclass` ¶

Frame-level facts a domain wants recorded that are not about any one object.

Kept separate from the object attribute schema because the question is different: an object attribute says what a thing is, a context attribute says what the whole scene was like, and the same frame carries one of each per axis. The engine already stores this on Frame.scene, which the ingest classifier fills with density, weather, road_type and time_of_day; this is the vocabulary a person may add to it.

A domain with nothing to say about the scene leaves it empty and the editor shows no context panel, rather than the engine inventing weather categories for a warehouse camera.

Source code in packs/base.py

@dataclass(frozen=True)
class ContextSpec:
    """Frame-level facts a domain wants recorded that are not about any one object.

    Kept separate from the object attribute schema because the question is different: an object attribute
    says what a thing is, a context attribute says what the whole scene was like, and the same frame carries
    one of each per axis. The engine already stores this on `Frame.scene`, which the ingest classifier fills
    with density, weather, road_type and time_of_day; this is the vocabulary a person may add to it.

    A domain with nothing to say about the scene leaves it empty and the editor shows no context panel,
    rather than the engine inventing weather categories for a warehouse camera.
    """
    attributes: Mapping[str, AttributeSpec] = field(default_factory=dict)

    def validate(self, attrs: Mapping[str, object]) -> list[str]:
        """Errors, empty when valid. Same shape as the ontology's attribute validation so a caller that
        already handles one handles the other."""
        errors: list[str] = []
        for key, val in attrs.items():
            spec = self.attributes.get(key)
            if spec is None:
                errors.append(f"unknown context attribute '{key}'")
                continue
            errors.extend(spec.errors_for(key, val))
        return errors

validate ¶

validate(attrs)

Errors, empty when valid. Same shape as the ontology's attribute validation so a caller that already handles one handles the other.

Source code in packs/base.py

def validate(self, attrs: Mapping[str, object]) -> list[str]:
    """Errors, empty when valid. Same shape as the ontology's attribute validation so a caller that
    already handles one handles the other."""
    errors: list[str] = []
    for key, val in attrs.items():
        spec = self.attributes.get(key)
        if spec is None:
            errors.append(f"unknown context attribute '{key}'")
            continue
        errors.extend(spec.errors_for(key, val))
    return errors

packs.base.RegionSpec `dataclass` ¶

How a domain turns a recorded place string into a stratum.

A corpus records places the way the capture rig happened to spell them, and the strings are not a taxonomy: this one says BLR on 372 sessions and Bengaluru on one, which is a single city that looks like two strata to anything counting coverage.

resolve maps a lowercased, punctuation-free string to (city, state, urban_class), or None when the string names nowhere this domain models. classes is the urban_class vocabulary, ordered from largest, so a report can render the strata in a meaningful order rather than alphabetically.

Source code in packs/base.py

@dataclass(frozen=True)
class RegionSpec:
    """How a domain turns a recorded place string into a stratum.

    A corpus records places the way the capture rig happened to spell them, and the strings are not a
    taxonomy: this one says `BLR` on 372 sessions and `Bengaluru` on one, which is a single city that looks
    like two strata to anything counting coverage.

    `resolve` maps a lowercased, punctuation-free string to (city, state, urban_class), or None when the
    string names nowhere this domain models. `classes` is the urban_class vocabulary, ordered from largest,
    so a report can render the strata in a meaningful order rather than alphabetically.
    """

    resolve: Callable[[str], tuple[str, str, str] | None]
    classes: tuple[str, ...]
    # Every string `resolve` accepts. Published so a filter can be built by inverting the same table the
    # resolver reads, rather than by adding a denormalised region column that could drift from it.
    keys: Callable[[], frozenset[str]]
    # Places the domain knows are outside its region model, so a resolver can say "outside India" rather
    # than "unknown". The difference matters: unknown is a data-quality problem, outside is a fact.
    outside: Callable[[str], str | None] = lambda _s: None

The engine's bridge¶

Every per-domain question the engine asks goes through here, so a second domain behaves differently at runtime rather than only existing in the registry.

services.domain ¶

Engine-facing access to the active domain pack.

The single seam the engine uses to consult the pack it belongs to, without statically importing any concrete pack (it goes through packs.registry, the sanctioned bridge). Governance, curation, and eval call these instead of the {"vru","animal"} literals and hardcoded strata the audit found copy-pasted across the tree.

Every helper takes an optional pack_id and defaults to the configured active pack ('av'), so the legacy paths resolve to the AV pack and stay byte-identical. Per-session routing is pack_for_session: a session records the pack it was captured under (Session.pack_id), and passing that id here is what makes the second domain behave differently at runtime rather than only existing in the registry.