Metadata-Version: 2.1
Name: svf-toolkit
Version: 1.0.0
Summary: Semantic Video Format — convert video to AI-native structured data
Home-page: https://github.com/svf-toolkit
Author: SVF Project
Author-email: svf@example.com
License: UNKNOWN
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Multimedia :: Video
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Provides-Extra: yolo
Provides-Extra: llm
Provides-Extra: full

# SVF Toolkit — Semantic Video Format

**Convert traditional video to AI-native structured data.**

SVF stores video as semantic data (objects, events, narrative) instead of pixel frames.
AI agents can understand a video by reading a ~50KB JSON file instead of re-encoding
and re-analyzing the entire MP4.

## Quick Start

```bash
pip install svf-toolkit

# Basic detection (zero ML deps)
svf generate input.mp4 output.svf

# YOLO detection (semantic labels: person, car, phone…)
pip install ultralytics
svf generate input.mp4 output.svf --backend yolo

# Ask questions (no LLM needed — pure structured data queries)
svf query output.svf "what happens"
svf query output.svf "how many people"

# Generate report
svf report output.svf

# Annotated frames
svf visualize output.svf --frames 20
svf visualize output.svf --gif annotated.gif --video input.mp4
svf visualize output.svf --compare --video input.mp4
```

## Features

| Feature | Basic | YOLO | LLM |
|---------|-------|------|-----|
| Zero ML deps | ✅ | ❌ | ❌ |
| Semantic labels | ❌ (color) | ✅ (person/car/…) | ✅ (any) |
| Installation | `pip install svf-toolkit` | `+ ultralytics` | `+ openai` |
| Speed | ~2fps CPU | ~15fps CPU | ~0.1fps |

## CLI Reference

```
svf generate <input> [output]  --backend  basic|yolo|llm  --sample-rate 2.0
svf info     <input.svf>
svf report   <input.svf> [--detailed]
svf query    <input.svf> <question>
svf timeline <input.svf>
svf validate <input.svf>
svf visualize <input.svf> [--frames 10] [--gif out.gif] [--compare]
svf check
```

## Architecture

```
Video → Detector (basic/yolo/llm) → FeatureTracker → SceneGraph
  → EventStream → NarrativeEngine → .svf (JSON)
                                     → AI Query (zero-cost)
                                     → Visualizer (PNG/GIF)
```

## Format

SVF is a 5-layer JSON structure:

1. **object_catalog** — unique objects with labels, appearance, persistence
2. **scene_graph_keyframes** — spatial relationships at key moments
3. **action_event_stream** — time-stamped actions with trajectories
4. **narrative_graph** — scene classification, causal chains, story summary
5. **render_manifest** — how to render back to pixels for human viewing

Spec: see `svf-prototype-schema.json`


