Files
ekcSchianoandClaude Fable 5.2 f8e4f575f4
CI / test (pull_request) Canceled after 0s
Screen tree, register rows in the master list, and bot runs coded from the picks that were played
- analysis/tree/build_tree.py -> data/public/tree.json, analysis/reports/TREE.md: every screen the bot has seen,
  every option, where each led (fixed or dice, with ranges), best known picks per colour chosen cautiously, where
  any picks end, and the untested options. solver.js screenPick(): least-tried and Thompson picks from the tree.
- The bot logs a pick it then overrode as a step: 37 runs were coded with choices they never made. Importer and
  graph.js now use the played steps only.
- runs_clean.csv: the Unofficial Dragon Register's 288 bonded dragons are in the master list as outcome-only
  rows, flagged (no analysis uses them).
- Cycle, refresh and the bot kit rebuild and carry the tree; tests check every generated report is current.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014jqCC2LZ4x1WHQ1V57nTsv
2026-11-16 15:50:12 +00:00

269 lines
16 KiB
Markdown
Raw Permalink 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 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`, `tree.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`).
- `tree.json` is the screen tree (every screen, every option, where each led). `plan.screenPicks` says where the
bot picks from it with `Solver.screenPick(tree, sceneId, offeredTexts, { mode, seed })`.
- 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.