- 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
134 lines
6.9 KiB
Markdown
134 lines
6.9 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.
|
||
|
||
### 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.
|