Labelled samples¶

Nerthus.Core (until cutover). This page describes the frozen system that runs today and is deleted at cutover. Replaced by: not yet written.

Every project in the Nerthus normalization programme produces labelled data as a side effect — resolve verdicts, parse decisions, measured morphology, typed proposals — and deposits it into repozytorium-adnotacji, a data repository of annotations over corpus spans. This route reads that store, and publishes the census a consumer needs in order to read the rows correctly.

Routes¶

client/Cmdlets-Entities.ps1 wraps all three. Paths are relative to /v1/api; the cross-cutting contract is on the API reference index.

Get-NerthusTrainingSample returns the whole envelope rather than unwrapping to .items, because three fields change how the rows must be read: stats counts the whole store rather than the filter, coverage says the store is partial by construction, and doesNotCheck says what a presence surface cannot answer. A cmdlet returning the rows alone would drop all three.

The read is replica-safe and poolable. The two writes touch the annotation tree and no other, and both honour ?dryRun. They cost sample.confirm (since 2026-09-03, ruling H123.3), which the Narrator and Radny bundles carry — a narrator ruling on a row from the close-session screen writes the sample store and nothing in the entity index, so the price is not entity.write.

Where the rows live¶

corpora.adnotacje in config.json names the working tree, the same shape corpora.mc and corpora.dziel already use. A host with no tree answers available: false with a reason rather than failing — an unreachable store and an empty one are different facts and read differently to whoever asked.

The tree carries samples/<class>.jsonl, one JSON object per line, and a published copy of schema.json. The contract is authored and enforced in Nerthus.Lang.Annotations, which writes that copy and fails when the two diverge; the daemon reads the copy, because bucketing a row needs the contract and a count without buckets is the number this route exists not to publish alone.

Query parameters¶

Awaiting confirmation is ?grade=proposed, and a caller that also wants the weak supervision beside it asks ?grade=proposed,measured. That filter is the pending view, rather than a second endpoint over the same rows.

Rows are served in the order the class file holds them, and a depositing project may make that order mean something. Project 56 writes its two classes in the order a confirmation is worth most — fields.queue carries the tier, the rank and the cluster the row belongs to — so ?class=narration-subject&project=56-found-labels pages a ranked queue head first with no ordering parameter and no second surface. A class file holds several projects' rows in deposit order, so the ranking is meaningful within a project's own rows and ?project= is what selects them.

A misspelled class or grade is a 400 rather than an empty page: a caller who mistypes one deserves to hear so, not to conclude the store is empty.

?entity= — the rows about one name, and why it echoes¶

An unrecognised query parameter is dropped in silence. That is the default across the API and it is safe for most parameters and unsafe for this one: a client filtering by a name against a host that predates this filter would render the whole store as that one name's rows, which is worse than the feature's absence. So two things travel with it.

The filter echoes itself. ?entity=Riveth comes back as "entity": "Riveth" on the body. A consumer compares the echo against what it asked for and refuses to render when it is missing or differs — that comparison is the only way to tell a host that filtered from one that ignored the parameter.

A name the index does not hold is refused, matching what class and grade already do rather than the silent-ignore default. An empty page cannot be told apart from a typo.

GET /v1/api/training/samples?entity=Riveth&limit=200
200  { "entity": "Riveth", "filtered": 23, "count": 23, … }

GET /v1/api/training/samples?entity=NieMaTakiego
400  { "error": "TrainingSampleFilterInvalid",
       "detail": "UnknownEntity: 'NieMaTakiego' is not a name this index holds" }

Which classes it can reach is published, because most of them it cannot. A class names an entity only where the store's schema.json declares entity_fields for it, and the response carries both halves:

{ "entityCoverage": {
    "searched": ["all-caps-token-kind", "derived-word-base", "entity-mention", "entity-proposal",
                 "identity-claim", "name-declension", "normalization-suggestion", "vocative-form"],
    "blind": ["addressee-by-exclusion", "document-diegesis", "… 14 classes in all"] } }

8 of the store's 22 classes name an entity; 14 are blind to this filter at any value. That is a property of the data, not a defect — a location-separator row is about a line, not about a person — but a caller reading a small number without it would conclude a name has few rows when it has few reachable rows. The map lives beside the classes in the store's schema and never in the daemon, so a class that gains an entity field is reachable without a daemon change.

fields.resolved on vocative-form and all-caps-token-kind is what the resolver answered, with the stage beside it — {"name": "Torneg", "type": "Mapa", "stage": "exact"} — or null with fields.resolved_note. The stage is load-bearing: exact is a lookup and fuzzy is a guess, and the two must not be rendered alike. It is evidence about the surface and never a claim that the surface is that entity; the class that asserts an identity is identity-claim.

The queue: the order the rows arrive in¶

A class file is paged in the order the file holds it, so where a depositing project wrote its rows in a considered order, ?class=…&project=… pages that order head first. There is no sort parameter and no second surface — the ranking is a property of the rows.

Where a project has ranked its rows it also records why, in fields.queue, so the order is readable rather than implicit. The three tiers in the store today, measured 2026-08-12 at repozytorium-adnotacji-dev fc46ed1:

Within a tier the order is lexicographic over measured properties and never a weighted sum, because a weight is a constant somebody chose: cluster reach first — every claim naming the same subject — then row reach.

A class file holds several projects' rows in deposit order, so a ranking is meaningful within one project's rows and ?project= is what selects them. entity-proposal serves project 33's rows before project 56's.

The response¶

{
  "count": 20, "total": 9618, "limit": 20, "offset": 0,
  "available": true,
  "filtered": 9618,
  "items": [ ... ],
  "stats": { "total": 9618, "byClass": {}, "byGrade": {}, "byProject": {}, "byLabel": {},
             "split": {}, "evidenceForm": {}, "claimKeyFold": {} },
  "coverage": { "partial": true, "depositors": [ ... ], "note": "..." },
  "doesNotCheck": [ ... ]
}

stats counts the whole store; items and filtered describe the filter. A census computed over the caller's filter answers a different question every time it is asked, and the number a consumer needs from this surface is one it can compare against yesterday's.

A read that names a class parses that class's file and no other, and a scope it can search for as text narrows the parse to the lines that carry it; stats still counts the whole store, from a streaming pass that keeps six fields per row. Measured 2026-09-04: the old read parsed all 26 874 rows into objects for a one-row question, threw OutOfMemoryException inside dev-eder's 3 GB container, and the daemon answered nothing for ten minutes. An error that is not a bad parameter value is no longer reported as TrainingSampleFilterInvalid.

The census reports parts, never a total¶

A store surface that answers how many samples, by class and by grade and stops there is the shape that shipped an aggregate recall of 0.77 averaging 0.95 on one family with 0.32 on another, and told nobody anything until a reviewer split it. So every axis a consumer could be misled by is broken out.

split — the four document-identity buckets, and they reconcile. A train/eval split over this store must partition by document and never by row: several of these corpora are formulaic, so one statement recurs across many documents in slightly different wording, and a row-level split puts near-duplicates on both sides while the floors it produces read as healthy.

reconciles is true when the four sum to total. undocumented is the actionable number and the other three are published so it cannot be made to look small by rows quietly leaving the census. Counting instead every row lacking locator.document gives most of the store, which is true, unactionable, and therefore unread.

evidenceForm — per label, never per class. label is a printed field found by typography, phrase a fixed formula matched as a string, prose an ordinary sentence with a predicate. A per-class figure reports "mixed" and hides the one label a model would learn typography from: measured on 2026-08-11 over the store's governance-transition rows, set runs 21 label / 3 phrase / 1 prose while appoint in the same class runs 42 prose to 3 label. A model trained on set learns layout, and an eval set drawn from the same sieve scores it well. The no-form column counts rows written before the field existed.

claimKeyFold — how each class compares its claim key, and which classes nothing checks. A class may declare a claim_key, the fields identifying what a row claims rather than which row it is, and two rows sharing one are refused as a duplicate. That comparison is a string comparison, so each class also declares how the string is folded: ordinal keeps it as written, whitespace collapses \s+, name folds case as well. Five classes are one row per occurrence, carry no key at all, and are checked for duplicates by nothing — the entry reports keyed: false so that limit is visible rather than inferred from a silence.

Coverage is partial by construction¶

coverage.depositors is derived from the rows rather than declared, so it cannot go stale. The store holds what the projects that have run so far deposited, and a class with no rows is a project that has not deposited, never a measurement that the corpus holds none of that shape.

What the surface does not check¶

doesNotCheck is on every response rather than only in this page, because the consumer reads the body. A read surface answers presence, and presence is not correctness: a recall figure asks is the fact there and never is it there with the right date, and one sentence once produced two ledger rows sixteen days apart that no census could see. The list names that, the unkeyed classes, the fold each class lets through, and the fact that locator hashes are checked by the store's own validator rather than here.

Confirming a row¶

A row deposited proposed is a work-queue entry. A human ruling on it is what makes it a training label, and this is the path that records the ruling. It writes into the annotation tree and nowhere else: where a confirmation implies a lore edit — an accepted alias — that edit stays a separate operator gesture, as POST /normalization/aliases/accept already keeps it.

POST /v1/api/training/samples/confirm
{ "id": "40/governance-transition/N1", "class": "governance-transition", "outcome": "affirm" }

The author is never in the body. method.accepted_by.who comes from the caller's token identity — gracz:<margonem id>, api:<margonem id>, token:<name> — so a client cannot attribute a ruling to somebody who did not make it, and the whole value of a confirmed row is that somebody did.

The three outcomes, and why a rejection is a verdict rather than a label¶

All three land as one confirmed row, and all three set method.accepted_by: who, artifact, at, and verdict.

A denial keeps the label, because the label says what was denied. A label answers which kind; a verdict answers true or false.

The test is one question, asked class by class: does the vocabulary contain a value that denies what the row's existence presupposes? Re-measured 2026-08-12 at repozytorium-adnotacji-dev fc46ed1, nine of the twenty-two classes have no such value, and they hold 1 701 of the 1 816 rows awaiting a human and 2 425 of all 10 819. The nine are the same nine; the store has grown around them.

The other thirteen partition their question exhaustively — 115 proposed rows, 8 394 in all — and there denying and correcting are the same act. 1 701 + 115 = 1 816, and 2 425 + 8 394 = 10 819.

So the verdict rides beside the label. It costs no class an invented negative label, it leaves every claim key alone, and it is expressible for every class at once. A consumer trains positives on verdict: affirmed and takes denied rows as its negatives, reading label for what they are negative for.

verdict and at are refused at this write path and counted over the store, the posture fields.evidence_form and locator.document already hold: the 65 rows confirmed before the key existed carry neither and keep validating, and validate.py prints them in a NO-VERDICT column. An absent verdict reads as nobody recorded one, never as an affirmation.

What a ruling refuses¶

One body, both routes¶

Both confirmation routes answer the same shape, and the batch's job carries it as its result:

{ "applied": true, "count": 2, "confirmed": 1, "unchanged": 0, "refused": 1,
  "at": "2026-08-11T14:03:22Z",
  "items": [ { "id": "40/governance-transition/N1", "class": "governance-transition",
               "ok": true, "status": "confirmed", "label": "appoint",
               "verdict": "affirmed", "who": "gracz:2444", "at": "2026-08-11T14:03:22Z" },
             { "id": "40/governance-transition/N1", "class": "governance-transition",
               "ok": false, "error": "SampleAlreadyConfirmed", "detail": "…" } ] }

items is a list at both routes, including for a single decision — a shape that changes with the count is a shape every caller has to branch on. A refused row carries error and detail instead of status; the single-row route additionally maps that refusal onto an HTTP status, because a caller ruling on one row wants one answer.

Ruling on many rows at once¶

POST /v1/api/training/samples/confirmations
{ "decisions": [ { "id": "40/governance-transition/N1", "outcome": "affirm" },
                 { "id": "40/governance-transition/N2", "outcome": "deny" } ] }

Answers 202 with job, status and statusUrl; the per-row results are at GET /jobs/{id}/result, in the body above. The 202 is an envelope rather than a promise of later work: the job runs inline, so its record is already completed when the answer goes out and GET /jobs/{id} never reports running. That is also why decisions[] is capped at 250 — an uncapped batch is one request holding the accept loop — and a larger set is more requests. The 85 governance transitions project 40 deposited are one sitting's work, and the sprawozdania they were read from are formulaic and monthly, so one ruling on a representative shape covers many rows.

Per-row results, and one refusal costs its own row only. That differs from a deposit into the store, which is all-or-nothing because half a project's output is worse than none; a batch here is a set of independent human rulings, each carrying its own author, verdict and instant.

The audit trail¶

Ruling 5 of this surface is that every confirmation answers who confirmed what, when, and against which corpus state, and the durable record of it is the row itself: method.accepted_by carries the author and the instant, label and verdict carry the ruling, locator.content_hash pins the corpus state the locator is valid against, and the annotation repository's own history carries the sequence. Reading it back is GET /training/samples?grade=confirmed — a filter over the read route rather than a fourth endpoint.

The daemon writes one audit line per ruling beside that, op: sample.confirm, into the never-rotated audit stream (GET /logs/audit, log.read). That stream is this host's operational echo; the store is the record.

The capability, and what is wider than it¶

The read is log.read, and it is the price of what the rows quote rather than of the shape of the answer. Measured 2026-08-12 over the store's 10 819 rows at fc46ed1: 9 039 carry a quote, 5 535 of them quoting transcript bytes — 459 069 characters of transcript in all — and a floor of dated session headings the daemon serves under session.read. Eighteen routes over those same bytes cost log.read: every /entities/{name}/{history,lines,speech,scenes,hits,mentions,dossier, timeline} read and the five /logs/… reads. A derived read priced below the reads it derives from is a door around them, and entity.read sits in the gracz bundle while log.read does not — so the earlier price served the speaker-attribution surface to every authenticated player through one route while eighteen siblings refused it.

A caller who loses this route keeps every other one. log.read is held by Narrator, Radny, IT and admin; gracz and bot are the two bundles it is not in, and they are the two that could not reach /logs/lines either.

A new training.* resource family is the other coherent answer and is not taken here, on a mechanism rather than a preference. Role bundles come from a committed roles.json that the seeder writes only when the file is absent, so a new capability id reaches an already-adopted repository not at all until the Rada edits that table (Capabilities). Until then it resolves through admin.all alone, and a new family would ship a route almost nobody could reach. Named tokens compound it: a named token freezes its capability set at mint, so it does not see the edit until it is re-minted. Session tokens do not — they store only the role and capabilities are recomputed on every request, so the edit reaches them immediately. log.read is the smallest change that makes the price consistent, and a new family stays an ordinary addition on a route that is already correctly gated.

The two writes cost entity.write, and the choice is expedient rather than analysed. The operator ruled on 2026-08-11 that capability assignment belongs to a future project and that a route should take any fitting existing id until then, so this one takes the id the programme's only other confirmation path already spends — POST /normalization/aliases/accept. entity.write fits in the sense that matters here: its seeded population is the Radny bundle and admin.all and no other role, which is the body that rules on the books. It sits coherently beside a log.read read, because nobody reaches the confirmation path who could not already reach the rows it confirms. It has not been reviewed as an assignment, and this page does not claim it has.

What a row carries¶

The grades never blur, and that is structural. A trained layer trains and evaluates on confirmed, treats measured as weak supervision, and reads proposed as a work queue. The store's validator refuses a measured row with no threshold, a confirmed row with no named acceptance, and a proposed row carrying either. A verdict is therefore only expressible on a confirmed row: a verdict with no human behind it is a category error the grade coupling already forbids.

Examples¶

Every class and grade, with the census:

GET /v1/api/training/samples?limit=1

What is awaiting a human ruling, one class at a time:

GET /v1/api/training/samples?class=governance-transition&grade=proposed&limit=20

One depositing project's rows:

GET /v1/api/training/samples?project=41-governance-epochs&limit=5

Ruling that a proposal is wrong, without claiming to know what is right:

POST /v1/api/training/samples/confirm
{ "id": "33/normalization-suggestion/alias/Harumcia", "outcome": "deny",
  "note": "to nie jest zdrobnienie od tej postaci" }

Ruling that it is right but mislabelled:

POST /v1/api/training/samples/confirm
{ "id": "33/entity-mention/Anela/01", "outcome": "correct", "label": "human" }

See also¶

• Entities — GET /normalization/suggestions, whose output the store records
• Capabilities — the capability list and the role bundles
• Configuration — corpora.adnotacje and the other configured working trees
• Search — the tier split this route defers