do.llth.ing / tokenling
a tiny pet with a GPT-2 brain, living in your browser
Star
Fork 1
Watch
tokenling docs extending.md
6.5 kB
Markdown
at main

Extending tokenling #

Anything the model must say or understand is a retraining event: the weights only know what was in the data. Anything purely visual or in the simulation is not. Each recipe says which it is.

After any change that touches world.py/world.ts, run node test/parity.mjs.

Retrain loop #

  1. Update train/world.py and web/world.ts together.
  2. Update the teacher prompt in train/gen_data.py (it builds word lists from world.py, but scenarios and examples are written out) and the validator so it accepts exactly the new grammar.
  3. Probe: gen_data.py probe.jsonl 6 2, read the rows, fix prompt or checks.
  4. Generate the full set (free the GPUs first, see deployment.md), train, run eval_pet.py, export, publish as a new model id, update site/release.json and deploy.

Add an emote #

Model-facing:

  • EMOTES in train/world.py and web/world.ts.

App-facing:

  • FACE in web/scene.ts (eyes, mouth) and any motion branch in drawPet;
  • an entry in ACT_WORD in web/app/text.ts and, if it has a floating icon, applyTags() in web/app/conversation.ts.

Retrain so the model produces it. A new word the model has not seen will not appear. (For a quick visual-only animation, add it to FACE/drawPet and trigger it from a care action with animate(); no retraining.)

Add a tool #

An action tool (like [gift] or [walk:left]): add the name to EFFECT_TOOLS in both world files (and a value list such as WALKS, which test/parity.mjs compares), validate its arguments in check_chat(), handle it in applyTags(), show a chip or an action word in chipsFor() / ACT_WORD, describe it in the teacher prompt, then retrain. Prefer a tag for anything the pet decides; the app should only carry out the decision.

A new offer (something the owner proposes and the pet accepts or refuses): add the event line to event_patterns() and offer_patterns() in world.py, the builder to events in world.ts, a branch in offer() / answerOffer() in web/app/care.ts, a NO_POOL entry and scenarios in gen_data.py, and a case in the parity test's event list. Then retrain.

A lookup tool (like [clock]): in addition to the above, add it to LOOKUP_TOOLS and tool_result() / toolResult() with identical logic in both languages, and update the three stop regexes: LOOKUP_END in web/brain.ts and train/eval_pet.py, and LOOKUP_TAIL in web/app/conversation.ts. Mention it in the static part of the teacher prompt and add scenarios that call it. Results must be deterministic functions of the prompt state, because the validator replaces whatever the teacher wrote.

Add a dream #

Add the value to DREAMS in both world files and provide its sprite. Foods and gifts are included automatically. dream_thing/dreamThing supplies the day-log and chip label. Update sleep teacher coverage and validation, retrain, and ship a new model. Preserve the closed sleeping grammar and bounded dream log. Body-only wake tuning uses wake_chance/wakeChance; parity covers it.

Add or change a food, gift or want #

  • Lists: FOODS, GIFTS or WANTS in both world files.
  • Art: add a sprite to SPRITES in web/sprites.ts (rows of 8 characters, see KEY for the palette) and, for wants, WANT_ICON in web/app/config.ts.
  • Behavior: feeding effects are in answerOffer() in web/app/care.ts.
  • Foods and gifts appear in prompts, so this is a retraining event. A food that exists in the app but not in the training data confuses the model.

Add a life stage or change timing #

  • Names: STAGES in both world files; voice text in STAGE_STYLE in gen_data.py; sampling weights in rand_state().
  • App: STAGE_AGE in web/app/config.ts, a SIZE entry and decorations in scene.ts.
  • The prompt only contains the stage name and day number, so changing ages alone is not a retraining event, but new stage names are.

Change the simulation #

Rates, poop timing, sleep rules and minigame tuning are constants in web/app/body.ts (rates(), simulateBody()) and web/app/game.ts (stepGame()). Keep them in sync with pet-simulation.md. If you change the stat words or thresholds (levelWords), it is a retraining event: the model learned those exact words.

Change the look of the page #

The host page is site/index.html (styles inline, tokens on :root, light and dark). Interactive markup and event handlers are Preact components in web/components/; body and model behavior stay in web/app/. Pixel art lives inside the LCD canvas and the sprite icons. Keep focus rings, the 360 px layout, reduced motion and the no-JavaScript notes working, and run node test/contract.mjs if you rename or remove an element.

Add a stored field #

Add it to fresh(). A new top-level key is filled for older saves by the ...fresh() spread, and a new setting whose absence means "off" needs nothing. Nested changes or renames need VERSION bumped and a step appended to MIGRATIONS in web/app/save-format.ts (it receives the previous version's object and must return one with v one higher). Never make load() accept a newer version: it shows the bad egg instead, and the save stays untouched. Test with an old save (export one before the change) and document it in pet-simulation.md.

Ship a feature only newer brains have #

When a feature needs training (a new tool, offer or event line the old brains never saw), the app must not use it with an older brain the visitor kept. Name the feature, list it under features in site/release.json (and in each older entry that has it), describe it in FEATURE_TEXT in web/app/config.ts for the upgrade dialog, and gate it: brainHas("name") for component disabled/class/title props, data-needs="name" for inspection, ACT_NEEDS for care actions, and brainHas("name") around any other code path that writes the new lines. A change to the prompt format itself cannot be gated this way: empty older instead (deployment.md).

Change the base model #

v1 used GPT-2 Medium; v2 and later use GPT-2 small on purpose (a smaller, sillier pet and a 97 MB download). A different size or tokenizer affects fit()'s context budget, the ][ handling, quantize.py (the embedding name and head layout in embedding_int8(), the head count in check_onnx.py and quant_eval.py comes from the config), and every size on the page. Re-run quant_eval.py, bench.html and the full browser flow.