Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,12 @@ entry per wave, newest first; the first six waves (V1–V6, the MVP) predate the
are recorded in PLAN.md §B and §J. Each entry carries the opening sentence of its row and
the reason the wave was built.

## V68 — Counterfactuals: what would have to change

F7, the last feature proposed.

_Why:_ Approved 13/11/2026. A learner who trains here should be able to carry the run to a notebook and see, in figures, what changed on the way.

## V67 — Early stopping for the boosting: measured, and not built

F9, opened by V66, which had shown the boosting's validation error lowest well before its 120th round on 17 runs of 30.
Expand Down
8 changes: 4 additions & 4 deletions PLAN.md

Large diffs are not rendered by default.

12 changes: 7 additions & 5 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -91,6 +91,7 @@ The project follows three non-negotiable principles:
| Python bridge | **A run, redone with scikit-learn.** One readable script carries the row numbers of each split and the preprocessing, and translates each model to its nearest estimator. It does not promise the lab's figures: it prints them next to its own, with the gap. Measured on 30 runs: the encoded matrix is equal to within 2.9e-14, the baseline, the linear regression and the naive Bayes agree to the last digit, k-NN agrees until two neighbours tie, and the hand-written families differ by up to several test rows on one split. A column name is never code: the run travels as one JSON block. |
| Competition path | **An unlabelled file becomes a submission.** Under a scored batch, one block writes an identifier and a prediction under the names the platform expects: a class, a probability or a value, every row kept in its order, missing and repeated identifiers counted. The lab guesses neither the identifier nor the names. The same family can be **fitted again on every labelled row**, announced as a model nobody measured: on the demos, against rows kept away from both models, it gained 5 accuracy points on the smallest text file, 0.8 on titanic, 2 to 3 % of RMSE on two regressions, nothing on two others, and lost one time in five to one in three even where it paid |
| Glass box | **One row, replayed through the model.** Beside the Shapley explanation (what weighed), a replay tells what happened: the questions a decision tree asked, in the units of the file, and the training rows that share its leaf; the count of a forest's 40 trees; the five rows of the file a k-NN compared it to, with its ties flagged; the prediction a boosting builds round after round, and its error on the validation rows. The replay walks the model itself: measured on 2,560 test rows of the demos, its last step is the model's answer on every one. The replay showed the boosting's validation error turning well before its last round; early stopping was then measured on rows kept away from everything and **not built**: fewer rounds improved the probabilities, not the predictions |
| Counterfactuals | **What would have to change.** For one row of a classification, the smallest change, one column or two, that makes the inspected model answer another class: only values the training rows hold, the columns the user locks left alone, free text never edited, and a plain « nothing found » with what was tried. Each change carries two readings the measure made necessary: whether the changed row still looks like a training row (8 to 60 % of the nearest changes did not), and how many of the other trained models follow it (14 to 54 % did). A counterfactual speaks of the model, not of the world |
| Speed | Heavy families train on **helper cores** (announced on the leaderboard, split by measured cost, never silent), and a model crosses back as JSON so it is rebuilt through the same path an imported model uses. Measured on a 60 000-row run: **74 s → 9.5 s**, with every leaderboard number identical. Every best-effort step that gives up is recorded in a **run journal** shown with the leaderboard and in the report: which step, which family, how many times, and the error it met |
| Persistence | Local run history with attached artifacts, opted-in dataset storage (compressed, explicit 50 MB budget), self-contained HTML reports, data-free share links (a damaged link is refused, never half-rendered) |
| Model card | A page for whoever must **decide to use** the model, in HTML or Markdown: intended use, data, performance with its interval, the selection gap, prediction-set coverage, the decision rule, where it fails, the run journal, and limits. The intended use is typed by the user; left empty the card says « not stated » and calls itself incomplete rather than guessing. Every analysis the run does not carry is listed under « Not assessed », and each section names the model it describes when that is not the winner |
Expand Down Expand Up @@ -282,12 +283,12 @@ Wikimedia Commons), the portrait is NASA, public domain._
so), slow model families train on measured, announced caps scored against the same
full test set, and parsing refuses past a named 20M-cell memory budget instead of
letting the tab die, in every section and for a batch to score.
- **Performance.** Every page — the sections, the home page and each of the fourteen
- **Performance.** Every page — the sections, the home page and each of the fifteen
documentation URLs — serves a prerendered static shell (hero paints before JavaScript;
a doc page carries its whole article, in English until the app mounts); Lighthouse
mobile ≈ 0.99 on `/ml` under real throttling. Heavy dependencies (Dexie, SheetJS, ONNX
Runtime) load lazily.
- **Quality bar.** 1294 unit tests and 133 Playwright end-to-end tests across five
- **Quality bar.** 1320 unit tests and 134 Playwright end-to-end tests across five
projects — desktop, a phone viewport in English and in French, dark mode, and
Cloudflare Pages' own routing emulated by `wrangler pages dev` (a real 404, the security
headers as served) — covering offline PWA, a fake webcam, a horizontal-overflow guard on
Expand Down Expand Up @@ -404,9 +405,10 @@ has arbitrated (V60), a production check that reads a new batch against a refere
carried by the model export (V61), and a noise ceiling under the Data Studio's drift
report, which had been calling small files drifted (V62), a data contract that
requires of the next file what was found on a reference (V63), and a scikit-learn script
that redoes a run outside the browser and measures its own gap (V64). Proposed, each with its launch condition and none
scheduled: counterfactuals, a step-by-step view of the hand-written models, and a
competition path from an unlabeled file to a submission. The consented generative chat (V12) stays
that redoes a run outside the browser and measures its own gap (V64), a submission file
for a competition (V65), a step-by-step replay of one row through the model (V66), early
stopping for the boosting, measured and not built (V67), and counterfactuals (V68). No
feature is proposed at the moment. The consented generative chat (V12) stays
postponed by product decision. No wave starts without an explicit launch command. The full plan, delivery log and design decisions live in
[PLAN.md](PLAN.md); [CHANGELOG.md](CHANGELOG.md) is extracted from it — one entry per
wave, newest first — by `npm run changelog`, and a test fails when the two disagree.
Expand Down
57 changes: 57 additions & 0 deletions e2e/counterfactual.spec.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,57 @@
import { expect, test } from '@playwright/test';

test.use({ locale: 'en-US' });
test.setTimeout(120_000);

// NOTE: keep this title ASCII-only: it names the test-results directory.
test('counterfactual: a change found is loaded and flips the prediction shown', async ({
page,
}) => {
await page.goto('/ml?demo=fraud&target=status');
await page.getByTestId('train-button').click();
await expect(page.getByTestId('train-again')).toBeVisible({ timeout: 60000 });
await page.getByRole('cell', { name: /Logistic regression/ }).click();

const prediction = page.getByTestId('what-if-prediction');
await expect(prediction).toBeVisible({ timeout: 30000 });
const before = (await prediction.textContent())!.trim();

await page.getByTestId('counterfactual-button').click();
const box = page.getByTestId('counterfactual');
await expect(box).toBeVisible({ timeout: 30000 });
await expect(box).toContainText(`stop answering "${before}"`);
const first = box.getByTestId('counterfactual-item').first();
await expect(first).toBeVisible();
// The first change names its column: lock that one and ask again.
const column = (await first.locator('span').first().textContent())!.split(':')[0].trim();
await expect(first).toContainText('The model then answers');
await expect(first.getByTestId('counterfactual-followed')).toContainText(
'other models that agreed',
);
await expect(box).toContainText('A counterfactual speaks of the model, not of the world');

// Loading it changes the row, and the prediction shown is the class announced.
await first.getByTestId('counterfactual-apply').click();
await expect(prediction).not.toHaveText(before, { timeout: 30000 });
// A new row empties the answer, which described the previous one.
await expect(page.getByTestId('counterfactual')).toHaveCount(0);

// Locked, the column is left alone and named.
await page.getByTestId(`lock-${column}`).check();
await page.getByTestId('counterfactual-button').click();
const again = page.getByTestId('counterfactual');
await expect(again).toBeVisible({ timeout: 30000 });
await expect(again.getByTestId('counterfactual-kept')).toContainText(
`Left as they are because you locked them: ${column}.`,
);
for (const item of await again.getByTestId('counterfactual-item').all()) {
await expect(item.locator('span').first()).not.toContainText(`${column}:`);
}

// A regression has no other class to reach: the button is not offered.
await page.goto('/ml?demo=mpg&target=mpg');
await page.getByTestId('train-button').click();
await expect(page.getByTestId('train-again')).toBeVisible({ timeout: 60000 });
await expect(page.getByTestId('what-if-prediction')).toBeVisible({ timeout: 30000 });
await expect(page.getByTestId('counterfactual-button')).toHaveCount(0);
});
4 changes: 2 additions & 2 deletions package-lock.json

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 1 addition & 1 deletion package.json
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
{
"name": "labml",
"private": true,
"version": "1.67.0",
"version": "1.68.0",
"license": "MIT",
"type": "module",
"engines": {
Expand Down
94 changes: 94 additions & 0 deletions src/content/docs/en/find-a-counterfactual.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,94 @@
---
slug: chercher-un-contrefactuel
kind: how-to
order: 7
title: Find what would change a prediction
summary: For one row, the smallest change of its values that makes the model answer another class, and how far to trust it.
---

## The gesture

1. Train a classification model and click a family in the leaderboard to inspect it.
2. In **What if…**, set the values of one row.
3. Tick **locked** on the columns that cannot change for this case: an age, a sex, a
past event. The lab does not guess them.
4. Click **What would have to change?**

:::try /ml?demo=titanic&target=survived | Train titanic and look for a change

Each answer is a change you could have typed yourself, « `pclass`: 3 → 1 », with a
button to load it into the form and see the prediction move.

## How the search works

It is a search a reader can follow, not an optimisation:

1. **one column at a time.** Every value the training rows hold for that column is
tried in place of the row's own; the column keeps the nearest one that changes
the answer;
2. **two columns together**, only when no single column changes the answer;
3. **never three.** A change of five columns is no longer an explanation.

Only values some training row holds are tried: no number outside the file, no
category that does not exist, nothing interpolated. Free-text columns are never
edited. With three classes or more you can ask for one class in particular.

When nothing changes the answer within these limits, the panel says so and says
how many rows it tried. That is an answer too: for this model, this row is far
from any other class.

## What the measure showed

On the classification demos, 60 test rows per run, seven families:

| Demo | One column is enough | Two are needed | Nothing found |
| ------- | -------------------- | -------------- | ------------- |
| titanic | 63 to 98 % of rows | 2 to 30 % | 0 to 9 % |
| fraud | 28 to 100 % | 0 to 69 % | 0 to 9 % |
| iris | 96 to 100 % | 0 to 4 % | none |
| reviews | 0 to 100 % | 0 to 38 % | 0 to 100 % |

On reviews most models find nothing: the answer is in the text, which the search
does not edit.

Two findings shaped the panel.

## Reading one: does the changed row still exist?

A row built from values that each exist can still look like no row at all. The
first search kept the nearest change whatever it was, and **8 to 60 % of its
answers were farther from every training row than training rows usually are from
each other**: the model was answering where it had seen nothing.

So the search now prefers, for each column, the nearest change that stays inside
the cloud of training rows, and flags the ones that do not. On iris about half
the answers stay flagged whatever is tried: its four columns move together, and
changing one alone leaves the cloud.

The lab also does not know that two columns say the same thing. On titanic,
`sex`, `who` and `adult_male` describe one fact; changing `adult_male` alone
describes a passenger who cannot exist. Lock the columns that duplicate another,
or better, leave them out of the features.

## Reading two: do the other models follow?

The smallest change that flips a model lands just across its boundary. Measured:
of the other trained models that agreed on the row, **only 14 to 54 % answered the
new class** for the same change.

So each answer says how many of the other models follow. A change most of them
follow says something about the data. A change only this model follows is an edge
of this model.

## A counterfactual speaks of the model, not of the world

« The model would answer yes with an income of 52 » is not « earn 52 and you will
get yes ». The model learned which values go together in the file, not what
causes what. Use a counterfactual to understand and to challenge a model, not as
advice to the person the row describes.

## Where to go next

- [Replay a prediction](/docs/rejouer-une-prediction) to read the steps the model took.
- [The limits](/docs/limites) for what the search does not do.
- [The ML Lab reference](/docs/reference-ml) for the rest of the what-if panel.
Loading
Loading