feat(perception): define semantic object understanding
This commit is contained in:
DCCONSTRUCTIONS
@@ -0,0 +1,929 @@
|
||||
"""Versioned semantic, state and advisory-risk projection for an obstacle.
|
||||
|
||||
The projection composes an immutable :class:`ObstacleObservation` instead of
|
||||
changing the strict v1 geometry contract. Semantic identity, observed state,
|
||||
class priors and advisory risk remain separate claims with explicit evidence.
|
||||
None of them can create occupancy or acquire navigation, safety or actuation
|
||||
authority.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import json
|
||||
import math
|
||||
import re
|
||||
from dataclasses import dataclass
|
||||
from enum import StrEnum
|
||||
from pathlib import Path
|
||||
from typing import Final
|
||||
|
||||
from .contracts import FalseAuthority, MotionState, ObstacleObservation
|
||||
|
||||
OBJECT_UNDERSTANDING_SCHEMA: Final = "missioncore.object-understanding/v1"
|
||||
OBJECT_SEMANTIC_VOCABULARY_SCHEMA: Final = "missioncore.object-semantic-vocabulary/v0"
|
||||
MAX_SEMANTIC_HYPOTHESES: Final = 5
|
||||
|
||||
_IDENTIFIER = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._:/-]{0,159}$")
|
||||
_NORMALIZED_LABEL = re.compile(r"^[a-z0-9][a-z0-9_]{0,79}$")
|
||||
|
||||
|
||||
class ObjectUnderstandingError(ValueError):
|
||||
"""An object-understanding document or vocabulary is incompatible."""
|
||||
|
||||
|
||||
class EvidenceKind(StrEnum):
|
||||
DETECTOR = "detector"
|
||||
SEMANTIC_MASK = "semantic-mask"
|
||||
HUMAN_REVIEW = "human-review"
|
||||
GEOMETRY = "geometry"
|
||||
TEMPORAL = "temporal"
|
||||
POLICY = "policy"
|
||||
|
||||
|
||||
class SemanticResolution(StrEnum):
|
||||
UNRESOLVED = "unresolved"
|
||||
SELECTED = "selected"
|
||||
AMBIGUOUS = "ambiguous"
|
||||
CONFLICT = "conflict"
|
||||
|
||||
|
||||
class AgencyState(StrEnum):
|
||||
UNKNOWN = "unknown"
|
||||
INERT = "inert"
|
||||
ANIMATE = "animate"
|
||||
SELF_PROPELLED = "self-propelled"
|
||||
|
||||
|
||||
class StateBasis(StrEnum):
|
||||
UNKNOWN = "unknown"
|
||||
OBSERVED = "observed"
|
||||
CLASS_PRIOR = "class-prior"
|
||||
FUSED = "fused"
|
||||
|
||||
|
||||
class RiskLevel(StrEnum):
|
||||
UNKNOWN = "unknown"
|
||||
LOW = "low"
|
||||
ELEVATED = "elevated"
|
||||
HIGH = "high"
|
||||
CRITICAL = "critical"
|
||||
|
||||
|
||||
class RiskBasis(StrEnum):
|
||||
UNKNOWN = "unknown"
|
||||
SEMANTIC_PRIOR = "semantic-prior"
|
||||
OBSERVED_STATE = "observed-state"
|
||||
GEOMETRY = "geometry"
|
||||
FUSED = "fused"
|
||||
|
||||
|
||||
class AdvisoryResponse(StrEnum):
|
||||
MONITOR = "monitor"
|
||||
REDUCE_SPEED = "reduce-speed"
|
||||
YIELD = "yield"
|
||||
STOP = "stop"
|
||||
ROUTE_AROUND = "route-around"
|
||||
|
||||
|
||||
@dataclass(frozen=True, slots=True)
|
||||
class EvidenceProvenance:
|
||||
"""One source-bound evidence item used by semantic, state or risk claims."""
|
||||
|
||||
evidence_id: str
|
||||
kind: EvidenceKind
|
||||
source_id: str
|
||||
frame_id: str
|
||||
provider_id: str
|
||||
model_id: str | None
|
||||
model_revision: str | None
|
||||
preprocess_id: str | None
|
||||
prompt_set_id: str | None = None
|
||||
|
||||
def __post_init__(self) -> None:
|
||||
if not isinstance(self.kind, EvidenceKind):
|
||||
raise ObjectUnderstandingError("evidence kind is invalid")
|
||||
for value, label in (
|
||||
(self.evidence_id, "evidence id"),
|
||||
(self.source_id, "evidence source id"),
|
||||
(self.frame_id, "evidence frame id"),
|
||||
(self.provider_id, "evidence provider id"),
|
||||
):
|
||||
_identifier(value, label)
|
||||
for optional_value, label in (
|
||||
(self.model_id, "evidence model id"),
|
||||
(self.model_revision, "evidence model revision"),
|
||||
(self.preprocess_id, "evidence preprocess id"),
|
||||
(self.prompt_set_id, "evidence prompt-set id"),
|
||||
):
|
||||
_optional_identifier(optional_value, label)
|
||||
if self.kind in {EvidenceKind.DETECTOR, EvidenceKind.SEMANTIC_MASK} and (
|
||||
self.model_id is None or self.model_revision is None or self.preprocess_id is None
|
||||
):
|
||||
raise ObjectUnderstandingError(
|
||||
"model evidence requires model, revision and preprocess identity"
|
||||
)
|
||||
|
||||
def to_dict(self) -> dict[str, object]:
|
||||
return {
|
||||
"evidence_id": self.evidence_id,
|
||||
"kind": self.kind.value,
|
||||
"source_id": self.source_id,
|
||||
"frame_id": self.frame_id,
|
||||
"provider_id": self.provider_id,
|
||||
"model_id": self.model_id,
|
||||
"model_revision": self.model_revision,
|
||||
"preprocess_id": self.preprocess_id,
|
||||
"prompt_set_id": self.prompt_set_id,
|
||||
}
|
||||
|
||||
@classmethod
|
||||
def from_dict(cls, value: object) -> EvidenceProvenance:
|
||||
document = _object(value, "evidence provenance")
|
||||
_exact_keys(
|
||||
document,
|
||||
{
|
||||
"evidence_id",
|
||||
"kind",
|
||||
"source_id",
|
||||
"frame_id",
|
||||
"provider_id",
|
||||
"model_id",
|
||||
"model_revision",
|
||||
"preprocess_id",
|
||||
"prompt_set_id",
|
||||
},
|
||||
"evidence provenance",
|
||||
)
|
||||
return cls(
|
||||
evidence_id=_string(document, "evidence_id"),
|
||||
kind=_enum(EvidenceKind, document.get("kind"), "evidence kind"),
|
||||
source_id=_string(document, "source_id"),
|
||||
frame_id=_string(document, "frame_id"),
|
||||
provider_id=_string(document, "provider_id"),
|
||||
model_id=_optional_string(document.get("model_id"), "model id"),
|
||||
model_revision=_optional_string(document.get("model_revision"), "model revision"),
|
||||
preprocess_id=_optional_string(document.get("preprocess_id"), "preprocess id"),
|
||||
prompt_set_id=_optional_string(document.get("prompt_set_id"), "prompt-set id"),
|
||||
)
|
||||
|
||||
|
||||
@dataclass(frozen=True, slots=True)
|
||||
class SemanticHypothesis:
|
||||
"""One ranked canonical class hypothesis, never an occupancy identity."""
|
||||
|
||||
rank: int
|
||||
class_id: str
|
||||
raw_label: str
|
||||
confidence: float
|
||||
evidence_ids: tuple[str, ...]
|
||||
|
||||
def __post_init__(self) -> None:
|
||||
_positive_integer(self.rank, "semantic rank")
|
||||
_identifier(self.class_id, "semantic class id")
|
||||
_label(self.raw_label, "raw semantic label")
|
||||
_confidence(self.confidence, "semantic confidence")
|
||||
_unique_identifiers(self.evidence_ids, "semantic evidence ids")
|
||||
|
||||
def to_dict(self) -> dict[str, object]:
|
||||
return {
|
||||
"rank": self.rank,
|
||||
"class_id": self.class_id,
|
||||
"raw_label": self.raw_label,
|
||||
"confidence": self.confidence,
|
||||
"evidence_ids": list(self.evidence_ids),
|
||||
}
|
||||
|
||||
@classmethod
|
||||
def from_dict(cls, value: object) -> SemanticHypothesis:
|
||||
document = _object(value, "semantic hypothesis")
|
||||
_exact_keys(
|
||||
document,
|
||||
{"rank", "class_id", "raw_label", "confidence", "evidence_ids"},
|
||||
"semantic hypothesis",
|
||||
)
|
||||
return cls(
|
||||
rank=_integer(document, "rank"),
|
||||
class_id=_string(document, "class_id"),
|
||||
raw_label=_string(document, "raw_label"),
|
||||
confidence=_number(document, "confidence"),
|
||||
evidence_ids=_string_tuple(document.get("evidence_ids"), "evidence ids"),
|
||||
)
|
||||
|
||||
|
||||
@dataclass(frozen=True, slots=True)
|
||||
class SemanticDecision:
|
||||
"""Resolution over ranked hypotheses; ambiguity remains first-class."""
|
||||
|
||||
resolution: SemanticResolution
|
||||
selected_class_id: str | None
|
||||
selected_confidence: float | None
|
||||
reason_codes: tuple[str, ...]
|
||||
|
||||
def __post_init__(self) -> None:
|
||||
if not isinstance(self.resolution, SemanticResolution):
|
||||
raise ObjectUnderstandingError("semantic resolution is invalid")
|
||||
_optional_identifier(self.selected_class_id, "selected semantic class id")
|
||||
if self.selected_confidence is not None:
|
||||
_confidence(self.selected_confidence, "selected semantic confidence")
|
||||
_unique_identifiers(self.reason_codes, "semantic decision reasons")
|
||||
has_selection = self.selected_class_id is not None and self.selected_confidence is not None
|
||||
if self.resolution is SemanticResolution.SELECTED:
|
||||
if not has_selection:
|
||||
raise ObjectUnderstandingError("selected semantics require class and confidence")
|
||||
elif self.selected_class_id is not None or self.selected_confidence is not None:
|
||||
raise ObjectUnderstandingError("non-selected semantics cannot publish a selected class")
|
||||
|
||||
def to_dict(self) -> dict[str, object]:
|
||||
return {
|
||||
"resolution": self.resolution.value,
|
||||
"selected_class_id": self.selected_class_id,
|
||||
"selected_confidence": self.selected_confidence,
|
||||
"reason_codes": list(self.reason_codes),
|
||||
}
|
||||
|
||||
@classmethod
|
||||
def from_dict(cls, value: object) -> SemanticDecision:
|
||||
document = _object(value, "semantic decision")
|
||||
_exact_keys(
|
||||
document,
|
||||
{
|
||||
"resolution",
|
||||
"selected_class_id",
|
||||
"selected_confidence",
|
||||
"reason_codes",
|
||||
},
|
||||
"semantic decision",
|
||||
)
|
||||
return cls(
|
||||
resolution=_enum(
|
||||
SemanticResolution,
|
||||
document.get("resolution"),
|
||||
"semantic resolution",
|
||||
),
|
||||
selected_class_id=_optional_string(
|
||||
document.get("selected_class_id"), "selected class id"
|
||||
),
|
||||
selected_confidence=_optional_number(
|
||||
document.get("selected_confidence"), "selected confidence"
|
||||
),
|
||||
reason_codes=_string_tuple(document.get("reason_codes"), "reason codes"),
|
||||
)
|
||||
|
||||
|
||||
@dataclass(frozen=True, slots=True)
|
||||
class ObjectStateEstimate:
|
||||
"""Observed motion and agency prior, with their bases kept explicit."""
|
||||
|
||||
motion: MotionState
|
||||
motion_confidence: float
|
||||
agency: AgencyState
|
||||
agency_basis: StateBasis
|
||||
evidence_ids: tuple[str, ...]
|
||||
reason_codes: tuple[str, ...]
|
||||
|
||||
def __post_init__(self) -> None:
|
||||
if not isinstance(self.motion, MotionState):
|
||||
raise ObjectUnderstandingError("motion state is invalid")
|
||||
if not isinstance(self.agency, AgencyState):
|
||||
raise ObjectUnderstandingError("agency state is invalid")
|
||||
if not isinstance(self.agency_basis, StateBasis):
|
||||
raise ObjectUnderstandingError("agency basis is invalid")
|
||||
_confidence(self.motion_confidence, "motion confidence")
|
||||
_unique_identifiers(self.evidence_ids, "state evidence ids", allow_empty=True)
|
||||
_unique_identifiers(self.reason_codes, "state reason codes")
|
||||
if self.agency is AgencyState.UNKNOWN:
|
||||
if self.agency_basis is not StateBasis.UNKNOWN:
|
||||
raise ObjectUnderstandingError("unknown agency must retain unknown evidence basis")
|
||||
elif self.agency_basis is StateBasis.UNKNOWN:
|
||||
raise ObjectUnderstandingError("agency claim requires an explicit basis")
|
||||
|
||||
def to_dict(self) -> dict[str, object]:
|
||||
return {
|
||||
"motion": self.motion.value,
|
||||
"motion_confidence": self.motion_confidence,
|
||||
"agency": self.agency.value,
|
||||
"agency_basis": self.agency_basis.value,
|
||||
"evidence_ids": list(self.evidence_ids),
|
||||
"reason_codes": list(self.reason_codes),
|
||||
}
|
||||
|
||||
@classmethod
|
||||
def from_dict(cls, value: object) -> ObjectStateEstimate:
|
||||
document = _object(value, "object state")
|
||||
_exact_keys(
|
||||
document,
|
||||
{
|
||||
"motion",
|
||||
"motion_confidence",
|
||||
"agency",
|
||||
"agency_basis",
|
||||
"evidence_ids",
|
||||
"reason_codes",
|
||||
},
|
||||
"object state",
|
||||
)
|
||||
return cls(
|
||||
motion=_enum(MotionState, document.get("motion"), "motion state"),
|
||||
motion_confidence=_number(document, "motion_confidence"),
|
||||
agency=_enum(AgencyState, document.get("agency"), "agency state"),
|
||||
agency_basis=_enum(StateBasis, document.get("agency_basis"), "agency basis"),
|
||||
evidence_ids=_string_tuple(document.get("evidence_ids"), "evidence ids"),
|
||||
reason_codes=_string_tuple(document.get("reason_codes"), "reason codes"),
|
||||
)
|
||||
|
||||
|
||||
@dataclass(frozen=True, slots=True)
|
||||
class AdvisoryRiskAssessment:
|
||||
"""Evidence-qualified risk hint that is never a planner command."""
|
||||
|
||||
policy_id: str
|
||||
level: RiskLevel
|
||||
confidence: float
|
||||
basis: RiskBasis
|
||||
responses: tuple[AdvisoryResponse, ...]
|
||||
evidence_ids: tuple[str, ...]
|
||||
reason_codes: tuple[str, ...]
|
||||
|
||||
def __post_init__(self) -> None:
|
||||
if not isinstance(self.level, RiskLevel):
|
||||
raise ObjectUnderstandingError("risk level is invalid")
|
||||
if not isinstance(self.basis, RiskBasis):
|
||||
raise ObjectUnderstandingError("risk basis is invalid")
|
||||
_identifier(self.policy_id, "risk policy id")
|
||||
_confidence(self.confidence, "risk confidence")
|
||||
_unique_enum_values(self.responses, "advisory responses", allow_empty=True)
|
||||
_unique_identifiers(self.evidence_ids, "risk evidence ids", allow_empty=True)
|
||||
_unique_identifiers(self.reason_codes, "risk reason codes")
|
||||
if self.level is RiskLevel.UNKNOWN:
|
||||
if self.basis is not RiskBasis.UNKNOWN or self.confidence != 0.0:
|
||||
raise ObjectUnderstandingError(
|
||||
"unknown risk must retain unknown basis and zero confidence"
|
||||
)
|
||||
elif self.basis is RiskBasis.UNKNOWN:
|
||||
raise ObjectUnderstandingError("risk claim requires an explicit basis")
|
||||
|
||||
def to_dict(self) -> dict[str, object]:
|
||||
return {
|
||||
"policy_id": self.policy_id,
|
||||
"level": self.level.value,
|
||||
"confidence": self.confidence,
|
||||
"basis": self.basis.value,
|
||||
"responses": [item.value for item in self.responses],
|
||||
"evidence_ids": list(self.evidence_ids),
|
||||
"reason_codes": list(self.reason_codes),
|
||||
}
|
||||
|
||||
@classmethod
|
||||
def from_dict(cls, value: object) -> AdvisoryRiskAssessment:
|
||||
document = _object(value, "advisory risk")
|
||||
_exact_keys(
|
||||
document,
|
||||
{
|
||||
"policy_id",
|
||||
"level",
|
||||
"confidence",
|
||||
"basis",
|
||||
"responses",
|
||||
"evidence_ids",
|
||||
"reason_codes",
|
||||
},
|
||||
"advisory risk",
|
||||
)
|
||||
return cls(
|
||||
policy_id=_string(document, "policy_id"),
|
||||
level=_enum(RiskLevel, document.get("level"), "risk level"),
|
||||
confidence=_number(document, "confidence"),
|
||||
basis=_enum(RiskBasis, document.get("basis"), "risk basis"),
|
||||
responses=tuple(
|
||||
_enum(AdvisoryResponse, item, "advisory response")
|
||||
for item in _array(document, "responses")
|
||||
),
|
||||
evidence_ids=_string_tuple(document.get("evidence_ids"), "evidence ids"),
|
||||
reason_codes=_string_tuple(document.get("reason_codes"), "reason codes"),
|
||||
)
|
||||
|
||||
|
||||
@dataclass(frozen=True, slots=True)
|
||||
class ObjectUnderstanding:
|
||||
"""Complete machine projection: geometry, semantics, state, risk and lineage."""
|
||||
|
||||
understanding_id: str
|
||||
vocabulary_id: str
|
||||
generated_monotonic_ns: int
|
||||
observation: ObstacleObservation
|
||||
hypotheses: tuple[SemanticHypothesis, ...]
|
||||
semantic: SemanticDecision
|
||||
state: ObjectStateEstimate
|
||||
risk: AdvisoryRiskAssessment
|
||||
provenance: tuple[EvidenceProvenance, ...]
|
||||
authority: FalseAuthority = FalseAuthority()
|
||||
|
||||
def __post_init__(self) -> None:
|
||||
_identifier(self.understanding_id, "understanding id")
|
||||
_identifier(self.vocabulary_id, "semantic vocabulary id")
|
||||
_nonnegative_integer(self.generated_monotonic_ns, "generation time")
|
||||
if not isinstance(self.observation, ObstacleObservation):
|
||||
raise ObjectUnderstandingError("object geometry observation is invalid")
|
||||
if (
|
||||
not isinstance(self.hypotheses, tuple)
|
||||
or any(not isinstance(item, SemanticHypothesis) for item in self.hypotheses)
|
||||
or len(self.hypotheses) > MAX_SEMANTIC_HYPOTHESES
|
||||
):
|
||||
raise ObjectUnderstandingError("semantic hypothesis set is invalid")
|
||||
if tuple(item.rank for item in self.hypotheses) != tuple(
|
||||
range(1, len(self.hypotheses) + 1)
|
||||
):
|
||||
raise ObjectUnderstandingError("semantic hypotheses must have contiguous ranks")
|
||||
class_ids = tuple(item.class_id for item in self.hypotheses)
|
||||
if len(set(class_ids)) != len(class_ids):
|
||||
raise ObjectUnderstandingError("semantic hypothesis classes must be unique")
|
||||
if any(
|
||||
self.hypotheses[index].confidence < self.hypotheses[index + 1].confidence
|
||||
for index in range(len(self.hypotheses) - 1)
|
||||
):
|
||||
raise ObjectUnderstandingError("semantic hypotheses must be ordered by confidence")
|
||||
if not isinstance(self.semantic, SemanticDecision):
|
||||
raise ObjectUnderstandingError("semantic decision is invalid")
|
||||
if not isinstance(self.state, ObjectStateEstimate):
|
||||
raise ObjectUnderstandingError("object state is invalid")
|
||||
if not isinstance(self.risk, AdvisoryRiskAssessment):
|
||||
raise ObjectUnderstandingError("advisory risk is invalid")
|
||||
if not isinstance(self.authority, FalseAuthority):
|
||||
raise ObjectUnderstandingError("object understanding authority is invalid")
|
||||
if not isinstance(self.provenance, tuple) or any(
|
||||
not isinstance(item, EvidenceProvenance) for item in self.provenance
|
||||
):
|
||||
raise ObjectUnderstandingError("evidence provenance is invalid")
|
||||
evidence_ids = tuple(item.evidence_id for item in self.provenance)
|
||||
if len(set(evidence_ids)) != len(evidence_ids):
|
||||
raise ObjectUnderstandingError("evidence provenance ids must be unique")
|
||||
if any(
|
||||
item.source_id != self.observation.source_id
|
||||
or item.frame_id != self.observation.frame_id
|
||||
for item in self.provenance
|
||||
):
|
||||
raise ObjectUnderstandingError("object evidence escaped its geometry source frame")
|
||||
known_evidence = set(evidence_ids)
|
||||
claimed_evidence = (
|
||||
{evidence_id for item in self.hypotheses for evidence_id in item.evidence_ids}
|
||||
| set(self.state.evidence_ids)
|
||||
| set(self.risk.evidence_ids)
|
||||
)
|
||||
if claimed_evidence - known_evidence:
|
||||
raise ObjectUnderstandingError("object claim references unknown evidence")
|
||||
if (
|
||||
self.semantic.resolution
|
||||
in {
|
||||
SemanticResolution.AMBIGUOUS,
|
||||
SemanticResolution.CONFLICT,
|
||||
}
|
||||
and not self.hypotheses
|
||||
):
|
||||
raise ObjectUnderstandingError("ambiguous or conflicting semantics require hypotheses")
|
||||
if self.semantic.resolution is SemanticResolution.CONFLICT and len(self.hypotheses) < 2:
|
||||
raise ObjectUnderstandingError("semantic conflict requires two hypotheses")
|
||||
if self.semantic.resolution is SemanticResolution.SELECTED:
|
||||
selected = next(
|
||||
(
|
||||
item
|
||||
for item in self.hypotheses
|
||||
if item.class_id == self.semantic.selected_class_id
|
||||
),
|
||||
None,
|
||||
)
|
||||
if selected is None or selected.confidence != self.semantic.selected_confidence:
|
||||
raise ObjectUnderstandingError(
|
||||
"selected semantics must match one ranked hypothesis"
|
||||
)
|
||||
|
||||
@property
|
||||
def occupancy_identity(self) -> str:
|
||||
"""Semantic or risk changes never replace the geometry-owned identity."""
|
||||
|
||||
return self.observation.occupancy_identity
|
||||
|
||||
def to_dict(self) -> dict[str, object]:
|
||||
return {
|
||||
"schema_version": OBJECT_UNDERSTANDING_SCHEMA,
|
||||
"understanding_id": self.understanding_id,
|
||||
"vocabulary_id": self.vocabulary_id,
|
||||
"generated_monotonic_ns": self.generated_monotonic_ns,
|
||||
"observation": self.observation.to_dict(),
|
||||
"hypotheses": [item.to_dict() for item in self.hypotheses],
|
||||
"semantic": self.semantic.to_dict(),
|
||||
"state": self.state.to_dict(),
|
||||
"risk": self.risk.to_dict(),
|
||||
"provenance": [item.to_dict() for item in self.provenance],
|
||||
"authority": self.authority.to_dict(),
|
||||
}
|
||||
|
||||
@classmethod
|
||||
def from_dict(cls, value: object) -> ObjectUnderstanding:
|
||||
document = _contract(
|
||||
value,
|
||||
OBJECT_UNDERSTANDING_SCHEMA,
|
||||
{
|
||||
"understanding_id",
|
||||
"vocabulary_id",
|
||||
"generated_monotonic_ns",
|
||||
"observation",
|
||||
"hypotheses",
|
||||
"semantic",
|
||||
"state",
|
||||
"risk",
|
||||
"provenance",
|
||||
"authority",
|
||||
},
|
||||
"object understanding",
|
||||
)
|
||||
return cls(
|
||||
understanding_id=_string(document, "understanding_id"),
|
||||
vocabulary_id=_string(document, "vocabulary_id"),
|
||||
generated_monotonic_ns=_integer(document, "generated_monotonic_ns"),
|
||||
observation=ObstacleObservation.from_dict(document.get("observation")),
|
||||
hypotheses=tuple(
|
||||
SemanticHypothesis.from_dict(item) for item in _array(document, "hypotheses")
|
||||
),
|
||||
semantic=SemanticDecision.from_dict(document.get("semantic")),
|
||||
state=ObjectStateEstimate.from_dict(document.get("state")),
|
||||
risk=AdvisoryRiskAssessment.from_dict(document.get("risk")),
|
||||
provenance=tuple(
|
||||
EvidenceProvenance.from_dict(item) for item in _array(document, "provenance")
|
||||
),
|
||||
authority=FalseAuthority.from_dict(document.get("authority")),
|
||||
)
|
||||
|
||||
|
||||
@dataclass(frozen=True, slots=True)
|
||||
class CanonicalObjectClass:
|
||||
"""One class in the bounded experimental object vocabulary."""
|
||||
|
||||
class_id: str
|
||||
parent_id: str | None
|
||||
aliases: tuple[str, ...]
|
||||
agency_prior: AgencyState
|
||||
risk_traits: tuple[str, ...]
|
||||
|
||||
def __post_init__(self) -> None:
|
||||
if not isinstance(self.agency_prior, AgencyState):
|
||||
raise ObjectUnderstandingError("canonical agency prior is invalid")
|
||||
_identifier(self.class_id, "canonical class id")
|
||||
_optional_identifier(self.parent_id, "canonical parent id")
|
||||
if not self.aliases:
|
||||
raise ObjectUnderstandingError("canonical class aliases must be nonempty")
|
||||
normalized = tuple(normalize_raw_label(item) for item in self.aliases)
|
||||
if len(set(normalized)) != len(normalized):
|
||||
raise ObjectUnderstandingError("canonical class aliases must be unique")
|
||||
_unique_identifiers(self.risk_traits, "class risk traits", allow_empty=True)
|
||||
|
||||
|
||||
@dataclass(frozen=True, slots=True)
|
||||
class ObjectSemanticVocabulary:
|
||||
"""Loaded executable vocabulary profile; not a runtime ontology service."""
|
||||
|
||||
vocabulary_id: str
|
||||
status: str
|
||||
scope: str
|
||||
classes: tuple[CanonicalObjectClass, ...]
|
||||
max_hypotheses: int
|
||||
|
||||
def __post_init__(self) -> None:
|
||||
_identifier(self.vocabulary_id, "vocabulary id")
|
||||
if self.status != "experimental":
|
||||
raise ObjectUnderstandingError("object vocabulary must remain experimental")
|
||||
_identifier(self.scope, "vocabulary scope")
|
||||
if not 1 <= self.max_hypotheses <= MAX_SEMANTIC_HYPOTHESES:
|
||||
raise ObjectUnderstandingError("vocabulary top-k bound is invalid")
|
||||
if not self.classes:
|
||||
raise ObjectUnderstandingError("object vocabulary must declare classes")
|
||||
by_id = {item.class_id: item for item in self.classes}
|
||||
if len(by_id) != len(self.classes):
|
||||
raise ObjectUnderstandingError("canonical class ids must be unique")
|
||||
for item in self.classes:
|
||||
if item.parent_id is not None and item.parent_id not in by_id:
|
||||
raise ObjectUnderstandingError("canonical class parent is undeclared")
|
||||
seen = {item.class_id}
|
||||
parent_id = item.parent_id
|
||||
while parent_id is not None:
|
||||
if parent_id in seen:
|
||||
raise ObjectUnderstandingError("canonical class hierarchy is cyclic")
|
||||
seen.add(parent_id)
|
||||
parent_id = by_id[parent_id].parent_id
|
||||
aliases = [normalize_raw_label(alias) for item in self.classes for alias in item.aliases]
|
||||
if len(set(aliases)) != len(aliases):
|
||||
raise ObjectUnderstandingError("canonical aliases must be globally unique")
|
||||
|
||||
def class_definition(self, class_id: str) -> CanonicalObjectClass:
|
||||
for item in self.classes:
|
||||
if item.class_id == class_id:
|
||||
return item
|
||||
raise ObjectUnderstandingError("canonical class is undeclared")
|
||||
|
||||
def resolve_label(self, raw_label: str) -> str | None:
|
||||
normalized = normalize_raw_label(raw_label)
|
||||
for item in self.classes:
|
||||
if normalized in {normalize_raw_label(alias) for alias in item.aliases}:
|
||||
return item.class_id
|
||||
return None
|
||||
|
||||
def ancestors(self, class_id: str) -> tuple[str, ...]:
|
||||
by_id = {item.class_id: item for item in self.classes}
|
||||
current = self.class_definition(class_id)
|
||||
result: list[str] = []
|
||||
while current.parent_id is not None:
|
||||
result.append(current.parent_id)
|
||||
current = by_id[current.parent_id]
|
||||
return tuple(result)
|
||||
|
||||
|
||||
def load_object_semantic_vocabulary(path: Path) -> ObjectSemanticVocabulary:
|
||||
"""Load and fail-close an executable vocabulary profile."""
|
||||
|
||||
try:
|
||||
document = json.loads(path.expanduser().resolve(strict=True).read_text("utf-8"))
|
||||
except (OSError, json.JSONDecodeError) as exc:
|
||||
raise ObjectUnderstandingError("object vocabulary cannot be read") from exc
|
||||
root = _object(document, "object semantic vocabulary")
|
||||
_exact_keys(
|
||||
root,
|
||||
{
|
||||
"schema_version",
|
||||
"vocabulary_id",
|
||||
"status",
|
||||
"scope",
|
||||
"classes",
|
||||
"policies",
|
||||
},
|
||||
"object semantic vocabulary",
|
||||
)
|
||||
if root.get("schema_version") != OBJECT_SEMANTIC_VOCABULARY_SCHEMA:
|
||||
raise ObjectUnderstandingError("object vocabulary schema is incompatible")
|
||||
policies = _object(root.get("policies"), "object vocabulary policies")
|
||||
_exact_keys(
|
||||
policies,
|
||||
{
|
||||
"occupancy_independent_of_semantics",
|
||||
"unknown_preserves_obstacle",
|
||||
"class_prior_is_not_observed_state",
|
||||
"risk_is_advisory_only",
|
||||
"planner_command_authority",
|
||||
"max_hypotheses",
|
||||
},
|
||||
"object vocabulary policies",
|
||||
)
|
||||
required_true = (
|
||||
"occupancy_independent_of_semantics",
|
||||
"unknown_preserves_obstacle",
|
||||
"class_prior_is_not_observed_state",
|
||||
"risk_is_advisory_only",
|
||||
)
|
||||
if (
|
||||
any(policies.get(key) is not True for key in required_true)
|
||||
or policies.get("planner_command_authority") is not False
|
||||
):
|
||||
raise ObjectUnderstandingError("object vocabulary authority policy changed")
|
||||
classes: list[CanonicalObjectClass] = []
|
||||
for raw in _array(root, "classes"):
|
||||
row = _object(raw, "canonical object class")
|
||||
_exact_keys(
|
||||
row,
|
||||
{"class_id", "parent_id", "aliases", "agency_prior", "risk_traits"},
|
||||
"canonical object class",
|
||||
)
|
||||
classes.append(
|
||||
CanonicalObjectClass(
|
||||
class_id=_string(row, "class_id"),
|
||||
parent_id=_optional_string(row.get("parent_id"), "parent id"),
|
||||
aliases=_string_tuple(row.get("aliases"), "aliases"),
|
||||
agency_prior=_enum(AgencyState, row.get("agency_prior"), "agency prior"),
|
||||
risk_traits=_string_tuple(row.get("risk_traits"), "risk traits"),
|
||||
)
|
||||
)
|
||||
return ObjectSemanticVocabulary(
|
||||
vocabulary_id=_string(root, "vocabulary_id"),
|
||||
status=_string(root, "status"),
|
||||
scope=_string(root, "scope"),
|
||||
classes=tuple(classes),
|
||||
max_hypotheses=_integer(policies, "max_hypotheses"),
|
||||
)
|
||||
|
||||
|
||||
def validate_object_understanding(
|
||||
value: ObjectUnderstanding,
|
||||
vocabulary: ObjectSemanticVocabulary,
|
||||
) -> None:
|
||||
"""Validate canonical class references without changing the document."""
|
||||
|
||||
if not isinstance(value, ObjectUnderstanding):
|
||||
raise ObjectUnderstandingError("object understanding is invalid")
|
||||
if value.vocabulary_id != vocabulary.vocabulary_id:
|
||||
raise ObjectUnderstandingError("object understanding vocabulary changed")
|
||||
declared = {item.class_id for item in vocabulary.classes}
|
||||
referenced = {item.class_id for item in value.hypotheses}
|
||||
if value.semantic.selected_class_id is not None:
|
||||
referenced.add(value.semantic.selected_class_id)
|
||||
if referenced - declared:
|
||||
raise ObjectUnderstandingError("object understanding uses undeclared classes")
|
||||
if len(value.hypotheses) > vocabulary.max_hypotheses:
|
||||
raise ObjectUnderstandingError("object understanding exceeds vocabulary top-k")
|
||||
|
||||
|
||||
def normalize_raw_label(value: str) -> str:
|
||||
"""Normalize a provider label only for alias lookup, never as class truth."""
|
||||
|
||||
_label(value, "raw semantic label")
|
||||
normalized = re.sub(r"[_\s-]+", "_", value.strip().lower())
|
||||
if _NORMALIZED_LABEL.fullmatch(normalized) is None:
|
||||
raise ObjectUnderstandingError("raw semantic label cannot be normalized")
|
||||
return normalized
|
||||
|
||||
|
||||
def _contract(
|
||||
value: object,
|
||||
schema: str,
|
||||
fields: set[str],
|
||||
label: str,
|
||||
) -> dict[str, object]:
|
||||
document = _object(value, label)
|
||||
_exact_keys(document, {"schema_version", *fields}, label)
|
||||
if document.get("schema_version") != schema:
|
||||
raise ObjectUnderstandingError(f"{label} schema is incompatible")
|
||||
return document
|
||||
|
||||
|
||||
def _object(value: object, label: str) -> dict[str, object]:
|
||||
if not isinstance(value, dict) or any(not isinstance(key, str) for key in value):
|
||||
raise ObjectUnderstandingError(f"{label} must be an object")
|
||||
return value
|
||||
|
||||
|
||||
def _exact_keys(document: dict[str, object], expected: set[str], label: str) -> None:
|
||||
if set(document) != expected:
|
||||
raise ObjectUnderstandingError(f"{label} fields are incompatible")
|
||||
|
||||
|
||||
def _array(document: dict[str, object], key: str) -> list[object]:
|
||||
value = document.get(key)
|
||||
if not isinstance(value, list):
|
||||
raise ObjectUnderstandingError(f"{key} must be an array")
|
||||
return value
|
||||
|
||||
|
||||
def _string(document: dict[str, object], key: str) -> str:
|
||||
return _string_value(document.get(key), key)
|
||||
|
||||
|
||||
def _string_value(value: object, label: str) -> str:
|
||||
if not isinstance(value, str) or not value:
|
||||
raise ObjectUnderstandingError(f"{label} must be a nonempty string")
|
||||
return value
|
||||
|
||||
|
||||
def _optional_string(value: object, label: str) -> str | None:
|
||||
if value is None:
|
||||
return None
|
||||
return _string_value(value, label)
|
||||
|
||||
|
||||
def _integer(document: dict[str, object], key: str) -> int:
|
||||
value = document.get(key)
|
||||
if not isinstance(value, int) or isinstance(value, bool):
|
||||
raise ObjectUnderstandingError(f"{key} must be an integer")
|
||||
return value
|
||||
|
||||
|
||||
def _number(document: dict[str, object], key: str) -> float:
|
||||
value = document.get(key)
|
||||
if (
|
||||
not isinstance(value, (int, float))
|
||||
or isinstance(value, bool)
|
||||
or not math.isfinite(float(value))
|
||||
):
|
||||
raise ObjectUnderstandingError(f"{key} must be finite")
|
||||
return float(value)
|
||||
|
||||
|
||||
def _optional_number(value: object, label: str) -> float | None:
|
||||
if value is None:
|
||||
return None
|
||||
if (
|
||||
not isinstance(value, (int, float))
|
||||
or isinstance(value, bool)
|
||||
or not math.isfinite(float(value))
|
||||
):
|
||||
raise ObjectUnderstandingError(f"{label} must be finite")
|
||||
return float(value)
|
||||
|
||||
|
||||
def _identifier(value: str, label: str) -> None:
|
||||
if not isinstance(value, str) or _IDENTIFIER.fullmatch(value) is None:
|
||||
raise ObjectUnderstandingError(f"{label} is not a safe identifier")
|
||||
|
||||
|
||||
def _optional_identifier(value: str | None, label: str) -> None:
|
||||
if value is not None:
|
||||
_identifier(value, label)
|
||||
|
||||
|
||||
def _label(value: str, label: str) -> None:
|
||||
if (
|
||||
not isinstance(value, str)
|
||||
or not value
|
||||
or value != value.strip()
|
||||
or len(value) > 120
|
||||
or any(ord(character) < 32 for character in value)
|
||||
):
|
||||
raise ObjectUnderstandingError(f"{label} is invalid")
|
||||
|
||||
|
||||
def _nonnegative_integer(value: object, label: str) -> int:
|
||||
if not isinstance(value, int) or isinstance(value, bool) or value < 0:
|
||||
raise ObjectUnderstandingError(f"{label} must be a nonnegative integer")
|
||||
return value
|
||||
|
||||
|
||||
def _positive_integer(value: object, label: str) -> int:
|
||||
result = _nonnegative_integer(value, label)
|
||||
if result == 0:
|
||||
raise ObjectUnderstandingError(f"{label} must be positive")
|
||||
return result
|
||||
|
||||
|
||||
def _confidence(value: object, label: str) -> float:
|
||||
if (
|
||||
not isinstance(value, (int, float))
|
||||
or isinstance(value, bool)
|
||||
or not math.isfinite(float(value))
|
||||
or not 0.0 <= float(value) <= 1.0
|
||||
):
|
||||
raise ObjectUnderstandingError(f"{label} must be within [0, 1]")
|
||||
return float(value)
|
||||
|
||||
|
||||
def _unique_identifiers(
|
||||
values: tuple[str, ...],
|
||||
label: str,
|
||||
*,
|
||||
allow_empty: bool = False,
|
||||
) -> None:
|
||||
if (not values and not allow_empty) or len(set(values)) != len(values):
|
||||
raise ObjectUnderstandingError(f"{label} must be unique")
|
||||
for value in values:
|
||||
_identifier(value, label)
|
||||
|
||||
|
||||
def _unique_enum_values(
|
||||
values: tuple[AdvisoryResponse, ...],
|
||||
label: str,
|
||||
*,
|
||||
allow_empty: bool,
|
||||
) -> None:
|
||||
if (not values and not allow_empty) or len(set(values)) != len(values):
|
||||
raise ObjectUnderstandingError(f"{label} must be unique")
|
||||
if any(not isinstance(value, AdvisoryResponse) for value in values):
|
||||
raise ObjectUnderstandingError(f"{label} are invalid")
|
||||
|
||||
|
||||
def _string_tuple(value: object, label: str) -> tuple[str, ...]:
|
||||
if not isinstance(value, list):
|
||||
raise ObjectUnderstandingError(f"{label} must be an array")
|
||||
return tuple(_string_value(item, label) for item in value)
|
||||
|
||||
|
||||
def _enum[ENUM: StrEnum](
|
||||
enum_type: type[ENUM],
|
||||
value: object,
|
||||
label: str,
|
||||
) -> ENUM:
|
||||
if not isinstance(value, str):
|
||||
raise ObjectUnderstandingError(f"{label} must be a string")
|
||||
try:
|
||||
return enum_type(value)
|
||||
except ValueError as exc:
|
||||
raise ObjectUnderstandingError(f"{label} is incompatible") from exc
|
||||
|
||||
|
||||
__all__ = [
|
||||
"MAX_SEMANTIC_HYPOTHESES",
|
||||
"OBJECT_SEMANTIC_VOCABULARY_SCHEMA",
|
||||
"OBJECT_UNDERSTANDING_SCHEMA",
|
||||
"AdvisoryResponse",
|
||||
"AdvisoryRiskAssessment",
|
||||
"AgencyState",
|
||||
"CanonicalObjectClass",
|
||||
"EvidenceKind",
|
||||
"EvidenceProvenance",
|
||||
"ObjectSemanticVocabulary",
|
||||
"ObjectStateEstimate",
|
||||
"ObjectUnderstanding",
|
||||
"ObjectUnderstandingError",
|
||||
"RiskBasis",
|
||||
"RiskLevel",
|
||||
"SemanticDecision",
|
||||
"SemanticHypothesis",
|
||||
"SemanticResolution",
|
||||
"StateBasis",
|
||||
"load_object_semantic_vocabulary",
|
||||
"normalize_raw_label",
|
||||
"validate_object_understanding",
|
||||
]
|
||||
Reference in New Issue
Block a user