Ai wizard interpreter

AI Wizard Interpreter

The ai-wizard skill produces a score but isn't very explainable on its own. This skill is the interpreter layer: hand it a dossier and it explains the result the way a coach would — grounded in the actual scoring math, not vibes.

It is strictly read-only toward ai-wizard: it never imports, runs, or edits that skill. It only reads the profile.json that ai-wizard already emitted.

What "submit your dossier" means

A dossier is the profile.json AI Wizard writes to Databases/ai-wizard/runs/<run-id>/profile.json. People can submit it three ways:

1. A file they hand you (any path to a profile.json, or a run directory).
2. A run id already in Databases/ai-wizard/runs/.
3. The latest run on this workspace.

Commands

# Explain a specific dossier file
python3 Skills/ai-wizard-interpreter/scripts/interpret.py explain --profile <path/to/profile.json>

# Explain by run id
python3 Skills/ai-wizard-interpreter/scripts/interpret.py explain --run <run-id>

# Explain the most recent run
python3 Skills/ai-wizard-interpreter/scripts/interpret.py explain --latest

# Machine-readable explanation (for a UI/API)
python3 Skills/ai-wizard-interpreter/scripts/interpret.py explain --latest --format json

# Save a copy of the report (markdown or json) alongside printing it
python3 Skills/ai-wizard-interpreter/scripts/interpret.py explain --run <run-id> --out report.md

How to run this skill

1. Locate the dossier (ask for a file, a run id, or use --latest).
2. Run explain. Default output is human-readable markdown.
3. Present the markdown to the person. If it's going into a page/API, use --format json.
4. If the script prints a WARNING: score reconstruction off by N points, ai-wizard's scoring formula has changed — tell the person the math walk-through is approximate and flag it for maintenance (see references/score-formula.md).

What the explanation contains

• Headline: score/1000, plain-language band, honest range, maturity stage + meaning, archetype.
• The actual math: the three skill groups, each group's 0–1 average, its weight, and roughly how many of the 1000 points it contributed — then the exact final equation. This is reconstructed from the profile and verified against the profile's own overall, so it's faithful, not a paraphrase.
• What pushed the score UP / DOWN: the strongest and weakest individual axes, in plain English.
• How much to trust each part: per-dimension confidence (when the profile stores it) and semantic-review status.
• Honest caveats, risks, and a prioritized "do these next" plan.

Submitting to the Vibe Pill scoreboard

The Vibe Pill site hosts a public, pseudonymous leaderboard at https://www.thevibepill.com/scoreboard. People can put their score on it straight from this skill.

How identity works (read this): submission is self-attested and pseudonymous. The skill derives a stable two-word handle — an adjective + animal like Rugged Walrus — by hashing a per-workspace seed (ZO_USER, falling back to the identity token or hostname). The seed is never transmitted; only the derived handle and an opaque, non-reversible dedup_key are sent. The same workspace always gets the same handle, so re-submitting updates the existing row instead of creating a duplicate.

The score is not trusted as-claimed. The payload includes the score components (section averages, coverage estimate, semantic bonus). The scoreboard server re-runs ai-wizard's exact formula on those components and rejects the submission if the recomputed score doesn't match the claimed one (±2 pts). This is the "simple authentication" of the score: a person can't just POST 999 — the math has to reproduce it.

# See your derived handle without submitting anything
python3 Skills/ai-wizard-interpreter/scripts/interpret.py handle

# Preview the exact payload without sending it (safe, no network)
python3 Skills/ai-wizard-interpreter/scripts/interpret.py submit --latest --dry-run

# Submit your latest run to the live scoreboard
python3 Skills/ai-wizard-interpreter/scripts/interpret.py submit --latest

# Submit a specific run/profile, or point at a different host
python3 Skills/ai-wizard-interpreter/scripts/interpret.py submit --run <run-id>
python3 Skills/ai-wizard-interpreter/scripts/interpret.py submit --latest --endpoint https://www.thevibepill.com

submit defaults to --endpoint https://www.thevibepill.com. It prints the server's verified score and a link to the board. Per workspace policy, only run a real (non---dry-run) submit when the person has asked to be put on the board — it's an external action.

Design notes

• Faithful, not invented. The score formula constants live in references/score-formula.md and are mirrored in the script. The interpreter solves for the two hidden inputs (evidence coverage and the semantic bonus) by inverting ai-wizard's confidence formula, then checks that its reconstruction reproduces the stored score. If it can't (delta > 1 point), it says so rather than bluffing.
• Degrades gracefully. Older profiles that lack range or per-dimension confidence still work — the range is recomputed from confidence using ai-wizard's documented uncertainty formula, and missing dimension data is stated plainly.
• Local explanation, explicit submission. explain and handle run locally. Only the explicit, non-dry-run submit command sends the documented pseudonymous score payload to the configured scoreboard.

Outputs

By default the explanation is printed to stdout. With --out <path> it is also written there (use --dry-run to preview without writing).