How to use Tales

You need Python 3.11 or newer and Ollama, running as a separate daemon. The package itself does not start the model server.

$ git clone https://github.com/Ewan-Dkhar/Tales
$ cd Tales
$ uv venv
$ uv pip install -e .
$ ollama serve
$ ollama pull gemma2:2b
# then, to see the whole pipeline once:
$ .venv/bin/haunt demo

uv pip install -e . puts a haunt script in .venv/bin/. Call it by path, or activate the environment and type haunt. With plain pip it is the same inside any virtual environment:

$ python -m venv .venv && source .venv/bin/activate
$ pip install -e .
$ haunt --help

Three commands tell you whether the parts agree with each other:

• haunt config — the resolved configuration, as JSON.
• haunt demo — a bundled crash, narrated end to end.
• haunt run -- python -c "raise SystemExit(1)" — the smallest real thing you can wrap.

haunt run [OPTIONS] -- COMMAND [ARGS...]

haunt starts COMMAND, waits for it to exit, and gathers the evidence if the process did not survive. Options before -- belong to haunt; everything after it belongs to your program.

$ haunt run -- python app.py                 # narrate the failure
$ haunt run -- pytest -q tests/              # flags pass through after --
$ haunt run -m gemma2:2b -- ./bin/worker     # another model, one run
$ haunt run -o reports/last-crash.md -- ./job.sh
$ haunt run --no-narrate -- ./job.sh         # evidence only
$ haunt run --exit-zero -- ./job.sh          # always exit 0

What happens to the process’s output

stdout and stderr are captured, not streamed. Your program’s output goes into a pipe for the evidence, so it does not appear live in the terminal, and the child does not see a TTY: progress bars, colour and line-buffering behave the way they do when output is piped. The last stderr_lines lines of each stream — 100 by default — end up in the report.

Exit codes

haunt run is a wrapper, so it exits the way your process did.

--exit-zero overrides all of it and forces 0, which is what haunt demo uses so a demonstration never fails your shell.

A process that survives

If the command exits cleanly, haunt prints The process survived. Nothing to bury. and writes no story and no report. There is no death to narrate, and inventing one would be exactly the failure mode this tool exists to avoid.

haunt analyze [OPTIONS] LOGFILE

Narrates a death that already happened, from a file you kept — a container log, a CI run, a machine you do not want to re-crash.

$ docker logs haunted-app > crash.log
$ haunt analyze crash.log
$ haunt analyze crash.log -m gemma2:9b -o postmortem.md
$ haunt analyze crash.log --no-narrate -o evidence.md

The file is the only witness, so exit_code and signal are null, duration_s is 0.0, and recent_files is empty. It still extracts the Python traceback if there is one, and it still reads the git context of your current directory, which is usually what makes the narration worth reading.

A missing file exits 2. Otherwise analyze exits 0: it did not run anything, so it has no status to report. --exit-zero does not exist here.

$ haunt demo                  # the default model
$ haunt demo -m gemma2:2b     # the fast one
$ haunt demo -o ""            # panels only, no file

It runs haunt/demo_crash.py with the interpreter that is running haunt, and narrates the resulting ZeroDivisionError. The demo program crashing is the point; it is not a bug to fix. demo always exits 0.

haunt config prints the resolved configuration as JSON — defaults merged with ~/.haunt/config.toml and the environment.

The report is written to GHOST_REPORT.md in the current directory unless -o says otherwise — and it is written whenever an output path is set, including when narration was skipped or the model could not be reached. In that case the story is replaced by one line:

# 👻 Ghost Report

_Summoned by haunt at 2026-10-29T09:26:55.060260+00:00_

_The ghost did not speak. The evidence it was given is recorded below, unchanged._

---

## Raw Evidence

A full report is five sections the prompt fixes, then the appendix.

Here is a real report from a crash with no traceback at all — ollama serve run while the daemon was already listening. The narration is verbatim; the JSON is abridged for width, but the report always carries the whole block.

{
  "command": ["ollama", "serve"],
  "exit_code": 1,
  "signal": null,
  "duration_s": 0.015,
  "stderr_tail": "Error: listen tcp 127.0.0.1:11434: bind: address already in use",
  "traceback": null,
  "git": { "branch": "main", "uncommitted": [] },
  "env": { "python": "3.12.5" }
}

The prose is a performance. The JSON is testimony. If a sentence in the story is not supported by the block underneath it, the block is what you trust — and the 2B model does get details wrong, which is precisely why the block is there. -o "" skips the file entirely when you only want the panels on screen.

model = "gemma2:9b"
fallback_model = "gemma2:2b"
ollama_host = "http://localhost:11434"
temperature = 0.8
stderr_lines = 100
output = "GHOST_REPORT.md"
# sentry_dsn = "https://<key>@<org>.ingest.sentry.io/<project>"

model and fallback_model take any Ollama tag; an empty fallback_model disables the fallback. temperature is 0.0–2.0 and lower is more literal. stderr_lines must be 10 or more. An empty output writes nothing. ollama_host may point at another machine if you run Ollama remotely.

Out-of-range values are rejected rather than silently clamped: stderr_lines = 5 fails with an error naming the field. For a single project, skip the file and set the environment:

$ HAUNT_MODEL=gemma2:2b HAUNT_OUTPUT=crash-report.md haunt run -- python app.py

• gemma2:2b — 1.6 GB, fast enough to feel interactive on a laptop, occasionally wrong about details. It once read return 1 / candles as “a candle’s value was being divided by one.” Good for demos and CI.
• gemma2:9b — the default. Slower, better prose, better at staying inside the evidence.
• Anything else — llama3.1, qwen2.5, a fine-tune, whatever ollama list shows. --model takes the tag verbatim and nothing else in the tool changes.

fallback_model is only tried when the primary model fails before emitting any text. If it fails halfway through, the error propagates instead of splicing two different stories together.

Because the evidence is serialized before it reaches the model, two models narrating the same crash produce different prose over an identical evidence block — apart from the timestamp. The diff comes back with one line changed, and it is the clock:

$ haunt analyze crash.log -m gemma2:2b -o fast.md
$ haunt analyze crash.log -m gemma2:9b -o careful.md
$ diff fast.md careful.md     # the story differs; the JSON does not

The sentry-sdk dependency is installed either way; nothing is sent without a DSN.

$ export SENTRY_DSN="https://<key>@<org>.ingest.sentry.io/<project>"
$ haunt run -- python app.py

One transaction per invocation — haunt.pipeline, named after the command it wrapped — with these spans:

Sampling is 1.0 and send_default_pii is False: the trace records timing and operation names, not the evidence itself.

Wrap a failing script and keep the report

$ haunt run -- python app.py
# the report lands in ./GHOST_REPORT.md

Record evidence in CI, with no model on the runner

The evidence is still written, the exit code is still propagated, and nothing is narrated.

$ haunt run --no-narrate -o crash-evidence.md -- ./run-tests.sh

Reproduce a native crash

$ cat > segv.py <<'PY'
import os, signal
os.kill(os.getpid(), signal.SIGSEGV)
PY
$ haunt run -- python segv.py; echo "exit=$?"
exit=11

There is no traceback in that report. The narration is built from the exit code, the signal and the last thing the process said — which is the whole point of capturing more than a stack trace.

Narrate a log from somewhere else

$ kubectl logs crashy-pod --previous > crash.log
$ haunt analyze crash.log -o postmortem.md

Keep a shell’s exit status while reading the story

$ haunt run --exit-zero -- ./job.sh

capture.run_command → gather.build_evidence → prompt.build_messages
                    → narrator.NarratorEngine → render.render_story / write_report

• capture.py runs the process, recording the exit code, signal, duration and both output streams.
• gather.py fills in the traceback, the git context, the environment fingerprint and the recently modified files.
• prompt.py serializes the evidence as JSON around the Ghost Narrator system prompt: five fixed headings, no invented facts, the word “unknown” allowed.
• narrator.py streams the model from Ollama, with the Sentry spans and the fallback model.
• render.py parses the Markdown into Rich panels and writes the report with the evidence appendix.

Every stage passes the same Evidence object along, which is why the pipeline is testable without a model: 21 tests, no network.

• One process, not a tree. A parent that spawns children and exits leaves the children unobserved.
• Captured output, not a terminal. Programs that need a TTY behave differently under haunt than under your shell.
• POSIX exit status. Signal numbers assume a POSIX system; the project is developed and tested on Linux.
• The model can still be wrong. The prompt forbids invented facts and the evidence is attached, but a small model can misread a line. The appendix is the part you trust.
• analyze is blind to exit codes and durations. A log is a partial witness.
• It does not fix your bug. It points at the line, quotes the evidence, and gets out of the way.