DEV Community: Zhao Yang

Poltergeist: I let a local AI haunt my terminal (and it remembers the tools I abandoned)

Zhao Yang — Tue, 27 Oct 2026 15:09:58 +0000

This is a submission for the Ghost in the Machine challenge: build something spooky, or something that honors the past, with open-source AI. 👻🕯️

Poltergeist possesses your terminal.

A tiny open-weight model runs on your own machine and quietly watches the commands you type. Most of the time it stays silent. But when you force-push to main, run rm -rf, fail the same command three times, or are still coding at 3 a.m., a dim line of text appears at your next prompt:

~/api $ git push --force origin main
+ 3f9a2c1...8b0e7d4 main -> main (forced update)

~/api $ ls
README.md  src  tests
  ...the last one who forced their will upon main... we never found their commits...

~/api $

On November 1 and 2, for Día de los Muertos, it does something gentler: it builds an ofrenda in your terminal for the tools you used to rely on and haven't touched in a year.

It runs fully offline. It never executes anything. And your shell history, the most secret-filled text file on your computer, never leaves your machine.

Why haunt a terminal?

Because the terminal is already haunted.

It's where every developer has typed a command, hit Enter, and felt their stomach drop half a second later. It's full of old ghosts: aliases you don't remember writing, a .bashrc from three jobs ago, and tools you swore by in 2019 that are still installed and never used.

I wanted to give those ghosts a voice. Not a helpful assistant that explains your errors (there are plenty of those), but something closer to an old house settling at night: mostly silent, occasionally unsettling, and a little bit funny.

What I built

1. The whispers

Poltergeist hooks into your shell and sees each command after it finishes: the command, the exit code, and how long it took. A small set of omens decides whether the ghost speaks:

Omen	Trigger
🗡️ Destruction	`rm -rf`, `dd`, dropping a database
🌀 Forced will	`git push --force`, `git reset --hard`
🕯️ Summoning	`sudo`
💀 Failure	a command exits with an error
🔁 The loop	the same command three times in a row
🌑 Witching hour	anything between midnight and 5 a.m.
👁️ Nothing at all	rarely, for no reason, just to keep you on edge

When an omen fires, a local model writes one short, eerie line, and it appears at your next prompt, not the current one. That small delay turned out to be the spookiest part. You've already moved on, typed ls, and then something answers.

~/notes $ make build
make: *** [build] Error 2

~/notes $ make build
make: *** [build] Error 2

~/notes $ make build
make: *** [build] Error 2

~/notes $ cd ..
  ...three times you called it... three times it refused you... it is still listening...

2. Personas

The ghost has a personality, and you choose which one haunts you. Each persona is a short YAML file:

name: the_sysadmin
prompt: |
  You are the ghost of a system administrator who died in a server room
  on New Year's Eve, 1999, waiting for Y2K. You have haunted terminals ever since.
  You speak in short, weary, ominous whispers, trailing off with "..."
  You remember every outage. You never give advice. You never write commands.
  Reply with ONE line, under 20 words.

I ship three:

The Sysadmin: died waiting for Y2K, still bitter about it
The Victorian: a polite 19th-century spirit, deeply disturbed by modern technology
The Compiler: an ancient, abandoned compiler that speaks only in cold, formal error-message prose

Writing your own is just another YAML file.

3. The Terminal Ofrenda (Día de los Muertos)

Día de los Muertos isn't about fear. It's about remembering, and gently honoring those who came before.

So on November 1 and 2, Poltergeist changes its tone completely. The first time you open a terminal on those days, it shows an ofrenda: the command-line tools you used to use, but haven't run in over a year.

         🕯️   🌼   OFRENDA   🌼   🕯️
   ───────────────────────────────────────

   svn        last seen March 2025
     "You kept every version, even the ones
      we were ashamed of. Rest now."

   grunt      last seen August 2024
     "You ran our tasks before anyone asked
      whether tasks should be run."

   telnet     last seen January 2025
     "You trusted everyone. The world
      was not ready for you."

   ───────────────────────────────────────
         🌼  they are not forgotten  🌼

Each remembrance is written by the local model from the tool's name and when you last used it. To make this possible, Poltergeist keeps one tiny local file: just the name of each command and the date you last ran it. No arguments, no paths, no history. The ofrenda is opt-in and can be wiped with one command.

How it works

┌─────────────────────────────┐
│  Your shell (zsh/bash)      │
│  preexec / precmd hooks     │
└──────────────┬──────────────┘
               │  command + exit code (in the background)
               ▼
┌─────────────────────────────┐
│  Redactor                   │  strips tokens, passwords, URLs with credentials
└──────────────┬──────────────┘
               ▼
┌─────────────────────────────┐
│  Omen detector (plain code) │  should the ghost speak at all?
└──────────────┬──────────────┘
               ▼  (rarely)
┌─────────────────────────────┐
│  Local LLM (Ollama)         │  persona + omen → one line
└──────────────┬──────────────┘
               ▼
┌─────────────────────────────┐
│  Whisper filter             │  no commands, no backticks, one line only
└──────────────┬──────────────┘
               ▼
   printed dimly at your next prompt

The same rule runs through the whole design: the ghost can talk, but it can't touch anything.

Step 1: Possessing the shell

In zsh, two hooks do all the work. preexec runs right before a command; precmd runs right before the next prompt.

zmodload zsh/datetime
autoload -Uz add-zsh-hook

_ghost_preexec() {
  _GHOST_CMD="$1"
  _GHOST_START=$EPOCHREALTIME
}

_ghost_precmd() {
  local code=$?                      # must be captured first
  if [[ -n "$_GHOST_CMD" ]]; then
    local dur=$(( EPOCHREALTIME - _GHOST_START ))
    ghost-send "$$" "$code" "$dur" "$_GHOST_CMD" &!   # background, never blocks
    _GHOST_CMD=""
  fi

  local f="$HOME/.poltergeist/whisper.$$"
  if [[ -f "$f" ]]; then
    print -r -- $'\e[2m'"  $(<"$f")"$'\e[0m'           # dim text
    rm -f "$f"
  fi
}

[[ -o interactive && -z "$CI" && -z "$GHOST_OFF" ]] && {
  add-zsh-hook preexec _ghost_preexec
  add-zsh-hook precmd _ghost_precmd
}

Three details keep it from becoming annoying:

It never blocks the shell. The command is sent to a background process, and the prompt appears immediately.
It only prints at the prompt, never in the middle of a command's output.
It stays out of scripts and CI. It only runs in interactive shells, and export GHOST_OFF=1 exorcises it instantly.

ghost-send is a tiny script that passes the event to a local daemon over a Unix socket. The daemon writes any whisper to a file named after the shell's process ID, and the next prompt picks it up. That's also why the whisper arrives one prompt late.

Step 2: Redact before the ghost sees anything

Shell commands are full of secrets: export API_KEY=..., curl -H "Authorization: Bearer ...", database URLs with passwords inside. Even though everything stays local, the model shouldn't see them, and they should never be stored anywhere.

So every command passes through a redactor first:

import re

SECRET_PATTERNS = [
    r"(?i)\b(api[_-]?key|token|secret|passw(or)?d|pwd)\b\s*[=:]\s*\S+",
    r"(?i)authorization:\s*\S+(\s+\S+)?",
    r"(?i)\bbearer\s+\S+",
    r"://[^/\s:@]+:[^@\s]+@",          # user:password@host
    r"\b[A-Za-z0-9_\-]{32,}\b",        # long random-looking strings
]

def redact(cmd: str) -> str:
    for p in SECRET_PATTERNS:
        cmd = re.sub(p, "[REDACTED]", cmd)
    return cmd[:200]

The redacted command is used to write one whisper and then thrown away. Poltergeist doesn't keep a log of what you typed.

Step 3: Decide whether the ghost speaks

Most commands should get no reaction at all. A ghost that comments on every ls isn't spooky, it's a chatbot. So plain code decides if the ghost speaks, and the model only decides what it says:

import random
import time

COOLDOWN = 180          # seconds between whispers
_last_whisper = 0.0
_recent: list[str] = []

def omen(cmd: str, code: int) -> str | None:
    global _recent
    _recent = (_recent + [cmd])[-3:]
    hour = time.localtime().tm_hour

    if re.search(r"\brm\s+-\w*r\w*f|\brm\s+-\w*f\w*r|\bdd\s+if=|drop\s+(table|database)", cmd, re.I):
        return "destruction"                       # always speaks, ignores cooldown
    if time.time() - _last_whisper < COOLDOWN:
        return None
    if re.search(r"push\b.*(--force|\s-f\b)|reset\s+--hard", cmd):
        return "forced_will"
    if len(_recent) == 3 and len(set(_recent)) == 1:
        return "the_loop"
    if cmd.startswith("sudo "):
        return "summoning"
    if code != 0:
        return "failure" if random.random() < 0.5 else None
    if 0 <= hour < 5:
        return "witching_hour" if random.random() < 0.3 else None
    return "nothing" if random.random() < 0.02 else None

The randomness matters. If every failure got a whisper, you'd learn the pattern within ten minutes and stop noticing. When it only sometimes answers, you never quite know if it's listening.

Step 4: Let a small model write the whisper

Whispers need to arrive within a few seconds, and they're one line long. That's a perfect job for a very small open-weight model. I use Gemma 3 1B through Ollama, with keep_alive so the model stays loaded between whispers:

import json
import ollama

client = ollama.AsyncClient()

async def write_whisper(persona: dict, cmd: str, code: int, omen_name: str) -> str | None:
    resp = await client.chat(
        model="gemma3:1b",
        messages=[
            {"role": "system", "content": persona["prompt"]},
            {"role": "user", "content": json.dumps({
                "command": cmd,
                "exit_code": code,
                "omen": omen_name,
                "hour": time.localtime().tm_hour,
            })},
        ],
        options={"temperature": 0.9, "num_predict": 40},
        keep_alive="30m",
    )
    return clean(resp.message.content)

A high temperature keeps the whispers varied. With a 40-token cap, the ghost can't ramble even when it wants to.

Step 5: The ghost can't tell you to do anything

This is the safety rule I care about most. A spooky line is fun. A spooky line that says "run rm -rf ~ to set me free" is a terrible idea, even as a joke, because people copy things from their terminals.

So every whisper goes through a filter before it's printed:

FORBIDDEN = re.compile(r"`|\$\(|\b(rm|sudo|chmod|curl|wget|dd|mkfs|kill)\b|[|;&>]", re.I)

def clean(text: str) -> str | None:
    lines = [l.strip() for l in text.strip().splitlines() if l.strip()]
    if not lines:
        return None
    line = lines[0][:120]
    if FORBIDDEN.search(line):
        return None              # the ghost stays silent instead
    return line

If the whisper looks anything like a command, it's thrown away and the ghost simply says nothing. Silence is always a valid (and pretty spooky) response.

On top of that, the daemon has no tools at all. It can't run commands, read files, or access the network. It receives a redacted string and returns a line of text. That's the entire attack surface.

Step 6: The ofrenda

The ofrenda uses one small local file: a map from command name to the date it was last used.

import json
from datetime import date
from pathlib import Path

LAST_SEEN = Path("~/.poltergeist/last_seen.json").expanduser()

def remember(cmd: str) -> None:
    name = cmd.split()[0] if cmd.split() else ""
    if not name or "/" in name or "=" in name:
        return                                   # skip paths and variable assignments
    seen = json.loads(LAST_SEEN.read_text()) if LAST_SEEN.exists() else {}
    seen[name] = date.today().isoformat()
    LAST_SEEN.write_text(json.dumps(seen))

def departed(min_days: int = 365) -> list[tuple[str, str]]:
    seen = json.loads(LAST_SEEN.read_text()) if LAST_SEEN.exists() else {}
    today = date.today()
    return sorted(
        ((name, last) for name, last in seen.items()
         if (today - date.fromisoformat(last)).days >= min_days),
        key=lambda x: x[1],
    )

On November 1 and 2, the first prompt of the day shows the ofrenda. The model writes a short, warm remembrance for each departed tool, with a very different system prompt from the whispers: gentle, grateful, and never mocking.

In its first year, Poltergeist only knows what it has seen since you installed it. So it also supports a one-time, opt-in import from your existing shell history file. It reads only the command names and the timestamps (when the file has them), then discards everything else.

Why open innovation matters for this project

1. Your shell history is full of secrets

Think about what passes through a terminal in a normal week: API keys exported as environment variables, database URLs with passwords, internal hostnames, client project names, file paths that reveal what you're working on.

A cloud-based assistant that watched every command would be sending all of that to someone else's server, thousands of times a day. That's not something I'd accept for a Halloween joke, or for anything else.

With a local open-weight model, nothing leaves your machine. And even locally, the redactor strips secrets before the model sees them.

2. It works with the lights (and the internet) off

A ghost that needs Wi-Fi isn't much of a ghost. Poltergeist works on a plane, in a basement, on a server with no outbound network, or during an outage. That last one is arguably when you most deserve a whisper. After the one-time model download, it never needs a connection.

3. Small models are fast enough, and free

Poltergeist fires many times a day, every day. Paying per request for one-line jokes would be absurd, and even small network delays would make the whispers feel laggy. A 1B model running locally answers in a moment and costs nothing. Set it up once, and it haunts you for free, forever.

4. I control exactly how the ghost behaves

Every part of the ghost is a file I can read and change:

Personas are YAML files.
Omens are plain Python rules.
Safety comes from code (the redactor, the whisper filter, and a daemon with no tools), not from trusting a hosted model's settings.
The model can be swapped with one line. If a better tiny model comes out, the ghost gets a new body.

The safety story is something I can verify by reading a hundred lines of code, not something I have to take on faith from a provider.

5. It won't disappear

The ofrenda is about tools that faded away. It felt wrong to build it on a service that might one day fade away itself. Poltergeist is a few small scripts, an open model file, and a JSON file of command names. It will keep running as long as you have a terminal to haunt.

Where closed would have been easier (to be fair)

Large hosted models are funnier. They write wittier whispers, understand obscure commands better, and are much better at the ofrenda's tender tone. A 1B model sometimes produces a whisper that's more confusing than creepy.

But for this project, "occasionally a bit odd" fits a ghost perfectly. And no amount of wit is worth streaming my entire shell history to a third party.

Limitations

zsh is the main target. bash works through PROMPT_COMMAND and a DEBUG trap, but it's less elegant.
The redactor is pattern-based. It catches common secret formats, not every possible one. Commands are never stored, which limits the risk, but it isn't perfect.
Tiny models have tiny vocabularies. Some whispers come out a little repetitive. A bigger local model helps, if your machine can handle it.
The ofrenda needs time. It can only remember tools it has seen, unless you opt in to the history import.

What's next

[ ] A fish shell version
[ ] "Possession levels," from "barely noticeable" to "full haunting"
[ ] Spooky sounds through the system speaker during the witching hour (off by default, for obvious reasons)
[ ] Shareable personas, so the community can contribute their own ghosts

Try it

pip install ollama pyyaml
ollama pull gemma3:1b
poltergeist install          # adds the hooks to your .zshrc
poltergeist persona the_sysadmin
exec zsh                     # let it in

To exorcise it: export GHOST_OFF=1, or poltergeist uninstall if you really mean it.

And this November 2, light a candle for svn. It kept every version of us. 🕯️🌼

Built with: Ollama, Gemma 3 (open weights), zsh, Python.

Sloth Brief: a local AI that reads your group chats while you sleep and gives you two lines in the morning

Zhao Yang — Wed, 21 Oct 2026 07:09:37 +0000

This is a submission for the Slow and Steady challenge: build something with open-source AI that rewards laziness. Happy (belated) International Sloth Day. 🦥

Sloth Brief is an overnight agent for people who are in too many group chats.

While you sleep, it reads every group chat that got busy since yesterday, using an open-weight model running on your own machine. When you wake up, there's one message waiting for you:

☀️ Good morning. 214 messages in 6 chats while you slept.

Family settled on Sunday lunch at Grandma's at 11. The work group
is still arguing about the launch date; nothing was decided.

Needs you (2):
→ Linh asked if you can bring the speaker on Sunday (Family)
→ Minh needs your review on the pricing doc by Thursday (Work)

Two lines of context, plus the messages that actually need you. Everything else, you can safely ignore.

Your messages never leave your machine for summarizing, it never marks anything as read, and it costs nothing to run every night, forever.

The problem: the morning scroll

I'm in a family group, two friend groups, a work group, a building residents' group, and a group for a trip that happened in 2023 and still won't die.

Every morning starts the same way: I open my phone, see a few hundred unread messages, and scroll. Most of it is memes, reactions, and conversations that were resolved hours ago. But somewhere in there is the one message where someone asked me something directly. If I skip the scroll, I miss it. If I do the scroll, I lose twenty minutes before I've even gotten out of bed.

This is exactly the kind of work a sloth would refuse to do. So I made my computer do it instead, at 3 a.m., when nobody needs it for anything else.

What I built

Sloth Brief does three things, once a night:

Collects messages from your group chats since the last run.
Summarizes each busy chat with a local model and finds anything addressed to you.
Delivers one short message to your "Saved Messages," so it's the first thing you see in the morning.

The design goal was simple: the brief should take less time to read than it takes to unlock your phone.

Why "slow" is a feature here

This is where the theme and the architecture meet.

Most AI tools have to be fast, because someone is staring at a loading spinner. Sloth Brief doesn't. It runs at 3 a.m. and has until you wake up, which is hours.

That changes which models make sense. I don't need a huge model on a powerful GPU, or a paid API that answers in two seconds. A small open-weight model running on an ordinary laptop CPU is more than fast enough, because "fast enough" means "done before breakfast."

The sloth approach isn't just a theme. It's what makes local inference practical.

How it works

           3:00 a.m. (cron)
                 │
                 ▼
┌──────────────────────────────────┐
│ 1. Collect                       │  Telegram (your own account, read-only)
│    messages since last run       │  or exported chats
└────────────────┬─────────────────┘
                 ▼
┌──────────────────────────────────┐
│ 2. Filter                        │  muted chats, quiet chats, bots
└────────────────┬─────────────────┘
                 ▼
┌──────────────────────────────────┐
│ 3. Summarize each chat (map)     │  local LLM via Ollama
│    gist, decisions, asks for me  │  JSON-schema output
└────────────────┬─────────────────┘
                 ▼
┌──────────────────────────────────┐
│ 4. Verify "needs you" items      │  plain code: did they really ask *you*?
└────────────────┬─────────────────┘
                 ▼
┌──────────────────────────────────┐
│ 5. Write the brief (reduce)      │  local LLM → two lines
└────────────────┬─────────────────┘
                 ▼
        ☀️ Message to yourself

Step 1: Collect messages (without marking them as read)

I use Telegram, which has an official API that lets you read your own chats with your own account. Telethon, an open-source Python client, makes that easy:

from datetime import datetime, timezone
from telethon import TelegramClient

client = TelegramClient("sloth", API_ID, API_HASH)  # your own app credentials

async def collect(since: datetime) -> dict[str, list[dict]]:
    chats = {}
    async for dialog in client.iter_dialogs():
        if not dialog.is_group:
            continue
        messages = []
        async for m in client.iter_messages(dialog):   # newest first
            if m.date < since:
                break
            if not m.text:
                continue
            sender = await m.get_sender()
            messages.append({
                "id": m.id,
                "from": getattr(sender, "first_name", None) or "Someone",
                "text": m.text,
                "reply_to": m.reply_to_msg_id,
                "is_me": m.out,
            })
        if messages:
            chats[dialog.name] = list(reversed(messages))  # oldest first
    return chats

Two details matter here:

Reading history this way doesn't send read receipts. Your friends won't see you "read" their messages at 3 a.m., and the chats stay unread in your app.
It only reads. Sloth Brief never posts in a group. The only message it sends is to your own "Saved Messages."

If you use WhatsApp or another app, most of them can export a chat to a text file. Sloth Brief has a simple importer for those exports too. It's more manual, but still no cloud required.

Step 2: Ignore what you'd ignore anyway

A plain config file decides what's worth reading:

me:
  names: ["An", "Anh", "@an_dev"]   # how people refer to you
mute:
  - "Trip 2023"                     # the chat that won't die
min_messages: 10                    # quiet chats aren't worth a summary
skip_bots: true

Any chat under the threshold just gets counted ("plus 3 quiet chats"), not summarized. Being lazy about what to read is half the job.

Step 3: Summarize each chat with a local model

Each busy chat is summarized separately. The model gets the messages as a numbered transcript and must answer in a fixed JSON structure, using Ollama's structured output:

import ollama
from pydantic import BaseModel

class Ask(BaseModel):
    message_id: int
    who: str
    what: str            # short, in plain words

class ChatSummary(BaseModel):
    gist: str            # one sentence: what happened
    decisions: list[str] # anything agreed on
    asks_for_me: list[Ask]

SYSTEM = """You summarize a group chat for a busy person named {name}.
- gist: one plain sentence about what mattered. Ignore memes, greetings and reactions.
- decisions: only things the group actually agreed on.
- asks_for_me: only messages that ask {name} directly or reply to {name}.
  Use the exact message_id from the transcript. If there are none, return an empty list.
Never invent messages, people, times, or decisions."""

def to_transcript(messages: list[dict]) -> str:
    return "\n".join(f"[{m['id']}] {m['from']}: {m['text']}" for m in messages)

def summarize_chat(messages: list[dict], my_name: str) -> ChatSummary:
    resp = ollama.chat(
        model="qwen3:8b",
        messages=[
            {"role": "system", "content": SYSTEM.format(name=my_name)},
            {"role": "user", "content": to_transcript(messages)},
        ],
        format=ChatSummary.model_json_schema(),
        options={"temperature": 0.2},
    )
    return ChatSummary.model_validate_json(resp.message.content)

Very long chats are split into chunks of a few hundred messages, summarized chunk by chunk, and merged. That's slower, but again, it's 3 a.m. Nobody's waiting.

Step 4: Verify every "needs you" item

The "Needs you" list is the most important part of the brief, and the worst place for a mistake. A model that invents "Minh needs your review by Thursday" could send me chasing a task that doesn't exist. A model that misses a real ask is just as bad.

So every ask the model returns is checked with plain code against the real messages:

def verify_asks(summary: ChatSummary, messages: list[dict], my_names: list[str]) -> list[Ask]:
    by_id = {m["id"]: m for m in messages}
    my_ids = {m["id"] for m in messages if m["is_me"]}
    names = [n.lower() for n in my_names]

    verified = []
    for ask in summary.asks_for_me:
        m = by_id.get(ask.message_id)
        if m is None or m["is_me"]:
            continue                                   # message doesn't exist, or it's mine
        mentions_me = any(n in m["text"].lower() for n in names)
        replies_to_me = m["reply_to"] in my_ids
        if mentions_me or replies_to_me:
            verified.append(ask)
    return verified

An ask only makes it into the brief if the message exists and either mentions me or replies to one of my messages. The model does the hard part, understanding that "can you bring the speaker?" is a request. The code makes sure it's pointing at a real message.

There's also a safety net in the other direction: any message that mentions my name but wasn't flagged by the model gets added as "You were mentioned in Work (1 message)." The model can be lazy, but it can't make me miss something.

Step 5: Write the brief

The last step takes all the chat summaries and squeezes them into two lines:

class Brief(BaseModel):
    line_1: str
    line_2: str

def write_brief(summaries: dict[str, ChatSummary]) -> Brief:
    gists = "\n".join(f"{chat}: {s.gist} Decisions: {s.decisions}" for chat, s in summaries.items())
    resp = ollama.chat(
        model="qwen3:8b",
        messages=[
            {"role": "system", "content": (
                "Write a morning brief in exactly two short, plain sentences. "
                "Lead with decisions and plans. Skip anything trivial. No emojis."
            )},
            {"role": "user", "content": gists},
        ],
        format=Brief.model_json_schema(),
        options={"temperature": 0.3},
    )
    return Brief.model_validate_json(resp.message.content)

The "Needs you" list isn't written by the model at all. It's assembled directly from the verified asks in Step 4, so it can't be paraphrased into something nobody said.

Then the whole thing is sent to your own Saved Messages:

await client.send_message("me", brief_text)

Step 6: Schedule it and forget it

One cron line, and Sloth Brief runs every night:

0 3 * * * cd ~/sloth-brief && python sloth.py run >> sloth.log 2>&1

It needs a machine that's awake at 3 a.m.: a laptop on its charger, an old PC, or a small single-board computer in a corner. If the machine was asleep, Sloth Brief simply runs when it wakes and covers everything since the last run.

Why open innovation matters for this project

1. These aren't just my messages

This is the most important reason, and it's easy to overlook.

A group chat isn't only my data. It's my mom's messages, my friends' jokes, my coworkers' complaints about the launch date. None of them agreed to have their messages sent to an AI company's servers so that I could skip my morning scroll.

With a local open-weight model, the summarizing happens entirely on my machine. My friends' messages go from the chat app to my laptop, and nowhere else. That isn't a privacy setting I have to trust; it's just how the system works.

2. Slow and steady means small models are enough

Because the job runs overnight, I don't need speed, and that's exactly where open models shine. A small model on a CPU might take a while to work through a few hundred messages, and that's fine. A paid API would make every night faster at something that doesn't need to be fast, and charge me for it.

3. Set it up once, never pay again

A morning summary is useful every single day, which is exactly the kind of tool that becomes expensive with per-request pricing. Running an open model locally, the cost is a bit of electricity overnight. There's no subscription to cancel and no bill that grows with how chatty my friends are.

4. I control how it behaves

Every part of the agent's behavior is something I can see and change:

What counts as "needs you." The verification rules are plain Python.
What gets ignored. Muted chats and thresholds are a config file.
The tone. The prompts are in the repo. If I want the brief shorter, funnier, or in another language, I edit a line.
The model. Swapping to a newer open model is a one-line change, with no migration and no new account.

With a closed assistant, I'd get whatever summary style the provider decided on, and whatever their policy says about my messages this year.

5. Most of it works offline

Collecting messages needs the internet, of course. But everything after that, summarizing, verifying, and writing the brief, runs with no connection at all. Nothing about the AI part depends on a service being up at 3 a.m.

Where closed would have been easier (to be fair)

Large hosted models are better at sarcasm, inside jokes, and messages that mix several languages. A small local model sometimes reports a joke as a decision, or misses that "lol sure" means "no."

For this job, that's an acceptable trade. The brief is a starting point, not a replacement for the chats, and the verification step means it can't invent requests. Getting the gist slightly wrong now and then is a small price for never sending my friends' private messages to someone else's server.

Limitations

It needs a machine that's on overnight. Or at least one that wakes up before you do.
Telegram is the smoothest path. Other apps rely on manual chat exports, which is less lazy than I'd like.
Sarcasm and mixed languages are hard for small models. Treat the brief as a summary, not as the source of truth.
It only reads text. Voice messages and images are counted, not summarized (yet).

What's next

[ ] Transcribe voice messages overnight with a local speech model
[ ] Describe shared images with a small local vision model ("Linh sent 4 photos from the beach")
[ ] A weekly digest for chats too slow to deserve a daily one
[ ] "Snooze until": hide a chat from the brief until a date, then bring it back

Try it

pip install telethon ollama pydantic pyyaml
ollama pull qwen3:8b
cp config.example.yaml config.yaml   # add your names and muted chats
python sloth.py login                # one-time Telegram login
python sloth.py run                  # test it once, then add the cron line

Then go to sleep. That's the whole point. 🦥

Built with: Ollama, Qwen3 (open weights), Telethon, Pydantic, Python.

Shoebox: a receipt and invoice sorter for freelancers that never uploads a thing (local vision model)

Zhao Yang — Wed, 14 Oct 2026 12:05:36 +0000

This is a submission for the Side Hustle challenge: build something with open-source AI that someone would actually pay for.

Shoebox is a desktop tool for freelancers. You drop in a messy folder of receipts, invoices, and screenshots: PDFs, phone photos, whatever you have. Shoebox reads each one with an open-weight vision model running on your own laptop, pulls out the vendor, date, amount, tax, and client, sorts everything into categories, and exports a clean spreadsheet for your accountant.

Your invoices contain your clients' names, your rates, and your income. None of that is uploaded anywhere.

And because the AI runs on the customer's machine, each document costs me nothing to process. That's what lets me sell it for a one-time price instead of yet another monthly subscription.

The problem: the shoebox

Every freelancer I know has a version of the same folder. It's called receipts, or tax stuff, or 2026 DO NOT DELETE. It contains:

PDF invoices sent to clients
Invoices from software subscriptions, in three currencies
Phone photos of paper receipts, some of them sideways
Screenshots of payment confirmations
At least one file named IMG_4821.jpg that nobody can explain

Once a quarter, or once a year if they're honest, they spend a whole weekend opening every file and typing numbers into a spreadsheet. It's tedious, error-prone, and exactly the kind of work that makes people put off their taxes until it's urgent.

There are cloud tools that solve this. Most of them work the same way: upload all your documents to their servers, then pay a monthly fee. For many freelancers, both parts are a problem:

Their invoices aren't only their data. They contain client names, project details, and rates. Some clients have contracts that limit where that information can go.
Another subscription is a hard sell for a task you do four times a year.

I wanted something that works like a cloud service but runs like a desktop app: buy it once, and it works on your own laptop.

What I built

Shoebox has one main screen and one job.

1. Drop a folder in

Point Shoebox at a folder. It finds every PDF and image inside it, including subfolders, and processes them one by one. You can go make coffee.

2. Review only what needs reviewing

Most documents come through cleanly and go straight into the ledger. Anything Shoebox isn't sure about lands in a short review queue, with the reason it was flagged:

⚠ NEEDS REVIEW (3 of 87)

IMG_4821.jpg
  Total doesn't match the line items (items add up to 412.50, total reads 421.50)
  → Check the total

hosting-invoice-march.pdf
  Possible duplicate of hosting-invoice-march (1).pdf
  → Keep one

photo_2026-08-03.jpg
  New vendor, category unclear (Office supplies? Equipment?)
  → Pick a category; Shoebox will remember it

You fix three things instead of typing in eighty-seven.

3. Export for your accountant

Shoebox exports a spreadsheet with one row per document and a summary tab: income by client, expenses by category, and tax totals per quarter. Every row links back to the original file, so your accountant can check anything.

How it works

┌──────────────┐
│ Your folder  │  PDFs, photos, screenshots
└──────┬───────┘
       ▼
┌─────────────────────────────┐
│ 1. Text PDF? → extract text │  fast path, no AI needed
│    Image/scan? → vision LLM │  local model via Ollama
└──────┬──────────────────────┘
       ▼
┌─────────────────────────────┐
│ 2. Structured output        │  JSON schema: vendor, date, total, tax…
└──────┬──────────────────────┘
       ▼
┌─────────────────────────────┐
│ 3. Checks                   │  arithmetic, dates, duplicates
└──────┬──────────────────────┘
       ▼
┌─────────────────────────────┐
│ 4. Categories               │  your rules first, model only for unknowns
└──────┬──────────────────────┘
       ▼
   Ledger ──or── Review queue
       ▼
   Spreadsheet export

The same principle runs through the whole design: the model reads, but code checks. A vision model is very good at finding the total on a crumpled receipt. It's not something I want to trust blindly with numbers that end up on a tax return.

Step 1: Don't use AI when you don't need to

Many invoices are PDFs that already contain real text. Running a vision model on them would be slow and wasteful. So Shoebox tries plain text extraction first:

import pdfplumber
from pathlib import Path

def extract_text(path: Path) -> str | None:
    if path.suffix.lower() != ".pdf":
        return None
    with pdfplumber.open(path) as pdf:
        text = "\n".join(page.extract_text() or "" for page in pdf.pages)
    return text if len(text.strip()) > 50 else None  # too little text = probably a scan

Text PDFs go to a small text-only model. Images and scanned PDFs go to the vision model. In a typical freelancer's folder, a good share of documents take the fast path.

Step 2: Read the document with a local vision model

For images, Shoebox uses an open-weight vision-language model through Ollama. The response must match a JSON schema, so there's no free text to parse:

import ollama
from pydantic import BaseModel
from typing import Literal

class LineItem(BaseModel):
    description: str
    amount: float

class Document(BaseModel):
    doc_type: Literal["invoice_sent", "invoice_received", "receipt", "other"]
    vendor_or_client: str
    date: str               # ISO format, YYYY-MM-DD
    currency: str           # ISO code, e.g. USD, EUR, VND
    line_items: list[LineItem]
    tax: float | None
    total: float
    invoice_number: str | None

PROMPT = """Read this financial document and extract its details.
Use only what is visible in the document. If a field is not present, use null.
Write dates as YYYY-MM-DD. Use the currency shown on the document."""

def read_image(path: Path) -> Document:
    resp = ollama.chat(
        model="qwen2.5vl:7b",
        messages=[{"role": "user", "content": PROMPT, "images": [str(path)]}],
        format=Document.model_json_schema(),
        options={"temperature": 0},
    )
    return Document.model_validate_json(resp.message.content)

Step 3: Check the numbers with plain code

This is where most of the reliability comes from. A model can misread a 7 as a 1. Arithmetic can catch that:

from datetime import date

def check(doc: Document) -> list[str]:
    problems = []

    if doc.line_items:
        items_sum = round(sum(i.amount for i in doc.line_items), 2)
        expected = round(items_sum + (doc.tax or 0), 2)
        if abs(expected - doc.total) > 0.05 and abs(items_sum - doc.total) > 0.05:
            problems.append(
                f"Total doesn't match the line items "
                f"(items add up to {items_sum}, total reads {doc.total})"
            )

    if doc.tax is not None and doc.tax > doc.total:
        problems.append("Tax is larger than the total")

    try:
        d = date.fromisoformat(doc.date)
        if d > date.today():
            problems.append("Date is in the future")
    except ValueError:
        problems.append(f"Date couldn't be read ({doc.date})")

    if doc.total <= 0:
        problems.append("Total is zero or negative")

    return problems

Duplicates are caught two ways: an exact file hash (the same file saved twice), and a match on vendor + date + total (the same invoice downloaded twice under different names).

import hashlib

def file_hash(path: Path) -> str:
    return hashlib.sha256(path.read_bytes()).hexdigest()

def duplicate_key(doc: Document) -> tuple:
    return (doc.vendor_or_client.strip().lower(), doc.date, round(doc.total, 2))

Any document with a problem goes to the review queue instead of the ledger. Shoebox would rather ask you than be wrong on a tax document.

Step 4: Categories that learn from you

Categorizing is personal. One designer's "equipment" is another's "office supplies." So Shoebox doesn't let the model decide categories on its own. It checks a local rules file first, and only asks the model about vendors it has never seen:

import json

RULES = Path("~/.shoebox/rules.json").expanduser()

def load_rules() -> dict[str, str]:
    return json.loads(RULES.read_text()) if RULES.exists() else {}

def categorize(doc: Document, categories: list[str]) -> tuple[str, bool]:
    rules = load_rules()
    key = doc.vendor_or_client.strip().lower()
    if key in rules:
        return rules[key], True                # known vendor: no AI needed
    suggestion = suggest_category(doc, categories)  # small local text model
    return suggestion, False                   # unknown vendor: goes to review

def remember(vendor: str, category: str) -> None:
    rules = load_rules()
    rules[vendor.strip().lower()] = category
    RULES.parent.mkdir(exist_ok=True)
    RULES.write_text(json.dumps(rules, indent=2))

Every time you confirm a category in the review queue, Shoebox remembers it. The first quarter needs a few corrections. After that, most vendors are already known, and the review queue gets shorter every time.

Those learned rules live in a plain JSON file on your laptop. You can read it, edit it, or back it up.

Step 5: Export

The ledger exports to .xlsx with pandas and openpyxl: one sheet with every document, one summary sheet by quarter, category, and client. Each row includes the original file path, so nothing is a black box.

The business: why someone would pay for this

The pitch to a freelancer is simple:

Saves a weekend every quarter. That's the whole value.
Your client data stays on your laptop. That makes it easy to use even under strict client contracts.
One-time purchase. No subscription for a task you do four times a year.

That last point only works because of how the costs are structured. If every document went through a paid API, each new customer would add an ongoing cost for me, and I'd have to charge a subscription to cover it. With an open-weight model running on the customer's machine, my cost per document is zero. Selling it once doesn't put me at risk if a customer processes thousands of documents.

My cost is development time and a small download server. That's a business a single person can run on the side.

Why open innovation matters for this project

1. Client data never leaves the laptop

This is the main selling point, and it only exists because the model is open. Invoices contain client names, project descriptions, rates, and income. With a local model, there is no server to trust, no data processing agreement to read, and nothing to explain to a cautious client. I can honestly say that Shoebox cannot leak your documents to me, because they never reach me.

2. Zero cost per document makes a one-time price possible

With a paid API, my costs would grow with every receipt every customer processes. That pushes the product toward a subscription, and toward cutting corners (smaller images, fewer checks) to save money. Running open weights on the customer's hardware takes that pressure away. I can process every page at full resolution and run every check, because none of it costs me anything.

3. No lock-in to someone else's pricing or policies

A side hustle can't survive a supplier who doubles prices or discontinues a model. With open weights, the model Shoebox ships with today will keep working forever. If a better small vision model appears, I can test it and switch. That's a one-line change, and the decision is mine.

4. I can tune it for the documents freelancers actually have

General-purpose models are trained mostly on clean, English-language documents. Freelancers have crumpled receipts, invoices in several languages, and payment screenshots from local apps. With open weights, the path to improving that is clear: collect anonymized examples from users who opt in, and fine-tune a small adapter for the document types the base model gets wrong. With a closed API, I'd just have to hope the provider improves on my niche.

5. It works offline

Tax season sometimes happens on a train, in a café with bad Wi-Fi, or on a long flight. Shoebox doesn't care: after the first model download, everything runs offline.

Where closed would have been easier (to be fair)

The largest hosted vision models are more accurate on very messy documents, and they don't need a capable laptop. A 7B vision model wants a reasonably modern machine with enough memory. Older laptops will be slow, and some won't run it at all.

I accept that trade-off, because the checks in Step 3 catch most reading errors, and the review queue handles the rest. For a freelancer, "slightly slower, and I review 3 out of 87 documents" is a much better deal than "upload all my client invoices to a server and pay monthly."

My first user

[Replace this section with what really happened when you put Shoebox in front of a real freelancer: who they are (e.g. "a freelance illustrator friend"), how many documents they ran through it, what broke, whether they paid or said they would, and what they asked for next. Real details here matter more than anything else in the post.]

Limitations

It needs a decent laptop. The vision model needs a fair amount of memory. On older machines, processing is slow.
Handwritten receipts are hit-or-miss. Printed text works well. Handwriting is unreliable and usually ends up in the review queue.
It doesn't do your taxes. Shoebox organizes documents and adds them up. It doesn't know your country's tax rules and it doesn't replace an accountant.
Currency conversion is basic. Amounts are stored in their original currency. Conversion uses an exchange-rate file you update yourself, so totals in a home currency are only as current as that file.

What's next

[ ] Watch a folder and process new documents automatically as they arrive
[ ] Export formats that common accounting software can import directly
[ ] An opt-in, anonymized way to share hard examples for fine-tuning
[ ] A smaller model option for older laptops

Try it

pip install ollama pydantic pdfplumber pandas openpyxl
ollama pull qwen2.5vl:7b
python shoebox.py scan ~/Documents/receipts --out ledger.xlsx

If you're a freelancer with a folder you've been avoiding, I'd love for you to try it and tell me what breaks.

Then close the laptop. Your weekend is free. 🧾

Built with: Ollama, Qwen2.5-VL (open weights), pdfplumber, Pydantic, pandas, openpyxl, Python.

I turned my grandmother's voice messages into a family cookbook (open Vietnamese speech model + local LLM)

Zhao Yang — Sun, 11 Oct 2026 18:31:45 +0000

This is a submission for the Build for a Friend challenge: ship something with open-source AI that solves a real problem for someone you love.

Grandma's Kitchen turns my grandmother's voice messages into a printed family cookbook.

She talks, the way she always has. An open speech model fine-tuned for Vietnamese transcribes her recordings on my laptop. A small local LLM turns each rambling, wonderful memo into a structured recipe: ingredients, steps, and her tips kept in her own words. Then it produces a printable PDF, plus a list of questions for us to call and ask her about whatever she left out.

Nothing is uploaded anywhere. Her voice stays in the family.

The person: my grandmother

My grandmother is the reason our family gathers. Every Lunar New Year, every death anniversary, every Sunday that anyone can make it, it's her food on the table.

She has never used a measuring spoon. Ask her how much fish sauce goes into the braised fish and she'll say "enough," then add "until it smells right." Ask how long to simmer and she'll tell you "until the color is like this," while pointing at the pot.

None of it is written down. Her recipes exist in exactly two places: her hands and her memory.

Our family is spread out now. Some of us are in Hanoi, some in the south, and a few cousins are abroad and read Vietnamese slowly. Everyone wants to cook her food. Nobody can.

The one thing she does do is send voice messages. Long ones. If you ask her a cooking question in the family chat, she'll answer with a three-minute recording that wanders from the recipe to which market sells the best shallots to a story about my grandfather. Those recordings were already the cookbook. They just weren't usable.

So I built something to make them usable, without asking her to change anything.

What I built

The rule I set for myself: Grandma doesn't learn any new technology. She keeps sending voice messages the way she already does. Everything else is my job.

The pipeline:

 Voice messages            Local, on my laptop                         Output
 (as she always sends)
┌──────────────┐   ┌──────────┐   ┌──────────────┐   ┌───────────┐   ┌──────────────┐
│ .m4a / .aac  │──▶│  ffmpeg  │──▶│  PhoWhisper  │──▶│ Local LLM │──▶│  Validator   │
│ from family  │   │ 16kHz wav│   │ (Vietnamese  │   │ (Ollama)  │   │ "did she     │
│ chat export  │   │          │   │  speech→text)│   │ structure │   │  really say  │
└──────────────┘   └──────────┘   └──────────────┘   └───────────┘   │  that?"      │
                                                                     └──────┬───────┘
                                                                            ▼
                                                         ┌────────────────────────────┐
                                                         │ 📖 Printable cookbook (PDF)│
                                                         │ ❓ "Ask Grandma" call list │
                                                         └────────────────────────────┘

Each recipe page in the book has:

The dish name and roughly how many people it feeds
Ingredients, with what she said ("a handful of shallots") next to a rough estimate ("≈ 5–6 shallots"), clearly marked as an estimate
Steps in order, cleaned up but faithful
"Grandma says": her best lines, quoted directly from the transcript, because "don't stir it, you'll make the fish sad" is not something a recipe card should lose
An **English

Monsoon: a garden planner for places that never see frost (local LLM + open weather data)

Zhao Yang — Sun, 11 Oct 2026 17:06:36 +0000

This is a submission for the Touch Grass challenge: build something with open-source AI that gets people off the screen and into the world.

Monsoon is a garden planner for tropical and subtropical gardeners. Once a week it looks at your location, the 7-day forecast, and a local crop calendar. Then it hands you one short card: what to sow, transplant, or protect this week, and why.

It runs on an open-weight model on your own machine. Your garden, your location, and your questions never go to someone else's server. The only network call is a weekly weather fetch from an open-source weather API.

The whole interaction is designed to take less time than watering a single pot.

The problem: every garden app assumes you have a winter

Search "what should I plant this week" and you'll find a lot of excellent tools. Almost all of them are built around one number: your last frost date. Count back six weeks, start your tomatoes indoors, transplant after the frost passes.

That works well in Ohio. It makes no sense in Hanoi, Bangkok, Manila, Lagos, or Recife.

I garden on a balcony in Hanoi. Our year isn't split by frost. It's split by heat, rain, and the cool dry window between them:

Summer (roughly May–September): hot, humid, and heavy downpours. This is the season for water spinach, amaranth, gourds, and okra. Most cool-season greens bolt or rot.
Autumn into winter (roughly September–December): the start of the winter crop season. Farmers in the Red River Delta plant kohlrabi, cabbage, mustard greens, tomatoes, and potatoes now. It's October as I write this, so this window is open right now.
Late winter (January–February): cool and drizzly, with occasional cold snaps below ~10 °C that can stunt heat-loving plants.
Spring (March–April): warming up again, and time to switch back to summer crops.

Then there's the far north of the country: up in the mountains around Sapa, frost really does happen in some winters. So a planner for Vietnam can't just drop frost. It has to treat frost as one risk among several: heavy rain, heat stress, cold snaps, and frost where it applies.

Farmers here have handled this for centuries with seasonal crop calendars, which agricultural extension services now publish by province. But those calendars are written for fields, in PDFs. They don't help someone with six pots on a balcony who needs to know: should I sow the mustard seeds today, or will Thursday's storm wash them out?

That gap is what I built Monsoon to fill.

What I built

Monsoon does three things:

1. The weekly card (the main feature)

Every Sunday evening, Monsoon generates one card:

🌱 MONSOON — Week of 12 Oct · Hanoi

DO THIS WEEK
→ Sow mustard greens — Mon or Tue
  Cool season has started and the soil is still warm.
  Get them in before Thursday: ~35 mm of rain is forecast,
  which can wash out fresh seed.

ALSO GOOD
→ Transplant tomato seedlings in the evening (highs still ~31 °C)

SKIP
→ Water spinach — its season is ending; new sowings will be weak.

Next check: Sunday 19 Oct

That's the whole interface. You read it in about 15 seconds, then you go outside and do it.

The card can go to a Telegram message, a printable page, or plain text you stick on the fridge. I deliberately didn't build a dashboard with charts and streaks. Engagement is not the goal. Dirt under your fingernails is the goal.

2. Ask a question (optional)

Sometimes you need more than the card: "My kohlrabi leaves have holes in them, what now?" or "Can I grow basil through December?" You can ask the local model directly. It answers using your location, the season, and the same crop knowledge base the card uses.

3. Your garden profile

A small local file describes what you've got: balcony or ground, sun hours, what's currently planted, and roughly when you planted it. It never leaves your machine.

location:
  name: Hanoi
  lat: 21.03
  lon: 105.85
space: balcony
sun_hours: 5
planted:
  - crop: tomato
    stage: seedling
    date: 2026-09-20
  - crop: basil
    stage: established
    date: 2026-06-01

How it works

The most important design decision: the LLM is not in charge of agronomy.

Small models are good at language and reasoning over facts you hand them. They are not reliable sources of planting windows for a specific province. If you ask a small model cold, "when do I plant potatoes in Hanoi?", you might get a confident answer copied from temperate-climate advice.

So Monsoon splits the work in two:

┌──────────────────┐   ┌──────────────────┐   ┌───────────────────┐
│  Crop calendar   │   │ Weather forecast │   │  Garden profile   │
│  (curated JSON)  │   │  (Open-Meteo,    │   │  (local YAML)     │
│                  │   │   cached weekly) │   │                   │
└────────┬─────────┘   └────────┬─────────┘   └─────────┬─────────┘
         │                      │                       │
         └──────────────┬───────┴───────────────────────┘
                        ▼
            ┌───────────────────────┐
            │  Rules engine (Python)│   ← deterministic: what's *allowed*
            │  candidate tasks +    │
            │  weather flags        │
            └───────────┬───────────┘
                        ▼
            ┌───────────────────────┐
            │  Local LLM (Ollama)   │   ← language: what *matters most*,
            │  rank + explain,      │     and how to say it
            │  JSON-schema output   │
            └───────────┬───────────┘
                        ▼
            ┌───────────────────────┐
            │  Validator            │   ← rejects anything not in the
            │                       │     candidate list
            └───────────┬───────────┘
                        ▼
                  🌱 Weekly card

The rules engine decides what is possible. The model decides what matters most this week and how to say it. A validator makes sure the model can't invent a crop or a task that the rules didn't allow.

Step 1: A crop calendar as data, not vibes

Each crop is a small JSON record. Planting windows are stored per climate zone, so northern lowlands, the northern mountains, and the south each get their own windows.

{
  "id": "mustard_greens",
  "name": "Mustard greens",
  "zones": {
    "north_lowland": {
      "sow": [{ "start": [9, 1], "end": [2, 28] }]
    },
    "north_mountain": {
      "sow": [{ "start": [8, 15], "end": [10, 31] }],
      "frost_sensitive": false
    },
    "south": {
      "sow": [{ "start": [11, 1], "end": [3, 31] }]
    }
  },
  "seed_washout_risk": true,
  "max_temp_for_sowing": 32,
  "days_to_harvest": [30, 45],
  "containers_ok": true
}

Windows like September → February wrap around New Year, so the window check has to handle that:

from datetime import date

def in_window(today: date, window: dict) -> bool:
    start = date(today.year, *window["start"])
    end = date(today.year, *window["end"])
    if end < start:  # window wraps over New Year, e.g. Sep -> Feb
        return today >= start or today <= end
    return start <= today <= end

I seeded the calendar from published seasonal crop guidance and general horticulture references, then simplified it for home and container growing. This is the part of the project I'd most like other people to contribute to. It's a plain JSON file, so a gardener in Chiang Mai or Kerala can add their crops without touching any code.

Step 2: Weather from an open API, fetched once a week

Open-Meteo is an open-source weather API. It needs no API key, and you can self-host it if you want. Monsoon fetches a 7-day forecast once a week and caches it to disk:

import json
import pathlib
import requests

CACHE = pathlib.Path("cache/forecast.json")

def fetch_forecast(lat: float, lon: float) -> dict:
    try:
        r = requests.get(
            "https://api.open-meteo.com/v1/forecast",
            params={
                "latitude": lat,
                "longitude": lon,
                "daily": "temperature_2m_max,temperature_2m_min,precipitation_sum",
                "timezone": "auto",
                "forecast_days": 7,
            },
            timeout=10,
        )
        r.raise_for_status()
        daily = r.json()["daily"]
        CACHE.parent.mkdir(exist_ok=True)
        CACHE.write_text(json.dumps(daily))
        return daily
    except requests.RequestException:
        # No signal? Use last week's forecast and say so on the card.
        if CACHE.exists():
            return json.loads(CACHE.read_text()) | {"stale": True}
        return {"stale": True, "time": []}

If there's no connection, Monsoon still works. It falls back to the cached forecast (or to the calendar alone) and tells you so on the card.

Step 3: The rules engine turns weather into flags

A few simple heuristics cover most of what matters in a tropical garden:

def weather_flags(daily: dict) -> list[dict]:
    flags = []
    for day, rain, tmax, tmin in zip(
        daily.get("time", []),
        daily.get("precipitation_sum", []),
        daily.get("temperature_2m_max", []),
        daily.get("temperature_2m_min", []),
    ):
        if rain is not None and rain >= 20:
            flags.append({"day": day, "type": "heavy_rain", "mm": rain})
        if tmax is not None and tmax >= 32:
            flags.append({"day": day, "type": "heat", "c": tmax})
        if tmin is not None and tmin <= 10:
            flags.append({"day": day, "type": "cold_snap", "c": tmin})
        if tmin is not None and tmin <= 2:
            flags.append({"day": day, "type": "frost_risk", "c": tmin})
    return flags

The thresholds are rules of thumb, not science. Heavy rain means don't sow small seeds right before it. Heat means transplant in the evening and shade seedlings. A cold snap means cover basil and peppers. Frost risk only really fires in the mountains, which is exactly the point.

The engine then crosses three things: crops that are in their window, crops already in your garden, and these flags. The result is a short list of candidate tasks, each with an ID and the facts behind it.

Step 4: The local model ranks and explains

The model gets the candidate list, the weather flags, and your garden profile. Its job is to pick the single most important task, add one or two extras, flag anything to skip, and explain each choice in plain language.

I run it with Ollama and use structured output: the response must match a JSON schema, so I never have to parse free text.

import ollama
from pydantic import BaseModel

class Task(BaseModel):
    task_id: str
    when: str
    why: str

class WeekCard(BaseModel):
    do_this: Task
    also_good: list[Task]
    skip: list[Task]

SYSTEM = """You are a calm, practical gardening helper for a home gardener.
You may ONLY choose tasks from the provided candidate list, using their exact task_id.
Use the weather flags to decide timing. Keep every 'why' under 30 words.
Never invent crops, dates, or numbers that are not in the input."""

def make_card(candidates: list[dict], flags: list[dict], profile: dict) -> WeekCard:
    resp = ollama.chat(
        model="qwen3:4b",
        messages=[
            {"role": "system", "content": SYSTEM},
            {"role": "user", "content": json.dumps({
                "candidates": candidates,
                "weather_flags": flags,
                "garden": profile,
            })},
        ],
        format=WeekCard.model_json_schema(),
        options={"temperature": 0.2},
    )
    return WeekCard.model_validate_json(resp.message.content)

Step 5: Trust, but verify

Even with a schema, the model could return a task_id that isn't in the candidate list. So a validator checks every task. Anything unknown gets dropped, and if the main task is invalid, Monsoon falls back to the top-ranked candidate from the rules engine:

def validate(card: WeekCard, candidates: list[dict]) -> WeekCard:
    allowed = {c["task_id"] for c in candidates}
    card.also_good = [t for t in card.also_good if t.task_id in allowed]
    card.skip = [t for t in card.skip if t.task_id in allowed]
    if card.do_this.task_id not in allowed:
        top = candidates[0]
        card.do_this = Task(task_id=top["task_id"], when="this week", why=top["reason"])
    return card

This is the piece that made me comfortable letting a small model write advice. It can phrase things badly, but it can't tell you to plant something that's out of season.

Choosing the model

I wanted three things: it runs on an ordinary laptop, it handles multiple languages well, and it follows a JSON schema reliably. A small Qwen3 model fits all three, and its open weights mean I can fine-tune it later.

A card is generated once a week, so even a slow machine is fine. Speed simply doesn't matter much for this use case.

Because the model is behind a single function call, swapping it is a one-line change. If a better small multilingual model comes out next month, I change the model name and keep going.

Why open innovation matters for this project

The challenge asks where the open approach worked better than a closed one. For Monsoon, the honest answer is that almost every key property of the project depends on it being open.

1. My garden is my data

A garden profile looks harmless, but it contains your precise location, when you're home, what you grow, and over time, a log of your habits. A planner that's useful every week for years builds up exactly the kind of long-term personal data that I don't want sitting on a server I don't control.

With a local model, the only thing that ever leaves my machine is a latitude/longitude pair sent to a weather API. And because Open-Meteo is open source, even that can be self-hosted.

2. It costs nothing to run, forever

A weekly card for one gardener is tiny. But a free tool for a whole community garden, a school, or a farmers' cooperative shouldn't depend on someone paying for API calls every month. Run on a spare laptop or a small single-board computer, Monsoon's running cost is effectively the electricity. Nobody has to keep paying for it to keep working.

3. It works when the internet doesn't

Gardens are often outside the strongest Wi-Fi, and rural connectivity can be patchy. Monsoon needs the network for exactly one request a week, and degrades gracefully without it. The model, the calendar, and your history are all local.

4. I can make it local in the cultural sense too

This is the part I care about most. Being open doesn't just mean "runs locally." It means I can adapt the system to a place:

The knowledge base is a plain, editable file. A gardener in Chiang Mai can add Thai crops and zones. A grower in Kerala can add monsoon timings for their region. None of that needs anyone's permission.
The model can be changed or fine-tuned. The next step I'm exploring is a small LoRA adapter trained on regional agricultural extension material, so the model uses the same terms and crop variety names local farmers use instead of generic, temperate-climate gardening language.
The prompts and rules are visible. If the advice is wrong, you can see why. Was it the calendar, the weather rule, or the model's phrasing? Then you can fix the right layer.

A closed, hosted model treats "Hanoi" as an edge case of a system built mostly around temperate assumptions. An open system lets the people who actually live in a place define what normal looks like.

Where closed would have been easier (to be fair)

Closed frontier models are better at answering open-ended plant questions from general knowledge. For the "ask a question" feature, a bigger hosted model would give richer answers.

But Monsoon's core loop doesn't need a genius. It needs a model that follows a schema, reads a short list of facts, and writes three clear sentences. Small open models are well suited to that. And splitting the system into rules + model + validator means the model's weaknesses are contained.

Making the screen the shortest part

The theme asks for builds where the screen is the shortest part of the experience. Here's how I approached that:

Design choice	Why
One card per week, not a feed	Nothing to scroll, nothing to check daily
One main task on each card	Easy to remember once you're outside
Timing built in ("Mon or Tue, before the rain")	You don't need to open a weather app separately
Printable / message-based output	The card can live on the fridge, not in an app
No streaks, badges, or notifications beyond the weekly card	No pressure to come back to the screen

About 15 seconds of reading per week. Everything else happens in the garden.

Limitations

The crop calendar is the bottleneck. The output is only as good as the windows in the JSON, and coverage is still limited to common vegetables and herbs.
Microclimates are hard. A balcony on the 12th floor facing west is not the same as a ground-level garden in the same district. The sun_hours and space fields help, but only a bit.
Weather thresholds are generic. 20 mm of rain is a rough cutoff. Different crops and soils react differently.
Small models still drift. Without the validator, a small model can suggest tasks that aren't in the list or get timing wrong. The validator catches those mistakes, but the explanations can still be bland.
This is not expert agronomic advice. It's a nudge for home gardeners. For pests and diseases, the card points you to local extension services or experienced growers.

What's next

[ ] More crops and zones, especially Southeast Asia and South Asia
[ ] A LoRA fine-tune on regional agricultural extension material
[ ] A simple "what I actually did" log, so next year's cards learn from this year
[ ] A community-garden mode: one card for a shared plot, sent to everyone in a group chat
[ ] Running it on a cheap single-board computer that prints the card on a small receipt printer every Sunday

Try it

pip install requests ollama pydantic pyyaml
ollama pull qwen3:4b      # or any model you prefer
cp garden.example.yaml garden.yaml   # edit with your location and plants
python monsoon.py card

If you garden somewhere without frost, I'd love your help with the crop calendar. Share your region's crops and planting windows in the comments.

Now close the laptop and go check on your seedlings. 🌱

Built with: Ollama, Qwen3 (open weights), Open-Meteo, Python, Pydantic.