avdm 0.2.2__py3-none-any.whl

avdm/__init__.py

@@ -0,0 +1,48 @@
+"""AVDM: the Audiovisual Scene Data Model (AVDM-001), revision 0.2.
+
+One canonical document for one shot, observed in existing media or planned for
+generation, and the serializers that render it into a model's text register.
+See AGENTS.md for adoption.
+"""
+
+from importlib.resources import files
+from pathlib import Path
+
+from avdm.budget import H3_TOKEN_LIMIT, over_budget, token_count
+from avdm.evidence import DEFAULT_POLICY, EvidencePolicy, assemble, assess, validate
+from avdm.model import *  # noqa: F403
+from avdm.model import __all__ as _model_all
+from avdm.observe import (
+    FrameClaims,
+    PersonClaims,
+    apply_frame_claims,
+    frame_claims_schema,
+)
+from avdm.render import UnrenderableError, to_h3, to_prose, to_ste
+
+
+def schema_path() -> Path:
+    """The JSON Schema file that is the source of truth for these models."""
+    return Path(str(files("avdm") / "schema" / "avdm-0.2.schema.json"))
+
+
+__all__ = [
+    *_model_all,
+    "DEFAULT_POLICY",
+    "H3_TOKEN_LIMIT",
+    "EvidencePolicy",
+    "FrameClaims",
+    "PersonClaims",
+    "UnrenderableError",
+    "apply_frame_claims",
+    "assemble",
+    "assess",
+    "frame_claims_schema",
+    "over_budget",
+    "schema_path",
+    "to_h3",
+    "to_prose",
+    "to_ste",
+    "token_count",
+    "validate",
+]

avdm/budget.py

@@ -0,0 +1,34 @@
+"""Caption length against a trainer's text-token limit.
+
+ai-toolkit truncates an H3 caption at 512 tokens from the end, so the last
+fields (the soundscape and the music) are lost first. This module warns; it
+never truncates.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Sequence
+
+#: ai-toolkit's `max_text_length` default for MiniMax H3.
+H3_TOKEN_LIMIT = 512
+
+
+def token_count(text: str, tokenize: Callable[[str], Sequence[object]] | None = None) -> int:
+    """Tokens in *text* under *tokenize*, or a whitespace word count without one.
+
+    The word count is an underestimate for most tokenizers. Pass the target
+    model's tokenizer when the limit matters.
+    """
+    return len(tokenize(text)) if tokenize else len(text.split())
+
+
+def over_budget(
+    text: str,
+    limit: int = H3_TOKEN_LIMIT,
+    tokenize: Callable[[str], Sequence[object]] | None = None,
+) -> bool:
+    """Whether *text* exceeds *limit* tokens."""
+    return token_count(text, tokenize) > limit
+
+
+__all__ = ["H3_TOKEN_LIMIT", "over_budget", "token_count"]

avdm/evidence.py

@@ -0,0 +1,239 @@
+"""Evidence rules: what an observation may claim, given what was inspected.
+
+Applied by `assemble()` to an observed document and checked by `validate()`.
+Planned documents state intent, not evidence, so these rules do not apply to
+them.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from dataclasses import dataclass
+
+from avdm.model import (
+    Aspect,
+    EntityAttribute,
+    Observation,
+    SceneDocument,
+    ShotAttribute,
+    Status,
+)
+
+#: Aspects that only audio evidence can establish (REQ-OBS-003).
+AUDIO_ASPECTS: frozenset[Aspect] = frozenset({"dialogue", "sound", "music"})
+
+#: Aspects about change over time.
+MOTION_ASPECTS: frozenset[Aspect] = frozenset({"subject_motion", "camera_motion"})
+
+
+@dataclass(frozen=True)
+class EvidencePolicy:
+    """Thresholds for motion seen through sampled frames.
+
+    Sampled frames are evidence of motion, but not complete evidence of what
+    happens between them (AVDM §15.4). Their weight depends on density: the
+    sample rate, and the fraction of the clip that the samples span. A model's
+    own confidence is not used, because a model score is not a probability.
+    """
+
+    min_motion_fps: float = 2.0
+    min_motion_coverage: float = 0.8
+
+
+DEFAULT_POLICY = EvidencePolicy()
+
+
+def assess(observation: Observation, policy: EvidencePolicy = DEFAULT_POLICY) -> Observation:
+    """*observation* with its status lowered to unknown when its evidence cannot carry it.
+
+    The reason is added to `limitations`. A status of unknown or not_applicable
+    is returned unchanged.
+    """
+    if observation.status != "specified":
+        return observation
+    reason = _insufficient(observation, policy)
+    if reason is None:
+        return observation
+    return observation.model_copy(
+        update={"status": "unknown", "limitations": [*observation.limitations, reason]}
+    )
+
+
+def _insufficient(observation: Observation, policy: EvidencePolicy) -> str | None:
+    scope = observation.evidence_scope
+    if observation.aspect in AUDIO_ASPECTS and "audio" not in scope.modalities:
+        return f"{observation.aspect} needs audio evidence; inspected {list(scope.modalities)}"
+    if observation.aspect in MOTION_ASPECTS:
+        if scope.sampling == "continuous":
+            return None
+        if scope.sampling != "sparse_frames":
+            return f"{observation.aspect} needs a sequence of frames; sampling was {scope.sampling}"
+        rate, coverage = scope.sample_rate_fps or 0.0, scope.coverage or 0.0
+        if rate < policy.min_motion_fps or coverage < policy.min_motion_coverage:
+            return (
+                f"{observation.aspect} from {rate:g} fps over {coverage:.0%} of the clip; "
+                f"needs {policy.min_motion_fps:g} fps over {policy.min_motion_coverage:.0%}"
+            )
+    return None
+
+
+def assemble(document: SceneDocument, policy: EvidencePolicy = DEFAULT_POLICY) -> SceneDocument:
+    """An observed *document* with each observation assessed and coverage derived.
+
+    An aspect is specified when an observation of it survives assessment,
+    not_applicable when every observation says so, and unknown otherwise. An
+    aspect with no observation is left out of coverage, which also means unknown.
+    """
+    if document.information_class != "observed":
+        return document
+    observations = [assess(o, policy) for o in document.observations]
+    carried = {o.id for o in observations if o.status == "specified"}
+    coverage: dict[Aspect, Status] = {}
+    for aspect in {o.aspect for o in observations}:
+        statuses = {o.status for o in observations if o.aspect == aspect}
+        if "specified" in statuses:
+            coverage[aspect] = "specified"
+        elif statuses == {"not_applicable"}:
+            coverage[aspect] = "not_applicable"
+        else:
+            coverage[aspect] = "unknown"
+    shot = document.shot.model_copy(
+        update={"attributes": [_carried(a, carried) for a in document.shot.attributes]}
+    )
+    entities = [
+        e.model_copy(update={"attributes": [_carried(a, carried) for a in e.attributes]})
+        for e in document.entities
+    ]
+    return document.model_copy(
+        update={
+            "observations": observations,
+            "coverage": coverage,
+            "shots": [shot],
+            "entities": entities,
+        }
+    )
+
+
+def _carried[A: (EntityAttribute, ShotAttribute)](attribute: A, carried: set[str]) -> A:
+    """*attribute*, made unknown when its observation does not survive assessment.
+
+    A claim is only as good as the evidence it names. Built anew rather than
+    copied, so the model's own rules are checked on the result.
+    """
+    if attribute.status != "specified" or attribute.observation_ref in carried:
+        return attribute
+    return type(attribute).model_validate(
+        {
+            "name": attribute.name,
+            "status": "unknown",
+            "reason": "unclear",
+            "observation_ref": attribute.observation_ref,
+        }
+    )
+
+
+def validate(document: SceneDocument, policy: EvidencePolicy = DEFAULT_POLICY) -> list[str]:
+    """Every rule *document* breaks, as messages. An empty list means valid."""
+    errors: list[str] = []
+    ids = _ids(document, errors)
+    assets = {a.id: a for a in document.assets}
+    events = {e.id for e in document.events}
+    entities = {e.id for e in document.entities}
+
+    def need(ref: str | None, pool: set[str], what: str, where: str) -> None:
+        if ref is not None and ref not in pool:
+            errors.append(f"{where}: {what} {ref!r} does not exist")
+
+    for ref in document.shot.event_refs:
+        need(ref, events, "event", document.shot.id)
+    for event in document.events:
+        for participant in event.participants:
+            need(participant.entity_ref, entities, "entity", event.id)
+    for cue in document.audio_cues:
+        need(cue.speaker_ref, entities, "speaker", cue.id)
+        need(cue.sync_event_ref, events, "event", cue.id)
+        if cue.category in {"dialogue", "lyrics"} and not cue.exact_text:
+            errors.append(f"{cue.id}: {cue.category} needs its exact text (REQ-AUD-004)")
+    for asset in document.assets:
+        if asset.derived_from is not None:
+            need(asset.derived_from.asset_ref, set(assets), "asset", asset.id)
+    for observation in document.observations:
+        need(observation.asset_ref, set(assets), "asset", observation.id)
+        for ref in observation.target_refs:
+            need(ref, ids, "object", observation.id)
+    observations = {o.id for o in document.observations}
+    owners: list[tuple[str, Sequence[EntityAttribute | ShotAttribute]]] = [
+        (document.shot.id, document.shot.attributes),
+        *((e.id, e.attributes) for e in document.entities),
+    ]
+    for owner, attributes in owners:
+        for attribute in attributes:
+            where = f"{owner}.{attribute.name}"
+            need(attribute.observation_ref, observations, "observation", where)
+            if (
+                document.information_class == "observed"
+                and attribute.status == "specified"
+                and attribute.observation_ref is None
+            ):
+                errors.append(f"{where}: an observed claim must name its observation")
+
+    errors.extend(_frame_ranges(document, assets))
+
+    if document.information_class == "observed":
+        assessed = [assess(o, policy) for o in document.observations]
+        for aspect, status in document.coverage.items():
+            supported = any(o.aspect == aspect and o.status == "specified" for o in assessed)
+            if status == "specified" and not supported:
+                errors.append(f"coverage: {aspect} is specified but no evidence supports it")
+    return errors
+
+
+def _ids(document: SceneDocument, errors: list[str]) -> set[str]:
+    seen: set[str] = set()
+    groups = (
+        document.assets,
+        document.entities,
+        document.shots,
+        document.events,
+        document.audio_cues,
+        document.observations,
+    )
+    for group in groups:
+        for item in group:
+            if item.id in seen:
+                errors.append(f"id {item.id!r} is used twice")
+            seen.add(item.id)
+    return seen
+
+
+def _frame_ranges(document: SceneDocument, assets: dict) -> list[str]:
+    """A source range in an asset's own frame rate must stay inside its frames (T12)."""
+    errors = []
+    ranges = [
+        *(a.derived_from.range for a in document.assets if a.derived_from),
+        *(e.range for e in document.events if e.range),
+        *(c.range for c in document.audio_cues if c.range),
+        *(o.evidence_scope.range for o in document.observations if o.evidence_scope.range),
+        *([document.shot.range] if document.shot.range else []),
+    ]
+    for r in ranges:
+        asset = assets.get(r.ref)
+        meta = asset.technical_metadata if asset else None
+        if r.domain != "source" or meta is None or meta.frame_count is None:
+            continue
+        if meta.frame_rate == r.rate and r.end > meta.frame_count:
+            errors.append(
+                f"range ends at frame {r.end} of {r.ref!r}, which has {meta.frame_count} frames"
+            )
+    return errors
+
+
+__all__ = [
+    "AUDIO_ASPECTS",
+    "DEFAULT_POLICY",
+    "MOTION_ASPECTS",
+    "EvidencePolicy",
+    "assemble",
+    "assess",
+    "validate",
+]

avdm/model.py

@@ -0,0 +1,369 @@
+"""Typed AVDM 0.2 objects, mirroring `schema/avdm-0.2.schema.json` by hand.
+
+The JSON Schema is the source of truth. `tests/contract` keeps the two in step:
+the same property names per definition, and the same verdict on every fixture.
+
+A missing optional field means "no assertion" (AVDM §5.3). `coverage` is where
+"we looked and found none" is told apart from "we did not look". An attribute
+says the same for one claim: `unknown` with a reason is "we looked and cannot
+tell"; an absent attribute is "we did not look".
+"""
+
+from __future__ import annotations
+
+import hashlib
+from fractions import Fraction
+from pathlib import Path
+from typing import Any, Literal
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+from avdm.vocabulary import ENTITY_TERMS, FREE_MAX_LENGTH, SHOT_TERMS, Term
+
+AVDM_VERSION = "0.2"
+
+Aspect = Literal["depiction", "subject_motion", "camera_motion", "dialogue", "sound", "music"]
+Status = Literal["specified", "unknown", "not_applicable"]
+Modality = Literal["image", "video", "audio", "text"]
+#: Why an attribute is unknown: the observer could not tell, or could not see the part.
+Reason = Literal["hidden", "unclear"]
+
+#: The names in `vocabulary.ENTITY_TERMS`, in order (a contract test keeps them equal).
+EntityAttributeName = Literal[
+    "figure",
+    "position",
+    "facing",
+    "hair_colour",
+    "hair_length",
+    "facial_hair",
+    "headwear",
+    "upper_garment",
+    "outer_garment",
+    "lower_garment",
+    "armour",
+    "accessory",
+    "held_object",
+    "expression",
+    "gaze",
+    "pose",
+    "action",
+]
+
+#: The names in `vocabulary.SHOT_TERMS`, in order.
+ShotAttributeName = Literal[
+    "shot_size",
+    "camera_angle",
+    "location",
+    "background",
+    "light_level",
+    "light_direction",
+    "visible_text",
+]
+
+ASPECTS: tuple[Aspect, ...] = (
+    "depiction",
+    "subject_motion",
+    "camera_motion",
+    "dialogue",
+    "sound",
+    "music",
+)
+
+
+class _Model(BaseModel):
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+
+class TimeBase(_Model):
+    """Ticks per second as the exact ratio num/den (AVDM §10.2)."""
+
+    num: int = Field(ge=1)
+    den: int = Field(ge=1)
+
+    def seconds(self, ticks: int) -> Fraction:
+        return Fraction(ticks * self.den, self.num)
+
+
+class TimeRange(_Model):
+    """`start <= t < start + duration`, in ticks of *rate*, in one domain (§10.3)."""
+
+    domain: Literal["source", "shot", "edit", "story"]
+    ref: str = Field(min_length=1)
+    rate: TimeBase
+    start: int = Field(ge=0)
+    duration: int = Field(ge=0)
+
+    @property
+    def end(self) -> int:
+        return self.start + self.duration
+
+
+class TechnicalMetadata(_Model):
+    """What the media actually is, measured, never requested (REQ-AST-002)."""
+
+    width_px: int | None = Field(default=None, ge=1)
+    height_px: int | None = Field(default=None, ge=1)
+    frame_rate: TimeBase | None = None
+    frame_count: int | None = Field(default=None, ge=1)
+    has_audio: bool | None = None
+    audio_sample_rate_hz: int | None = Field(default=None, ge=1)
+
+
+class Derivation(_Model):
+    """The source range an asset was cut from, kept apart from its own time (T27)."""
+
+    asset_ref: str = Field(min_length=1)
+    range: TimeRange
+
+
+class Asset(_Model):
+    id: str = Field(min_length=1)
+    media_type: Literal["image", "video", "audio"]
+    locator: str = Field(min_length=1)
+    content_hash: str = Field(pattern=r"^sha256:[0-9a-f]{64}$")
+    availability: Literal["available", "unavailable", "pending"]
+    technical_metadata: TechnicalMetadata | None = None
+    derived_from: Derivation | None = None
+
+    @classmethod
+    def from_path(
+        cls,
+        path: Path,
+        *,
+        id: str,  # noqa: A002 -- the field's own name
+        media_type: Literal["image", "video", "audio"],
+        locator: str | None = None,
+        technical_metadata: TechnicalMetadata | None = None,
+        derived_from: Derivation | None = None,
+    ) -> Asset:
+        """An available asset for a file that exists, hashed from its bytes.
+
+        Raises FileNotFoundError for a path that does not exist: a described
+        file is not an asset (REQ-AST-001, test T22).
+        """
+        digest = hashlib.sha256(path.read_bytes()).hexdigest()
+        return cls(
+            id=id,
+            media_type=media_type,
+            locator=locator or path.name,
+            content_hash=f"sha256:{digest}",
+            availability="available",
+            technical_metadata=technical_metadata,
+            derived_from=derived_from,
+        )
+
+
+def _check_attribute(
+    name: str, status: Status, value: str | None, reason: str | None, term: Term
+) -> None:
+    """One claim's rules: a value only when specified, from the closed list if there is one."""
+    if status == "specified":
+        if value is None:
+            raise ValueError(f"{name}: a specified attribute needs a value")
+        if reason is not None:
+            raise ValueError(f"{name}: a specified attribute has no reason")
+        if term.values is not None and value not in term.values:
+            raise ValueError(f"{name}: {value!r} is not one of {list(term.values)}")
+        return
+    if value is not None:
+        raise ValueError(f"{name}: an attribute that is {status} has no value")
+    if reason == "hidden" and not term.hideable:
+        raise ValueError(f"{name}: cannot be hidden")
+
+
+class EntityAttribute(_Model):
+    """One claim about an entity, such as its headwear (AVDM 0.2).
+
+    `unknown` with `reason` is "looked, cannot tell"; it is never a default value.
+    `observation_ref` names the observation whose evidence carries the claim.
+    """
+
+    name: EntityAttributeName
+    status: Status
+    value: str | None = Field(default=None, min_length=1, max_length=FREE_MAX_LENGTH)
+    reason: Reason | None = None
+    observation_ref: str | None = None
+
+    @model_validator(mode="after")
+    def _rules(self) -> EntityAttribute:
+        _check_attribute(self.name, self.status, self.value, self.reason, ENTITY_TERMS[self.name])
+        return self
+
+
+class ShotAttribute(_Model):
+    """One claim about the shot as a whole, such as its size or its light (AVDM 0.2)."""
+
+    name: ShotAttributeName
+    status: Status
+    value: str | None = Field(default=None, min_length=1, max_length=FREE_MAX_LENGTH)
+    reason: Reason | None = None
+    observation_ref: str | None = None
+
+    @model_validator(mode="after")
+    def _rules(self) -> ShotAttribute:
+        _check_attribute(self.name, self.status, self.value, self.reason, SHOT_TERMS[self.name])
+        return self
+
+
+class Entity(_Model):
+    id: str = Field(min_length=1)
+    kind: str | None = None
+    label: str | None = None
+    attributes: list[EntityAttribute] = []
+
+
+class Description(_Model):
+    """Free text for a picture that has no attribute claims, such as a planned shot."""
+
+    text: str = Field(min_length=1)
+
+
+class CameraMove(_Model):
+    """One camera operation. Translation, rotation and zoom stay distinct (REQ-CAM-001)."""
+
+    term: Literal[
+        "pan", "tilt", "roll", "push", "pull", "truck", "pedestal", "arc", "track", "zoom"
+    ]
+    direction: str | None = None
+
+
+class Camera(_Model):
+    """The camera's moves. No moves, with camera_motion specified, is a static camera."""
+
+    moves: list[CameraMove]
+
+
+class Shot(_Model):
+    """One shot. Its picture is its attribute claims when any is specified, else `description`."""
+
+    id: str = Field(min_length=1)
+    range: TimeRange | None = None
+    description: Description | None = None
+    camera: Camera | None = None
+    event_refs: list[str] = []
+    attributes: list[ShotAttribute] = []
+
+
+class Action(_Model):
+    text: str = Field(min_length=1)
+    term: str | None = None
+
+
+class Participant(_Model):
+    entity_ref: str = Field(min_length=1)
+    role: Literal["performer", "target", "instrument", "recipient", "observer"]
+
+
+class Event(_Model):
+    id: str = Field(min_length=1)
+    action: Action
+    participants: list[Participant] = []
+    range: TimeRange | None = None
+
+
+class AudioCue(_Model):
+    """One audible occurrence. Category, story relation and source visibility
+    are separate properties (REQ-AUD-002): an off-screen radio is diegetic music.
+    """
+
+    id: str = Field(min_length=1)
+    category: Literal["dialogue", "lyrics", "non_verbal", "ambience", "effect", "music"]
+    story_relation: Literal["diegetic", "non_diegetic"]
+    source_visibility: Literal["on_screen", "off_screen", "mixed", "not_applicable"] | None = None
+    description: str | None = None
+    exact_text: str | None = None
+    speaker_ref: str | None = None
+    language: str | None = Field(default=None, pattern=r"^[A-Za-z]{2,3}(-[A-Za-z0-9]{2,8})*$")
+    sync_event_ref: str | None = None
+    range: TimeRange | None = None
+
+
+class EvidenceScope(_Model):
+    """What was inspected: modalities, how the frames were sampled, and how much."""
+
+    modalities: list[Modality]
+    sampling: Literal["none", "single_frame", "sparse_frames", "continuous"]
+    frame_count: int | None = Field(default=None, ge=0)
+    sample_rate_fps: float | None = Field(default=None, ge=0)
+    coverage: float | None = Field(default=None, ge=0, le=1)
+    range: TimeRange | None = None
+
+
+class Method(_Model):
+    producer: str = Field(min_length=1)
+    params: dict[str, Any] = {}
+    human: bool = False
+
+
+class Observation(_Model):
+    """An evidence-based statement about one asset (AVDM §15.4)."""
+
+    id: str = Field(min_length=1)
+    aspect: Aspect
+    status: Status
+    target_refs: list[str] = []
+    asset_ref: str = Field(min_length=1)
+    evidence_scope: EvidenceScope
+    method: Method
+    basis: Literal["explicit", "observed", "necessary_inference", "creative_default", "measurement"]
+    recorded_at: str | None = None
+    value_text: str | None = None
+    limitations: list[str] = []
+
+
+class SceneDocument(_Model):
+    """One shot, observed in existing media or planned for generation."""
+
+    avdm_version: Literal["0.2"] = AVDM_VERSION
+    id: str = Field(min_length=1)
+    information_class: Literal["observed", "planned"]
+    assets: list[Asset]
+    entities: list[Entity] = []
+    shots: list[Shot] = Field(min_length=1, max_length=1)
+    events: list[Event] = []
+    audio_cues: list[AudioCue] = []
+    observations: list[Observation] = []
+    coverage: dict[Aspect, Status] = {}
+
+    @property
+    def shot(self) -> Shot:
+        return self.shots[0]
+
+    def status(self, aspect: Aspect) -> Status:
+        """An aspect's coverage. Absent means unknown, never none (REQ-VAL-001)."""
+        return self.coverage.get(aspect, "unknown")
+
+    def to_json(self) -> str:
+        return self.model_dump_json(exclude_none=True, indent=2)
+
+
+__all__ = [
+    "ASPECTS",
+    "AVDM_VERSION",
+    "Action",
+    "Aspect",
+    "Asset",
+    "AudioCue",
+    "Camera",
+    "CameraMove",
+    "Derivation",
+    "Description",
+    "Entity",
+    "EntityAttribute",
+    "EntityAttributeName",
+    "Event",
+    "EvidenceScope",
+    "Method",
+    "Modality",
+    "Observation",
+    "Participant",
+    "Reason",
+    "SceneDocument",
+    "Shot",
+    "ShotAttribute",
+    "ShotAttributeName",
+    "Status",
+    "TechnicalMetadata",
+    "TimeBase",
+    "TimeRange",
+]