machine #

A Pi extension for parametric learning.

Tag the last turn as a good or bad example, reconstruct the full user → tool-call → result → answer trajectory, and run Tinker SFT.

Install #

Pi #

Install Machine from Tangled:

pi install git:tangled.org/cameron.stream/machine

To use a local checkout instead, run this command from the repository root:

pi install .

Start Pi after installation. If Pi is already running, run /reload.

Machine now includes the Tinker provider and /tinker commands. Uninstall pi-tinker if it is still listed in Pi packages, or /tinker will be registered twice.

Python 3.11+ is required for Tinker/Inkling. From this repo:

uv venv --python 3.12 .venv
uv pip install -p .venv/bin/python -U tinker-cookbook tml-renderers

/train uses .venv/bin/python from the machine package or the current project if it exists.

Commands #

/good
/good --as "The exact answer you want the model to learn."
/machine auto on
/machine data
/machine student
/machine work
/correction too terse
/corrections
/tagged

Command	Writes	What is saved
/good	Machine store traces.jsonl	Last-turn trajectory, tag: "good"; links a pending correction when present
/correction	same file + corrections.jsonl	Rejected turn (tag: "bad"); proposes trainable reasoning, then optional reasoning-first teacher retry
/corrections	—	Lists or shows correction/contribution evidence for this project
/tagged	—	Lists recent pool rows
/machine auto	same file	Unlabeled compact/headless spans, tag: "observed" (off by default)
/machine data	—	Shows this project's store, pool counts, and auto-capture setting

One pool. Every row is a Tinker chat trace (messages, including tool calls and results). Tags distinguish judgment; they do not split files.

Options:

Option	Meaning
leftover args / --note	Why this turn was tagged
--as	Override the final assistant text
--reasoning	Override proposed trainable reasoning (headless /correction)
--out	Write somewhere else

Train by expanding each conversation into one full-prefix row per assistant turn and training with TrainOnWhat.LAST_ASSISTANT_MESSAGE. Tool results stay in context for later targets and are not themselves the loss target. This matches Tinker Cookbook guidance for renderers without the sequence-extension property (including Qwen) and is used for every model, including Inkling. When a test split is configured, the holdout counts source conversations; all expanded targets from one source stay on the same side.

Data storage #

Machine keeps captured conversations outside the working tree. Each project gets a directory named from the project and a hash of its absolute path:

Platform	Default base directory
All	~/.machine

Run /machine data to see the exact directory. Set MACHINE_DATA_DIR to override the base; Machine still creates a separate subdirectory for each project. On POSIX systems, Machine creates directories with mode 0700 and files with mode 0600.

Each project store has one pool: traces.jsonl. Automatic capture is off until you run /machine auto on. The setting persists per project. Automatic rows use tag: "observed" in that same file; finishing a run or reaching compaction does not mark the behavior good. Only /good creates positive training examples. Corrections also write a ledger at corrections.jsonl (diagnosis, proposed and approved reasoning, provenance). Observed Pi reasoning is never saved; /good injects explicitly approved reasoning as a structured ThinkingPart when a correction is pending. Full trajectories can contain tool output, source text, and other private material, so inspect them before training or copying them elsewhere.

Older split files (train.jsonl, rejected.jsonl, observed.jsonl) and pre-0.2.0 project-local data/ directories are not selected or migrated. Review them, then pass a path explicitly or copy the rows you want into the pool.

Training #

/train validate
/train sft --force
/train run --steps 2 --yes
/train eval init --force
/train eval baseline --yes

Without a path, /train validate and /train sft use good rows from this project's traces.jsonl. Pass another path only when you intend to train from a different reviewed dataset. /train sft writes train_sft.py and tinker.yaml into the Machine store, pointed at the pool. /train run --yes runs that script (a real Tinker job). --steps 2 is a short run. Default model for /train and /machine student is thinkingmachines/Inkling-Small.

Behavior releases #

Machine treats checkpoint activation as a release decision rather than a training side effect. BR-001 preregisters the first project-local candidate: reliable Pi file repair with fixed training bounds, frozen regression gates, external holdouts, and an explicit trial before default-student eligibility.

Examples #

• examples/minimal-sft/ — the product loop: a self-authored corpus, /train validate → sft → run → eval, and a measured baseline-vs-checkpoint delta on a strict answer style.
• examples/project-euler/ — research harness: sequential multilingual Project Euler agents with Docker-confined Pi evaluation, transfer tasks, tool RL, and receipts. Not the default Machine workflow.

Example corpora, answer keys, rollouts, and checkpoints are not bundled. Each example documents its own provenance, license, setup, metrics, and limitations.

Files #

extensions/machine.ts   Pi: /good, /correction, /corrections, /tagged, /machine
extensions/train.ts     Pi: /train validate, sft, run, eval
extensions/tinker.ts    Pi: Tinker provider + /tinker use (load checkpoints)
lib/cli.ts              shared arg parsing and JSONL helpers
lib/correction.ts       correction ledger and interpretation wiring
lib/reasoning-machine.ts reasoning-contributor contracts and hygiene gates
lib/thinking-renderer.ts  training-time structured-thinking renderer validation
lib/report.ts           Pi report rendering
lib/storage.ts          private per-project data paths and settings
lib/statusline.ts       Pi footer: last-turn nudge and dataset counts
lib/tinker-catalog.ts   shared Tinker chat catalog (Inkling, Qwen, checkpoints)
lib/trajectory.ts       Pi session → trajectory reconstruction
lib/python.ts           platform-specific virtual-environment lookup
skills/                 Tinker research and debug skills
templates/              generated Python
docs/commands.md        Command reference
docs/tinker/            /tinker command and coding-agent docs
CHANGELOG.md            release notes

Letta Code integration lives on the letta-code branch while host issues are addressed. main is Pi-only.