| # 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. |
|
|
