12  The cure method

Repairing a produced collection by measured iterations

12.1 Purpose

A PDAI collection that is already produced can still carry defects: lost footnotes, flattened tables, generation loops, apparatus entries filed as body text. The cure is the method for removing them. It differs from production in one respect: it never processes a collection as a whole. It measures, selects the defective pages, tests a remedy on a few of them, and applies it only where the measurement found the defect.

The method is written down in three places that state the same thing at different levels:

Level Location
Documentation (this part) pdai/docs/cure/
Instructions for agents pdai/skills/pipeline/pdai-cure/SKILL.md and one sub-skill per stage
Executable plan Partitur pdai-cure, pdai/skills/pipeline/pdai-cure/partitur.yaml, goal_path pipeline/cure/collection

12.2 Four rules

NoteRules of the cure
  1. Diagnose before repairing. No repair starts without a measured defect.
  2. Test before applying. A remedy is tried on 3–5 specimen pages before it touches a collection.
  3. Touch only defective pages. Pages with verdict ok are never processed again.
  4. Recompute downstream incrementally. Only changed pages go to later stages.

12.3 The loop

cure s0 0 Scope s1 1 Diagnose s0->s1 s2 2 Attribute s1->s2 s3 3 Remedy 3–5 specimen pages s2->s3 s4 4 Gate s3->s4 s4->s3 fail s5 5 Apply flagged pages only s4->s5 pass s8 8 Learn s8->s2 next defect class s7 7 Downstream delta s7->s8 s6 6 Certify s6->s7 s5->s6

One iteration handles one defect class. After stage 8 the next iteration begins at stage 2 with the next class of the attribution.

12.4 Iteration budget and stop criterion

Every iteration runs within a page budget and a time budget, declared in the collection’s config/cure.yaml:

budget:
  pages_per_iteration: 40
  minutes_per_iteration: 90
  specimen_min: 3
  specimen_max: 5

The runner reports pages beyond the budget as deferred and does not process them. A pilot with deferred pages fails. An iteration whose target metric does not improve ends with a report of the measurement; it does not start another run of the same remedy. This rule answers the failure that gave rise to the method: a repair session on copernicus-prim ran for half a day because each unsatisfactory result started a new collection-wide run instead of a narrower test (see the Copernicus case).

12.5 One processing agent at a time

Only one process that writes page XML or occupies the OCR engines runs at a time: the targeted re-OCR runner (ocr_runner.cure_run), the normalizer application (normalize_apply --apply), the overlay learning loop (ocr_runner.cure_learn) or a production run (ai-scholar process). On the M1 Ultra a second request to qwen3.8:27b-mlx saturates the GPU; it does not double throughput. The gate and apply ops of the Partitur refuse to start while another such process is live.

12.6 Chapters of this part

Chapter Stages
Diagnosis 0 Scope, 1 Diagnose
Attribution 2 Attribute
Remedy and gate 3 Remedy, 4 Gate
Application 5 Apply
Certification and downstream 6 Certify, 7 Downstream
Learning 8 Learn
Reference metrics, thresholds, models, CLI, schema package
The Copernicus case measured numbers and anti-patterns

The production pipeline that creates a collection is described in The Production Pipeline; the defect codes in Audit taxonomy.