traces/README.md

LLM-call traces

The Apprentice writes one JSONL record per LLM call into this directory at runtime (default-on; opt out with ORACLES_TRACE_DISABLE=1).

Directory layout

• oracles-trace-<session>.jsonl — raw session traces. Gitignored. Each session writes a fresh file named with a 12-char UUID.
• sample/ — committed sample traces from real playthroughs. Shipped with the repo as the Sharing-is-Caring badge deliverable.

What's in a record

Each line is one JSON object describing a single LLM call:

{
  "ts":              <unix epoch float>,
  "session":         "<12-char hex session id>",
  "mode":            "json" | "text",
  "model":           "oracle-wizard-lora",          // legacy alias
  "model_requested": "oracle-wizard-lora",
  "model_returned":  "oracle-wizard-lora",          // server echo
  "using_lora":      true,                          // computed from model_returned
  "temperature":     0.9,
  "max_tokens":      900,
  "system":          "<full system prompt>",
  "user":            "<full user prompt>",
  "response":        "<raw LLM response, JSON or plain text>",
  "latency_ms":      4231,
  "usage":           {"prompt_tokens": ..., "completion_tokens": ..., ...}
}

Curating a sample for the badge

After a playthrough:

# Find your session's trace
ls -lt traces/oracles-trace-*.jsonl | head -1

# Copy it to the sample dir under a friendlier name
cp traces/oracles-trace-<id>.jsonl traces/sample/full-playthrough-fantasy-en.jsonl

# Optionally scrub: if you wrote anything personal as an oracle, run
# the included scrub helper (see scripts/scrub_trace.py).

git add traces/sample/full-playthrough-fantasy-en.jsonl
git commit -m "Add sample trace from fantasy/English playthrough"
git push

Privacy note

Traces include every prompt and response. The system prompt is template text (no PII). The user prompt is the obstacle setup + the player's oracle text — so if a player typed their own name or anything sensitive as an oracle, that lands in the trace. The hero name and village name also get baked into prompts. If you don't want any of that public, don't copy that session's trace into sample/.

The default hero name "Tobin" and default village "the Hollow" are already non-personal placeholders; sticking with the defaults makes any trace safe to share verbatim.