Files
threshing-atlas/collection/etl/handoff.py
ekcSchianoandClaude Opus 5.5 e10312ab02
CI / test (pull_request) Successful in 2m3s
Known answers for the bot: the guide's encounter answers and the bot's own results, by choice text (#35)
analysis/known/build_known.py writes data/public/known_answers.json from pdf_encounters.json and tree.json;
solver.js knownAnswer(known, offered, { target, sceneColour }) matches a screen's choices against it (the guide's
paraphrases by their words, the bot's texts exactly) and returns a pick when one choice is clearly on the guide's
recommended path to the target, plus the evidence for every choice to hand to Clef. Rebuilt daily, checked in CI,
and sent to the bot with the route model.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UCzTd31GphpMXDhQqWrCMQ
2026-11-19 13:32:09 +00:00

200 lines
9.7 KiB
Python

"""Hand-offs without GitHub: the zip of atlas files for the bot, and the local equivalent of the daily workflow.
python -m collection export-bot-kit -> exports/atlas-for-bot-<date>-<policy id>.zip
policy.json, experiments.json, solver.js and graph.js (what the bot vendors into vendor/threshing-atlas/), plus a README and
checksums. Send it to the bot's maintainer; they unzip it into vendor/threshing-atlas/.
python -m collection refresh [--bot PATH ...]
Every source (and any bot folders or zips given), then the graph, the route model, the statistics and the
build: what .github/workflows/update-sources.yml does every day.
python -m collection cycle --bot PATH [--deliver DIR] [--community] [--force]
The loop with the bot, in one command and safe to run on a timer: import the bot's new runs, refit the
route model, rebuild the experiment plan, and put the bot's files where it reads them. Does nothing but
deliver when the bot has no new runs.
"""
import hashlib
import json
import shutil
import subprocess
import sys
import zipfile
from datetime import datetime, timezone
from pathlib import Path
from .common import ROOT, path
KIT = {"policy.json": "data/public/policy.json", "experiments.json": "data/public/experiments.json",
"tree.json": "data/public/tree.json",
"solver.js": "core/solver.js", "graph.js": "core/graph.js"}
README = """Threshing Atlas files for the DragonKind bot
============================================
Policy id: {policy}
Made: {made}
Unzip these five files into the bot's vendor/threshing-atlas/ folder, replacing the old ones, and keep them
together: solver.js reads the game from this policy.json.
policy.json the route model (the game, the counts behind every roll, the best routes per colour)
experiments.json the experiment plan: what each attempt of each account is for (read it with assign())
tree.json the screen tree: every screen, every option, where each led (read it with screenPick())
solver.js the advisor: advisor(), recommendOption(), solverHistory(), assign(), screenPick()
graph.js trajectoryVariables(): the bot's steps -> the community form's variables
How the bot uses them: docs/BOT_INTEGRATION.md in the atlas repo. Log the policy id above as policyId on each run,
and the plan's id as planId.
Checksums (sha256):
{sums}
To send runs back: zip the bot's data/runs.jsonl, data/knowledge.json and logs/encounters.jsonl (keep the folder
names) and send the zip. It is imported with `python -m collection refresh --bot <the zip>`; only anonymised
steps and outcomes are kept (no game prose, no account names).
"""
def export_bot_kit(out_dir="exports"):
policy = json.loads(path(KIT["policy.json"]).read_text(encoding="utf-8"))
pid = str(policy.get("id", "unknown"))[:12]
made = datetime.now(timezone.utc).strftime("%Y-%m-%d")
sums = "\n".join(f" {hashlib.sha256(path(src).read_bytes()).hexdigest()} {name}" for name, src in KIT.items())
out = path(out_dir)
out.mkdir(parents=True, exist_ok=True)
zpath = out / f"atlas-for-bot-{made}-{pid}.zip"
with zipfile.ZipFile(zpath, "w", zipfile.ZIP_DEFLATED) as z:
for name, src in KIT.items():
z.writestr(zipfile.ZipInfo(name, (2026, 1, 1, 0, 0, 0)), path(src).read_bytes(), zipfile.ZIP_DEFLATED)
z.writestr(zipfile.ZipInfo("README.txt", (2026, 1, 1, 0, 0, 0)), README.format(policy=pid, made=made, sums=sums))
return zpath
def _step(label, cmd):
print(f"\n== {label}: {' '.join(cmd)}", flush=True)
subprocess.run(cmd, cwd=ROOT, check=True)
def rebuild():
"""Everything built from the runs, in order. The one list the local refresh, the bot cycle and the daily
workflows all use (`python -m collection rebuild`), so a new report only needs adding here."""
py = sys.executable
# the runs first: if they do not match data/dictionary.yaml, stop here rather than model yesterday's runs
_step("runs, checked against the dictionary", [py, "-m", "collection", "build"])
if shutil.which("node"):
_step("route graph", ["node", "analysis/network/build-graph.js"])
else:
print("\n(node is not installed: data/public/graph.json is not rebuilt; everything else is)")
_step("route model (a few minutes)", [py, "planner/build_policy.py"])
_step("experiment plan", [py, "planner/build_experiments.py"])
_step("what the runs show about the Black", [py, "analysis/black/evidence.py"])
_step("screen tree", [py, "analysis/tree/build_tree.py"])
_step("known answers for the bot (guide + screen tree)", [py, "analysis/known/build_known.py"])
try:
import scipy # noqa: F401
_step("statistics", [py, "analysis/stats/site_stats.py"])
except ImportError:
print("\n(scipy is not installed: data/public/stats.json is not rebuilt)")
_step("runs, generated files and metadata", [py, "-m", "collection", "build"])
return 0
def refresh(update_main, bots=()):
"""update -> (graph, policy, stats, build) when something changed. Returns 0 on success."""
py = sys.executable
args = ["update", "--report", str(path("exports/last-report.md"))]
path("exports").mkdir(exist_ok=True)
rc = update_main(args)
for i, b in enumerate(bots):
rc |= update_main(["update", "--source", "bot", "--file", f"bot={b}", "--report", str(path(f"exports/last-report-bot{i + 1}.md"))])
rebuild()
print(f"\nDone. What changed: exports/last-report.md. Send the bot its files with: {py} -m collection export-bot-kit")
return rc
# ---------------------------------------------------------------- the automated cycle with the bot
def _fingerprint():
"""What the route model and the plan are built from: the coded runs and the bot's anonymised files."""
h = hashlib.sha256()
for p in [path("data/public/runs_clean.csv"), *sorted(path("data/bot").glob("*.json*")), path("planner/knowledge.yaml"),
path("planner/policy.yaml"), path("planner/experiments.yaml"), path("core/spec/game.yaml")]:
if p.exists():
h.update(p.name.encode())
h.update(p.read_bytes())
return h.hexdigest()
def _headline():
"""The numbers a person checks after a cycle: {label: value}."""
out = {}
try:
pol = json.loads(path("data/public/policy.json").read_text(encoding="utf-8"))
out["policy id"] = pol["id"]
t = pol["samples"]["all"]["targets"]
pct = lambda d: f"{100 * d['mean']:.2f}% ({100 * d['lo']:.2f}-{100 * d['hi']:.2f})" # noqa: E731
out["Black, first attempt"] = pct(t["Black"]["firstAttempt"]["thisAttempt"]["pX"])
out["Black, later attempt"] = pct(t["Black"]["thisAttempt"]["pX"])
out["Blue, per attempt"] = pct(t["Blue"]["thisAttempt"]["pX"])
out["runs the model learns from"] = pol["source"]["runs"]
out["bot runs"] = pol["source"]["by_source"].get("bot", 0)
except (OSError, KeyError, ValueError):
pass
try:
plan = json.loads(path("data/public/experiments.json").read_text(encoding="utf-8"))
out["plan id"] = plan["id"]
for e in plan["experiments"]:
p = e["progress"]
out[f"experiment {e['id']}"] = f"{e['status']}: {p['observed']} observed, {p['rare']} rare" + (f" [{e['note']}]" if e.get("note") else "")
except (OSError, KeyError, ValueError):
pass
return out
def deliver(dest):
"""Copy the bot's files (KIT) into a folder, each one whole (written beside it, then renamed), with a manifest
the bot can check before an attempt: atlas-kit.json = {policyId, planId, made, sha256: {file: sum}}."""
dest = Path(dest).expanduser()
dest = dest if dest.is_absolute() else path(str(dest))
dest.mkdir(parents=True, exist_ok=True)
sums = {}
for name, src in KIT.items():
data = path(src).read_bytes()
sums[name] = hashlib.sha256(data).hexdigest()
tmp = dest / (name + ".incoming")
tmp.write_bytes(data)
tmp.replace(dest / name)
head = _headline()
manifest = {"policyId": head.get("policy id"), "planId": head.get("plan id"),
"made": datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"), "sha256": sums}
tmp = dest / "atlas-kit.json.incoming"
tmp.write_text(json.dumps(manifest, indent=1) + "\n", encoding="utf-8")
tmp.replace(dest / "atlas-kit.json") # last: a kit whose manifest matches its files is complete
return dest
def cycle(update_main, bots, deliver_to=None, community=False, force=False):
"""Import the bot's runs -> refit -> re-plan -> deliver. Returns 0 on success. Writes exports/last-cycle.md."""
py = sys.executable
path("exports").mkdir(exist_ok=True)
before, was = _fingerprint(), _headline()
rc = 0
if community:
rc |= update_main(["update", "--report", str(path("exports/last-report.md"))])
for i, b in enumerate(bots):
rc |= update_main(["update", "--source", "bot", "--file", f"bot={b}", "--report", str(path(f"exports/last-report-bot{i + 1}.md"))])
built = all(path(src).exists() for src in KIT.values())
changed = force or not built or _fingerprint() != before
if changed:
rebuild()
else:
print("\nNo new runs: the route model and the plan are unchanged.")
now = _headline()
lines = [f"# Bot cycle, {datetime.now(timezone.utc).strftime('%Y-%m-%d %H:%M')} UTC", "",
"The model and the plan were rebuilt." if changed else "No new runs: nothing was rebuilt.", "",
"| | Before | Now |", "|---|---|---|"]
lines += [f"| {k} | {was.get(k, '-')} | {v} |" for k, v in now.items()]
if deliver_to:
lines += ["", f"Delivered to `{deliver(deliver_to)}`."]
path("exports/last-cycle.md").write_text("\n".join(lines) + "\n", encoding="utf-8")
print("\n" + "\n".join(lines))
return rc