A private, candle-lit ofrenda for the people you miss.
Write down their stories, then talk about them with an AI that only knows what you tell it,
by typing or by a hands-free voice call. Everything runs on your own computer.
Quick start · How it works · Voice calls · Privacy · Why open source
Built for the Hacktoberfest Open-Source AI Challenge, Week 4: Ghost in the Machine. The ghost here is not a haunting. It is the people who stay with us through the stories we keep.
Screenshots use the bundled demo data: an illustrated, fictional grandmother. Replies in your own copy come from your own local model, so the wording will differ.
| 🕯️ Build an ofrenda | Add a person with a photo, their years, and who they were to you. Place their favorite foods, songs and flowers on the altar, and light candles. |
| 📖 Keep their stories | Write memories in your own words (or record them and let Whisper write them down). They are saved in one JSON file that you own. |
| 💬 Talk about them | Ask "What did she sing while cooking?" The AI answers from your stories only, and streams the reply as it thinks. |
| 📞 Call | Press the phone button and talk. A local speech model hears you, a local language model answers, and a local voice reads the reply sentence by sentence. Tap the photo to interrupt. |
| ✍️ Write a remembrance | The model turns the stories into a short, warm remembrance for the altar. |
| 🖨️ Share a page | Export one self-contained, printable HTML page with the photo and stories inside. |
Everything on this diagram runs on your machine. There is no cloud box, because there is no cloud.
flowchart TB
you(["🧑 You: type, speak, listen"])
cloud["☁️ Cloud AI services<br/>not used, not needed"]
subgraph PC["🖥️ YOUR COMPUTER · nothing leaves this box"]
BR["🌐 <b>Browser</b><br/>🕯️ altar and chat · 🎤 voice detector · 🔊 local voice"]
SV["🐍 <b>Ofrenda server</b><br/>127.0.0.1 only · REST API · story finder"]
STT["🎧 <b>Whisper</b><br/>speech to text<br/><i>open source</i>"]
LLM["🦙 <b>Ollama</b><br/>open-weight model<br/><i>open source</i>"]
DB[("📒 <b>ofrenda.json</b><br/>stories and photos<br/><i>a file you own</i>")]
end
you <--> BR
BR <-- "text · audio · streamed words" --> SV
SV -- "audio" --> STT
SV -- "grounded prompt" --> LLM
SV <-- "read / write" --> DB
cloud ~~~ you
classDef off fill:#2a1030,stroke:#e0357a,stroke-dasharray:5 4,color:#d9a8c0;
class cloud off;
Before the model sees a question, Ofrenda looks for stories that match it. No match means the model is never called. When there is a match, the model gets only those stories, and a rule: speak about them, never as them.
flowchart TD
Q(["❓ Your question"]) --> K{"Does any story share<br/>words with it?"}
K -- "no" --> N["💬 “I have no story about that yet.”<br/><b>The model is never called.</b>"]
K -- "yes" --> P["📝 Build the prompt<br/>top 3 stories + last few turns"]
P --> R["🛡️ Rules: use ONLY these stories ·<br/>speak ABOUT them, never AS them"]
R --> M["🦙 Local model streams an answer"]
M --> O(["✨ Words appear and are spoken"])
N --> E(["Add a story and ask again"])
classDef good fill:#3a1d5a,stroke:#ffb000,color:#fff3dc;
classDef stop fill:#4a1530,stroke:#e0357a,color:#fff3dc;
class P,R,M,O good;
class N,E stop;
You need Python 3.10+ and Ollama. The core has no other dependencies.
# 1. get an open-weight model (about 2 GB, once)
ollama pull llama3.2:3b
# 2. get Ofrenda
git clone https://github.com/Hasalawa/ofrenda.git
cd ofrenda
pip install -e .
# 3. light the candles
python -m ofrenda serve # opens http://localhost:8765Want to look around first? Open the bundled demo (no data of yours involved):
python -m ofrenda --data examples/demo.json serve🪟 Windows tips
- Use
python -m ofrenda ...instead ofofrenda .... It always works, even if theofrendacommand is not on your PATH. - Start Ollama from the Start menu (a llama icon appears in the tray), then run
ollama listto check the model is there. - In PowerShell, keep quotes around names with spaces:
python -m ofrenda add-person "Abuela Rosa".
⌨️ Prefer the command line?
python -m ofrenda add-person "Abuela Rosa" --years "1941-2019" --relation grandmother --photo rosa.jpg
python -m ofrenda add-fav "Abuela Rosa" food "pan de muerto"
python -m ofrenda add-story "Abuela Rosa" --title "The night the mole burned" --text "She forgot the chocolate..."
python -m ofrenda remember "Abuela Rosa" # write a remembrance
python -m ofrenda ask "Abuela Rosa" "Why did the mole burn?"
python -m ofrenda build --out ofrenda.html # one printable page| Command | What it does |
|---|---|
serve [--port N] [--no-open] |
The interactive altar in your browser |
add-person NAME [--years] [--relation] [--photo] |
Add someone to the ofrenda |
add-story NAME --title T [--text] |
Save a memory (reads stdin if --text is omitted) |
add-fav NAME food|song|flower VALUE |
Place an offering |
transcribe NAME AUDIO --title T |
Turn a recorded story into text, offline (needs [audio]) |
remember NAME [--speak] |
Write a remembrance, optionally read aloud (needs [voice]) |
ask NAME QUESTION [--speak] |
Ask a question from the terminal |
build [--out FILE] [--title T] |
Export a self-contained HTML page |
Use --data FILE (or OFRENDA_DATA) to keep separate ofrendas in separate files.
pip install faster-whisper # open-source Whisper, runs on your computer
python -m ofrenda serve # then press the 📞 button next to the message boxThe first call downloads a small speech model (about 150 MB) once. After that it works with no internet.
sequenceDiagram
autonumber
actor You
participant B as 🌐 Browser
participant S as 🐍 Ofrenda server
participant W as 🎧 Whisper (local)
participant L as 🦙 Ollama (local)
You->>B: speak, then pause
B->>B: detect the end of the sentence
B->>S: POST /api/transcribe (16 kHz WAV)
S->>W: transcribe
W-->>S: "Tell me about the red notebook"
S-->>B: text
B->>S: POST /api/ask (question + recent turns)
S->>S: find matching stories
alt no story matches
S-->>B: "I have no story about that yet"
B-->>You: speaks it
else stories found
S->>L: grounded prompt (stories only)
loop while the model writes
L-->>S: next words
S-->>B: next words
B-->>You: speaks each finished sentence
end
end
Note over B: mic is paused while it speaks,<br/>then it listens again
For the best call
- Wear headphones. Otherwise the speakers can leak into the mic and it may answer itself.
- Speak English, in full sentences, then pause for a second.
- Use words that appear in your stories ("notebook", "marigold"). Small talk like "how are you?" has nothing to match, so it gets the "no story" reply.
- Follow-ups work: ask "What happened with the mole?" then "And then?".
- Pick a voice marked as local in the call screen. Voices labelled "(online)" send text to a cloud service.
| Question | Answer |
|---|---|
| Where are my stories stored? | One JSON file (ofrenda.json) and a photos/ folder, next to where you start the app. |
| Does anything go to the internet? | No. The server listens on 127.0.0.1 only and rejects requests with a foreign Host header. The only internet use is the one-time download of the models themselves (the Ollama model, and the Whisper model if you use voice). |
| Which AI reads my stories? | The open-weight model you run in Ollama. |
| Which AI hears my voice? | Whisper, running on your CPU. Audio is not saved. |
| Can it pretend to be my grandmother? | No. The prompt forbids speaking as the person. It talks about them. |
| Can it make things up? | It is only given the stories that match your question, and told to say so when they do not answer it. A small model can still slip, so treat it as a companion for memories, not a source of truth. |
| What if Ollama is not running? | The app still works: it falls back to a simple template and shows the matching stories. |
| Closed cloud AI | Ofrenda (open weights) | |
|---|---|---|
| Your family's stories | Uploaded to someone else's server | Never leave your computer |
| Works with no internet | ❌ | ✅ |
| Still works if a company changes or shuts down a service | ❌ | ✅ you hold the model and the file |
| Swap the model | Whatever they offer | OFRENDA_MODEL=qwen2.5:7b or any model Ollama runs |
| Cost per question | Metered | Free after the download |
| Tune it to your family's language | Rarely possible | Possible: open weights can be fine-tuned |
| Variable | Default | Meaning |
|---|---|---|
OFRENDA_MODEL |
llama3.2:3b |
Any model Ollama can run. Try qwen2.5:7b for richer answers (needs more RAM) or qwen2.5:1.5b for a slow laptop. |
OLLAMA_HOST |
http://localhost:11434 |
Where your model server lives |
OFRENDA_STT_MODEL |
base.en |
Whisper size: tiny.en (fastest), base.en, small.en (most accurate) |
OFRENDA_DATA |
ofrenda.json |
Where your memories are stored |
Optional extras: pip install -e ".[audio]" (Whisper), ".[voice]" (read-aloud in the terminal), ".[dev]" (tests and linting).
ofrenda/
├─ ofrenda/
│ ├─ cli.py command line + prompts (the "speak about them, never as them" rules)
│ ├─ web.py local web server and REST API (127.0.0.1 only)
│ ├─ page.py the whole interface: altar, chat, voice call (one offline HTML page)
│ ├─ llm.py talks to Ollama, with streaming
│ ├─ stt.py speech to text with Whisper (faster-whisper)
│ ├─ retrieve.py finds the stories that match a question
│ ├─ store.py the JSON file
│ ├─ render.py printable, self-contained HTML export
│ └─ voice.py optional read-aloud for the terminal
├─ tests/ pytest suite for the core, the web API and voice decoding
├─ examples/ demo ofrenda (illustrated portrait + 4 stories)
├─ docs/ banner, diagrams, screenshots, demo GIF
└─ .github/workflows/ CI and GitHub Pages
pip install -e ".[dev]"
ruff check .
pytestCI runs on every push, and the demo page is published to GitHub Pages.
flowchart LR
push(["⬆️ git push"]) --> lint["🧹 ruff"]
lint --> test["🧪 pytest<br/>Python 3.10 · 3.11 · 3.12 · 3.13"]
test --> smoke["💨 CLI smoke test"]
smoke --> pkg["📦 build package"]
pkg -- "tag v*" --> rel["🚀 GitHub Release"]
push -- "main" --> pg["🏗️ build demo page"] --> dep["🌍 GitHub Pages"]
To enable the demo page, set Settings → Pages → Source to GitHub Actions once.
🖼️ Diagrams as images (for posts and slides)
Pre-rendered copies live in docs/diagrams/: architecture.png, grounding.png, voice-call.png, cicd.png.
Their Mermaid sources (.mmd) are next to them.
In Mexico, Día de los Muertos (November 1 and 2) is not about fear. Families build an ofrenda: photos, candles, marigolds and the foods their people loved, so the ones who died can find their way home for a night. Ofrenda keeps that spirit. The "ghost in the machine" is a memory that is looked after, in a machine that is yours.
MIT. See LICENSE. The portrait in examples/ is an original illustration of a fictional person.




