@pablotech/akesi 0.1.22

package/benchmarks/retry-corrections.ts

@@ -0,0 +1,231 @@
+// A sampled benchmark on the one retry claim this package actually rests on: when an attempt is
+// rejected, does sending EVERY prior rejection beat sending only the latest?
+//
+// README.md § "When the model gets it wrong" states it as fact — "the model fixed each named
+// problem and broke a different one" — from a single six-attempt run. That is an anecdote, and an
+// anecdote about a discipline that exists to catch failures cannot be checked in a regime where
+// nothing fails. So the cases below are chosen to make the validator fire: lab units a model has a
+// strong prior against (a lab reporting protein in g/L when the model wants g/dL), several of which
+// ALSO require an imperial explanation. Two independent conditions is the structure the claim is
+// about — fix one, break the other.
+//
+// Why this is the right subject where a binary rubric was not:
+//   - it compares two strategies, which is the question compareBrains exists for;
+//   - the outcome has a gradient (attempts until valid, censored), so it does not saturate;
+//   - the verdict is the package's own shipped validate(), not a rubric written to be passed.
+//
+// The two strategies differ ONLY in what is passed to correctionSuffix — the same shipped function,
+// the same wording, one list against its last element. So the comparison isolates accumulation and
+// cannot quietly be measuring a reworded prompt. ../tests/retry-corrections-bench.test.ts asserts
+// exactly that, offline.
+//
+// Never part of `npm test`: it issues real model calls. No client is constructed here and no key is
+// read; the host supplies both, because ../../ARCHITECTURE.md is explicit that neither package
+// imports the other and a host is what joins them.
+//
+//   npx tsx benchmarks/retry-corrections.ts --preview   # the prompt, both suffixes, the call budget
+import type Anthropic from "@anthropic-ai/sdk";
+import { fileURLToPath } from "node:url";
+import { systemPromptFor, rangesUserMessage, RANGE_SCHEMA, validate, type RangeAIResponse } from "../ranges-prompt";
+import { correctionSuffix } from "../finding-generate";
+import type { Client } from "../types";
+
+export const MAX_TOKENS = 1024;
+
+/** The shipped ceiling. README.md § "When the model gets it wrong" derives it from cost, so the
+ *  benchmark measures the loop that actually runs rather than an idealized unbounded one. */
+export const MAX_ATTEMPTS = 3;
+
+/** The score for a case that never validated. One worse than the ceiling, so "failed" is ordered
+ *  after "succeeded on the last attempt" without pretending to know how many more it would need. */
+export const CENSORED = MAX_ATTEMPTS + 1;
+
+export interface RetryCase {
+  label: string;
+  client: Client;
+  marker: string;
+  /** What the lab reported in, and therefore what validate() requires back. */
+  expectedUnit: string;
+}
+
+export interface Strategy {
+  label: "accumulate" | "replace";
+  /** What gets appended to the user message after `priorRejections` failed attempts. */
+  suffix: (priorRejections: string[]) => string;
+}
+
+export const VERSIONS: Strategy[] = [
+  // The shipped behaviour: every rejection so far.
+  { label: "accumulate", suffix: correctionSuffix },
+  // The plausible alternative, and what the two call sites sent before this was fixed: the latest
+  // rejection only. Same function, so the wording is byte-identical for a given list.
+  { label: "replace", suffix: (prior) => correctionSuffix(prior.slice(-1)) },
+];
+
+const DATES = ["2024-02-14", "2024-09-03", "2025-04-21", "2025-11-08", "2026-05-19"];
+const GOALS = ["lower ApoB", "improve insulin sensitivity", "preserve lean mass", "lower inflammation"];
+const FOCUS = ["cardiovascular", "metabolic", "body composition", "inflammatory"];
+
+function labCase(
+  i: number,
+  marker: string,
+  unit: string,
+  dob: string,
+  gender: "male" | "female",
+  values: number[],
+): RetryCase {
+  const client: Client = {
+    displayName: `Bench ${String(i).padStart(2, "0")}`,
+    dob,
+    gender,
+    watchlist: [marker],
+    results: values.map((value, j) => ({ marker, group: "Chemistry", source: "lab", date: DATES[j], value, unit })),
+    factors: { goal: GOALS[i % GOALS.length], focus: FOCUS[i % FOCUS.length], athletic: "moderate" },
+  };
+  return { label: `${marker} in ${unit}`, client, marker, expectedUnit: unit };
+}
+
+// Twelve synthetic patients, no PHI. Every unit here is one a lab really reports and a model really
+// tends to answer in something else — SI where the model reaches for conventional US units, and in
+// four cases (g/L, cm, kg) a unit that ALSO makes explanationImperial mandatory. That second
+// condition is the point: it is what lets an attempt fix the unit and lose the imperial line.
+export const CASES: RetryCase[] = [
+  labCase(1, "Total Protein", "g/L", "1958-03-11", "male", [68, 71, 70]),
+  labCase(2, "Albumin", "g/L", "1990-07-22", "female", [42, 44, 43, 45]),
+  labCase(3, "Hemoglobin", "g/L", "1975-01-05", "male", [148, 152, 150]),
+  labCase(4, "Glucose", "mmol/L", "1982-11-30", "female", [5.1, 5.4]),
+  labCase(5, "Total Cholesterol", "mmol/L", "1965-06-18", "male", [4.8, 5.2, 5.0, 4.9, 5.1]),
+  labCase(6, "Triglycerides", "mmol/L", "1988-09-02", "female", [1.1, 1.3, 1.2]),
+  labCase(7, "Creatinine", "µmol/L", "1970-04-14", "male", [82, 88, 85, 90]),
+  labCase(8, "Vitamin D, 25-OH", "nmol/L", "1993-12-25", "female", [62, 71, 68]),
+  labCase(9, "Ferritin", "µg/L", "1960-02-09", "male", [120, 145]),
+  labCase(10, "Testosterone, Total", "nmol/L", "1978-08-17", "male", [15.2, 16.8, 14.9]),
+  labCase(11, "Waist Circumference", "cm", "1985-05-27", "female", [82, 80, 79, 81]),
+  labCase(12, "Body Weight", "kg", "1955-10-03", "male", [78.4, 77.1, 76.5]),
+];
+
+/** k independent samples per case, expressed as k copies of the case list. compareBrains scores a
+ *  flat array, so replicates need no API change — and variance across identical cases is the only
+ *  way to tell a real difference from one sampling run. */
+export function withReplicates(cases: RetryCase[], k: number): RetryCase[] {
+  return Array.from({ length: k }, (_, r) => cases.map((c) => ({ ...c, label: `${c.label} #${r + 1}` }))).flat();
+}
+
+export interface RetryOutcome {
+  /** 1..MAX_ATTEMPTS when it validated; CENSORED when it never did. */
+  attempts: number;
+  ok: boolean;
+  /** The validator's own messages, in order — what each strategy had available to send. */
+  rejections: string[];
+}
+
+/** The retry loop, shaped exactly like generateFindingResponse's: build the message, call, validate,
+ *  and on rejection append the validator's message and go again. The only thing the strategy
+ *  changes is which of those messages the next attempt gets to see. */
+export async function runCase(
+  anthropic: Anthropic,
+  model: string,
+  c: RetryCase,
+  strategy: Strategy,
+): Promise<RetryOutcome> {
+  const rejections: string[] = [];
+  for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
+    const response = await anthropic.messages.create({
+      model,
+      max_tokens: MAX_TOKENS,
+      system: [{ type: "text", text: systemPromptFor(c.client) }],
+      output_config: { format: { type: "json_schema", schema: RANGE_SCHEMA } },
+      messages: [{ role: "user", content: rangesUserMessage(c.client, c.marker) + strategy.suffix(rejections) }],
+    });
+    const textBlock = response.content.find((b) => b.type === "text");
+    let parsed: RangeAIResponse | null = null;
+    if (textBlock && textBlock.type === "text") {
+      try {
+        parsed = JSON.parse(textBlock.text) as RangeAIResponse;
+      } catch (e) {
+        rejections.push(`response was not valid JSON: ${(e as Error).message}`);
+        continue;
+      }
+    }
+    if (!parsed) {
+      rejections.push("no text block in response");
+      continue;
+    }
+    try {
+      validate(c.marker, c.expectedUnit, parsed);
+      return { attempts: attempt, ok: true, rejections };
+    } catch (e) {
+      rejections.push((e as Error).message);
+    }
+  }
+  return { attempts: CENSORED, ok: false, rejections };
+}
+
+/** Attempts until the package's own validate() passed, censored at CENSORED. Lower is better —
+ *  the one place in this repo where a lower mean is the better result, which BENCHMARKS.md says
+ *  next to the table rather than leaving to be inferred. */
+export function score(result: RetryOutcome): number {
+  return result.attempts;
+}
+
+/** Reported alongside the mean, never instead of it: a mean over censored values hides a difference
+ *  that is entirely in the failure rate. */
+export function successRate(outcomes: RetryOutcome[]): number {
+  return outcomes.length === 0 ? 0 : outcomes.filter((o) => o.ok).length / outcomes.length;
+}
+
+/** Wilson score interval — the right interval for a proportion at small n, where the textbook
+ *  normal approximation puts the bound above 1 and reports [1.00, 1.00] for a clean sweep. */
+export function wilson(successes: number, n: number, z = 1.96): [number, number] {
+  if (n === 0) return [0, 1];
+  const p = successes / n;
+  const d = 1 + (z * z) / n;
+  const centre = p + (z * z) / (2 * n);
+  const half = z * Math.sqrt((p * (1 - p)) / n + (z * z) / (4 * n * n));
+  return [Math.max(0, (centre - half) / d), Math.min(1, (centre + half) / d)];
+}
+
+/** Exact two-sided sign test over the discordant pairs — the cases where the two strategies
+ *  disagreed. Paired, because both strategies run the same case: the cases differ enormously in
+ *  difficulty, and an unpaired comparison spends most of its power on that instead of on the
+ *  strategy. Ties carry no information about direction and are excluded, which is the test. */
+export function signTest(wins: number, discordant: number): number {
+  if (discordant === 0) return 1;
+  const tail = Math.min(wins, discordant - wins);
+  let sum = 0;
+  let c = 1;
+  for (let i = 0; i <= tail; i++) {
+    sum += c;
+    c = (c * (discordant - i)) / (i + 1);
+  }
+  return Math.min(1, (2 * sum) / Math.pow(2, discordant));
+}
+
+/** The smallest number of discordant wins that would reach p < 0.05 — the minimum detectable
+ *  effect, pre-registered rather than discovered afterwards. Returns Infinity when no split of
+ *  `discordant` pairs can reach significance, which is the honest answer at very small n and the
+ *  reason to compute it BEFORE spending on a run. */
+export function minimumDetectableWins(discordant: number, alpha = 0.05): number {
+  for (let w = Math.ceil(discordant / 2); w <= discordant; w++) if (signTest(w, discordant) < alpha) return w;
+  return Infinity;
+}
+
+function main(): void {
+  const replicates = process.argv.includes("--replicates") ? Number(process.argv[process.argv.indexOf("--replicates") + 1]) : 1;
+  const cases = withReplicates(CASES, replicates);
+  const rejections = [
+    `range for "Total Protein" returned unit "g/dL" but lab data is in "g/L"`,
+    `range for "Total Protein" (unit g/L) missing imperial explanation`,
+  ];
+  const [accumulate, replace] = VERSIONS;
+  process.stdout.write(
+    `retry-corrections: ${cases.length} cases × ${VERSIONS.length} strategies × up to ${MAX_ATTEMPTS} attempts ` +
+      `= at most ${cases.length * VERSIONS.length * MAX_ATTEMPTS} calls\n` +
+      `This module makes no calls itself; a host drives it through compareBrains (see BENCHMARKS.md).\n\n` +
+      `--- the user message (case 1, attempt 1) ---\n${rangesUserMessage(CASES[0].client, CASES[0].marker)}\n\n` +
+      `--- after two rejections, "${accumulate.label}" appends ---\n${accumulate.suffix(rejections)}\n\n` +
+      `--- after the same two, "${replace.label}" appends ---\n${replace.suffix(rejections)}\n`,
+  );
+}
+
+if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) main();

package/dates.ts

@@ -0,0 +1,36 @@
+// Authored-date helpers. Dates entered in the app are ISO strings; legacy values were month-only
+// (`YYYY-MM`, from the old month pickers). The convention: a partial date means the last day of that
+// period (the agreed migration rule), so both display and comparison are deterministic.
+
+const MONTHS = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"];
+
+// Coerce a partial ISO date to the last day of its month/year: "2026-04" → "2026-04-30",
+// "2026" → "2026-12-31". Full dates and "" pass through. Idempotent — safe to apply repeatedly.
+export function endOfMonth(iso: string | undefined | null): string {
+  if (!iso) return "";
+  const [y, m, d] = iso.trim().split("-");
+  if (!y) return "";
+  if (d) return iso.trim();
+  if (!m) return `${y}-12-31`;
+  // Day 0 of the next month is the last day of month `m` (1-based), so `new Date(y, m, 0)` — used
+  // only to count days, never for display, so no timezone drift.
+  const last = new Date(Number(y), Number(m), 0).getDate();
+  return `${y}-${m.padStart(2, "0")}-${String(last).padStart(2, "0")}`;
+}
+
+// Human, unambiguous date: "Apr 30, 2026". Partial values are coerced to end-of-month first. Parsed
+// from the ISO string directly (not `new Date(iso)`), so it never drifts a day across timezones.
+export function formatDay(iso: string | undefined | null): string {
+  const full = endOfMonth(iso);
+  if (!full) return "";
+  const [y, m, d] = full.split("-");
+  return `${MONTHS[Number(m) - 1]} ${Number(d)}, ${y}`;
+}
+
+// M107 — a type="date" input fires `change` on every keystroke inside an already-plausible year
+// segment, zero-padded (e.g. typing just "2" of "2026" reports "0002-08-15") — not only once the
+// full year is typed. A plain truthiness/length check on `value` fires on that first padded digit.
+// Require a 4-digit year that isn't itself a padding artifact (<1000) before treating it as done.
+export function isCompleteDate(value: string): boolean {
+  return !!value && Number(value.slice(0, 4)) >= 1000;
+}

package/document-model.ts

@@ -0,0 +1,96 @@
+// The transport half of "send a document to Claude and get JSON back", lifted out of
+// report-extract.ts so the structured report extraction and the new plain-prose document reading
+// (document-read.ts) cannot drift apart in how they assemble content, cap output, or report a
+// failure. Pure of Node/process/env for the same reason report-extract.ts is: a Node caller, an
+// edge-runtime caller and a browser-facing relay all run the identical code path.
+//
+// The thrown message PREFIXES are load-bearing, not cosmetic: a caller separates "the model
+// produced something unusable" from a transport error by matching on them. They are API.
+import type Anthropic from "@anthropic-ai/sdk";
+
+// The document to read: already-extracted plaintext (a Node caller, via pdfjs; or a .txt/.md
+// attachment read straight through) OR the raw PDF bytes as base64, which go to Claude as a native
+// `document` block — an edge runtime has no pdfjs.
+export type DocumentSource = { text: string } | { pdfBase64: string };
+
+// Structural — a caller's own usage accumulator satisfies this, so no cost-accounting module is
+// dragged in. Lives here rather than in report-extract.ts so both readers can record usage without
+// importing the report module.
+export interface UsageRecorder {
+  // Field types mirror the Anthropic SDK's Usage (nullable numbers) so response.usage passes
+  // straight through.
+  record(
+    model: string,
+    usage:
+      | {
+          input_tokens?: number | null;
+          output_tokens?: number | null;
+          cache_creation_input_tokens?: number | null;
+          cache_read_input_tokens?: number | null;
+        }
+      | null
+      | undefined,
+  ): void;
+}
+
+export interface DocumentModelCall {
+  anthropic: Anthropic;
+  source: DocumentSource;
+  /** Only ever used to name the file in the prompt and in error messages. */
+  sourceFile: string;
+  system: string;
+  /** JSON Schema. Index-signature shaped, which is what the SDK's output_config requires. */
+  schema: { [key: string]: unknown };
+  /** The instruction that accompanies the document, e.g. "Extract the report as JSON." */
+  instruction: string;
+  model: string;
+  maxTokens: number;
+  usage?: UsageRecorder;
+}
+
+/**
+ * One document in, one validated-shape-free JSON object out. Callers own their own validation —
+ * this only guarantees the response was a complete, parseable JSON body.
+ */
+export async function readDocumentAsJson<T>(call: DocumentModelCall): Promise<T> {
+  const { anthropic, source, sourceFile, system, schema, instruction, model, maxTokens, usage } = call;
+
+  // Document block first, text last — the ordering Anthropic recommends for document/image inputs,
+  // and the one leaf-regen-anthropic.ts mirrors for images.
+  const content =
+    "text" in source
+      ? `Document file: ${sourceFile}\n\n--- BEGIN DOCUMENT ---\n${source.text}\n--- END DOCUMENT ---\n\n${instruction}`
+      : [
+          {
+            type: "document" as const,
+            source: { type: "base64" as const, media_type: "application/pdf" as const, data: source.pdfBase64 },
+          },
+          { type: "text" as const, text: `Document file: ${sourceFile}\n\n${instruction}` },
+        ];
+
+  const response = await anthropic.messages.create({
+    model,
+    max_tokens: maxTokens,
+    system: [{ type: "text", text: system, cache_control: { type: "ephemeral" } }],
+    output_config: { format: { type: "json_schema", schema } },
+    messages: [{ role: "user", content }],
+  });
+
+  if (response.stop_reason === "max_tokens") {
+    throw new Error(`extraction truncated (hit max_tokens) for "${sourceFile}" — raise max_tokens`);
+  }
+  const textBlock = response.content.find((b) => b.type === "text");
+  if (!textBlock || textBlock.type !== "text") {
+    throw new Error(
+      `no text block in response for "${sourceFile}" — stop_reason=${response.stop_reason}, types=${response.content.map((b) => b.type).join(",")}`,
+    );
+  }
+  let parsed: T;
+  try {
+    parsed = JSON.parse(textBlock.text) as T;
+  } catch {
+    throw new Error(`invalid JSON for "${sourceFile}": ${textBlock.text.slice(0, 200)}`);
+  }
+  usage?.record(model, response.usage);
+  return parsed;
+}

package/document-read.ts

@@ -0,0 +1,171 @@
+// Reading an attached document as PROSE — the general-purpose counterpart to report-extract.ts's
+// structured extraction. Reports needs a schema (diseases/markers/comorbidities); a note, a chat
+// turn or a treatment needs the document's own words, so they can be quoted and reasoned over.
+//
+// Text out, not a schema, because every consumer downstream wants something quotable: a leaf turn
+// folds it in as context, chat discusses it, the UI shows how much was read. The one structured
+// field that IS returned is `isMedicalReport` — the owner's decision that Reports must reject a
+// non-report while Chat and Notes accept anything. Getting it from the same call the transcription
+// comes from means the gate costs nothing extra.
+import type Anthropic from "@anthropic-ai/sdk";
+import { readDocumentAsJson, type DocumentSource, type UsageRecorder } from "./document-model";
+
+// A transcription is bounded by the document, not by the model's inclination to keep writing; 16k
+// output tokens is roughly 60 pages of dense clinical prose, comfortably past MAX_DOCUMENT_PAGES.
+export const DOCUMENT_READ_MAX_TOKENS = 16_000;
+
+// The page ceiling, checked in the browser BEFORE upload (attachment-store.ts, via pdf-render's
+// openPdf().numPages). Without it a 200-page PDF is billed in full as input and only then fails on
+// the output ceiling — you pay for everything and get nothing.
+export const MAX_DOCUMENT_PAGES = 60;
+
+export interface DocumentReading {
+  /** A short human label for what the document is, e.g. "Radiology report", "Supplement label". */
+  documentKind: string;
+  /** True only for a clinical/lab/imaging report about a patient — the Reports import gate. */
+  isMedicalReport: boolean;
+  /** Present when isMedicalReport is false: one sentence saying what this is instead. */
+  notReportReason?: string;
+  /** The document's content as prose. */
+  text: string;
+}
+
+/** What the R2 sidecar holds, and what /api/document-extract returns — the reading plus provenance. */
+export interface StoredExtraction extends DocumentReading {
+  at: string;
+  chars: number;
+  model?: string;
+}
+
+// How much of one document's text may ride along with a turn, and how much may in total. A
+// transcription is bounded by MAX_DOCUMENT_PAGES, but a patient with several long documents on one
+// leaf could still assemble a request larger than the relay's body cap — and unlike an image, text
+// truncates gracefully. Truncation is always announced in the injected text, never silent.
+export const MAX_DOCUMENT_CHARS = 60_000;
+export const MAX_DOCUMENTS_TOTAL_CHARS = 150_000;
+
+/** One document's extracted text, named, ready to ride along with a turn. */
+export interface DocumentText {
+  name: string;
+  text: string;
+}
+
+/**
+ * The per-document and total caps, applied.
+ *
+ * This was enforced in the BROWSER only (a host-side extraction client), so the caps described
+ * two lines up as bounding "a request" bounded nothing a caller could not opt out of: the relay
+ * validated `documents` for shape and passed it straight to Anthropic, leaving a CLI or a scripted
+ * caller bounded by the 8 MB body cap alone — 8 MB of text into a prompt whose max_tokens assumes
+ * far less. Same rule, same wording, both sides of the relay; the browser now calls this rather than
+ * carrying its own copy of the arithmetic.
+ *
+ * Truncates rather than rejects, because a document that is too long is still worth reading most of,
+ * and the cut is always announced IN the text so the model never treats an excerpt as complete.
+ */
+export function capDocuments(docs: DocumentText[]): DocumentText[] {
+  const out: DocumentText[] = [];
+  let budget = MAX_DOCUMENTS_TOTAL_CHARS;
+  for (const d of docs) {
+    const limit = Math.min(MAX_DOCUMENT_CHARS, budget);
+    if (limit <= 0) break;
+    const text = d.text.length > limit ? `${d.text.slice(0, limit)}\n\n[document truncated here — it is longer than this excerpt]` : d.text;
+    budget -= Math.min(d.text.length, limit);
+    out.push({ name: d.name, text });
+  }
+  return out;
+}
+
+/**
+ * One prompt-ready block naming each document and quoting it, or "" when there are none.
+ *
+ * Pure, and here rather than in document-extract-client.ts, because both sides of the relay need
+ * it: the browser to size a request, the Anthropic caller (leaf-regen-anthropic.ts, which also runs
+ * from a Node CLI) to build the actual message. One wording, one place.
+ */
+export function documentsPromptBlock(docs: DocumentText[]): string {
+  if (docs.length === 0) return "";
+  return [
+    "The patient attached the following document(s). Their contents were transcribed and are",
+    "reproduced verbatim below. Treat them as evidence the patient has provided: you may quote them",
+    "and rely on them, but do not infer beyond what they say, and do not treat a document's own",
+    "claims as established clinical fact when it is not a clinical report.",
+    "",
+    ...docs.map((d) => `--- BEGIN DOCUMENT: ${d.name} ---\n${d.text}\n--- END DOCUMENT: ${d.name} ---`),
+  ].join("\n");
+}
+
+export const DOCUMENT_READ_SCHEMA = {
+  type: "object",
+  properties: {
+    documentKind: { type: "string" },
+    isMedicalReport: { type: "boolean" },
+    notReportReason: { type: "string" },
+    text: { type: "string" },
+  },
+  required: ["documentKind", "isMedicalReport", "notReportReason", "text"],
+  additionalProperties: false,
+} as const;
+
+export const DOCUMENT_READ_SYSTEM_PROMPT = [
+  "You transcribe ONE attached document into plain text so it can be quoted and reasoned over",
+  "later. You are a reader, not an interpreter: never add a finding, a conclusion, a diagnosis or a",
+  "number the document does not itself contain.",
+  "",
+  "Return:",
+  "- text: the document's content as readable prose, faithful to the original. Keep every heading,",
+  "  label, date, value and unit exactly as printed — those are what a later step will quote. Render",
+  "  a table as one line per row with its column labels, since the consumer sees text only. Keep the",
+  "  document's own order. Do not summarize, do not shorten, do not editorialize, and do not add",
+  "  commentary of your own. If part of the document is unreadable, write [unreadable] there rather",
+  "  than guessing at it.",
+  "- documentKind: a short Title Case label for what this document IS, e.g. 'Radiology report',",
+  "  'Lab results', 'Supplement label', 'Insurance letter', 'Research paper', 'Receipt'.",
+  "- isMedicalReport: true ONLY when this is a clinical report ABOUT A PATIENT that states results",
+  "  — a lab panel, an imaging/radiology study, a pathology report, a diagnostic test result. It is",
+  "  FALSE for a product label, a package insert, a research paper, a bill or an explanation of",
+  "  benefits, an appointment letter, a consent form, marketing material, or anything not reporting",
+  "  a patient's own measured results.",
+  "- notReportReason: when isMedicalReport is false, ONE sentence naming what the document is",
+  "  instead. Empty string when it is true.",
+].join("\n");
+
+export function validateReading(sourceFile: string, r: DocumentReading): void {
+  if (!r || typeof r !== "object") throw new Error(`document "${sourceFile}" produced no object`);
+  if (typeof r.text !== "string" || r.text.trim() === "") {
+    throw new Error(`document "${sourceFile}" produced no text`);
+  }
+  if (typeof r.isMedicalReport !== "boolean") {
+    throw new Error(`document "${sourceFile}" missing isMedicalReport`);
+  }
+  if (typeof r.documentKind !== "string") {
+    throw new Error(`document "${sourceFile}" missing documentKind`);
+  }
+}
+
+export async function readDocument(
+  anthropic: Anthropic,
+  source: DocumentSource,
+  sourceFile: string,
+  model: string,
+  usage?: UsageRecorder,
+): Promise<DocumentReading> {
+  const reading = await readDocumentAsJson<DocumentReading>({
+    anthropic,
+    source,
+    sourceFile,
+    system: DOCUMENT_READ_SYSTEM_PROMPT,
+    schema: DOCUMENT_READ_SCHEMA,
+    instruction: "Transcribe this document as JSON.",
+    model,
+    maxTokens: DOCUMENT_READ_MAX_TOKENS,
+    usage,
+  });
+  validateReading(sourceFile, reading);
+  return reading;
+}
+
+// The prefixes readDocumentAsJson and validateReading throw with — everything here is the model
+// failing to produce something usable, as opposed to a transport error worth retrying. A caller
+// matches on this to decide which of the two it has, so the shape is API.
+export const DOCUMENT_READ_FAILURE = /^document "|^extraction truncated|^invalid JSON for|^no text block/;