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 Ollama 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 Ollama and Kokoro sidecar containers alongside the main app.

2. Pull the Vision Model

Once the containers are running, pull the Gemma 4 model:

docker exec openchore-ollama ollama pull gemma4:e2b

3. 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:

  • Ollama (gemma4:e2b) — Handles both vision tasks (photo review) and text generation (TTS descriptions). A single model serves both purposes.
  • Kokoro-FastAPI (kokoro-82m) — Audio synthesis engine with an OpenAI-compatible API. Converts text descriptions into natural-sounding speech.

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
Ollama Endpoint http://ollama:11434 Ollama 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

The AI containers add moderate memory overhead:

Component RAM
Gemma 4 E2B (Q4) ~7.3 GB
Kokoro TTS ~2 GB
Total AI stack ~10 GB additional

Recommended VM sizing is 12-14 GB total RAM to accommodate the OS and OpenChore alongside the AI stack. For constrained environments, llama.cpp server with reduced context window (~ctx 2048) can cut Ollama overhead roughly in half. See project README for details.

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

Clone this wiki locally