Skip to content

AI Features

Jump to bottom
William Forsyth edited this page Apr 5, 2026 · 2 revisions

AI Features

OpenChore includes optional AI features that make chore management smarter and more accessible. Both features run as Docker sidecar containers and can be enabled independently.

AI Photo Review

For chores that require photo proof, the AI can automatically review submissions and give kids instant feedback — no waiting for a parent to approve.

How It Works

  1. A kid finishes a chore and submits a photo (e.g., a picture of the clean kitchen)
  2. The Gemma 4 vision model analyzes the photo and scores it against the chore's expectations
  3. If the confidence score meets the threshold (default 0.85), the chore is auto-approved
  4. If the score is below the threshold, the kid sees friendly, specific feedback on their chore card

Kid-Friendly Feedback

When a photo doesn't pass review, the AI generates an encouraging message that tells the kid exactly what to fix — not a generic rejection. For example:

  • "Great start! There are still a few dishes on the counter."
  • "Almost there! The bed looks good but the pillows need straightening."
  • "Nice work on the floor! Don't forget to wipe down the table too."

Kids can re-submit a new photo after addressing the feedback.

Graceful Fallback

If the AI sidecar is unavailable (container down, network issue, etc.), OpenChore falls back to the normal completion flow — the chore goes into the parent approval queue as usual. AI review is an enhancement, never a blocker.

Text-to-Speech

TTS makes chores accessible to younger kids who can't read yet, and adds a fun audio element for everyone.

How It Works

Text-to-speech generation happens in two stages:

  1. LLM text generation — Gemma 4 creates a short, kid-friendly description of each chore (e.g., "Time to make your bed! Pull the covers up nice and smooth, and don't forget your pillows.")
  2. Audio synthesis — Kokoro TTS converts that description into a natural-sounding audio file

Audio is pre-generated in the background when chores are created, so playback is instant with no loading delay.

Frontend Fallback Chain

The app uses a three-tier fallback to ensure kids always hear something:

  1. Audio file — plays the pre-generated Kokoro audio if available
  2. Browser TTS with LLM description — uses the browser's built-in speech synthesis with the AI-generated text
  3. Browser TTS with raw title — reads the chore title aloud as a last resort

AI feedback messages (from photo review) can also be synthesized as audio, so younger kids can hear what they need to fix.

Setup

Getting the AI stack running takes just a few steps:

1. Enable the AI Profile

Start OpenChore with the AI containers included:

docker compose --profile ai up

This adds the LiteRT and Kokoro sidecar containers alongside the main app. On first start, the LiteRT container automatically downloads the Gemma 4 model (~2.6 GB one-time download). Subsequent starts are instant.

2. Enable in Admin Settings

  1. Go to Admin > Settings > AI Photo Review
  2. Toggle Enable to turn on AI review
  3. Toggle TTS if you want audio descriptions as well

That's it — chores with photo requirements will now use AI review, and new chores will get audio descriptions generated automatically.

Architecture

The AI stack consists of two optional sidecar containers, activated via Docker Compose profiles:

  • LiteRT (gemma4:e2b) — Google's optimized on-device runtime for Gemma 4. Handles both vision tasks (photo review) and text generation (TTS descriptions) from a single model. 15x faster and 3x less RAM than Ollama. The model auto-downloads on first start.
  • Kokoro-FastAPI (kokoro-82m) — Audio synthesis engine with an OpenAI-compatible API. Converts text descriptions into natural-sounding speech.

An Ollama alternative is also available (--profile ollama) for users who prefer it, though it requires significantly more RAM and is slower on CPU.

Both containers are fully optional. The main OpenChore app works fine without them — you just won't get AI photo review or pre-generated audio.

Configuration

All AI settings are managed from the Admin panel under Settings.

Setting Default Description
AI Enabled false Master switch for all AI features
Endpoint http://litert:8080 Vision/text model server URL
Model gemma4:e2b Vision and text model
Auto-approve Threshold 0.85 Confidence score cutoff for auto-approval
TTS Enabled false Enable audio description generation
TTS Endpoint http://kokoro:8880 Kokoro server URL
TTS Voice af_heart Kokoro voice name

Resource Requirements

Component RAM Speed
LiteRT (Gemma 4 E2B) ~2.3 GB ~5s per review
Kokoro TTS ~2 GB <1s per synthesis
Total AI stack ~4.3 GB

For users who prefer Ollama over LiteRT, expect ~7.3 GB RAM and ~75s per review on CPU.

If you're running OpenChore on a device with limited RAM, you can enable just one of the two AI features. Photo review is useful without TTS, and TTS can work with browser fallback if the AI sidecar is down.

Clone this wiki locally