video-semantic-chapters

Local, asynchronous room chapter suggestions for continuous residential walkthroughs. Python API, CLI and optional Modal/Daytona execution adapters. No hosted AI API is used.

Release candidate: models and cloud deployments are not yet qualified. Synthetic tests prove software behavior, not room-recognition accuracy. Automatic publication belongs to a separately qualified application policy.

Install

Python 3.10+ and FFmpeg/ffprobe on PATH:

python -m venv .venv
. .venv/bin/activate
pip install -e '.[vision,test]'
pytest
video-semantic-chapters --help

Run one file:

video-semantic-chapters analyze walkthrough.mp4 --request private-data/request.json --output artifacts/result.json
video-semantic-chapters validate artifacts/result.json

request.json contains inputId, outputRevision, checksum (SHA-256), durationMs, and recipe. Generate model locks with python scripts/lock-model.py google/siglip2-base-patch16-224 --revision main --kind siglip2 --output private-data/siglip.json; this downloads weights locally and records the immutable commit and every required file checksum. Put that spec in recipe.models. Model assets must be reviewed and pinned before release; the lock command resolves main once, and runtime manifests contain only immutable commits. Never substitute a floating reference in a runtime manifest.

examples/request.template.json deliberately contains no pretend model hashes. Fill its models using the lock command before analysis. Tests generate their own synthetic video with a deterministic fake evidence adapter; these are not model benchmarks.

Contracts

The core accepts a local file, AnalysisRequest, and ModelAdapter, then returns AnalysisResult. Milliseconds refer to the analyzed playback timeline. Observed intervals cover the whole timeline, including unknowns. Chapter candidates are separate navigation items. Identity suggestions do not establish legal room counts or verified property facts.

The runtime speaks a scoped control-plane protocol; JobStore, ArtifactStore, and ExecutionProvider are replaceable interfaces. SplitIn database/auth code is not part of the engine. The API does not need Supabase or a cloud account for local analysis.

Evaluation

video-semantic-chapters evaluate private-data/dataset.json artifacts/predictions private-data/thresholds.json
video-semantic-chapters benchmark artifacts/recipe-reports.json

Dataset entries include id, propertyId, split, checksum, evaluationAuthorized, and areas with areaType/startMs/endMs/boundaryRangeMs/recognizable/secondReviewer/ambiguous. Group all clips of a property in one split. Missing predictions remain failures. Only held-out test data counts toward qualification; development data is for tuning. See docs/QUALIFICATION.md.

Licensing

Project-owned code: Apache-2.0. Model weights, FFmpeg builds and sample data have separate terms. No customer footage or training dataset is distributed. See MODEL_NOTICES.md.