From 07f5f341e61be05c44b6588f536e465f10877442 Mon Sep 17 00:00:00 2001 From: adlee-was-taken Date: Sun, 5 Apr 2026 09:48:12 -0400 Subject: [PATCH] docs: add pets subsystem reference --- docs/architecture/subsystems/pets.md | 34 ++++++++++++++++++++++++++++ 1 file changed, 34 insertions(+) create mode 100644 docs/architecture/subsystems/pets.md diff --git a/docs/architecture/subsystems/pets.md b/docs/architecture/subsystems/pets.md new file mode 100644 index 0000000..43f1863 --- /dev/null +++ b/docs/architecture/subsystems/pets.md @@ -0,0 +1,34 @@ +# pets + +## Purpose + +Pet rule engine. Defines composable conditions (detected-in-zone, not-seen-for-N-minutes, detected-without-person, time-of-day, etc.) and per-pet state tracking that downstream code uses to trigger pet-specific alerts and automations. The on-camera pet identification itself lives in `vigilar/detection/pet_id.py`; this package is the behavioural layer on top of those sightings. + +## Key files + +- `vigilar/pets/rules.py` — `PetState` dataclass, `evaluate_condition`, rule evaluator; reads `pet_rules` via `get_all_enabled_rules` +- `vigilar/pets/__init__.py` (empty) + +## MQTT topics + +**Subscribes:** No MQTT subscribers found at time of writing. The module is invoked as a library — typically from the events processor or an evaluator that already has topic payloads in hand. +**Publishes:** No MQTT publishers found at time of writing. + +## Database tables + +- `pet_rules` — loaded via `vigilar.storage.queries.get_all_enabled_rules` +- `pets`, `pet_sightings`, `pet_training_images` — owned schema-wise by this feature area but written from elsewhere (events processor for sightings, detection/trainer for training images, web for pets CRUD) + +## Depends on + +- `storage` — reads `pet_rules` +- `alerts.profiles` — reuses `is_in_time_window` for time-of-day conditions + +## Consumed by + +- `events` / rule evaluator — drives pet-specific alert actions +- `web` — the `pets` blueprint manages pets, training images, and rules + +## Notes + +`PetState` is per-pet, in-memory, and tracks last-seen camera and time, current zone with entry time, and whether a person is currently present alongside the pet. This makes rules like "cat in kitchen for more than 5 minutes while nobody is home" possible without joining SQLite on every frame. The condition schema is a plain dict with a `type` discriminator, so new condition kinds can be added without schema changes.