Metadata-Version: 2.5
Name: avdm
Version: 0.2.3
Summary: Audiovisual Scene Data Model: one canonical scene document and its serializers
License-Expression: MIT
License-File: LICENSE
Requires-Python: >=3.12
Requires-Dist: pydantic>=2.7
Description-Content-Type: text/markdown

# avdm

The **Audiovisual Scene Data Model** (AVDM-001), revision 0.2: one canonical document for
one shot, and the serializers that render it into the text a video model reads.

```
media ──observe──▶ SceneDocument ──render──▶ caption / prompt ──generate──▶ media
                    (observed)                 to_h3, to_prose
                    SceneDocument (planned) ──render──┘
```

The same serializer writes a **training caption** from an observed document and an
**inference prompt** from a planned one, so the two registers match by construction.

## What is in 0.2

| Part | File |
|---|---|
| JSON Schema, the source of truth | `src/avdm/schema/avdm-0.2.schema.json` |
| Attribute vocabulary, one table | `src/avdm/vocabulary.py` |
| The form an observer model fills in | `src/avdm/observe.py` |
| Typed models (pydantic v2), mirrored by hand | `src/avdm/model.py` |
| Evidence rules: `assess`, `assemble`, `validate` | `src/avdm/evidence.py` |
| Serializers: `to_h3`, `to_prose`, `to_ste` | `src/avdm/render.py` |
| Token budget warning | `src/avdm/budget.py` |

The subset is a single observed or planned shot: `Asset`, `Shot` with camera moves,
`Entity`, `Event`, `AudioCue`, `Observation`, exact rational `TimeRange`s, and per-aspect
`coverage`. 0.2 adds attribute claims on entities and on the shot, from a controlled
vocabulary, where `unclear` is always an answer and never a default. When a claim is
specified, the serializers write the picture from the claims, not from free prose. Intent,
constraints, baselines, bindings and edits come later.

## Use

```python
import avdm

doc = avdm.assemble(avdm.SceneDocument.model_validate_json(raw))  # apply evidence rules
assert not avdm.validate(doc)
caption = avdm.to_h3(doc, trigger="ohwx")
```

## Develop

```bash
uv sync
uv run pytest
uv run ruff check . && uv run ruff format --check . && uv run ty check
```

To adopt AVDM in another repository, point that repository's agent at [AGENTS.md](AGENTS.md).
