DEMO.md

Tiny Trigger Demo Runbook

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

Launch

pip install -r requirements.txt
python server.py

Or:

poetry install
poetry run python server.py

Open:

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:

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

Enter/exit behavior:

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

Cooldown behavior:

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

Simple presence:

When a laptop is visible, notify me.

Simple motion:

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.