SmartestHome/chores/README.md

# chores

Camera-verified household task distribution, from
[Phase 20 of the project plan](../docs/project-plan.md).

**The principle, stated once because it drives every design choice here: "I don't
care who does it, as long as it gets done."** This is not an assignment system that
picks one fair person and waits on them — it's a nudge system that keeps redirecting
to whoever is actually around until the chore is done. Fairness is tracked for
comparison, not enforced by any algorithm — see "The tally is passive" below.

Runs every ~2 hours via a systemd timer with `RandomizedDelaySec=1800` (systemd's
own built-in jitter — the "+/-30 min in case something else is running" the phase
was specified with, not custom code). Three steps, in order — see `check.py`'s own
module docstring for the full reasoning on each:

1. **Trash-day-eve** — reads the same personal collection-date feed
   `trash-calendar` reads (`WASTE_ICS_URL`); if pickup is tomorrow, opens a "trash"
   chore.
2. **Camera checks** (opt-in, needs `FRIGATE_URL` + `CAMERA_WATCHPOINTS`) — grabs a
   Frigate snapshot per configured watch point (optionally moving a PTZ camera to a
   preset first), asks an Ollama vision model a one-word question ("is this bin
   FULL/PARTIAL/EMPTY", "is this counter DIRTY/CLEAN", "is there litter left out
   here, YES/NO"), opens a chore on "needs attention," auto-closes one on "clear."
3. **Nudging** — ASAP, not on a fixed schedule: the first run after a chore opens
   nudges whoever `identity` reports home right now — preferring anyone **assigned**
   that chore type, minus anyone `chore_exempt`, both below. If the chore is still open `NEGLECT_THRESHOLD_HOURS` after the last
   nudge (and the household calendar isn't showing a busy window), the nudge goes
   to **someone different from who was last asked** — "the next person that walks
   by" — rather than re-nagging the same person. `litter` chores are special-cased
   to prefer whoever the camera most recently recognized nearby (a best-effort
   "who left this" guess), since the point there is telling the actual person, not
   just whoever's around — and `litter` also ignores `chore_exempt` entirely, see
   below. Each nudge's wording is a plain template unless the target has a
   `chore_reminder_style` set, see below.

## Assignment is a preference, not a lock

Set in `identity`'s admin panel (`admin.html`, People → a person → Chores), stored as
that person's `chore_assignments` and read off the same `/presence` call as everything
else here.

When someone assigned to a chore type **is home**, they get nudged instead of whoever
happens to be nearest — that's the point of assigning it. When **no assignee is home**,
the nudge falls through to the ordinary whoever's-here rotation rather than waiting,
because the stated principle is still *"I don't care who does it, as long as it gets
done."* An absent assignee doesn't get to be the reason the bin stays full.

Set **`CHORE_ASSIGNMENT_STRICT=true`** if your household wants the opposite: the chore
waits for its assignee and nobody else is asked. Both readings of "assign chores" are
legitimate and this file can't pick for you, so it's one env var rather than a
hard-coded opinion. Strict mode still never stalls a chore that was assigned to
*nobody* — that falls through regardless.

**Litter can't be assigned** (`_ASSIGNMENTS_DONT_APPLY` in `check.py`), for the same
reason it ignores exemptions: it goes to whoever left the mess, and cleaning up after
yourself was never a task anyone could be handed.

## Chore-exempt people — everyone except litter

Set in the same place (`identity`'s admin panel, or `POST /people/<id>/chore-settings`
directly). A `chore_exempt` person is
dropped from the nudge rotation entirely — the "cousin visits often but doesn't owe
me chores" case. **Litter is the deliberate exception** (`_EXEMPTIONS_DONT_APPLY`
in `check.py`): an exempt person still gets told to put trash they left out into
the bin, because that isn't "doing a chore," it's cleaning up after yourself. If
everyone currently home is chore_exempt for a non-litter chore, that run just logs
and skips — the chore stays open until someone eligible is around.

## Reminder tone is per-person and LLM-phrased, but never LLM-decided

`identity`'s `chore_reminder_style` free-text field ("be assertive, don't let up" /
"be gentle, give me a few minutes of grace") is passed to `OLLAMA_TEXT_MODEL` (if
configured) purely to phrase the ntfy message text — see `_compose_message()`. This
is deliberately scoped narrower than the general chore-distribution LLM idea from
earlier in the project: it changes *how the reminder is worded*, never *who* gets
nudged or *when* — that decision stays presence/calendar-driven, per the module
docstring's stated principle. No `OLLAMA_TEXT_MODEL` configured, no style set for
that person, or the call fails/returns nothing for any reason: the plain
un-styled template is used verbatim, same wording as before this feature existed.

## The tally is passive

Every nudge is logged with who got it. **Nothing reads that log to decide who to
nudge next** — that decision is presence/calendar-driven only, per the stated
principle. The log exists purely so a household member can look at the numbers
later and judge fairness for themselves ("comparison for fairness's sake," not an
automated fairness algorithm) — `print_tally()` logs a rolling 30-day count each
run; nothing renders it anywhere yet, see "What's not built."

## The calendar busy-check is household-wide, not per-person

`_household_currently_busy()` looks for a currently-active event on the **one**
shared household calendar whose summary contains a configured keyword (`busy`,
`meeting`, `call`, `movie`, `sleep`, ...) and pauses nudging for that run if it
finds one. This is a real, honest limitation: it can't tell that only one person is
in that meeting and nudge someone else who's free — everyone's nudges pause
together. A real per-person calendar/availability model would need per-person
calendars, which this project doesn't have (see `docs/project-plan.md`'s open
decisions). Fails open (treats an unreachable/misconfigured calendar as "not busy")
so a broken calendar check can never be the reason chores stop getting nudged
entirely.

## Never auto-completes from nudging

Only a fresh camera check finding a watch point clear, or a manual close (not built
here — see "What's not built" below), ever marks a chore done. A nudge firing is
not the same as the chore being done; conflating the two would let something that
was repeatedly nudged but never actually done silently vanish.

## Why this is a separate service, not folded into `identity` or `pantry-vision`

It reads from `identity` (who's home, who's nearby, who was recently seen by a
camera) and reuses `trash-calendar`'s own ICS feed config and digest-engine's own
CalDAV credential names, but owns a genuinely different job — task state,
presence-driven nudging, notification escalation — that doesn't belong bolted onto
any of those services' own single responsibilities. Same reasoning as
`trash-calendar` itself being separate from `digest-engine`'s read-only calendar
ingestion.

## What's not built

- **No way to manually mark a chore done** — no HA button, no voice phrase, no API
  endpoint. Right now the only way a chore closes is a camera re-check finding it
  clear, or direct SQLite surgery. A real deployment probably wants an HA
  button/voice "mark the trash as done" — deliberately left out of this pass rather
  than guessed at without knowing how the household actually wants to interact with
  it.
- **No per-person ntfy topics** — one shared `NTFY_TOPIC`, message text names who
  it's for. Set up real per-person routing yourself if that's not enough.
- **No web UI / dashboard for chore history or the fairness tally** —
  `chore_events` logs everything (created, nudged, auto_closed) and the tally is
  logged each run, but nothing renders either anywhere yet.
- **No per-person calendar availability** — see "household-wide, not per-person"
  above.
- **No re-check of `_compose_message()`'s LLM output** — whatever the model
  returns (if anything) is sent as-is, no validation that it's actually on-topic,
  on-tone, or even non-empty garbage beyond the plain empty-string fallback check.
- **No confirmation that an assignee actually did it** — assignment changes who gets
  asked, not who gets credited. Attribution when a chore closes is still the same
  best-effort "whoever was nudged most recently" heuristic, which an assignment doesn't
  make any more truthful. See "The tally is passive" above.

## Configure

```sh
cp chores/chores.env.example /opt/smart-home/chores/chores.env
chmod 600 /opt/smart-home/chores/chores.env
$EDITOR /opt/smart-home/chores/chores.env
```

Works with nothing but `IDENTITY_URL`/`IDENTITY_TOKEN` and ntfy filled in — the
trash-day-eve check, calendar busy-check, and camera checks all individually no-op
when left unconfigured.

## Manual verification still outstanding

1. **Frigate's PTZ move-to-preset API shape** (`_frigate_snapshot()`'s
   `POST /api/<camera>/ptz/move/<preset>`) is assumed from Frigate's general PTZ
   feature set, not confirmed against a real Tapo PTZ camera wired into Frigate —
   see `docs/project-plan.md` §1.18/Phase 20's own callout. A wrong endpoint just
   means the snapshot is taken from wherever the camera already was.
2. Whether the vision model's one-word FULL/PARTIAL/EMPTY/DIRTY/CLEAN/YES/NO
   answers are actually reliable for a real bin/sink/hallway from a real camera
   angle — completely unmeasured, same caveat as pantry-vision's own vision-model
   accuracy note.
3. `_likely_culprit()`'s reliance on `identity`'s `face_seen_recently` field
   assumes Frigate face-recognition presence corroboration is actually wired up
   and working (`identity/README.md`'s own "Camera face recognition" section is
   itself unverified) — until then, litter chores just fall back to "whoever's
   around," same as every other chore type.
4. `_household_currently_busy()`'s CalDAV read has never been run against a real
   Nextcloud instance from this specific code path (digest-engine's own
   `ingest/caldav.py` is a separate, independently-tested read).
5. No camera hardware has been chosen (`docs/project-plan.md` §1.18) — nothing here
   has been run against a real Tapo camera or Frigate PTZ integration at all.
6. `_compose_message()`'s LLM-phrased reminders have never been checked against a
   real `OLLAMA_TEXT_MODEL` for whether the output actually respects a given
   `chore_reminder_style` reliably, vs. just producing generically-toned text —
   same "no measured accuracy" caveat as the vision checks above. A bad or
   off-style result still gets sent (there's no re-check of the LLM's own output
   here), just not blocked — see "What's not built" for why there's no re-check.