MVP working. Missing: add cloud providers

README.md

@@ -15,9 +15,9 @@ short_description: 'Open-vocabulary video automations with YOLOE and llama.cpp'
 # Tiny Trigger
 
 Tiny Trigger is a local-first hackathon prototype for open-vocabulary video
-automations. It uses YOLOE to detect user-supplied classes in a video, then
-evaluates small structured rules that can trigger simulated actions or optional
-webhook POSTs.
+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: llama.cpp compiles natural language
 into JSON/YAML automation rules. The app validates those rules before evaluating
@@ -81,7 +81,7 @@ rules:
     when:
       all:
         - present: {label: person, min_count: 1}
-        - near: {a: person, b: steering wheel, max_distance: 0.45}
+        - near: {a: person, b: steering wheel, max_gap_percent: 8}
     gate:
       enabled: true
       cooldown: {key: turn-on-pc, minutes: 5}
@@ -90,8 +90,31 @@ rules:
         name: turn on pc
 ```
 
-Initial video conditions include presence, count, and near. Gates include enabled
-state and cooldown. Initial actions are simulated events and optional webhooks.
+Initial video conditions include presence, count, near, and far. Near/far use the
+minimum horizontal/vertical gap between detection boxes in normalized frame
+percent. 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. Initial actions are simulated events and optional webhooks.
+
+```yaml
+rules:
+  - name: monitor-presence-lights
+    when:
+      all:
+        - near: {a: person, b: monitor, max_gap_percent: 8}
+    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.
 

examples/feed-cat.yaml

@@ -3,7 +3,7 @@ rules:
     when:
       all:
         - present: {label: cat, min_count: 1}
-        - near: {a: cat, b: feeder robot, max_distance: 0.35}
+        - near: {a: cat, b: feeder robot, max_gap_percent: 8}
         - cooldown: {key: feed-cat, minutes: 30}
     then:
       - type: webhook

examples/turn-on-pc.yaml

@@ -3,7 +3,7 @@ rules:
     when:
       all:
         - present: {label: person, min_count: 1}
-        - near: {a: person, b: steering wheel, max_distance: 0.45}
+        - near: {a: person, b: steering wheel, max_gap_percent: 8}
     gate:
       enabled: true
       cooldown: {key: turn-on-pc, minutes: 5}

frontend/src/lib/api.ts

@@ -4,6 +4,7 @@ import type {
   CompilerProvider,
   DetectParams,
   LocalConfig,
+  RuleMutationResult,
   RunResult,
   ValidationResult,
 } from "./types"
@@ -51,6 +52,7 @@ export async function detectAndAutomate(
 export async function compileRules(
   instruction: string,
   classes: string,
+  existingRulesText: string,
   provider: CompilerProvider,
   baseUrl: string,
   model: string,
@@ -58,6 +60,8 @@ export async function compileRules(
   return call<CompileResult>("/compile_rules", {
     instruction,
     classes,
+    existing_rules_text: existingRulesText,
+    append: true,
     provider,
     base_url: baseUrl,
     model,
@@ -72,6 +76,28 @@ export async function saveRules(rulesText: string): Promise<{ ok: boolean; rule_
   return call("/save_rules", { rules_text: rulesText })
 }
 
+export async function setRuleEnabled(
+  rulesText: string,
+  ruleName: string,
+  enabled: boolean,
+): Promise<RuleMutationResult> {
+  return call<RuleMutationResult>("/set_rule_enabled", {
+    rules_text: rulesText,
+    rule_name: ruleName,
+    enabled,
+  })
+}
+
+export async function deleteRule(
+  rulesText: string,
+  ruleName: string,
+): Promise<RuleMutationResult> {
+  return call<RuleMutationResult>("/delete_rule", {
+    rules_text: rulesText,
+    rule_name: ruleName,
+  })
+}
+
 export async function loadRules(): Promise<{ rules_text: string | null }> {
   return call("/load_rules", {})
 }

frontend/src/lib/dashboard.tsx

@@ -25,7 +25,7 @@ const DEFAULT_RULES = `rules:
     when:
       all:
         - present: {label: person, min_count: 1}
-        - near: {a: person, b: steering wheel, max_distance: 0.45}
+        - near: {a: person, b: steering wheel, max_gap_percent: 8}
     gate:
       enabled: true
       cooldown: {key: turn-on-pc, minutes: 5}
@@ -62,6 +62,8 @@ interface DashboardState {
   validation: ValidationResult | null
   validate: () => Promise<void>
   save: () => Promise<void>
+  setRuleEnabled: (ruleName: string, enabled: boolean) => Promise<void>
+  deleteRule: (ruleName: string) => Promise<void>
   compilerProvider: CompilerProvider
   setCompilerProvider: (provider: CompilerProvider) => void
   compile: (instruction: string) => Promise<CompileResult | null>
@@ -82,6 +84,14 @@ export function DashboardProvider({ children }: { children: ReactNode }) {
   const [compilerProvider, setCompilerProvider] = useState<CompilerProvider>("cloud")
   const [compiling, setCompiling] = useState(false)
   const previewRef = useRef<string | null>(null)
+  const compileInFlightRef = useRef(false)
+
+  const applyRulesText = useCallback(async (nextRulesText: string) => {
+    setRulesText(nextRulesText)
+    const nextValidation = await api.validateRules(nextRulesText)
+    setValidation(nextValidation)
+    return nextValidation
+  }, [])
 
   // Hydrate defaults from backend config + saved rules on mount.
   useEffect(() => {
@@ -104,9 +114,11 @@ export function DashboardProvider({ children }: { children: ReactNode }) {
       .catch(() => void 0)
     api
       .loadRules()
-      .then((r) => r.rules_text && setRulesText(r.rules_text))
+      .then((r) => {
+        if (r.rules_text) void applyRulesText(r.rules_text)
+      })
       .catch(() => void 0)
-  }, [])
+  }, [applyRulesText])
 
   const setParam = useCallback(
     <K extends keyof DetectParams>(key: K, value: DetectParams[K]) => {
@@ -156,8 +168,7 @@ export function DashboardProvider({ children }: { children: ReactNode }) {
 
   const validate = useCallback(async () => {
     try {
-      const v = await api.validateRules(rulesText)
-      setValidation(v)
+      const v = await applyRulesText(rulesText)
       if (v.ok) toast.success(`Validated — ${v.rules.length} rule${v.rules.length === 1 ? "" : "s"}`)
       else toast.error("Validation failed")
     } catch (e) {
@@ -165,7 +176,7 @@ export function DashboardProvider({ children }: { children: ReactNode }) {
         description: e instanceof Error ? e.message : String(e),
       })
     }
-  }, [rulesText])
+  }, [applyRulesText, rulesText])
 
   const save = useCallback(async () => {
     try {
@@ -178,19 +189,52 @@ export function DashboardProvider({ children }: { children: ReactNode }) {
     }
   }, [rulesText])
 
+  const setRuleEnabled = useCallback(
+    async (ruleName: string, enabled: boolean) => {
+      try {
+        const result = await api.setRuleEnabled(rulesText, ruleName, enabled)
+        await applyRulesText(result.rules_text)
+        toast.success(`${enabled ? "Enabled" : "Disabled"} ${ruleName}`)
+      } catch (e) {
+        toast.error("Rule update failed", {
+          description: e instanceof Error ? e.message : String(e),
+        })
+      }
+    },
+    [applyRulesText, rulesText],
+  )
+
+  const deleteRule = useCallback(
+    async (ruleName: string) => {
+      try {
+        const result = await api.deleteRule(rulesText, ruleName)
+        await applyRulesText(result.rules_text)
+        toast.success(`Deleted ${ruleName}`)
+      } catch (e) {
+        toast.error("Delete failed", {
+          description: e instanceof Error ? e.message : String(e),
+        })
+      }
+    },
+    [applyRulesText, rulesText],
+  )
+
   const compile = useCallback(
     async (instruction: string): Promise<CompileResult | null> => {
+      if (compileInFlightRef.current) return null
+      compileInFlightRef.current = true
       setCompiling(true)
       try {
         const c = await api.compileRules(
           instruction,
           params.classes,
+          rulesText,
           compilerProvider,
           "http://127.0.0.1:8080/v1",
           "ggml-org/Qwen3-1.7B-GGUF:Q4_K_M",
         )
-        setRulesText(c.rules_text)
-        toast.success(`Compiled ${c.rule_count} rule${c.rule_count === 1 ? "" : "s"}`)
+        await applyRulesText(c.rules_text)
+        toast.success(`Added rule. ${c.rule_count} total.`)
         return c
       } catch (e) {
         toast.error("Compile failed", {
@@ -198,10 +242,11 @@ export function DashboardProvider({ children }: { children: ReactNode }) {
         })
         return null
       } finally {
+        compileInFlightRef.current = false
         setCompiling(false)
       }
     },
-    [compilerProvider, params.classes],
+    [applyRulesText, compilerProvider, params.classes, rulesText],
   )
 
   const value = useMemo<DashboardState>(
@@ -220,6 +265,8 @@ export function DashboardProvider({ children }: { children: ReactNode }) {
       validation,
       validate,
       save,
+      setRuleEnabled,
+      deleteRule,
       compilerProvider,
       setCompilerProvider,
       compile,
@@ -239,6 +286,8 @@ export function DashboardProvider({ children }: { children: ReactNode }) {
       validation,
       validate,
       save,
+      setRuleEnabled,
+      deleteRule,
       compilerProvider,
       compile,
       compiling,

frontend/src/lib/types.ts

@@ -41,6 +41,8 @@ export interface RunResult {
 export interface RuleSummary {
   name: string
   enabled: boolean
+  trigger: "while" | "enter" | "exit" | "change"
+  labels: string[]
   conditions: number
   actions: { type: string; name: string }[]
 }
@@ -57,6 +59,12 @@ export interface CompileResult {
   rule_count: number
 }
 
+export interface RuleMutationResult {
+  ok: boolean
+  rules_text: string
+  rule_count: number
+}
+
 export type CompilerProvider = "local" | "cloud"
 
 export interface LocalConfig {

frontend/src/modules/rules/RuleStudioPanel.tsx

@@ -8,6 +8,7 @@ import {
   Save,
   ShieldCheck,
   Sparkles,
+  Trash2,
   Wand2,
 } from "lucide-react"
 import { useDashboard } from "@/lib/dashboard"
@@ -26,6 +27,8 @@ export function RuleStudioPanel() {
     validate,
     validation,
     save,
+    setRuleEnabled,
+    deleteRule,
     compilerProvider,
     setCompilerProvider,
     compile,
@@ -34,6 +37,7 @@ export function RuleStudioPanel() {
   const [instruction, setInstruction] = useState(
     "If a person is near the steering wheel, turn on the PC. Don't repeat for five minutes.",
   )
+  const [armedDelete, setArmedDelete] = useState<string | null>(null)
 
   return (
     <Tabs defaultValue="compose">
@@ -67,7 +71,7 @@ export function RuleStudioPanel() {
           ))}
       </div>
 
-      {/* Compose: NL → rules via llama.cpp */}
+      {/* Compose: NL → rules */}
       <TabsContent value="compose">
         <div className="space-y-3">
           <div className="flex flex-col gap-3 sm:flex-row sm:items-center sm:justify-between">
@@ -147,7 +151,7 @@ export function RuleStudioPanel() {
             {validation.rules.map((r) => (
               <div
                 key={r.name}
-                className="flex items-center justify-between rounded-lg border border-border bg-black/20 px-4 py-3"
+                className="flex flex-col gap-3 rounded-lg border border-border bg-black/20 px-4 py-3 sm:flex-row sm:items-center sm:justify-between"
               >
                 <div className="min-w-0">
                   <div className="flex items-center gap-2">
@@ -158,18 +162,58 @@ export function RuleStudioPanel() {
                       )}
                     />
                     <span className="truncate font-mono text-sm text-foreground">{r.name}</span>
+                    <Badge variant="default">{r.trigger}</Badge>
                   </div>
                   <div className="mt-1 pl-3.5 text-xs text-muted-foreground">
                     {r.conditions} condition{r.conditions === 1 ? "" : "s"} →{" "}
                     {r.actions.map((a) => `${a.type}:${a.name}`).join(", ")}
                   </div>
+                  {r.labels.length > 0 && (
+                    <div className="mt-2 flex flex-wrap gap-1 pl-3.5">
+                      {r.labels.map((label) => (
+                        <span
+                          key={label}
+                          className="rounded border border-border bg-black/30 px-1.5 py-0.5 font-mono text-[0.625rem] text-muted-foreground"
+                        >
+                          {label}
+                        </span>
+                      ))}
+                    </div>
+                  )}
+                </div>
+                <div className="flex shrink-0 items-center gap-2">
+                  <Label htmlFor={`enabled-${r.name}`} className="text-xs text-muted-foreground">
+                    {r.enabled ? "enabled" : "disabled"}
+                  </Label>
+                  <Switch
+                    id={`enabled-${r.name}`}
+                    checked={r.enabled}
+                    onCheckedChange={(checked) => setRuleEnabled(r.name, checked)}
+                  />
+                  <Button
+                    variant={armedDelete === r.name ? "destructive" : "secondary"}
+                    size="sm"
+                    onClick={() => {
+                      if (armedDelete === r.name) {
+                        void deleteRule(r.name)
+                        setArmedDelete(null)
+                      } else {
+                        setArmedDelete(r.name)
+                      }
+                    }}
+                  >
+                    <Trash2 className="size-4" />
+                    {armedDelete === r.name ? "Confirm" : "Delete"}
+                  </Button>
                 </div>
-                <Badge variant={r.enabled ? "live" : "default"}>
-                  {r.enabled ? "enabled" : "disabled"}
-                </Badge>
               </div>
             ))}
           </div>
+        ) : validation?.ok ? (
+          <div className="flex flex-col items-center gap-2 py-8 text-center text-muted-foreground">
+            <ShieldCheck className="size-7 opacity-40" />
+            <p className="text-sm">No rules saved.</p>
+          </div>
         ) : (
           <div className="flex flex-col items-center gap-2 py-8 text-center text-muted-foreground">
             <ShieldCheck className="size-7 opacity-40" />

server.py

@@ -28,6 +28,8 @@ from tiny_trigger import (
     parse_class_prompt,
     process_video,
 )
+from tiny_trigger.automation import ActionSpec, AutomationDocument, AutomationRule
+from tiny_trigger.automation import document_labels, rule_labels
 from tiny_trigger.actions import dispatch_events
 from tiny_trigger.store import (
     load_local_config,
@@ -112,10 +114,11 @@ def detect_and_automate(
         raise ValueError("A video file is required.")
 
     rules = load_automation_text(rules_text)
+    detection_classes = _merge_class_names(parse_class_prompt(classes), document_labels(rules))
 
     result = process_video(
         video_path=video_path,
-        class_prompt=classes,
+        class_prompt=detection_classes,
         confidence=confidence,
         frame_stride=frame_stride,
         max_frames=max_frames,
@@ -129,6 +132,7 @@ def detect_and_automate(
     events, _last_fired = evaluate_video_detections(
         rules.rules,
         result.detections,
+        frames=result.frames,
         # Uploaded videos use clip-relative timestamps, so cooldowns reset for
         # each run. A live camera mode can persist wall-clock cooldowns later.
         last_fired=None,
@@ -170,6 +174,8 @@ def detect_and_automate(
 def compile_rules(
     instruction: str,
     classes: str = "",
+    existing_rules_text: str = "",
+    append: bool = True,
     provider: str = "local",
     base_url: str = "http://127.0.0.1:8080/v1",
     model: str = "ggml-org/Qwen3-1.7B-GGUF:Q4_K_M",
@@ -178,6 +184,9 @@ def compile_rules(
 ) -> dict:
     """Compile a natural-language request into validated automation rules."""
     class_names = parse_class_prompt(classes) if classes else []
+    if existing_rules_text.strip():
+        existing = load_automation_text(existing_rules_text)
+        class_names = _merge_class_names(class_names, document_labels(existing))
     cfg = load_local_config()
     if provider == "cloud":
         api_token = os.environ.get("REPLICATE_API_TOKEN") or cfg.replicate_api_token
@@ -199,10 +208,15 @@ def compile_rules(
             base_url=base_url or cfg.llamacpp_base_url or "http://127.0.0.1:8080/v1",
             model=model or cfg.llamacpp_model or "ggml-org/Qwen3-1.7B-GGUF:Q4_K_M",
         )
+    document = compiled.document
+    if append and existing_rules_text.strip():
+        existing = load_automation_text(existing_rules_text)
+        document = _merge_documents(existing, compiled.document)
+    save_automations(document)
     return {
-        "rules_text": compiled.document.model_dump_json(by_alias=True, indent=2),
+        "rules_text": document.model_dump_json(by_alias=True, indent=2),
         "raw_text": compiled.raw_text,
-        "rule_count": len(compiled.document.rules),
+        "rule_count": len(document.rules),
     }
 
 
@@ -220,8 +234,10 @@ def validate_rules(rules_text: str) -> dict:
             {
                 "name": r.name,
                 "enabled": r.gate.enabled,
+                "trigger": r.trigger.on,
+                "labels": rule_labels(r),
                 "conditions": len(r.when.all_conditions) + len(r.when.any_conditions),
-                "actions": [{"type": a.type, "name": a.name} for a in r.then],
+                "actions": [_action_dict(a) for a in _rule_actions(r)],
             }
             for r in document.rules
         ],
@@ -235,6 +251,40 @@ def save_rules(rules_text: str) -> dict:
     return {"ok": True, "rule_count": len(document.rules)}
 
 
+@app.api(name="set_rule_enabled")
+def set_rule_enabled(rules_text: str, rule_name: str, enabled: bool) -> dict:
+    document = load_automation_text(rules_text)
+    found = False
+    for rule in document.rules:
+        if rule.name == rule_name:
+            rule.gate.enabled = enabled
+            found = True
+            break
+    if not found:
+        raise ValueError(f"Rule not found: {rule_name}")
+    save_automations(document)
+    return {
+        "ok": True,
+        "rules_text": document.model_dump_json(by_alias=True, indent=2),
+        "rule_count": len(document.rules),
+    }
+
+
+@app.api(name="delete_rule")
+def delete_rule(rules_text: str, rule_name: str) -> dict:
+    document = load_automation_text(rules_text)
+    remaining = [rule for rule in document.rules if rule.name != rule_name]
+    if len(remaining) == len(document.rules):
+        raise ValueError(f"Rule not found: {rule_name}")
+    updated = AutomationDocument(rules=remaining)
+    save_automations(updated)
+    return {
+        "ok": True,
+        "rules_text": updated.model_dump_json(by_alias=True, indent=2),
+        "rule_count": len(updated.rules),
+    }
+
+
 @app.api(name="load_rules")
 def load_rules() -> dict:
     document = load_saved_automations()
@@ -249,6 +299,39 @@ def get_config() -> dict:
     return cfg.model_dump(exclude={"replicate_api_token"})
 
 
+def _merge_documents(existing: AutomationDocument, compiled: AutomationDocument) -> AutomationDocument:
+    by_name = {rule.name: rule for rule in existing.rules}
+    order = [rule.name for rule in existing.rules]
+    for rule in compiled.rules:
+        if rule.name not in by_name:
+            order.append(rule.name)
+        by_name[rule.name] = rule
+    return AutomationDocument(rules=[by_name[name] for name in order])
+
+
+def _rule_actions(rule: AutomationRule) -> list[ActionSpec]:
+    if isinstance(rule.then, list):
+        return rule.then
+    return [*rule.then.enter, *rule.then.exit, *rule.then.while_actions]
+
+
+def _action_dict(action: ActionSpec) -> dict[str, str]:
+    return {"type": action.type, "name": action.name}
+
+
+def _merge_class_names(*groups: list[str]) -> list[str]:
+    seen: set[str] = set()
+    merged: list[str] = []
+    for group in groups:
+        for label in group:
+            normalized = " ".join(label.strip().split())
+            key = normalized.lower()
+            if normalized and key not in seen:
+                seen.add(key)
+                merged.append(normalized)
+    return merged
+
+
 # ── static frontend + media (custom routes take priority over gradio's) ──────
 @app.get("/", response_class=HTMLResponse)
 def index() -> Any:

tests/test_automation.py

@@ -5,8 +5,8 @@ import json
 import pytest
 from pydantic import ValidationError
 
-from tiny_trigger.automation import RuleEngine, evaluate_video_detections, load_automation_text
-from tiny_trigger.models import Detection
+from tiny_trigger.automation import RuleEngine, document_labels, evaluate_video_detections, load_automation_text, rule_labels
+from tiny_trigger.models import Detection, FrameSample
 
 
 def detection(label: str, box: tuple[float, float, float, float], frame: int = 0, time: float = 0.0) -> Detection:
@@ -34,6 +34,7 @@ def test_presence_near_and_cooldown_fire_once_per_window() -> None:
                                 {"cooldown": {"key": "feed-cat", "seconds": 60}},
                             ]
                         },
+                        "trigger": {"on": "while"},
                         "then": [{"type": "simulate", "name": "feed cat"}],
                     }
                 ]
@@ -73,6 +74,54 @@ def test_count_condition() -> None:
     assert len(engine.evaluate_frame(two, frame_index=1, timestamp_sec=1.0)) == 1
 
 
+def test_default_trigger_is_enter_not_every_frame() -> None:
+    document = load_automation_text(
+        json.dumps(
+            {
+                "rules": [
+                    {
+                        "name": "guitar-amplifier-on",
+                        "when": {"all": [{"present": {"label": "guitar"}}]},
+                        "then": [{"type": "simulate", "name": "turn on amplifier"}],
+                    }
+                ]
+            }
+        )
+    )
+    engine = RuleEngine(document.rules)
+    frame = [detection("guitar", (0.1, 0.1, 0.2, 0.2))]
+
+    assert [event.action for event in engine.evaluate_frame(frame, frame_index=0, timestamp_sec=0.0)] == [
+        "turn on amplifier"
+    ]
+    assert engine.evaluate_frame(frame, frame_index=1, timestamp_sec=1.0) == []
+
+
+def test_rule_labels_include_condition_labels() -> None:
+    document = load_automation_text(
+        json.dumps(
+            {
+                "rules": [
+                    {
+                        "name": "person-near-monitor",
+                        "when": {
+                            "all": [
+                                {"present": {"label": "person"}},
+                                {"near": {"a": "person", "b": "monitor"}},
+                                {"far": {"a": "cat", "b": "door"}},
+                            ]
+                        },
+                        "then": [{"type": "simulate", "name": "notify"}],
+                    }
+                ]
+            }
+        )
+    )
+
+    assert rule_labels(document.rules[0]) == ["person", "monitor", "cat", "door"]
+    assert document_labels(document) == ["person", "monitor", "cat", "door"]
+
+
 def test_gate_cooldown_fire_once_per_window() -> None:
     document = load_automation_text(
         json.dumps(
@@ -86,6 +135,7 @@ def test_gate_cooldown_fire_once_per_window() -> None:
                                 {"near": {"a": "person", "b": "steering wheel", "max_distance": 0.45}},
                             ]
                         },
+                        "trigger": {"on": "while"},
                         "gate": {"enabled": True, "cooldown": {"key": "turn-on-pc", "seconds": 60}},
                         "then": [{"type": "simulate", "name": "turn on pc"}],
                     }
@@ -132,6 +182,7 @@ def test_evaluate_video_detections_returns_updated_last_fired() -> None:
                     {
                         "name": "turn-on-pc",
                         "when": {"all": [{"present": {"label": "person"}}]},
+                        "trigger": {"on": "while"},
                         "gate": {"cooldown": {"key": "turn-on-pc", "seconds": 60}},
                         "then": [{"type": "simulate", "name": "turn on pc"}],
                     }
@@ -163,6 +214,7 @@ def test_video_cooldowns_are_fresh_without_persisted_last_fired() -> None:
                     {
                         "name": "turn-on-pc",
                         "when": {"all": [{"present": {"label": "person"}}]},
+                        "trigger": {"on": "while"},
                         "gate": {"cooldown": {"key": "turn-on-pc", "seconds": 60}},
                         "then": [{"type": "simulate", "name": "turn on pc"}],
                     }
@@ -180,6 +232,74 @@ def test_video_cooldowns_are_fresh_without_persisted_last_fired() -> None:
     assert first_last_fired == second_last_fired == {"turn-on-pc": 12.0}
 
 
+def test_change_trigger_fires_enter_and_exit() -> None:
+    document = load_automation_text(
+        json.dumps(
+            {
+                "rules": [
+                    {
+                        "name": "monitor-lights",
+                        "when": {
+                            "all": [
+                                {"near": {"a": "person", "b": "monitor", "max_gap_percent": 8}},
+                            ]
+                        },
+                        "trigger": {"on": "change"},
+                        "then": {
+                            "enter": [{"type": "simulate", "name": "turn on lights"}],
+                            "exit": [{"type": "simulate", "name": "turn off lights"}],
+                        },
+                    }
+                ]
+            }
+        )
+    )
+    engine = RuleEngine(document.rules)
+    matching = [
+        detection("person", (0.10, 0.10, 0.20, 0.20)),
+        detection("monitor", (0.23, 0.10, 0.33, 0.20)),
+    ]
+
+    enter_events = engine.evaluate_frame(matching, frame_index=0, timestamp_sec=0.0)
+    while_events = engine.evaluate_frame(matching, frame_index=1, timestamp_sec=1.0)
+    exit_events = engine.evaluate_frame([], frame_index=2, timestamp_sec=2.0)
+
+    assert [event.action for event in enter_events] == ["turn on lights"]
+    assert while_events == []
+    assert [event.action for event in exit_events] == ["turn off lights"]
+
+
+def test_video_evaluation_uses_empty_frames_for_exit_triggers() -> None:
+    document = load_automation_text(
+        json.dumps(
+            {
+                "rules": [
+                    {
+                        "name": "person-presence",
+                        "when": {"all": [{"present": {"label": "person"}}]},
+                        "trigger": {"on": "change"},
+                        "then": {
+                            "enter": [{"type": "simulate", "name": "arrived"}],
+                            "exit": [{"type": "simulate", "name": "left"}],
+                        },
+                    }
+                ]
+            }
+        )
+    )
+
+    events, _last_fired = evaluate_video_detections(
+        document.rules,
+        [detection("person", (0.1, 0.1, 0.2, 0.2), frame=0, time=0.0)],
+        frames=[
+            FrameSample(frame_index=0, timestamp_sec=0.0),
+            FrameSample(frame_index=1, timestamp_sec=1.0),
+        ],
+    )
+
+    assert [event.action for event in events] == ["arrived", "left"]
+
+
 def test_invalid_rule_rejected() -> None:
     with pytest.raises(ValidationError):
         load_automation_text(

tests/test_llm.py

@@ -47,9 +47,13 @@ def test_prompt_teaches_near_relations() -> None:
         class_names=["person", "steering wheel"],
     )
 
-    assert '"near": {"a": "person", "b": "steering wheel", "max_distance": 0.45}' in prompt
+    assert '"near": {"a": "person", "b": "steering wheel", "max_gap_percent": 8}' in prompt
     assert "Do not replace a near relation with two present conditions." in SYSTEM_PROMPT
+    assert "Use max_gap_percent for near/far box-edge distance." in SYSTEM_PROMPT
     assert "Use state gates in gate: enabled, cooldown." in SYSTEM_PROMPT
+    assert 'Use trigger.on="enter" for state assertions' in SYSTEM_PROMPT
+    assert 'trigger.on="change"' in SYSTEM_PROMPT
+    assert '"trigger": {"on": "enter"}' in prompt
     assert '"gate": {"enabled": true}' in prompt
     assert '"gate": {"enabled": true, "cooldown": {"key": "package-at-door", "minutes": 15}}' in prompt
 

tests/test_server.py

@@ -0,0 +1,49 @@
+from __future__ import annotations
+
+import json
+
+from server import _merge_class_names, _merge_documents
+from tiny_trigger.automation import AutomationDocument, load_automation_text
+
+
+def test_merge_documents_replaces_same_named_rule() -> None:
+    existing = load_automation_text(
+        json.dumps(
+            {
+                "rules": [
+                    {
+                        "name": "monitor-lights",
+                        "when": {"all": [{"present": {"label": "person"}}]},
+                        "then": [{"type": "simulate", "name": "old action"}],
+                    }
+                ]
+            }
+        )
+    )
+    compiled = load_automation_text(
+        json.dumps(
+            {
+                "rules": [
+                    {
+                        "name": "monitor-lights",
+                        "when": {"all": [{"present": {"label": "monitor"}}]},
+                        "then": [{"type": "simulate", "name": "new action"}],
+                    }
+                ]
+            }
+        )
+    )
+
+    merged = _merge_documents(existing, compiled)
+
+    assert isinstance(merged, AutomationDocument)
+    assert [rule.name for rule in merged.rules] == ["monitor-lights"]
+    assert merged.rules[0].then[0].name == "new action"
+
+
+def test_merge_class_names_adds_rule_labels_without_duplicates() -> None:
+    assert _merge_class_names(["person", "Monitor"], ["monitor", "guitar"]) == [
+        "person",
+        "Monitor",
+        "guitar",
+    ]

tiny_trigger/automation.py

@@ -1,19 +1,30 @@
 from __future__ import annotations
 
 import json
-import math
 from collections import defaultdict
 from typing import Any, Literal
 
 from pydantic import AliasChoices, BaseModel, ConfigDict, Field, ValidationError, model_validator
 
-from .models import ActionEvent, Detection
+from .models import ActionEvent, Detection, FrameSample
 
 
 def _label(value: str) -> str:
     return value.strip().lower()
 
 
+def _dedupe_labels(labels: list[str]) -> list[str]:
+    seen: set[str] = set()
+    result: list[str] = []
+    for label in labels:
+        normalized = " ".join(label.strip().split())
+        key = normalized.lower()
+        if normalized and key not in seen:
+            seen.add(key)
+            result.append(normalized)
+    return result
+
+
 class PresentCondition(BaseModel):
     label: str
     min_count: int = Field(default=1, ge=1)
@@ -27,7 +38,26 @@ class CountCondition(BaseModel):
 class NearCondition(BaseModel):
     a: str
     b: str
-    max_distance: float = Field(default=0.35, ge=0.0)
+    max_gap_percent: float = Field(
+        default=8.0,
+        ge=0.0,
+        validation_alias=AliasChoices("max_gap_percent", "max_distance"),
+    )
+
+    @model_validator(mode="before")
+    @classmethod
+    def migrate_max_distance(cls, data: Any) -> Any:
+        if isinstance(data, dict) and "max_distance" in data and "max_gap_percent" not in data:
+            value = data["max_distance"]
+            if isinstance(value, int | float) and value <= 1:
+                return {**data, "max_gap_percent": value * 100.0}
+        return data
+
+
+class FarCondition(BaseModel):
+    a: str
+    b: str
+    min_gap_percent: float = Field(default=25.0, ge=0.0)
 
 
 class CooldownCondition(BaseModel):
@@ -48,11 +78,12 @@ class ConditionBlock(BaseModel):
     present: PresentCondition | None = None
     count: CountCondition | None = None
     near: NearCondition | None = None
+    far: FarCondition | None = None
     cooldown: CooldownCondition | None = None
 
     @model_validator(mode="after")
     def exactly_one_condition(self) -> "ConditionBlock":
-        selected = [self.present, self.count, self.near, self.cooldown]
+        selected = [self.present, self.count, self.near, self.far, self.cooldown]
         if sum(item is not None for item in selected) != 1:
             raise ValueError("Each condition block must contain exactly one condition.")
         return self
@@ -78,6 +109,18 @@ class ActionSpec(BaseModel):
     payload: dict[str, Any] = Field(default_factory=dict)
 
 
+class TriggerClause(BaseModel):
+    on: Literal["while", "enter", "exit", "change"] = "enter"
+
+
+class ActionSet(BaseModel):
+    model_config = ConfigDict(populate_by_name=True)
+
+    enter: list[ActionSpec] = Field(default_factory=list)
+    exit: list[ActionSpec] = Field(default_factory=list)
+    while_actions: list[ActionSpec] = Field(default_factory=list, alias="while")
+
+
 class GateClause(BaseModel):
     enabled: bool = True
     cooldown: CooldownCondition | None = None
@@ -86,12 +129,27 @@ class GateClause(BaseModel):
 class AutomationRule(BaseModel):
     name: str
     when: WhenClause
+    trigger: TriggerClause = Field(default_factory=TriggerClause)
     gate: GateClause = Field(default_factory=GateClause)
-    then: list[ActionSpec] = Field(min_length=1)
+    then: list[ActionSpec] | ActionSet
+
+    @model_validator(mode="after")
+    def has_actions_for_trigger(self) -> "AutomationRule":
+        if isinstance(self.then, list):
+            if not self.then:
+                raise ValueError("A rule needs at least one action.")
+            if self.trigger.on in {"exit", "change"}:
+                raise ValueError("exit/change triggers need then.exit or then.enter/then.exit actions.")
+            return self
+
+        actions = _actions_for_trigger(self.then, self.trigger.on)
+        if not actions:
+            raise ValueError(f"A rule with trigger.on={self.trigger.on!r} needs matching actions.")
+        return self
 
 
 class AutomationDocument(BaseModel):
-    rules: list[AutomationRule] = Field(min_length=1)
+    rules: list[AutomationRule] = Field(default_factory=list)
 
 
 def load_automation_text(text: str) -> AutomationDocument:
@@ -126,10 +184,39 @@ def automation_schema() -> dict[str, Any]:
     return AutomationDocument.model_json_schema()
 
 
+def rule_labels(rule: AutomationRule) -> list[str]:
+    labels: list[str] = []
+    for condition in [*rule.when.all_conditions, *rule.when.any_conditions]:
+        if condition.present:
+            labels.append(condition.present.label)
+        if condition.count:
+            labels.append(condition.count.label)
+        if condition.near:
+            labels.extend([condition.near.a, condition.near.b])
+        if condition.far:
+            labels.extend([condition.far.a, condition.far.b])
+    return _dedupe_labels(labels)
+
+
+def document_labels(document: AutomationDocument, *, enabled_only: bool = True) -> list[str]:
+    labels: list[str] = []
+    for rule in document.rules:
+        if enabled_only and not rule.gate.enabled:
+            continue
+        labels.extend(rule_labels(rule))
+    return _dedupe_labels(labels)
+
+
 class RuleEngine:
-    def __init__(self, rules: list[AutomationRule], last_fired: dict[str, float] | None = None) -> None:
+    def __init__(
+        self,
+        rules: list[AutomationRule],
+        last_fired: dict[str, float] | None = None,
+        last_matched: dict[str, bool] | None = None,
+    ) -> None:
         self.rules = rules
         self.last_fired: dict[str, float] = dict(last_fired or {})
+        self.last_matched: dict[str, bool] = dict(last_matched or {})
 
     def evaluate_frame(
         self,
@@ -141,15 +228,22 @@ class RuleEngine:
         events: list[ActionEvent] = []
         for rule in self.rules:
             if not self._gate_allows(rule, timestamp_sec):
+                self.last_matched[rule.name] = False
                 continue
-            if not self._rule_matches(rule, detections, timestamp_sec):
+            matched = self._rule_matches(rule, detections, timestamp_sec)
+            previous = self.last_matched.get(rule.name, False)
+            edge = _trigger_edge(previous=previous, matched=matched)
+            self.last_matched[rule.name] = matched
+            actions = _actions_to_fire(rule, edge)
+            if not matched and not actions:
                 continue
 
             self._mark_cooldowns(rule, timestamp_sec)
-            for action in rule.then:
+            for action in actions:
                 payload = {
                     "rule": rule.name,
                     "action": action.name,
+                    "trigger": edge,
                     "frame_index": frame_index,
                     "timestamp_sec": timestamp_sec,
                     "detections": [item.model_dump(mode="json") for item in detections],
@@ -208,7 +302,14 @@ class RuleEngine:
             right = by_label[_label(condition.near.b)]
             if not left or not right:
                 return False
-            return _min_center_distance(left, right) <= condition.near.max_distance
+            return _min_box_gap_percent(left, right) <= condition.near.max_gap_percent
+
+        if condition.far:
+            left = by_label[_label(condition.far.a)]
+            right = by_label[_label(condition.far.b)]
+            if not left or not right:
+                return False
+            return _min_box_gap_percent(left, right) >= condition.far.min_gap_percent
 
         if condition.cooldown:
             return self._cooldown_allows(condition.cooldown, rule_name, timestamp_sec)
@@ -232,6 +333,7 @@ def evaluate_video_detections(
     rules: list[AutomationRule],
     detections: list[Detection],
     *,
+    frames: list[FrameSample] | None = None,
     last_fired: dict[str, float] | None = None,
 ) -> tuple[list[ActionEvent], dict[str, float]]:
     engine = RuleEngine(rules, last_fired=last_fired)
@@ -240,6 +342,9 @@ def evaluate_video_detections(
 
     for detection in detections:
         grouped[(detection.frame_index, detection.timestamp_sec)].append(detection)
+    if frames:
+        for frame in frames:
+            grouped.setdefault((frame.frame_index, frame.timestamp_sec), [])
 
     for (frame_index, timestamp_sec), frame_detections in sorted(grouped.items()):
         events.extend(
@@ -259,16 +364,55 @@ def _group_by_label(detections: list[Detection]) -> dict[str, list[Detection]]:
     return grouped
 
 
-def _center(detection: Detection) -> tuple[float, float]:
-    x1, y1, x2, y2 = detection.bbox_xyxy_norm
-    return ((x1 + x2) / 2.0, (y1 + y2) / 2.0)
-
-
-def _min_center_distance(left: list[Detection], right: list[Detection]) -> float:
+def _min_box_gap_percent(left: list[Detection], right: list[Detection]) -> float:
     best = float("inf")
     for left_detection in left:
-        lx, ly = _center(left_detection)
         for right_detection in right:
-            rx, ry = _center(right_detection)
-            best = min(best, math.dist((lx, ly), (rx, ry)))
+            best = min(best, _box_gap_percent(left_detection, right_detection))
     return best
+
+
+def _box_gap_percent(left: Detection, right: Detection) -> float:
+    ax1, ay1, ax2, ay2 = left.bbox_xyxy_norm
+    bx1, by1, bx2, by2 = right.bbox_xyxy_norm
+    gap_x = max(0.0, max(bx1 - ax2, ax1 - bx2))
+    gap_y = max(0.0, max(by1 - ay2, ay1 - by2))
+    return max(gap_x, gap_y) * 100.0
+
+
+def _trigger_edge(*, previous: bool, matched: bool) -> Literal["enter", "exit", "while", "none"]:
+    if matched and not previous:
+        return "enter"
+    if not matched and previous:
+        return "exit"
+    if matched:
+        return "while"
+    return "none"
+
+
+def _actions_to_fire(rule: AutomationRule, edge: str) -> list[ActionSpec]:
+    trigger = rule.trigger.on
+    if trigger == "while":
+        return _actions_for_trigger(rule.then, "while") if edge in {"enter", "while"} else []
+    if trigger == "enter":
+        return _actions_for_trigger(rule.then, "enter") if edge == "enter" else []
+    if trigger == "exit":
+        return _actions_for_trigger(rule.then, "exit") if edge == "exit" else []
+    if trigger == "change":
+        return _actions_for_trigger(rule.then, edge) if edge in {"enter", "exit"} else []
+    return []
+
+
+def _actions_for_trigger(
+    actions: list[ActionSpec] | ActionSet,
+    trigger: Literal["while", "enter", "exit", "change"],
+) -> list[ActionSpec]:
+    if isinstance(actions, list):
+        return actions if trigger in {"while", "enter"} else []
+    if trigger == "while":
+        return actions.while_actions or actions.enter
+    if trigger == "enter":
+        return actions.enter
+    if trigger == "exit":
+        return actions.exit
+    return [*actions.enter, *actions.exit]

tiny_trigger/llm.py

@@ -12,12 +12,17 @@ from .automation import AutomationDocument, automation_schema
 SYSTEM_PROMPT = """You compile home automation requests into Tiny Trigger rules.
 Return JSON only. Never return code, markdown, explanations, or tool calls.
 The root object MUST include a non-empty "rules" array.
-Use video conditions in when: present, count, near.
+Use video conditions in when: present, count, near, far.
 Use state gates in gate: enabled, cooldown.
+Use trigger.on for edge behavior: while, enter, exit, change.
 Use only these action types: simulate, webhook.
+Use trigger.on="enter" for state assertions like "must be on", "should be on", "keep on", "turn on when", or "notify when".
+Use trigger.on="while" only when the user explicitly wants repeated actions while a condition remains true, usually with a cooldown.
 When the request says one object is near, next to, beside, at, by, close to, or in front of another object, you MUST emit a near condition.
 Do not replace a near relation with two present conditions.
+Use max_gap_percent for near/far box-edge distance. It is the largest horizontal/vertical edge gap between boxes in normalized frame percent; touching or overlapping boxes have gap 0.
 If the user mentions elapsed time since an action or limiting repeat fires, encode it as gate.cooldown.
+If the user asks for an action when a condition starts and another action when it stops, use trigger.on="change" and then.enter / then.exit.
 """
 
 
@@ -176,7 +181,10 @@ def _post_chat_completion(
 
 def _validate_compile_result(raw_text: str) -> LLMCompileResult:
     data = json.loads(extract_json_object(raw_text))
-    return LLMCompileResult(raw_text=raw_text, document=AutomationDocument.model_validate(data))
+    document = AutomationDocument.model_validate(data)
+    if not document.rules:
+        raise ValueError("LLM response must include a non-empty rules array.")
+    return LLMCompileResult(raw_text=raw_text, document=document)
 
 
 def extract_json_object(text: str) -> str:
@@ -206,6 +214,7 @@ Return a JSON object matching this high-level shape:
     {{
       "name": "short-kebab-case-name",
       "when": {{"all": [{{"present": {{"label": "cat", "min_count": 1}}}}]}},
+      "trigger": {{"on": "while"}},
       "gate": {{"enabled": true}},
       "then": [{{"type": "simulate", "name": "action name"}}]
     }}
@@ -223,9 +232,10 @@ JSON:
       "when": {{
         "all": [
           {{"present": {{"label": "person", "min_count": 1}}}},
-          {{"near": {{"a": "person", "b": "steering wheel", "max_distance": 0.45}}}}
+          {{"near": {{"a": "person", "b": "steering wheel", "max_gap_percent": 8}}}}
         ]
       }},
+      "trigger": {{"on": "enter"}},
       "gate": {{"enabled": true}},
       "then": [{{"type": "simulate", "name": "turn on pc"}}]
     }}
@@ -241,15 +251,55 @@ JSON:
       "when": {{
         "all": [
           {{"present": {{"label": "package", "min_count": 1}}}},
-          {{"near": {{"a": "package", "b": "door", "max_distance": 0.45}}}}
+          {{"near": {{"a": "package", "b": "door", "max_gap_percent": 8}}}}
         ]
       }},
+      "trigger": {{"on": "while"}},
       "gate": {{"enabled": true, "cooldown": {{"key": "package-at-door", "minutes": 15}}}},
       "then": [{{"type": "simulate", "name": "notify me"}}]
     }}
   ]
 }}
 
+User: While there is a guitar in the scene, amplifier must be on.
+JSON:
+{{
+  "rules": [
+    {{
+      "name": "guitar-amplifier-on",
+      "when": {{
+        "all": [
+          {{"present": {{"label": "guitar", "min_count": 1}}}}
+        ]
+      }},
+      "trigger": {{"on": "enter"}},
+      "gate": {{"enabled": true}},
+      "then": [{{"type": "simulate", "name": "turn on amplifier"}}]
+    }}
+  ]
+}}
+
+User: If person is near monitor turn on lights. When they leave, turn off lights.
+JSON:
+{{
+  "rules": [
+    {{
+      "name": "monitor-presence-lights",
+      "when": {{
+        "all": [
+          {{"near": {{"a": "person", "b": "monitor", "max_gap_percent": 8}}}}
+        ]
+      }},
+      "trigger": {{"on": "change"}},
+      "gate": {{"enabled": true}},
+      "then": {{
+        "enter": [{{"type": "simulate", "name": "turn on lights"}}],
+        "exit": [{{"type": "simulate", "name": "turn off lights"}}]
+      }}
+    }}
+  ]
+}}
+
 Full validation schema:
 {json.dumps(automation_schema(), indent=2)}
 """

tiny_trigger/models.py

@@ -14,10 +14,16 @@ class Detection(BaseModel):
     bbox_xyxy_norm: tuple[float, float, float, float]
 
 
+class FrameSample(BaseModel):
+    frame_index: int = Field(ge=0)
+    timestamp_sec: float = Field(ge=0.0)
+
+
 class VideoProcessResult(BaseModel):
     output_video_path: str
     classes: list[str]
     detections: list[Detection]
+    frames: list[FrameSample] = Field(default_factory=list)
     processed_frames: int
     source_fps: float
     output_fps: float

tiny_trigger/video.py

@@ -9,7 +9,7 @@ from typing import Callable
 from uuid import uuid4
 
 from .detector import Detector, UltralyticsYOLOEDetector, parse_class_prompt
-from .models import ActionEvent, Detection, VideoProcessResult
+from .models import ActionEvent, Detection, FrameSample, VideoProcessResult
 
 
 ProgressCallback = Callable[[int, int | None], None]
@@ -68,6 +68,7 @@ def process_video(
         raise ValueError(f"Could not create annotated video: {output_path}")
 
     detections: list[Detection] = []
+    frames: list[FrameSample] = []
     processed_frames = 0
     frame_index = -1
     try:
@@ -82,6 +83,7 @@ def process_video(
                 break
 
             timestamp_sec = frame_index / source_fps
+            frames.append(FrameSample(frame_index=frame_index, timestamp_sec=timestamp_sec))
             frame_detections = detector.detect(
                 frame,
                 frame_index=frame_index,
@@ -105,6 +107,7 @@ def process_video(
         output_video_path=str(output_path),
         classes=classes,
         detections=detections,
+        frames=frames,
         processed_frames=processed_frames,
         source_fps=source_fps,
         output_fps=output_fps,