@matchbox-ai/train 0.1.0

package/dist/train.d.ts

@@ -0,0 +1,276 @@
+/** Runs the same validation, selection, and packaging pipeline as the CLI. */
+export declare function train(target: string, options?: {
+    onProgress?: (epoch: number, loss: number) => void;
+}): Promise<{
+    evaluation: {
+        examples: number;
+        invalidOutputRate: number;
+        exactAccuracy: number;
+        accepted: number;
+        acceptedAccuracy: number | null;
+        abstentionRate: number;
+        correctAbstentions: number;
+        failures: {
+            input: string;
+            expected: unknown;
+            actual: unknown;
+        }[];
+    };
+    report?: never;
+    output?: never;
+} | {
+    evaluation?: never;
+    report: {
+        formatVersion: number;
+        architecture: "embedding-window-mlp";
+        backend: string;
+        seed: number;
+        artifactSha256: string;
+        bytes: number;
+        parameters: number;
+        datasetSha256: {
+            source: string;
+            sha256: string;
+        }[];
+        examples: {
+            train: number;
+            validation: number;
+            eval: number;
+        };
+        shuffledLabelsUngated: {
+            examples: number;
+            invalidOutputRate: number;
+            exactAccuracy: number;
+            accepted: number;
+            acceptedAccuracy: number | null;
+            abstentionRate: number;
+            correctAbstentions: number;
+            failures: {
+                input: string;
+                expected: unknown;
+                actual: unknown;
+            }[];
+        } | null;
+        supervisedTokens: number;
+        loss: number[];
+        exportParity: {
+            examples: number;
+            maxConfidenceError: number;
+            labelDisagreements: number;
+        };
+        validation: {
+            examples: number;
+            invalidOutputRate: number;
+            exactAccuracy: number;
+            accepted: number;
+            acceptedAccuracy: number | null;
+            abstentionRate: number;
+            correctAbstentions: number;
+            failures: {
+                input: string;
+                expected: unknown;
+                actual: unknown;
+            }[];
+        };
+        untrainedUngated: {
+            examples: number;
+            invalidOutputRate: number;
+            exactAccuracy: number;
+            accepted: number;
+            acceptedAccuracy: number | null;
+            abstentionRate: number;
+            correctAbstentions: number;
+            failures: {
+                input: string;
+                expected: unknown;
+                actual: unknown;
+            }[];
+        };
+        untrained: {
+            examples: number;
+            invalidOutputRate: number;
+            exactAccuracy: number;
+            accepted: number;
+            acceptedAccuracy: number | null;
+            abstentionRate: number;
+            correctAbstentions: number;
+            failures: {
+                input: string;
+                expected: unknown;
+                actual: unknown;
+            }[];
+        };
+        float: {
+            examples: number;
+            invalidOutputRate: number;
+            exactAccuracy: number;
+            accepted: number;
+            acceptedAccuracy: number | null;
+            abstentionRate: number;
+            correctAbstentions: number;
+            failures: {
+                input: string;
+                expected: unknown;
+                actual: unknown;
+            }[];
+        };
+        quantized: {
+            examples: number;
+            invalidOutputRate: number;
+            exactAccuracy: number;
+            accepted: number;
+            acceptedAccuracy: number | null;
+            abstentionRate: number;
+            correctAbstentions: number;
+            failures: {
+                input: string;
+                expected: unknown;
+                actual: unknown;
+            }[];
+        };
+        challenges: {
+            examples: number;
+            invalidOutputRate: number;
+            exactAccuracy: number;
+            accepted: number;
+            acceptedAccuracy: number | null;
+            abstentionRate: number;
+            correctAbstentions: number;
+            failures: {
+                input: string;
+                expected: unknown;
+                actual: unknown;
+            }[];
+        } | null;
+        baseline: {
+            examples: number;
+            invalidOutputRate: number;
+            exactAccuracy: number;
+            accepted: number;
+            acceptedAccuracy: number | null;
+            abstentionRate: number;
+            correctAbstentions: number;
+            failures: {
+                input: string;
+                expected: unknown;
+                actual: unknown;
+            }[];
+        } | null;
+        trainingMs: number;
+        notes: string;
+    };
+    output: string;
+} | {
+    report: {
+        formatVersion: number;
+        architecture: "bag-of-words-mlp";
+        backend: string;
+        seed: number;
+        artifactSha256: string;
+        bytes: number;
+        parameters: number;
+        datasetSha256: {
+            source: string;
+            sha256: string;
+        }[];
+        examples: {
+            train: number;
+            validation: number;
+            eval: number;
+        };
+        loss: number[];
+        exportParity: {
+            examples: number;
+            labelDisagreements: number;
+            maxConfidenceError: number;
+        };
+        validation: {
+            examples: number;
+            invalidOutputRate: number;
+            exactAccuracy: number;
+            accepted: number;
+            acceptedAccuracy: number | null;
+            abstentionRate: number;
+            correctAbstentions: number;
+            failures: {
+                input: string;
+                expected: unknown;
+                actual: unknown;
+            }[];
+        };
+        quantized: {
+            examples: number;
+            invalidOutputRate: number;
+            exactAccuracy: number;
+            accepted: number;
+            acceptedAccuracy: number | null;
+            abstentionRate: number;
+            correctAbstentions: number;
+            failures: {
+                input: string;
+                expected: unknown;
+                actual: unknown;
+            }[];
+        };
+        float: {
+            examples: number;
+            invalidOutputRate: number;
+            exactAccuracy: number;
+            accepted: number;
+            acceptedAccuracy: number | null;
+            abstentionRate: number;
+            correctAbstentions: number;
+            failures: {
+                input: string;
+                expected: unknown;
+                actual: unknown;
+            }[];
+        };
+        untrained: {
+            examples: number;
+            invalidOutputRate: number;
+            exactAccuracy: number;
+            accepted: number;
+            acceptedAccuracy: number | null;
+            abstentionRate: number;
+            correctAbstentions: number;
+            failures: {
+                input: string;
+                expected: unknown;
+                actual: unknown;
+            }[];
+        };
+        untrainedUngated: {
+            examples: number;
+            invalidOutputRate: number;
+            exactAccuracy: number;
+            accepted: number;
+            acceptedAccuracy: number | null;
+            abstentionRate: number;
+            correctAbstentions: number;
+            failures: {
+                input: string;
+                expected: unknown;
+                actual: unknown;
+            }[];
+        };
+        baseline: {
+            examples: number;
+            invalidOutputRate: number;
+            exactAccuracy: number;
+            accepted: number;
+            acceptedAccuracy: number | null;
+            abstentionRate: number;
+            correctAbstentions: number;
+            failures: {
+                input: string;
+                expected: unknown;
+                actual: unknown;
+            }[];
+        } | null;
+        trainingMs: number;
+        notes: string;
+    };
+    output: string;
+}>;
+//# sourceMappingURL=train.d.ts.map

package/dist/train.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"train.d.ts","sourceRoot":"","sources":["../src/train.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,wBAAsB,KAAK,CACzB,MAAM,EAAE,MAAM,EACd,OAAO,GAAE;IAAE,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;CAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAKrE"}

package/dist/types.d.ts

@@ -0,0 +1,17 @@
+export interface TrainingConfig {
+    formatVersion?: 1;
+    challenges?: string;
+    sequence?: {
+        recipe: string;
+        decoder: string;
+    };
+    baseline?: string;
+    task?: string;
+    train?: string;
+    validation?: string;
+    eval?: string;
+    output?: string;
+    minAccuracy?: number;
+    maxBytes?: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,cAAc;IAC7B,aAAa,CAAC,EAAE,CAAC,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAC/C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB"}

package/docs/README.md

@@ -0,0 +1,9 @@
+# Matchbox documentation
+
+Start with [getting started](getting-started.md), then read [project structure](project-structure.md), [pipelines](pipelines.md), and [evaluation](evaluation.md).
+
+The [primitive reference](primitives/README.md) describes supported authoring choices. [React](react.md), [browser runtime](runtime-backends.md), and [CLI](cli.md) cover application integration and local development. [Repository design](repository-design.md) is for contributors.
+
+These docs ship in all three packages under node_modules/@matchbox-ai/{core,train}/docs and node_modules/matchbox-ai/docs. Use the installed version when assisting an application author. The bundled agent-skill.md provides the corresponding coding-agent workflow.
+
+See [Releases](releases.md) for Changesets, package versions, and npm publishing.

package/docs/agent-skill.md

@@ -0,0 +1,22 @@
+---
+name: matchbox
+description: Author, train, evaluate, and integrate tiny browser-local Matchbox parsers using explicit TypeScript primitives.
+---
+
+# Matchbox
+
+Read the installed package docs/README.md first, then project-structure.md, pipelines.md, evaluation.md, and primitives/README.md. In the framework repository, use root docs/. Match examples to the installed version.
+
+1. Inspect parser.ts, pipeline.ts, data/train.jsonl, and independent evals before changing behavior.
+2. Keep the output schema focused on valid application values. Make representation and supervision choices explicit in pipeline.ts or imported helpers.
+3. Use fieldClassifier for finite output domains and tokenClassifier for explicitly supervised token recognition. Explain their limits; do not promise unseen numeric outputs from a finite classifier.
+4. Keep domain dictionaries and normalizers application-owned and visible. Never insert one silently to make an evaluation pass.
+5. Fit preprocessing only on training data. Put data generators in project-level scripts/ and preserve validation/test fixtures. Add meaningful held-out compositions and negative cases independently of model fitting.
+6. Use the CLI from matchbox-ai or programmatic train from @matchbox-ai/train to apply validation gates, measure results, and package weights. Report failures honestly. Never fabricate benchmark figures.
+7. Distinguish uncertain interpretation from invalid user input. Confidence is currently uncalibrated; inspect diagnostics before attributing uncertainty to one cause.
+8. Import generated artifacts in the app and use @matchbox-ai/core/react when needed. Keep @matchbox-ai/train and native TensorFlow outside browser code.
+9. Let TensorFlow serialize, load, and execute models. Do not implement custom inference kernels or a backend-selection framework. Verify native-to-browser export parity and benchmark the shipped TensorFlow runtime. Label emulated mobile measurements accurately.
+
+Scope changes to existing, documented primitives. Propose a new primitive separately with its contract, limitations, and evaluation evidence. Preserve authored code and tests when reorganizing folders.
+
+Matchbox owns authoring, workflows, evals, packaging, validation, and typed results. TensorFlow owns model execution. A schema must never silently select numeric encodings or domain normalizers.

package/docs/cli.md

@@ -0,0 +1,54 @@
+# CLI
+
+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.
+
+## Add a task
+
+```sh
+matchbox-ai init
+matchbox-ai init money --template money
+matchbox-ai init intent --template blank
+```
+
+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.
+
+Package-manager build-script policies still apply. With pnpm, run `pnpm approve-builds` and select `@tensorflow/tfjs-node` before training.
+
+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.
+
+## Open the workbench
+
+```sh
+matchbox-ai dev money
+matchbox-ai dev money --port 4191 --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.
+
+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.
+
+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 and evaluate
+
+```sh
+matchbox-ai train money
+matchbox-ai train money --verbose
+matchbox-ai eval money
+matchbox-ai eval money --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.
+
+## Inspect and script
+
+```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}'
+```
+
+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`.
+
+Bare `matchbox-ai` shows available tasks and next actions. It does not create files. Use the one-shot commands for machine-readable results.

package/docs/dataset-format.md

@@ -0,0 +1,58 @@
+# Dataset format
+
+Matchbox dataset format version 1 uses separate local `train.jsonl` and `evals.jsonl` files. Each nonblank line is one JSON object with exactly two properties: `input` and `output`.
+
+```jsonl
+{"input":"Swedish customers","output":{"country":"SE"}}
+{"input":"German customers","output":{"country":"DE"}}
+```
+
+`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.
+
+## 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.
+
+Use `JSON.stringify({ input, output })` to generate each row. Newlines within an input string must be JSON escapes, rather than physical line breaks. Pretty-printed multiline objects and comments are rejected. Input whitespace, row order, and duplicate examples are preserved. Use unique object property names; parsing uses standard `JSON.parse` semantics, which retain the last occurrence of duplicate keys.
+
+## Validation API
+
+```ts
+import { defineParser, parseDatasets } from "@matchbox-ai/core";
+import { z } from "zod";
+
+const task = defineParser({
+  input: z.string().min(1),
+  output: z.strictObject({ country: z.enum(["SE", "DE"]) }),
+});
+
+// File loading is the caller's responsibility. This example runs in Bun.
+const result = parseDatasets(task, {
+  formatVersion: 1,
+  train: { source: "train.jsonl", text: await Bun.file("train.jsonl").text() },
+  eval: { source: "evals.jsonl", text: await Bun.file("evals.jsonl").text() },
+});
+
+if (result.success) {
+  const trainingExamples = result.data.train;
+  const heldOutExamples = result.data.eval;
+  // Both collections infer output.country as "SE" | "DE".
+  console.log(trainingExamples.length, heldOutExamples.length);
+} else {
+  for (const issue of result.issues) {
+    console.error(issue.source, issue.line, issue.path, issue.message);
+  }
+}
+```
+
+The function accepts text and performs no filesystem access, network requests, or model inference. `source` is a diagnostic label, normally the filename. Validation collects issues from both splits and returns no partial dataset on failure. Each issue includes its split, source, one-based physical line number, code, schema path, and message. Empty sources report line 1. Schema paths begin with `input` or `output`; syntax and envelope errors use an empty path.
+
+## 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.
+
+## 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.

package/docs/end-to-end.md

@@ -0,0 +1,3 @@
+# End-to-end workflow
+
+See [getting started](getting-started.md), [explicit pipelines](pipelines.md), [evaluation](evaluation.md), and [runtime backends](runtime-backends.md). The filters task now lives in examples/filters/matchbox/filters; its browser UI lives in apps/playground.

package/docs/evaluation.md

@@ -0,0 +1,9 @@
+# Evaluation
+
+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.
+
+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.
+
+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.
+
+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.

package/docs/filter-research.md

@@ -0,0 +1,63 @@
+# Historical filter proof findings
+
+This document records BOO-46 before the TensorFlow migration. BOO-47 removes these handwritten trainers and routes filters through the shared neural training path. Current results and limitations are in the [neural training guide](neural-training.md).
+
+The first full toolchain works: examples train a small local model, validation selects a candidate, packaging generates a typed file import, and React uses it to filter a table. This experiment does not yet establish a compelling advantage over a reasonable deterministic parser.
+
+## Reproduction and data
+
+Run `bun run train`, `bun run eval`, `bun run research`, and `bun run test:browser`. The artifact report is generated beside `examples/filters/.matchbox/filters/model.matchbox`; challenge results are in `challenges.report.json`. Browser results are written under `test-results/` and uploaded by CI.
+
+The fixed corpus contains 176 single-clause training examples, 32 validation examples, and 32 evaluation examples across 13 output classes. These cover three statuses, churn exclusion, four countries, five numeric operators, and explicit AND/OR combinations. Examples contain no missing labels and must satisfy the application schema before fitting. All three splits are separate files. Exact input overlap across splits is rejected.
+
+The corpus was assembled locally from a small set of controlled phrase variations. Validation and evaluation contain distinct inputs and unseen combinations/amounts, but share vocabulary and phrase families with training. This is a software integration benchmark, not an independent linguistic generalization study. BOO-35's broader requirement for independent eval templates, dates, ownership, ranges, and adversarial coverage remains open.
+
+The eight additional challenge queries are diagnostic examples, not a second hidden test set. We used them to discover and fix mixed-field partial parses and unsupported negation. They cannot be used as unbiased evidence of the resulting parser's generalization.
+
+## Models and selection
+
+Both candidates use 212 normalized word/bigram features and 13 predicate classes, giving 2,756 weights. Numeric spans are replaced by a shared feature during fitting; their actual values are normalized after recognition. Field-exclusive tokens learned from training reject detected mixed-field clauses. That guard is a heuristic, not a proof that all input semantics were consumed.
+
+Nearest centroid averages and normalizes feature vectors by label. The linear model uses deterministic full-batch softmax regression, zero initialization, 300 training iterations, and a small L2 penalty. Each candidate is quantized to signed int8 values with a shared scale before scoring. The artifact currently stores those integers as JSON, rather than a binary tensor format.
+
+Selection uses validation exact match and serialized artifact size. The initial exploratory 80% requirement chose the centroid model. We raised the example's requirement to 95% after inspecting validation failures, selecting linear regression at a modest size increase. The held-out report is now visible during development, so these results should not be treated as preregistered research.
+
+| Approach         |       Validation exact | Eval exact | Eval abstention | Invalid output | Serialized artifact |
+| ---------------- | ---------------------: | ---------: | --------------: | -------------: | ------------------: |
+| Nearest centroid |                 81.25% |    84.375% |         15.625% |             0% |        14,597 bytes |
+| Linear softmax   |                   100% |       100% |              0% |             0% |        17,090 bytes |
+| Rules            | Not used for selection |       100% |              0% |             0% |    No model weights |
+
+The selected artifact SHA-256 is `03ef341142e8b2779a48d1033f58f08ded5e036101bcf72a2a36277f40027cfb`. The generated report records the corresponding data hashes. Package changes or project paths can change the artifact hash; rerun the commands to obtain current results.
+
+Zero invalid output is enforced by deterministic validation. It does not establish semantic accuracy. Confidence bins and individual failures are included in the report. The score uses classification margin and vocabulary coverage; it has not been calibrated as a probability.
+
+## Browser measurements
+
+A local macOS arm64 run used Playwright Chromium, 20 warm-up parses followed by 300 measured parses over three fixed queries per approach. All 300 parses were accepted for each candidate. The desktop result was:
+
+| Approach                   |               Warm p50 | Warm p95 | Module load and initialization |
+| -------------------------- | ---------------------: | -------: | -----------------------------: |
+| Nearest centroid           |                 0.1 ms |   0.2 ms |                         7.3 ms |
+| Linear comparison artifact |                 0.1 ms |   0.2 ms |                         9.2 ms |
+| Rules                      | Below timer resolution |   0.1 ms |                         7.4 ms |
+
+The selected parser's initial lazy module load took 39.5 ms; its warm p50/p95 were 0.1/0.2 ms. The mobile viewport run reported 41.3 ms initial loading and the same warm quantiles. Mobile emulation uses the same host CPU and is not a phone hardware benchmark. Comparison modules load later with shared dependencies already warm, so their load times are not directly comparable to initial application loading. Timings include local static asset delivery and are affected by timer precision, JIT, and concurrent test workers.
+
+The Vite build emits the selected model module at about 3.16 KB gzip, with shared runtime and application code separately. The application entry is about 109.4 KB gzip and includes React, Zod, the task definition, and UI code. The raw artifact size is not the total runtime cost. A 64,000-byte artifact limit and a generous 50 ms selected-parser browser p95 limit are enforced as regression budgets.
+
+## The rule comparison matters
+
+The baseline has three anchored recognition regexes after common-word normalization: status, country, and numeric comparison. It uses explicit country/operator maps, three recognition branches, and the same boolean compiler and schema validation as the learned parser. Its current implementation is under 100 lines. It was expanded to cover the authored training language rather than left as a weak straw baseline.
+
+The baseline matches the model's supported eval accuracy and runs faster. On the challenge set it also handles `not active customers`, which the model abstains on because only churn exclusion was trained. Both approaches abstain on the implicit multi-field flagship query. The linear model's successful import and tiny weights do not by themselves demonstrate that it should replace these rules.
+
+## What this establishes
+
+A developer can define a typed task, edit ordinary JSONL examples, run one Bun command, and import a local learned parser without handling tensors, model architecture, or runtime prompts. Quantized learned inference is fast enough here that adding WebGPU has no demonstrated payoff. The API and file-import packaging are ready to support a better parser without changing application call sites.
+
+The next substantive research step is independently authored language data and semantic span classification. It should target implicit conjunctions, operator/value attachment, negation, ranges, dates, and ownership, and measure false acceptance as well as exact match. We should compare that against this clause model and the rule baseline before generalizing the framework or claiming a regex replacement advantage.
+
+## Ticket coverage
+
+BOO-46 delivers this integration proof. It implements the bounded AST, rule baseline, two learned candidates, local runtime, generated wrapper/import, React integration, and training command. It also establishes initial eval and report commands. It leaves BOO-35's independent broad dataset, BOO-37's span-versus-generation comparison, BOO-38's proper calibration, and BOO-43/44's unified component/latency reporting unfinished. The broader tickets should remain open where their acceptance criteria exceed this proof.

package/docs/getting-started.md

@@ -0,0 +1,88 @@
+# Getting started
+
+Matchbox is a TypeScript framework for building small models that run in the browser. Start with the money example inside your existing application, train it locally, and import the result.
+
+The CLI requires Bun 1.4.2 or newer and Node 24 or newer for the local training toolchain.
+
+## Add Matchbox to your app
+
+Once the first release is published, run this inside your existing React or Next.js app:
+
+```sh
+bunx matchbox-ai init money --template money
+bunx matchbox-ai dev money
+```
+
+The CLI installs `@matchbox-ai/core` as an application dependency and `@matchbox-ai/train` and `matchbox-ai` as development dependencies, using your package manager. It preserves existing scripts and framework configuration. Run your app's dev server separately. Use `--skip-install` to defer installation.
+
+When developing Matchbox itself, run `bun install` and `bun run build:packages` in this repository. Run `bun run matchbox init money --template money --directory /path/to/app --skip-install` to inspect a scaffold before the packages are published. It writes registry versions; it does not vendor a copy of the checkout.
+
+## Train in the workbench
+
+Choose **Train model**. Once training finishes, try `$15` or `around twenty six grand in euros`. Predictions run in your browser. Choose **Evaluate** to check independent test examples, or **Measure browser speed** to time the current input.
+
+The same operations are available in the terminal:
+
+```sh
+bunx matchbox-ai train money
+bunx matchbox-ai eval money
+```
+
+## Understand the authored task
+
+```text
+matchbox/money/
+  parser.ts
+  pipeline.ts
+  lib/recipe.ts
+  lib/decode.ts
+  data/train.jsonl
+  data/train-spans.json
+  evals/validation.jsonl
+  evals/test.jsonl
+.matchbox/money/
+  model.matchbox
+  model.ts
+  report.json
+```
+
+The parser defines valid output. The pipeline explicitly selects a token model. The recipe supplies supervised token labels; the decoder normalizes recognized spans. New training examples may need new token annotations. Read the generated task README before extending it.
+
+Use `matchbox-ai init my-task --template blank` to author another task. The blank starter explicitly uses word features and finite field classification; replace that pipeline if it does not suit your task. Schemas do not automatically select numeric encodings or transformations.
+
+## Import into React or Next.js
+
+The generated TypeScript wrapper needs no bundler plugin. This example assumes a component at your application root; adjust the relative path for your component's location. In Next.js, use a client component:
+
+```tsx
+"use client";
+
+import { useMatchbox } from "@matchbox-ai/core/react";
+
+const loadMoney = () => import("./.matchbox/money/model");
+
+export function MoneyButton() {
+  const { parse, status } = useMatchbox(loadMoney);
+
+  return (
+    <button
+      disabled={status !== "ready"}
+      onClick={async () => {
+        const result = await parse("twenty dollars");
+        if (result.status === "ok") console.log(result.value.amount);
+        else console.log(result.reason);
+      }}
+    >
+      Parse an amount
+    </button>
+  );
+}
+```
+
+Train before your application build. Generated artifacts remain ignored, so CI needs to train or restore a previously evaluated artifact. Import training helpers only in the authored pipeline and training scripts, never in client components. For `.matchbox` imports with Vite, the optional [Vite integration](react.md) remains available.
+
+## Run the repository showcase
+
+From the Matchbox checkout, `bun run dev` trains the examples and starts the showcase. The home page demonstrates customer filtering; `/training` demonstrates money parsing and the parity training check.
+
+Continue with [CLI](cli.md), [Evaluation](evaluation.md), [Training pipelines](pipelines.md), or [Project structure](project-structure.md).

package/docs/neural-training.md

@@ -0,0 +1,3 @@
+# Neural training
+
+See [pipelines](pipelines.md) for the supported native TensorFlow trainers and [evaluation](evaluation.md) for dataset separation and export checks. Examples use explicit pipeline.ts declarations; recipes and decoders are application-owned.