Step 4b of the Python-first core. - core/solver.js is now a 250-line advisor (was 900 lines): it reads the game (core/spec/game.yaml, published inside policy.json as model.game) and the count tables, and re-solves from any point in a run with the same interpreter as the Python model. Same API for the site and Ken's bot (advisor, recommendOption, solverHistory). The bot's on-screen text for each option moves to game.yaml (bot_text); the deadly rolls carry their risk labels there too. - tests/core/advisor.test.js: the advisor gives exactly the Python model's values and choices for every colour and goal (to 1e-12, every decision on every published route), walks a run in the game's order, and maps advice onto the bot's screen. - Removed core/engine.js and everything that only compared it with Python (tests/parity/run_engine, compare_runs, compare_results, compare_routes, compare_solver, compare_stats, analysis/stats/ analyze.py). In their place: tests/core/test_stats.py checks the statistics against known answers, test_solver.py checks the route model on a synthetic world (tests/fixtures/synthetic_policy.py). - analysis/network/build-graph.js reads the Python-coded runs; graph.json is byte-identical. - docs/BOT_INTEGRATION.md: what changed for the bot (history keys, new choices, re-sync all three files). Claude-Session: https://claude.ai/code/session_01UCzTd31GphpMXDhQqWrCMQ Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
151 lines
8.1 KiB
Markdown
151 lines
8.1 KiB
Markdown
# Connecting the DragonKind bot to the atlas
|
||
|
||
Data flows both ways:
|
||
|
||
```
|
||
community form, register, PDF ──┐
|
||
├─► threshing-atlas ──► policy.json + solver.js ──► bot (advice per screen)
|
||
bot runs (anonymised) ──────────┘ ▲ │
|
||
└──────────── import-bot + pull request ◄──┘
|
||
```
|
||
|
||
## 1. From the atlas to the bot
|
||
|
||
### What is published
|
||
|
||
GitHub Pages serves these files (they update whenever new data is merged):
|
||
|
||
| File | What it is |
|
||
|---|---|
|
||
| `https://ekcschiano.github.io/threshing-atlas/data/policy.json` | The model: count tables, fitted shrinkage, allowed options, and for every colour the recommended decision tree under both objectives, with credible intervals. About 400 KB. Has an `id` (content hash). |
|
||
| `https://ekcschiano.github.io/threshing-atlas/solver.js` | The solver and the bot helper (`advisor`, `recommendOption`, `solverHistory`). No dependencies, CommonJS or browser. |
|
||
| `https://ekcschiano.github.io/threshing-atlas/graph.js` | `trajectoryVariables()`: turns the bot's step trail into the community form's variables. |
|
||
|
||
### Getting them into the bot
|
||
|
||
Keep a pinned local copy, so a bad publish can never change the bot mid-run. A small sync script in the bot
|
||
repo (for example `scripts/sync-atlas.js`):
|
||
|
||
```js
|
||
// node scripts/sync-atlas.js -> vendor/threshing-atlas/{solver.js,graph.js,policy.json}
|
||
const fs = require('node:fs');
|
||
const path = require('node:path');
|
||
const BASE = 'https://ekcschiano.github.io/threshing-atlas/';
|
||
const OUT = path.join(__dirname, '..', 'vendor', 'threshing-atlas');
|
||
(async () => {
|
||
fs.mkdirSync(OUT, { recursive: true });
|
||
for (const f of ['solver.js', 'graph.js', 'data/policy.json']) {
|
||
const res = await fetch(BASE + f);
|
||
if (!res.ok) throw new Error(`${f}: HTTP ${res.status}`);
|
||
const body = await res.text();
|
||
if (f.endsWith('.json')) JSON.parse(body); // refuse a broken file
|
||
fs.writeFileSync(path.join(OUT, path.basename(f)), body);
|
||
}
|
||
const { id } = JSON.parse(fs.readFileSync(path.join(OUT, 'policy.json'), 'utf8'));
|
||
console.log('atlas policy', id);
|
||
})();
|
||
```
|
||
|
||
Run it by hand, or once a day before the first attempt. Commit `vendor/threshing-atlas/` in the bot repo if you
|
||
want the exact policy in its history.
|
||
|
||
### What changed in November 2026
|
||
|
||
The calls above are unchanged, but `solver.js` is now a small advisor (about 250 lines) that reads the game itself
|
||
from `policy.json` (`samples.*.model.game`, from `core/spec/game.yaml`) instead of having it written into the code.
|
||
For the bot that means:
|
||
|
||
- Histories (`h`) use the game's step names: `company`, `leave`, `direction`, `fs`, `react`, `scream`, `clearing`,
|
||
`fight`, `dagger`, `fate` or `wounded`, `post`, `hour`, `shadow`, `shadowColour`, `descend`, `red`, `valley`,
|
||
`meadow`, `encounter`. `solverHistory()` already produces these; the old `cadet` and `left` keys are no longer read.
|
||
- New choices the bot will be asked about: leaving your squadmates (`leave`), how you react to the first dragon
|
||
(`react`), and, below the tree, jumping onto the Red or letting it pass (`red`). The text the bot sees for each
|
||
option is in `game.yaml` under `bot_text`, so new screens can be matched by editing that file.
|
||
- If a history skips a decision but already has a later step (an older record, say), the recommended option is
|
||
assumed for the skipped one.
|
||
- Re-sync `solver.js`, `graph.js` and `policy.json` together: the new `solver.js` needs the game inside the new
|
||
`policy.json`.
|
||
|
||
### Asking for advice on a screen
|
||
|
||
```js
|
||
const Solver = require('../vendor/threshing-atlas/solver.js');
|
||
const Graph = require('../vendor/threshing-atlas/graph.js');
|
||
const policy = require('../vendor/threshing-atlas/policy.json');
|
||
|
||
// once per attempt: target colour from settings, "eventually" because the bot burns on purpose
|
||
const advisor = Solver.advisor(policy.samples.all, 'Black', 'eventually');
|
||
|
||
// on every decision screen
|
||
function atlasAdvice(run, offeredChoiceTexts, seen) {
|
||
const { vars } = Graph.trajectoryVariables({ steps: run.steps, outcome: {} });
|
||
const h = Solver.solverHistory(vars, seen); // seen: { shadow: 'yes'|'no', shadowColour, meadow }
|
||
return Solver.recommendOption(advisor, h, offeredChoiceTexts);
|
||
}
|
||
```
|
||
|
||
`recommendOption` returns `null` when the next step is chance (nothing to decide), or
|
||
`{ index, decision, choice, margin, options, reason }`:
|
||
|
||
- `index` is the option to click, or `null` when the advice cannot be matched to this screen. Then use the bot's own rules.
|
||
- `decision === 'encounter'` comes without an index: `choice` is `"Attempt the bond"` or `"Die on purpose"`, and the
|
||
bot already knows which of its options do each.
|
||
- `margin` is the gap in P(target) between the best and second-best option. `options` has every option's value.
|
||
|
||
`seen` is what only the bot can observe: whether the shadow was at the treetop (`shadow: 'yes' | 'no'`), its colour
|
||
(`shadowColour`), and the colour waiting in the meadow (`meadow`), all from the scene tint.
|
||
|
||
The advisor re-solves the model on the bot's machine (a few milliseconds), so it gives advice from any history,
|
||
including runs that have already left the recommended route.
|
||
|
||
### Where it goes in the decision order
|
||
|
||
The atlas is advice. The bot's own safety rules stay in charge:
|
||
|
||
1. Account Lock Guard and the intentional-burn protection (never risk a non-target bond).
|
||
2. Atlas advice, when `index` is not null and the margin is clear (see ties below).
|
||
3. The bot's PDF strategy and learned rules.
|
||
|
||
Log every atlas pick with `rule: 'ATLAS_POLICY'`, `source: 'atlas'`, and the run-level `policyId: policy.id`
|
||
(see `docs/BOT_DATA_PROTOCOL.md`), so we can tell which policy produced which runs.
|
||
|
||
### Ties are free experiments
|
||
|
||
Many choices barely matter by the data we have (for Black, the first direction differs by a tenth of a percentage
|
||
point). When `margin` is below the tie threshold (start with 0.002, i.e. 0.2 percentage points), pick at random
|
||
among the tied options and log `propensity` (1 / number of tied options). That costs nothing in expected success,
|
||
and it is exactly the randomised data the atlas needs to tell real history effects from guide-copying.
|
||
|
||
### Which numbers to trust
|
||
|
||
`policy.json` has two samples:
|
||
|
||
- `samples.all`: every run. Use it for the advisor (more data, decisions are about relative differences).
|
||
- `samples.lowBias`: bulk logs and riders not chasing a rare dragon. Use it for absolute expectations, such as how
|
||
many attempts a Blue should take. Rare sightings are over-reported in form posts, so `all` is optimistic for Blue.
|
||
|
||
Current headline (from `analysis/reports/POLICY.md`): Black about 1.7% per attempt (about 60 attempts), Blue 3.7–7% per attempt
|
||
(14–28 attempts), depending on the sample.
|
||
|
||
## 2. From the bot to the atlas
|
||
|
||
Already in place: `npm run import-bot -- --bot /path/to/DragonKind` in the atlas repo converts the bot's
|
||
`knowledge.json`, `runs.jsonl` and `logs/encounters.jsonl` into anonymised files under `data/bot/`, and refuses to
|
||
write prose or account names. Commit them by pull request; CI rebuilds the graph and checks everything.
|
||
|
||
What would make the bot's data far more useful (details in `docs/BOT_DATA_PROTOCOL.md`):
|
||
|
||
- record the options on screen, what was seen (tint, shadow), `policyId`, `propensity` and `decisionMode` on every step;
|
||
- split goal accounts (follow the advisor) from research accounts (run the tie experiments and the
|
||
experiment list);
|
||
- add `accountKey` (salted hash), and the reason for every deliberate burn.
|
||
|
||
## 3. Limits to keep in mind
|
||
|
||
- The community form does not record the answers inside each bonding encounter, so the bond chance at an encounter is
|
||
the community average. The bot's own scene-level data will refine that over time.
|
||
- The model learns how much history matters from the data. Today it finds that the meadow colour does not depend on
|
||
earlier choices at all, and the shadow only weakly. The bot's randomised runs are what can confirm or overturn that.
|
||
- The policy is only as good as the crosswalk between the bot's screen text and the form's variables. If the game
|
||
changes its wording, `OPTION_PATTERNS` in `solver.js` and `CROSSWALK` in `graph.js` need updating.
|