README.md

metadata

title: Tiny Trigger
emoji: 🔌
colorFrom: red
colorTo: gray
sdk: gradio
sdk_version: 6.17.3
python_version: '3.13'
app_file: server.py
pinned: false
license: other
short_description: Open-vocabulary video automations with YOLOE
tags:
  - track:backyard
  - achievement:offbrand

Tiny Trigger

Tiny Trigger is a local-first hackathon prototype for open-vocabulary video automations. It uses YOLOE to detect user-supplied classes plus every label referenced by enabled rules in a video, then evaluates small structured rules that can trigger simulated actions or optional webhook POSTs.

The LLM path is intentionally constrained: Replicate, OpenAI, or Claude compile natural language into JSON/YAML automation rules. The app validates those rules before evaluating them, and the LLM never emits executable code.

DEMO video: https://youtu.be/BfXir6fonR0

For a quick operator checklist, see DEMO.md.

Development Attribution

Tiny Trigger was developed by Javier Montalvo with assistance from AI coding tools, including Anthropic Claude and OpenAI Codex. Some earlier assisted work may not consistently include co-author trailers in the commit history; future assisted commits should include explicit attribution where applicable.

Run Locally

pip install -r requirements.txt
python server.py

Or with Poetry:

poetry install
poetry run python server.py

The detector defaults to the Small YOLOE model (yoloe-26s-seg.pt) at 640px, which Ultralytics downloads on first use if it is not already cached. Model weights are not checked into the repo.

For small or background objects, use a larger model such as yoloe-26l-seg.pt, set device to cuda:0, lower confidence to 0.05-0.15, and raise image size to 960 or 1280.

Run tests with:

pip install -r requirements-dev.txt
python -m pytest

Or:

poetry run pytest

Cloud Rule Compiler

Choose Replicate, OpenAI, or Claude in Settings and paste the matching API key. Keys entered in the UI are sent only with compile requests. Hugging Face Space owners can also set REPLICATE_API_TOKEN, OPENAI_API_KEY, or ANTHROPIC_API_KEY as Space secrets.

Rule Shape

Rules can be written directly as YAML or compiled from natural language:

rules:
  - name: person-near-steering-wheel
    when:
      all:
        - present: {label: person, min_count: 1}
        - near: {a: person, b: steering wheel, max_gap_percent: 16}
    gate:
      enabled: true
      cooldown: {key: turn-on-pc, minutes: 5}
    then:
      - type: webhook
        name: turn on pc

Initial video conditions include presence, count, near, far, and moving. Near/far use the minimum horizontal/vertical gap between detection boxes in normalized frame percent. Moving uses detector-provided track IDs across sampled frames; YOLOE enables Ultralytics ByteTrack only when active rules include a moving condition, so presence/near/count rules keep the higher-recall prediction path. Moving tolerates one missed sampled frame by default to avoid repeat alerts from detector flicker. Gates include enabled state and cooldown. Triggers can fire while a condition is true, when it becomes true, when it becomes false, or on either change. Tiny Trigger does not yet support speed, direction, long-gap re-identification, or trajectory path rules.

rules:
  - name: monitor-presence-lights
    when:
      all:
        - near: {a: person, b: monitor, max_gap_percent: 16}
    trigger:
      on: change
    gate:
      enabled: true
    then:
      enter:
        - type: webhook
          name: turn on lights
      exit:
        - type: webhook
          name: turn off lights

Home Assistant, live RTSP/webcam monitoring, and trajectory logic are planned later increments.

Local State

Private local settings and runtime memory live under .local/, which is ignored by git:

.local/config.yaml       private defaults such as camera/webhook URLs
.local/automations.json  saved editable automation rules
.local/state.json        cooldown memory and last-fired timestamps
.local/events.jsonl      append-only fired action history

Example .local/config.yaml:

webhook_url: "http://127.0.0.1:8123/api/webhook/example"
default_detector_model: "yoloe-26x-seg.pt"
default_device: "cuda:0"
default_image_size: 640
default_max_detections: 300
llm_provider: "anthropic"
replicate_model: "openai/gpt-5.2"
openai_model: "gpt-5.5"
anthropic_model: "claude-sonnet-4-6"

License

This repository is provided under a temporary all-rights-reserved hackathon prototype license. See LICENSE.