@matchbox-ai/train 0.1.0 → 0.2.1

package/docs/cli.md

@@ -1,54 +1,111 @@
-# CLI
+# CLI reference
 
-Run Matchbox inside an existing React, Next.js, or other JavaScript application. Your application keeps its own dev server and framework configuration. The command is provided by the matchbox-ai development dependency. Pipeline authoring and training APIs remain in @matchbox-ai/train. The CLI uses Commander for commands and Ink for interactive setup and status.
+Install through `bunx matchbox-ai init` or run the installed `matchbox-ai` binary. Bun 1.4.2+ and Node.js 24+ are required for training.
 
-## Add a task
+## Commands
+
+| Command               | Purpose                                                 |
+| --------------------- | ------------------------------------------------------- |
+| [`init`](#init)       | Add a task to an existing app and install dependencies. |
+| [`dev`](#dev)         | Open the local browser workbench.                       |
+| [`train`](#train)     | Train, validate, and package.                           |
+| [`eval`](#eval)       | Evaluate the saved model against the test split.        |
+| [`parse`](#parse)     | Return a prediction.                                    |
+| [`inspect`](#inspect) | Show model recognition and the final result.            |
+| [`info`](#info)       | Show resolved paths and strategy.                       |
+| [`save`](#save)       | Add or replace a training example.                      |
+
+## Common options
+
+`-h, --help` works on every command. `-v, --version` prints the package version from the root command.
+
+Every command except `init` accepts `[task]`, a task name, directory, or config path, and `-c, --config <path>` as an alternative. Do not combine a task argument with `--config`. Omitting the task works when discovery finds exactly one; interactive `dev` also offers a task picker.
+
+Every command except `dev` accepts `--json`. JSON goes to stdout; diagnostics and installer output go to stderr. Bare `matchbox-ai` lists tasks and next actions without creating files.
+
+## init
 
 ```sh
-matchbox-ai init
-matchbox-ai init money --template money
-matchbox-ai init intent --template blank
+bunx matchbox-ai init [name] --template money
+bunx matchbox-ai init intent --template blank --directory ./my-app
 ```
 
-Interactive setup offers the money example or a blank task. In scripts, specify `--template`. `--directory <path>` selects an existing application directory containing package.json. Matchbox preserves existing scripts, adds `matchbox:dev`, `matchbox:train`, and `matchbox:eval` if absent, and ignores `.matchbox/`. It refuses to replace an existing task directory. It installs dependencies automatically using the app’s package-manager declaration or lockfile, including workspace ancestors. With neither, it uses the invoking package manager, then Bun as a fallback. Use `--skip-install` to handle installation yourself. Installer logs go to stderr so `--json` stays machine-readable. If installation fails, the scaffold remains and the CLI prints the command to retry.
+| Option               | Default                                              | Behavior                                                       |
+| -------------------- | ---------------------------------------------------- | -------------------------------------------------------------- |
+| `[name]`             | `money` for the money template; `my-task` for blank. | Names the task directory. Pass a name to override the default. |
+| `--template <name>`  | Interactive choice.                                  | `money` or `blank`; specify in scripts.                        |
+| `--directory <path>` | Current directory.                                   | Existing application with a `package.json`.                    |
+| `--skip-install`     | False.                                               | Write files without installing dependencies.                   |
+| `--json`             | False.                                               | Print scaffold results as JSON.                                |
 
-Package-manager build-script policies still apply. With pnpm, run `pnpm approve-builds` and select `@tensorflow/tfjs-node` before training.
+Adds `matchbox/<name>/`, ignores `.matchbox/`, and adds missing `matchbox:dev`, `matchbox:train`, and `matchbox:eval` scripts. Existing task directories are never overwritten. Framework config stays unchanged.
 
-The money template has an explicit token model, supervision, and decoder. The blank template has an editable label schema, an explicit word-feature classifier, and empty datasets. Write examples and independent evals before training it. Names do not select learning strategies.
+Installs core as an application dependency and train/CLI as development dependencies. Package-manager selection uses the app declaration or lockfile (including workspace ancestors), then the invoking package manager, then Bun. Failed installation preserves the scaffold and prints a retry command.
 
-## Open the workbench
+The blank template requires examples and evals before training. The money template includes token supervision and an application-owned decoder. No time template ships in 0.1.0; the time example is available in the repository.
+
+## dev
 
 ```sh
-matchbox-ai dev money
-matchbox-ai dev money --port 4191 --no-open
+bunx matchbox-ai dev [task] --port 4190 --no-open
 ```
 
-The browser workbench runs on loopback, alongside your app. Try inputs, inspect recognition, save explicit corrections, train, evaluate, and measure browser inference. Source changes mark the model as stale. Training remains an explicit action. A successful training run reloads the model.
+`--port <number>` defaults to `4190`. The browser opens unless `--no-open` is set. The workbench listens on loopback and runs alongside your app's own dev server. It supports training, prediction, corrections, evaluation, and browser timing. Changes mark an artifact stale; training remains explicit.
 
-Predictions and timing run through TensorFlow.js CPU in the browser. Training and evaluation run in local child processes with fresh task modules. The speed measurement repeats the current input 100 times after 20 warmups; it excludes model loading and does not measure accuracy.
+Browser timing uses the current input, 20 warmups, and 100 measured predictions. It excludes loading and does not measure accuracy. `dev` has no JSON mode.
 
-Saving validates output and rejects held-out inputs. It only changes training data. Token pipelines also need matching supervision from their authored recipe; the save result points to that file. Matchbox does not infer labels or normalization rules from a correction.
+## train
 
-## Train and evaluate
+```sh
+bunx matchbox-ai train [task] --verbose --json
+```
+
+`--verbose` shows epoch loss outside JSON mode. Training validates datasets and token annotations, fits a model, gates on validation accuracy and size, and writes the artifact, TypeScript wrapper, declarations, and report.
+
+Validation-gate failure stops export and exits nonzero. An independent test score below the threshold is reported after packaging; use `eval` to enforce the test threshold in CI.
+
+## eval
 
 ```sh
-matchbox-ai train money
-matchbox-ai train money --verbose
-matchbox-ai eval money
-matchbox-ai eval money --json
+bunx matchbox-ai eval [task] --json
 ```
 
-Training validates datasets, fits the model, checks validation requirements, and exports a model plus a report. Failing validation stops export. The separate test set measures the selected model without influencing training. `eval` exits with status 1 if exact accuracy is below the configured threshold and includes expected/actual failures. `--verbose` reveals epoch loss. JSON output stays on stdout; diagnostics go to stderr.
+Evaluates the saved artifact against the configured test file. Reports exact accuracy, acceptance, abstention, invalid outputs, and expected/actual failures. Exits `1` when exact accuracy is below `minAccuracy`. It does not retrain.
 
-## Inspect and script
+## parse
 
 ```sh
-matchbox-ai parse money "fifteen euros" --json
-matchbox-ai inspect money "eleven grand" --json
-matchbox-ai info money
-matchbox-ai save money "twenty euros please" '{"amount":20,"currency":"EUR","approximate":false}'
+bunx matchbox-ai parse money 'twenty dollars' --json
 ```
 
-A task argument can be a name, task directory, or config file. Omit the name when discovery finds exactly one task. Interactive `dev` offers a picker for multiple tasks; scripts require a name. `--config` selects an explicit path and cannot be combined with a task argument. Each command has its own `--help`.
+Returns a [ParseResult](reference/runtime.md). Uncertainty is a prediction result and does not itself cause a nonzero exit. The CLI uses local inference, not a browser timing measurement.
+
+## inspect
+
+```sh
+bunx matchbox-ai inspect money 'eleven grand' --json
+```
+
+Returns `{ input, ...diagnostics, result }`. Token models include labeled tokens and the decoded candidate; field models expose their strategy-specific diagnostics. `result` is the validated prediction. Diagnostics are for debugging and should not be treated as a stable application contract.
+
+## info
+
+```sh
+bunx matchbox-ai info [task] --json
+```
+
+Returns resolved `config`, `authoring`, `pipeline`, `task`, `train`, `validation`, `eval`, and `output` paths. It does not require a trained artifact.
+
+## save
+
+```sh
+bunx matchbox-ai save money 'twenty euros please' '{"amount":20,"currency":"EUR","approximate":false}' --json
+```
+
+Validates both values, then adds or replaces a matching input in training data. Matching ignores surrounding whitespace and case. Rejects held-out inputs and ambiguous duplicate training rows. Returns `{ saved, action, example, next }` where `action` is `added` or `updated`.
+
+It does not retrain. Token pipelines also require updated recipe supervision before training. Corrections never modify validation or test data.
+
+## Exit status
 
-Bare `matchbox-ai` shows available tasks and next actions. It does not create files. Use the one-shot commands for machine-readable results.
+Successful commands exit `0`, including uncertain predictions. Invalid arguments, missing tasks/artifacts, malformed data, training failures, and failed eval thresholds exit nonzero. `--help` and `--version` exit `0`.

package/docs/contributing.md

@@ -0,0 +1,43 @@
+# Contributing
+
+Matchbox uses a shared Rust engine for native training and browser inference, with TypeScript authoring and application APIs.
+
+## Project structure
+
+```text
+Cargo.toml                         # The Rust workspace owns the shared dependency versions.
+crates/
+  matchbox-engine/src/             # Burn model, training and record serialization.
+  matchbox-node/src/               # Node-API training adapter and native parity checks.
+  matchbox-wasm/src/               # Browser inference adapter.
+packages/
+  core/src/runtime/burn/           # Loading, typed prediction and disposal.
+  train/src/native/                # TypeScript calls into the native addon.
+  cli/                            # Existing commands and workbench.
+scripts/
+  build-rust.ts                   # Builds the native addon and browser WASM module.
+  copy-rust.ts                    # Copies binaries into npm package output.
+```
+
+TypeScript continues to own task schemas, tokenization, authored supervision, decoding and validation. Burn owns the embedding network, autodiff, Adam, model records and execution. The adapters share the same model implementation. They do not implement a separate inference engine.
+
+A contributor compiles the native addon and WASM runtime once. Training produces model data, without compiling Rust for each task. Published packages bundle native binaries for the supported platforms.
+
+## Local development
+
+Install Bun and Rust through rustup or Homebrew. The repository discovers Rust tools from PATH, Homebrew rustup and the Cargo bin directory without changing your shell configuration. The checked-in toolchain file pins Rust and requests the WASM target.
+
+```sh
+bun install --frozen-lockfile
+bun run setup:rust
+bun run dev
+bun run check
+MATCHBOX_PREBUILT=1 bun run test:browser
+bun run eval:examples
+```
+
+`bun run setup:rust` is a one-time contributor setup for the pinned wasm-bindgen CLI. Subsequent `bun run dev`, builds and checks locate the installed tools automatically. Package consumers use bundled prebuilds and do not need Rust.
+
+Generated native binaries, WASM output, Cargo build output and model artifacts are ignored by Git. `Cargo.lock` pins Rust dependencies. `bun run check` includes Rust formatting, Clippy and engine tests.
+
+See [native package distribution](native-packages.md) for platform coverage and release verification.

package/docs/dataset-format.md

@@ -9,6 +9,8 @@ Matchbox dataset format version 1 uses separate local `train.jsonl` and `evals.j
 
 `input` must satisfy the task's string schema. `output` must satisfy its structured output schema. There are no row headers, split labels, IDs, or metadata properties in version 1. Application-specific fields belong inside `output` and must be declared by the task.
 
+The conventional training workflow uses `data/train.jsonl`, `evals/validation.jsonl`, and `evals/test.jsonl`. The two-source validation API below is a lower-level utility, not the complete training configuration.
+
 ## Authoring rules
 
 Write UTF-8 text without a byte-order mark, with LF or CRLF line endings. Empty and whitespace-only lines are ignored. Diagnostics still count those physical lines. Each split must contain at least one example. A final newline is optional.
@@ -49,10 +51,10 @@ The function accepts text and performs no filesystem access, network requests, o
 
 ## Train and eval separation
 
-Both splits are explicit and required. Matchbox does not shuffle, merge, deduplicate, or automatically split them. Keep held-out examples separate from training and synthetic expansion. Authors are responsible for preventing overlap and paraphrase leakage; validation establishes structural correctness, not evaluation independence. Automatic holdout selection and leakage diagnostics can be designed with the training ticket.
+Both splits are explicit and required. Matchbox does not shuffle, merge, deduplicate, or automatically split them. Keep held-out examples separate from training and synthetic expansion. Authors are responsible for preventing overlap and paraphrase leakage; validation establishes structural correctness, not evaluation independence. The training workflow additionally rejects inputs shared across splits after trimming and case folding. The lower-level `parseDatasets` API performs structural validation only.
 
 ## Versioning
 
 The required `formatVersion: 1` in the dataset configuration describes both sources. Keep that configuration under version control alongside the JSONL files and task definition. Raw JSONL files are not self-describing; preserve their configuration when sharing them. No implicit version is assumed. Missing or unsupported versions throw a `RangeError` before rows are read. Invalid rows return validation issues instead.
 
-Breaking changes to row structure or interpretation require a new format version and explicit migration. Do not silently reinterpret existing files. Dataset format versions are independent of package versions and the task metadata's format version. Business-schema changes require revalidation of both datasets against the updated task. Artifact hashes and provenance belong to the build metadata ticket.
+Breaking changes to row structure or interpretation require a new format version and explicit migration. Do not silently reinterpret existing files. Dataset format versions are independent of package versions and the task metadata's format version. Business-schema changes require revalidation of both datasets against the updated task. Build reports include artifact and dataset hashes.

package/docs/evaluation.md

@@ -1,9 +1,70 @@
-# Evaluation
+# Evaluate a model
 
-Training fits vocabulary, field domains, and weights using data/train.jsonl only. Validation in evals/validation.jsonl gates artifact export. Independent evals/test.jsonl measures the selected model. Input overlap across these splits is rejected.
+Evaluation checks an existing model against inputs with known answers. It does not update weights or train on your test data.
 
-Run matchbox-ai eval money to evaluate saved artifacts without retraining or requiring the training data. A failing accuracy threshold produces a nonzero exit code. Optional evals/baseline.ts exports a parser with the same parse contract. Optional evals/challenges.json contains abstention cases with input and output: null. Other research formats must have distinct filenames and explicit runners.
+## Run the test split
 
-Reports include accuracy, abstention, invalid-output rate, artifact bytes, loss, export parity, dataset hashes, and control-model results where supported. Confidence is uncalibrated. Zero confidence for unfamiliar vocabulary means the current model declines to answer; it does not prove the input is invalid or diagnose the only cause.
+After [training](training.md), run:
 
-When evaluating new numeric representations, withhold complete output values and meaningful input compositions. Never teach test answers through a dictionary or rewrite evals to make training pass. Schema validity establishes output shape, not semantic correctness.
+```sh
+bunx matchbox-ai eval money
+bunx matchbox-ai eval money --json
+```
+
+This loads the saved artifact and scores `evals/test.jsonl`. It does not require the training dataset. The command exits `1` when exact accuracy is below the configured `minAccuracy`, making it suitable for a CI gate.
+
+The workbench's **Evaluate** action runs the same test evaluation. The programmatic [`evaluate`](reference/evaluation.md) API returns metrics without applying an acceptance gate.
+
+## Keep the splits separate
+
+| Split                    | Used for                                                               |
+| ------------------------ | ---------------------------------------------------------------------- |
+| `data/train.jsonl`       | Learning vocabulary, output domains, and weights.                      |
+| `evals/validation.jsonl` | Checking accuracy and size requirements before exporting a candidate.  |
+| `evals/test.jsonl`       | Measuring the selected model without influencing fitting or selection. |
+
+Withhold meaningful input compositions and complete output values where the chosen strategy supports unseen values. Avoid near-duplicate paraphrases across splits. A low test score should lead to better training coverage or a different explicit pipeline, not edited test answers.
+
+## Read the results
+
+| Metric              | Meaning                                                                             |
+| ------------------- | ----------------------------------------------------------------------------------- |
+| Exact accuracy      | The fraction of complete outputs matching the expected value.                       |
+| Accepted accuracy   | Accuracy among answers the parser returned; `null` when it returned none.           |
+| Abstention rate     | The fraction of inputs on which the parser declined to answer.                      |
+| Invalid-output rate | The fraction of returned answers that fail output validation.                       |
+| Failures            | Inputs with their expected output and actual result. Uncertainty appears as `null`. |
+
+Read accuracy and abstention together. A model that answers only easy inputs can have high accepted accuracy and poor coverage. Schema validity guarantees an output's shape, not that its meaning is correct.
+
+## Test uncertainty
+
+Confidence is an uncalibrated model score. Zero confidence means the current model declined to answer; it does not establish that the input is invalid or that training coverage is the only problem.
+
+For sequence models, add negative cases in `evals/challenges.json`:
+
+```json
+[{ "input": "sometime soon", "output": null }]
+```
+
+Training includes these in the report's separate `challenges` section. They do not become training examples or select the model. The CLI `eval` command scores the configured test split; it does not automatically rerun the challenge file.
+
+The programmatic evaluator also accepts expected `null` for abstention cases. This is an evaluation convention, not a change to the task's successful output schema.
+
+## Measure browser speed
+
+Use **Measure browser speed** in the workbench or the benchmark controls on the examples page. They run inference through Burn WASM CPU on the current device, including output validation.
+
+These measurements exclude model loading and UI rendering. Record the input, sample count, browser, and device with the result. The workbench uses 100 timed runs after 20 warmups; the website demo uses 300 timed runs after 20 warmups. Repeated-input latency is separate from held-out accuracy.
+
+See the [evaluation API](reference/evaluation.md) for exact metric fields and return types.
+
+## Repository example audit
+
+After `bun run train`, run `bun run eval:examples`. It writes `.matchbox/example-evaluation.json` with all predictions that disagree with expected outputs, slice metrics, false accepts, source hashes, and token-sequence overlap with training. Each example owns a frozen `evals/generalization.json` file. Treat those files as audit data; create new development fixtures when fixing failures and obtain a fresh independent evaluation before claiming improvement.
+
+A held-out string can still be identical to training at the model's input representation. Word tokenization maps all numbers to `<number>`. Changing 15 to 90 tests deterministic copying and arithmetic, not learned numerical generalization. Report accuracy on feature-novel inputs separately.
+
+The audit evaluates model outputs against the task’s expected results. Positive coverage, accuracy among accepted answers, and false acceptance of negative examples matter alongside exact match. A high abstention rate can hide an ineffective parser. Threshold curves are diagnostics, not permission to pick a threshold on test data.
+
+See [the measured example audit](example-evaluation.md) for current results and limitations.

package/docs/example-evaluation.md

@@ -0,0 +1,47 @@
+# Example evaluation
+
+The examples are evaluated against expected structured outputs and rejection cases. Timing in the demo measures execution speed on your device, independently of these accuracy checks.
+
+## Current results
+
+These small, synthetic suites are regression evidence. Known failures informed training coverage and candidate selection. The evaluation fixtures were preserved, but their scores are not independent estimates of performance on user traffic. Exact match includes correct abstentions.
+
+| Example | Audit exact match | Language test   | False accepts on audit negatives |
+| ------- | ----------------- | --------------- | -------------------------------- |
+| is-even | 8/8               | Not applicable. | 0/3                              |
+| Money   | 19/20             | 12/12           | 0/8                              |
+| Time    | 20/20             | 12/12           | 0/8                              |
+| Filters | 16/16             | 11/12           | 0/6                              |
+
+All three language-development suites pass 12/12. No language-test negative case is falsely accepted. Confidence remains uncalibrated.
+
+Money still abstains on “Henrik paid 19 dollars yesterday”. Filters still abstain on “show me all companies based in Norway” in the language test. These are valid requests with incomplete model coverage.
+
+## Training coverage
+
+Money training includes payment framing, subscriptions and bounds that must be rejected rather than returned as exact amounts. Time includes mixed day/hour expressions and sentence framing. Filters include country/location phrasing and exclusion supervision. These are authored training examples; runtime decoders and the model architecture were unchanged.
+
+Two money and six time language-test inputs match training token sequences after numeric normalization. Novel quantities are not necessarily novel model inputs. Even a new full sentence can consist of familiar three-token windows. Country normalization uses an application-owned reference.
+
+## Model size
+
+Sizes include metadata, vocabulary and float32 model records. The shared WASM runtime and application decoders are additional downloads. The website reads these figures from the current build.
+
+| Example | Parameters | Artifact bytes |
+| ------- | ---------: | -------------: |
+| is-even |        530 |           3898 |
+| money   |       1530 |          10351 |
+| time    |       1287 |           9188 |
+| filters |       7760 |          58555 |
+
+## Reproduce
+
+```sh
+bun run train
+bun scripts/evaluate-language.ts development
+bun scripts/evaluate-language.ts test
+bun run eval:examples
+bun run test:browser
+```
+
+[Current results](example-results.json) include case and artifact hashes, failures and feature-overlap counts. The evaluation scripts write fresh reports into the ignored .matchbox directory.

package/docs/example-results.json

@@ -0,0 +1,280 @@
+{
+  "provenance": "Synthetic regression fixtures. Known failures informed training coverage and candidate selection. These are not independent production accuracy estimates. Evaluation fixtures were preserved.",
+  "examples": [
+    {
+      "name": "is-even",
+      "parameters": 530,
+      "bytes": 3898,
+      "artifactSha256": "c659fbf61017dc88037e8314335c4e73622006c3549620f23ca459bc4098cb6f",
+      "caseSha256": "93cff9748ccc3ce575274f04dec41861ac59f7bcdd42d35bbcfe86f026774177",
+      "evaluation": {
+        "examples": 8,
+        "invalidOutputRate": 0,
+        "exactAccuracy": 1,
+        "accepted": 5,
+        "acceptedAccuracy": 1,
+        "abstentionRate": 0.375,
+        "correctAbstentions": 3,
+        "failures": [],
+        "negatives": 3,
+        "falseAccepts": 0
+      }
+    },
+    {
+      "name": "money",
+      "parameters": 1530,
+      "bytes": 10351,
+      "artifactSha256": "8aab74105bda77422fb3ab10a67adb96fe589142bf21d3bfb244cce0aaba2db4",
+      "caseSha256": "c8b46c03eee72e24e8a297771cb8c7b026c9f3de31c2ea1822e681c87458e234",
+      "evaluation": {
+        "examples": 20,
+        "invalidOutputRate": 0,
+        "exactAccuracy": 0.95,
+        "accepted": 11,
+        "acceptedAccuracy": 1,
+        "abstentionRate": 0.44999999999999996,
+        "correctAbstentions": 8,
+        "failures": [
+          {
+            "input": "Henrik paid 19 dollars yesterday",
+            "expected": {
+              "amount": 19,
+              "currency": "USD",
+              "approximate": false
+            },
+            "actual": null
+          }
+        ],
+        "negatives": 8,
+        "falseAccepts": 0
+      },
+      "language": {
+        "name": "money",
+        "split": "test",
+        "artifactSha256": "8aab74105bda77422fb3ab10a67adb96fe589142bf21d3bfb244cce0aaba2db4",
+        "caseSha256": "21463aad45c9584858acca629aeee7d96f300bd8937268cbb17b9552bff695a0",
+        "featureEquivalent": ["invoice 718 totals SEK 54", "from 16 to 28 dollars"],
+        "novelOnly": {
+          "examples": 10,
+          "invalidOutputRate": 0,
+          "exactAccuracy": 1,
+          "accepted": 5,
+          "acceptedAccuracy": 1,
+          "abstentionRate": 0.5,
+          "correctAbstentions": 5,
+          "failures": []
+        },
+        "examples": 12,
+        "invalidOutputRate": 0,
+        "exactAccuracy": 1,
+        "accepted": 6,
+        "acceptedAccuracy": 1,
+        "abstentionRate": 0.5,
+        "correctAbstentions": 6,
+        "failures": [],
+        "falseAccepts": 0
+      },
+      "development": {
+        "name": "money",
+        "split": "development",
+        "artifactSha256": "8aab74105bda77422fb3ab10a67adb96fe589142bf21d3bfb244cce0aaba2db4",
+        "caseSha256": "8f0b9f5cfa2bfbb202d27579c13c822f1962f64a428771ff5c9f42c3d72480c9",
+        "featureEquivalent": ["invoice 657 totals $ 91", "between 18 and 29 euros"],
+        "novelOnly": {
+          "examples": 10,
+          "invalidOutputRate": 0,
+          "exactAccuracy": 1,
+          "accepted": 5,
+          "acceptedAccuracy": 1,
+          "abstentionRate": 0.5,
+          "correctAbstentions": 5,
+          "failures": []
+        },
+        "examples": 12,
+        "invalidOutputRate": 0,
+        "exactAccuracy": 1,
+        "accepted": 6,
+        "acceptedAccuracy": 1,
+        "abstentionRate": 0.5,
+        "correctAbstentions": 6,
+        "failures": [],
+        "falseAccepts": 0
+      }
+    },
+    {
+      "name": "time",
+      "parameters": 1287,
+      "bytes": 9188,
+      "artifactSha256": "1aca94d5192cd70ddca6dca6e0a3a1a38b1d8c0e0cd8849b5cbaf1942da1d2e5",
+      "caseSha256": "9735ba19d8feb772fa074a0cbee03cb7d8b6fb009bdb734d0128a0836739487f",
+      "evaluation": {
+        "examples": 20,
+        "invalidOutputRate": 0,
+        "exactAccuracy": 1,
+        "accepted": 12,
+        "acceptedAccuracy": 1,
+        "abstentionRate": 0.4,
+        "correctAbstentions": 8,
+        "failures": [],
+        "negatives": 8,
+        "falseAccepts": 0
+      },
+      "language": {
+        "name": "time",
+        "split": "test",
+        "artifactSha256": "1aca94d5192cd70ddca6dca6e0a3a1a38b1d8c0e0cd8849b5cbaf1942da1d2e5",
+        "caseSha256": "ba60a69928392d1ba8d0f3f7b961135791b157f00d35bd08504deacfdef66ade",
+        "featureEquivalent": [
+          "please wait for 0.25 hours",
+          "the reminder is in 41 minutes",
+          "tomorrow at 6:37 pm please",
+          "in minus 38 seconds",
+          "tomorrow at 27:19",
+          "for 3 days or 22 minutes"
+        ],
+        "novelOnly": {
+          "examples": 6,
+          "invalidOutputRate": 0,
+          "exactAccuracy": 1,
+          "accepted": 5,
+          "acceptedAccuracy": 1,
+          "abstentionRate": 0.16666666666666663,
+          "correctAbstentions": 1,
+          "failures": []
+        },
+        "examples": 12,
+        "invalidOutputRate": 0,
+        "exactAccuracy": 1,
+        "accepted": 8,
+        "acceptedAccuracy": 1,
+        "abstentionRate": 0.33333333333333337,
+        "correctAbstentions": 4,
+        "failures": [],
+        "falseAccepts": 0
+      },
+      "development": {
+        "name": "time",
+        "split": "development",
+        "artifactSha256": "1aca94d5192cd70ddca6dca6e0a3a1a38b1d8c0e0cd8849b5cbaf1942da1d2e5",
+        "caseSha256": "d0c0d22b10a8707ab48b3983a6973ef104447ed49427026ed01575ed2581e0c8",
+        "featureEquivalent": [
+          "please wait for 13 minutes",
+          "in 1.25 hours",
+          "in minus 12 minutes",
+          "tomorrow at 26:11",
+          "for 5 hours or 18 minutes"
+        ],
+        "novelOnly": {
+          "examples": 7,
+          "invalidOutputRate": 0,
+          "exactAccuracy": 1,
+          "accepted": 6,
+          "acceptedAccuracy": 1,
+          "abstentionRate": 0.1428571428571429,
+          "correctAbstentions": 1,
+          "failures": []
+        },
+        "examples": 12,
+        "invalidOutputRate": 0,
+        "exactAccuracy": 1,
+        "accepted": 8,
+        "acceptedAccuracy": 1,
+        "abstentionRate": 0.33333333333333337,
+        "correctAbstentions": 4,
+        "failures": [],
+        "falseAccepts": 0
+      }
+    },
+    {
+      "name": "filters",
+      "parameters": 7760,
+      "bytes": 58555,
+      "artifactSha256": "489334acf5e497fd07e51bdc4ff04313e3f094342c5eca92e15df056bb00b321",
+      "caseSha256": "5c47c1e8b9cca57c904a21523a7f975ced84cbc418af12afd4e38ea2e3f0203c",
+      "evaluation": {
+        "examples": 16,
+        "invalidOutputRate": 0,
+        "exactAccuracy": 1,
+        "accepted": 10,
+        "acceptedAccuracy": 1,
+        "abstentionRate": 0.375,
+        "correctAbstentions": 6,
+        "failures": [],
+        "negatives": 6,
+        "falseAccepts": 0
+      },
+      "language": {
+        "name": "filters",
+        "split": "test",
+        "artifactSha256": "489334acf5e497fd07e51bdc4ff04313e3f094342c5eca92e15df056bb00b321",
+        "caseSha256": "f4974e1ae31abf497acb0fe4b66033f81ba94fe26fde429d7c620d56ba778b4b",
+        "featureEquivalent": [],
+        "novelOnly": {
+          "examples": 12,
+          "invalidOutputRate": 0,
+          "exactAccuracy": 0.9166666666666666,
+          "accepted": 7,
+          "acceptedAccuracy": 1,
+          "abstentionRate": 0.41666666666666663,
+          "correctAbstentions": 4,
+          "failures": [
+            {
+              "input": "show me all companies based in Norway",
+              "expected": {
+                "field": "country",
+                "operator": "eq",
+                "value": "NO"
+              },
+              "actual": null
+            }
+          ]
+        },
+        "examples": 12,
+        "invalidOutputRate": 0,
+        "exactAccuracy": 0.9166666666666666,
+        "accepted": 7,
+        "acceptedAccuracy": 1,
+        "abstentionRate": 0.41666666666666663,
+        "correctAbstentions": 4,
+        "failures": [
+          {
+            "input": "show me all companies based in Norway",
+            "expected": {
+              "field": "country",
+              "operator": "eq",
+              "value": "NO"
+            },
+            "actual": null
+          }
+        ],
+        "falseAccepts": 0
+      },
+      "development": {
+        "name": "filters",
+        "split": "development",
+        "artifactSha256": "489334acf5e497fd07e51bdc4ff04313e3f094342c5eca92e15df056bb00b321",
+        "caseSha256": "7b3dcb7b5898d40594322fef3c98e4a5f06622d6764d8e77191390cbd9543c6d",
+        "featureEquivalent": [],
+        "novelOnly": {
+          "examples": 12,
+          "invalidOutputRate": 0,
+          "exactAccuracy": 1,
+          "accepted": 8,
+          "acceptedAccuracy": 1,
+          "abstentionRate": 0.33333333333333337,
+          "correctAbstentions": 4,
+          "failures": []
+        },
+        "examples": 12,
+        "invalidOutputRate": 0,
+        "exactAccuracy": 1,
+        "accepted": 8,
+        "acceptedAccuracy": 1,
+        "abstentionRate": 0.33333333333333337,
+        "correctAbstentions": 4,
+        "failures": [],
+        "falseAccepts": 0
+      }
+    }
+  ]
+}

package/docs/examples/money.md

@@ -0,0 +1,19 @@
+# Money parsing
+
+The money template trains a token recognizer for amounts, currencies, and multipliers. Its decoder converts recognized number words and applies arithmetic.
+
+```sh
+bunx matchbox-ai init money --template money
+bunx matchbox-ai train money
+bunx matchbox-ai dev money
+```
+
+Try `invoice 31415 totals € 28.65`, `in 2026 we paid USD 59.20`, or `around twenty six grand in euros`. The first two require distinguishing money from other numbers.
+
+The output is `{ amount: number, currency: "EUR" | "USD" | "GBP" | "SEK", approximate: boolean }`. In this example `$` means USD. English number words below one hundred are supported by application code. Conflicting currencies and undecodable amounts cause uncertainty.
+
+Read `parser.ts` for the output contract, `pipeline.ts` for the learning strategy, `recipe.ts` for supervision, and `decode/decode.ts` for normalization. Add training annotations when adding examples. Evals stay independent.
+
+The recognizer is learned; number conversion and multiplication are authored. Training a different domain does not automatically inherit these rules.
+
+Training includes explicit neutral spans, rejection examples, and unknown-token masking. These choices are visible in the recipe and generator. The original test cases are development regressions. The frozen `evals/generalization.json` cases check new contexts and rejection behavior. See [the example audit](../example-evaluation.md).