Files
threshing-atlas/docs/BOT_INTEGRATION.md
T
ekcSchianoandClaude Opus 5.5 d2ffb84b5e Solver: best decisions per dragon colour, and the bot advisor
- packages/core/src/solver.js: decision tree with perfect recall over the
  community form's choices; chance events (first dragon, deaths, shadow,
  meadow dragon, encounter outcome) depend on earlier choices through
  hierarchical Dirichlet back-off with empirical-Bayes concentration per
  event; backward induction for P(colour this attempt) and Dinkelbach for
  P(colour) / (P(colour) + P(other colour)); 200 posterior draws for
  credible intervals and "still best" rates; cross-fitted held-out check.
- Only genuine attempts inform encounter outcomes (goal / Malek intent).
- data/public/policy.json (all runs and a low-bias sample) and the readable
  docs/POLICY.md; published on Pages with solver.js for the bot.
- Bot advisor: re-solves from any history, maps advice onto screen text,
  reports margins so ties can be randomised. docs/BOT_INTEGRATION.md.
- Tests on a synthetic world with known answers; daily source update now
  rebuilds the policy.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UCzTd31GphpMXDhQqWrCMQ
2026-11-01 22:34:38 +00:00

134 lines
6.9 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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.
### 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 `docs/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.