- planner/knowledge.yaml: what the game's developer has said (paraphrased, dated, graded), what the Atlas does with each statement, and the open questions with the experiment that tests each. - analysis/black/evidence.py -> analysis/reports/BLACK.md: counts from the runs. On the same recorded route the shadow shows on 21 of 79 first attempts and 1 of 80 later ones; no single route; Blue then Black after the shadow. - game.yaml: the shadow is a guard (not a roll); what follows it is the Blue, then the Black; on-screen text for the squad's direction screen. - planner/experiments.yaml v2: one exact path on every fresh account (fresh-replicate), then one choice changed at a time (fresh-ablate); shadow-again, second-attempt-same-path, veteran-repeat, veteran-variety; what the bot records about the account; the sequence to follow once the shadow shows. - solver.js: assign() takes account facts, account offsets and cycled arms; recommendOption() answers the squad screen (stay + direction) in one pick. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_014jqCC2LZ4x1WHQ1V57nTsv
267 lines
16 KiB
Markdown
267 lines
16 KiB
Markdown
# Connecting the DragonKind bot to the atlas
|
||
|
||
Data flows both ways:
|
||
|
||
```
|
||
community sources, reports ─────┐
|
||
├─► threshing-atlas ──► policy.json + solver.js ──► bot (advice per screen)
|
||
bot runs (anonymised) ──────────┘ ▲ │
|
||
└──────────── collection --source bot + PR ◄┘
|
||
```
|
||
|
||
## The automated cycle
|
||
|
||
One command closes the loop, and it is meant to run on a timer on the machine that has the bot's folder:
|
||
|
||
```
|
||
python -m collection cycle --bot /path/to/DragonKind --deliver /path/to/DragonKind/vendor/threshing-atlas
|
||
```
|
||
|
||
1. **Ingest.** It imports the bot's new runs (anonymised: no prose, no account names; set `DK_ACCOUNT_SALT`, the
|
||
same value every time, so an account keeps its hash).
|
||
2. **Refit.** When there are new runs it rebuilds the coded runs, the route model (`policy.json`) and
|
||
3. **Re-plan:** the experiment plan (`experiments.json`): progress per arm, and which experiments are still
|
||
running (`planner/experiments.yaml` is the design).
|
||
4. **Deliver.** It copies `policy.json`, `experiments.json`, `solver.js` and `graph.js` into the `--deliver` folder,
|
||
each file whole, then writes `atlas-kit.json` (`policyId`, `planId`, checksums) last. The bot should load the
|
||
kit at the start of an attempt, never in the middle of one, and log both ids on the run.
|
||
|
||
With no new runs it only delivers, so running it every hour costs nothing. `exports/last-cycle.md` says what
|
||
changed (ids, headline odds, experiment progress). `--community` also checks the community sources first.
|
||
On Gitea, `.gitea/workflows/bot-cycle.yml` runs the same command on a runner that can see the bot's folder and
|
||
opens the pull request with the new data.
|
||
|
||
### What each attempt is for: the plan
|
||
|
||
```js
|
||
const plan = require('../vendor/threshing-atlas/experiments.json');
|
||
// accountSeq: the account's number in the order accounts were made (0, 1, 2, ...), fixed for its life
|
||
// attempt: the account's attempt number (1 = its first threshing)
|
||
const a = Solver.assign(plan, { accountSeq, attempt, facts: { sawShadowBefore } });
|
||
// -> { experimentId, arm, fix, target, objective, sampling, seed, propensity, burn, planId } (null: no experiment)
|
||
const advisor = Solver.advisor(policy.samples.all, a.target, a.objective,
|
||
{ attempt, fix: a.fix, sampling: a.sampling, seed: a.seed });
|
||
```
|
||
|
||
- **`attempt` matters.** The shadow is close to a first-attempt event, so `advisor(..., { attempt: 1 })` uses the
|
||
first attempt's odds. Without `attempt` a later attempt is assumed. **Attempt 1 must be played by the bot and
|
||
logged** (today the bot's records start at attempt 2).
|
||
- **`fix`** holds some decisions to the arm's options; the advisor plays its best around them.
|
||
- **`sampling: "uniform"`** (the mapping experiment): `recommendOption()` picks one of the options on the screen
|
||
at random and returns its propensity.
|
||
- Log on the run: `experimentId`, `arm`, `planId: plan.id`, `policyId: policy.id`, `accountAttempt`, and the
|
||
propensity. On the steps an arm fixes, the propensity is `a.propensity`.
|
||
- `burn` names the deliberate-burn rule the experiment expects (`TREE_NO_SHADOW_AUTO_BURN`,
|
||
`MEADOW_NO_BLUE_AUTO_BURN`). A genuine Black or Blue bond is always accepted.
|
||
- The account's life (`plan.lifecycle`): attempt 1 is the Black attempt; then about three days of research
|
||
attempts; then the account retires, except two in ten, which keep going (one repeating a path, one varying it).
|
||
- `plan.record` lists what to log about the account on every run; `plan.scripts.shadow` is the sequence to follow
|
||
once the shadow shows (`docs/BOT_CYCLE_FOR_KEN.md`).
|
||
- With squadmates, staying together and the direction are one screen; `recommendOption()` answers both at once
|
||
and says so in `also`.
|
||
|
||
An experiment that reaches its planned count becomes `complete`, one that meets its stopping rule becomes `paused`;
|
||
either way `assign()` stops giving it out and its share goes to the others. Nothing in the bot changes.
|
||
|
||
## From the Atlas's Gitea repository
|
||
|
||
Both repositories live on git.kenschiano.net. The bot can read the atlas files straight from the repository with a
|
||
Gitea token that can read it (the repository is "limited": signed-in users only), instead of a zip:
|
||
|
||
```
|
||
https://git.kenschiano.net/<owner>/threshing-atlas/raw/branch/main/data/public/policy.json
|
||
https://git.kenschiano.net/<owner>/threshing-atlas/raw/branch/main/core/solver.js
|
||
https://git.kenschiano.net/<owner>/threshing-atlas/raw/branch/main/core/graph.js
|
||
```
|
||
|
||
(header `Authorization: token <token>`), plus `data/public/experiments.json`. Keep the files together: solver.js
|
||
reads the game from policy.json.
|
||
|
||
## Without a shared repository: swapping zips
|
||
|
||
When GitHub Pages is not available, the same files travel as zips:
|
||
|
||
- **Atlas → bot:** `python -m collection export-bot-kit` writes `exports/atlas-for-bot-<date>-<policy id>.zip`
|
||
(`policy.json`, `solver.js`, `graph.js`, a README with checksums). Unzip it into the bot's `vendor/threshing-atlas/`.
|
||
- **Bot → atlas:** zip the bot's `data/` and `logs/` folders (folder names kept; a zip of the whole repo works too;
|
||
screenshots are not needed) and send it. The importer reads `data/knowledge.json` and, for every account,
|
||
`data/accounts/<account>/runs.jsonl` and `logs/accounts/<account>/encounters.jsonl` (with one folder per
|
||
account, the top-level `data/runs.jsonl` and `logs/encounters.jsonl` mirror the first account and are skipped).
|
||
Run records that carry their own steps (the bot's schema 2) are used as they are, including what the bot saw
|
||
(shadow, meadow dragons), its decision mode and the policy id; older runs are rebuilt from the decision log.
|
||
Account names become salted hashes. Put it in the atlas's `inbox/` and run
|
||
`python -m collection refresh --bot inbox/<the zip>`: it imports the runs (anonymised: no prose, no account names),
|
||
rebuilds everything, and then `export-bot-kit` makes the new zip to send back.
|
||
|
||
## 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.
|
||
|
||
### Learning: goal accounts follow the best route, research accounts sample
|
||
|
||
The atlas learns from the bot's own runs: every zip of the bot's data that is imported adds its rolls (first dragon,
|
||
deaths, the shadow, the meadow dragon, bond results) to the route model, and the next `atlas-for-bot` zip carries
|
||
the updated model. Deliberate burns (Malek, "no shadow", "no Blue") never count as failed bond attempts.
|
||
|
||
How the bot should choose depends on the account's role:
|
||
|
||
- **Goal accounts** (`accountRole: "goal"`): the best route under the model, as before:
|
||
`Solver.advisor(policy.samples.all, target, 'eventually')`.
|
||
- **Research accounts** (`accountRole: "research"`): Thompson sampling. Make a new advisor for every attempt with a
|
||
new seed:
|
||
|
||
```js
|
||
const adv = Solver.advisor(policy.samples.all, target, 'eventually', { sampling: 'thompson', seed: attemptNumber });
|
||
```
|
||
|
||
Each attempt follows the best route of one plausible version of the odds, drawn from the model's uncertainty. An
|
||
option that might be the best one gets tried about as often as it is likely to be the best, so the attempts go
|
||
where the model is least sure; as the data firm up, sampling settles on the best route by itself.
|
||
`recommendOption()` then returns a `propensity` (the chance this option was picked, from 40 other draws; set
|
||
`draws` to change that). Log it on the step with `decisionMode: "atlas_thompson"`, so the runs can be re-weighted.
|
||
Making the advisor takes a few seconds per attempt (it solves the game once per draw).
|
||
|
||
The tie rule below still works for goal accounts; research accounts don't need it.
|
||
|
||
### Ties are free experiments
|
||
|
||
### 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 (November 2026): Black about 1.4% on an account's first attempt (95% range 0.7–2.2%; 0.8% in the
|
||
low-bias sample) and about 0.07% on any later attempt; Blue about 1.9–2.5% per attempt (40–55 attempts), depending
|
||
on the sample. The first-attempt figure rests on form submissions and an assumed reporting bias (see below): the
|
||
bot and bulk logs have only 28 first attempts at the tree, and no shadow in about 570 tree runs in all.
|
||
|
||
The shadow is gated: it can only appear on runs that investigated the scream and helped the squadmate (the
|
||
"Black Dragon Gates" of the community route PDF, and the runs agree). The model knows this
|
||
(`core/spec/game.yaml`, `requires`), so it never sends a Black attempt off the gate.
|
||
|
||
Form submissions over-report rare sightings: riders report a meadow Blue about 4 times more readily than a meadow
|
||
without one. The model estimates that bias for each kind of source and corrects for it (`planner/policy.yaml`,
|
||
`reporting_bias`; the estimates are in `policy.json` under `model.reportingBias`). For the shadow the bias cannot be
|
||
measured (complete logs have never seen one), so it is assumed equal to the meadow Blue's (`borrow`).
|
||
|
||
## 2. From the bot to the atlas
|
||
|
||
Already in place: `DRAGONKIND_BOT_DIR=/path/to/DragonKind python -m collection update --source bot` 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 the crosswalk in `collection/specs/bot.yaml` (written into `graph.js` by `python -m collection build`) need updating.
|