README.md

---
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`](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

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

Or with Poetry:

```bash
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:

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

Or:

```bash
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:

```yaml
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.

```yaml
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:

```text
.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`:

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