DEMO.md

# Tiny Trigger Demo Runbook

Use this if you need to run the demo without rebuilding context.

## Launch

```bash
pip install -r requirements.txt
python server.py
```

Or:

```bash
poetry install
poetry run python server.py
```

Open:

```text
http://127.0.0.1:7860
```

For Hugging Face Spaces, the entrypoint is `server.py`; it serves the already
built frontend from `frontend/dist`.

## API Keys

Open Settings, choose one compiler provider, and paste its API key:

- Replicate: `REPLICATE_API_TOKEN`
- OpenAI: `OPENAI_API_KEY`
- Claude: `ANTHROPIC_API_KEY`

Keys pasted in the UI are only sent with compile requests. If you own the Space,
set the matching variable as a Space secret instead.

## Demo Video

No demo video is checked in yet. Record a short MP4 or MOV with:

- one obvious person or hand
- one clear object such as guitar, monitor, steering wheel, cup, laptop, chair
- at least one moment where the object appears or disappears
- 5-15 seconds is enough

The detector downloads YOLOE weights on first use, so the first run can be slow.

Recommended starting detector settings:

- Classes: leave defaults, or add obvious objects from the video.
- Confidence: `0.15` for normal objects, `0.05` if detections are missing.
- Sample interval: `1.0s`.
- Max frames: `120`.
- Model size: Small for speed, Large/XLarge for a stronger demo.
- Resolution: `640` by default, `960` or `1280` if detections are missing.

Rules automatically add their referenced labels to the detector class list.
Rules can use presence, count, near, far, moving, enter, exit, change, and
cooldown. Moving uses detector-provided track IDs across sampled frames; YOLOE
uses Ultralytics ByteTrack only when active rules include motion. It requires at
least three tracked observations and tolerates one missed sampled frame by
default. Speed, direction, long-gap re-identification, and trajectory paths are
not supported yet.

## Prompts To Try

State assertion, should fire once when true:

```text
While there is a guitar in the scene, amplifier must be on.
```

Enter/exit behavior:

```text
If a person is near the monitor, turn on the LED lights. When the person leaves, turn them off.
```

Cooldown behavior:

```text
If a person is near the steering wheel, turn on the PC. Do not repeat for five minutes.
```

Simple presence:

```text
When a laptop is visible, notify me.
```

Simple motion:

```text
If a car is moving, notify me.
```

## Expected Flow

1. Upload the video in Detector.
2. Go to Settings and choose a cloud compiler provider.
3. Paste the API key if the Space has no secret configured.
4. Go to Rule Studio, Compose.
5. Compile one of the prompts above.
6. Check Source to see the generated rule document.
7. Check Rules to see enabled rules and label pills.
8. Run detection.
9. Watch Activity & Firings for fired actions.
10. Use the replay to inspect detections and event timing.

## What To Say

Tiny Trigger turns natural language video automation ideas into validated rules.
The LLM only writes JSON/YAML, never executable code. YOLOE searches both user
classes and labels referenced by active rules. Rules use edge triggers by
default, so "turn on when present" does not spam every frame.

## If Something Fails

- No compile: check the provider and API key.
- No detections: lower confidence, add labels manually, or try a larger YOLOE model.
- Slow first run: model weights are downloading.
- Repeated actions: check the rule trigger. For most demos, prefer `enter` or `change`.
- Missing frontend in a Space: make sure `frontend/dist` is included in the upload.