@precisa-saude/fhir-ocr-utils 0.25.1 → 0.26.0

package/dist/cli.js

@@ -2,10 +2,17 @@
 
 // src/cli/index.ts
 import { parseArgs } from "util";
-import { exitWithError } from "@precisa-saude/fhir/cli-utils";
+import { exitWithError as exitWithError3 } from "@precisa-saude/fhir/cli-utils";
 
-// src/cli/commands/codes.ts
-import { getInput, outputJson, outputText } from "@precisa-saude/fhir/cli-utils";
+// src/cli/commands/check.ts
+import {
+  exitWithError,
+  formatTable,
+  getInput,
+  outputJson,
+  outputText,
+  parseJson
+} from "@precisa-saude/fhir/cli-utils";
 
 // src/anchor.ts
 import {
@@ -373,35 +380,371 @@ function getMatchedCodes(result) {
   return result.matches.map((m) => m.code);
 }
 
+// src/extraction-to-lab-result.ts
+import { loincToCode } from "@precisa-saude/fhir";
+function flagFor(b) {
+  if (typeof b.value !== "number") return "";
+  if (typeof b.referenceMax === "number" && b.value > b.referenceMax) return "H";
+  if (typeof b.referenceMin === "number" && b.value < b.referenceMin) return "L";
+  return "";
+}
+function extractionToLabResult(biomarkers, options = {}) {
+  const reportId = options.reportId ?? "laudo-demo";
+  const userId = options.userId ?? "paciente-demo";
+  const collectionDate = options.collectionDate ?? (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
+  const observations = biomarkers.flatMap((b) => {
+    const code = b.loinc ? loincToCode(b.loinc) : void 0;
+    if (!code) return [];
+    return [
+      {
+        biomarkerCode: code,
+        biomarkerName: b.name,
+        flag: flagFor(b),
+        ...typeof b.referenceMax === "number" ? { referenceMax: b.referenceMax } : {},
+        ...typeof b.referenceMin === "number" ? { referenceMin: b.referenceMin } : {},
+        reportId,
+        unit: b.unit,
+        value: b.value
+      }
+    ];
+  });
+  return {
+    observations,
+    profile: { name: "Paciente de Demonstra\xE7\xE3o", userId },
+    report: {
+      collectionDate,
+      createdAt: `${collectionDate}T00:00:00Z`,
+      overallStatus: observations.some((o) => o.flag !== "") ? "ANORMAL" : "NORMAL",
+      processingStatus: "complete",
+      reportId,
+      userId
+    }
+  };
+}
+
+// src/extraction-validator.ts
+import { loincToCode as loincToCode2 } from "@precisa-saude/fhir";
+var isRecord = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+function schemaErrors(raw) {
+  if (!isRecord(raw)) return ["n\xE3o \xE9 um objeto"];
+  const errors = [];
+  const { confidence, loinc, name, referenceMax, referenceMin, sourceText, unit, value } = raw;
+  if (typeof name !== "string" || name.length === 0) errors.push("`name` ausente ou vazio");
+  if (typeof sourceText !== "string" || sourceText.length === 0)
+    errors.push("`sourceText` ausente ou vazio");
+  if (typeof unit !== "string") errors.push("`unit` ausente");
+  if (typeof value !== "number" && typeof value !== "string") errors.push("`value` ausente");
+  if (typeof confidence !== "number" || confidence < 0 || confidence > 1)
+    errors.push("`confidence` fora de 0..1");
+  if (loinc !== void 0 && loinc !== null && typeof loinc !== "string")
+    errors.push("`loinc` n\xE3o \xE9 string nem null");
+  for (const [key, v] of [
+    ["referenceMax", referenceMax],
+    ["referenceMin", referenceMin]
+  ]) {
+    if (v !== void 0 && v !== null && typeof v !== "number")
+      errors.push(`\`${key}\` n\xE3o \xE9 n\xFAmero nem null`);
+  }
+  return errors;
+}
+function allowedKeys(anchors) {
+  const allowed = /* @__PURE__ */ new Set();
+  for (const match of anchors.matches) {
+    allowed.add(match.code);
+    if (match.loinc) allowed.add(match.loinc);
+  }
+  return allowed;
+}
+function validateExtraction(raw, options = {}) {
+  const { anchors } = options;
+  if (!isRecord(raw)) {
+    return { accepted: [], errors: ["a sa\xEDda n\xE3o \xE9 um objeto JSON"], rejected: [], valid: false };
+  }
+  if (!Array.isArray(raw.biomarkers)) {
+    return {
+      accepted: [],
+      errors: ["`biomarkers` ausente ou n\xE3o \xE9 lista"],
+      rejected: [],
+      valid: false
+    };
+  }
+  const allowed = anchors ? allowedKeys(anchors) : void 0;
+  const accepted = [];
+  const rejected = [];
+  for (const entry of raw.biomarkers) {
+    const problems = schemaErrors(entry);
+    if (problems.length > 0) {
+      rejected.push({ detail: problems.join("; "), raw: entry, reason: "schema" });
+      continue;
+    }
+    const biomarker = entry;
+    if (allowed) {
+      const loinc = biomarker.loinc ?? void 0;
+      if (!loinc) {
+        rejected.push({
+          detail: `"${biomarker.name}" veio sem c\xF3digo LOINC`,
+          raw: entry,
+          reason: "not-anchored"
+        });
+        continue;
+      }
+      const internalCode = loincToCode2(loinc);
+      const isAnchored = allowed.has(loinc) || internalCode !== void 0 && allowed.has(internalCode);
+      if (!isAnchored) {
+        rejected.push({
+          detail: `${loinc} n\xE3o foi ancorado no texto de origem`,
+          raw: entry,
+          reason: "not-anchored"
+        });
+        continue;
+      }
+    }
+    accepted.push(biomarker);
+  }
+  return { accepted, errors: [], rejected, valid: true };
+}
+
+// src/cli/commands/check.ts
+async function check(args, json, options = {}) {
+  const sourcePath = typeof options.source === "string" ? options.source : void 0;
+  const raw = parseJson(await getInput(args[0]), "Sa\xEDda do modelo n\xE3o \xE9 JSON v\xE1lido.");
+  const anchors = sourcePath ? findBiomarkersInText(await getInput(sourcePath)) : void 0;
+  const result = validateExtraction(raw, { anchors });
+  if (options.convert === true) {
+    if (!result.valid) {
+      exitWithError(`Sa\xEDda inv\xE1lida: ${result.errors.join("; ")}`);
+    }
+    const envelope = extractionToLabResult(result.accepted);
+    const semCodigo = result.accepted.length - envelope.observations.length;
+    if (semCodigo > 0) {
+      process.stderr.write(
+        `aviso: ${String(semCodigo)} grandeza(s) aprovada(s) ficaram de fora do envelope por n\xE3o terem c\xF3digo no cat\xE1logo
+`
+      );
+    }
+    if (envelope.observations.length === 0) {
+      process.stderr.write("aviso: nenhuma observa\xE7\xE3o no envelope\n");
+    }
+    outputJson(envelope);
+    return;
+  }
+  if (json) {
+    outputJson(result);
+    return;
+  }
+  if (!result.valid) {
+    exitWithError(`Sa\xEDda inv\xE1lida: ${result.errors.join("; ")}`);
+  }
+  if (result.accepted.length > 0) {
+    outputText(
+      formatTable(
+        ["LOINC", "Nome", "Valor", "Unidade"],
+        result.accepted.map((b) => [
+          b.loinc ?? "\u2014",
+          b.name,
+          String(b.value),
+          b.unit === "" ? "\u2014" : b.unit
+        ])
+      )
+    );
+  }
+  if (result.rejected.length > 0) {
+    outputText(`
+Recusados: ${result.rejected.length}`);
+    for (const r of result.rejected) {
+      outputText(`  [${r.reason}] ${r.detail}`);
+    }
+  }
+  const total = result.accepted.length + result.rejected.length;
+  outputText(
+    `
+Aceitos: ${result.accepted.length} de ${total}${anchors ? "" : "   (sem --source: ancoragem n\xE3o conferida)"}`
+  );
+}
+
 // src/cli/commands/codes.ts
+import { getInput as getInput2, outputJson as outputJson2, outputText as outputText2 } from "@precisa-saude/fhir/cli-utils";
 async function codes(args, json) {
-  const text = await getInput(args[0]);
+  const text = await getInput2(args[0]);
   const result = findBiomarkersInText(text);
   const matched = getMatchedCodes(result);
   if (json) {
-    outputJson(matched);
+    outputJson2(matched);
     return;
   }
   if (matched.length === 0) {
-    outputText("Nenhum biomarcador encontrado no texto.");
+    outputText2("Nenhum biomarcador encontrado no texto.");
     return;
   }
-  outputText(matched.join("\n"));
-  outputText(`
+  outputText2(matched.join("\n"));
+  outputText2(`
 Total: ${matched.length} c\xF3digos encontrados`);
 }
 
+// src/cli/commands/extract.ts
+import { exitWithError as exitWithError2, getInput as getInput3, outputJson as outputJson3 } from "@precisa-saude/fhir/cli-utils";
+
+// src/extraction-schema.ts
+var LAB_EXTRACTION_SCHEMA = {
+  $id: "https://fhir-brasil.dev.br/schemas/lab-extraction.json",
+  $schema: "https://json-schema.org/draft/2020-12/schema",
+  additionalProperties: false,
+  properties: {
+    biomarkers: {
+      description: "The measurements read from the report.",
+      items: {
+        additionalProperties: false,
+        properties: {
+          confidence: {
+            description: "Confidence in this reading, from 0 to 1.",
+            maximum: 1,
+            minimum: 0,
+            type: "number"
+          },
+          loinc: {
+            anyOf: [{ type: "string" }, { type: "null" }],
+            description: "A LOINC code from the allowed list, or null when none of them applies."
+          },
+          name: {
+            description: "The measurement name as the report prints it.",
+            type: "string"
+          },
+          referenceMax: {
+            anyOf: [{ type: "number" }, { type: "null" }],
+            description: "Upper bound of the range printed on the report, or null."
+          },
+          referenceMin: {
+            anyOf: [{ type: "number" }, { type: "null" }],
+            description: "Lower bound of the range printed on the report, or null."
+          },
+          sourceText: {
+            description: "The snippet of the report carrying this measurement and its value.",
+            type: "string"
+          },
+          unit: {
+            description: "Unit as the report prints it. Empty string when there is none.",
+            type: "string"
+          },
+          value: {
+            anyOf: [{ type: "number" }, { type: "string" }],
+            description: "Numeric value, or text for a qualitative result."
+          }
+        },
+        required: ["name", "value", "unit", "sourceText", "confidence"],
+        type: "object"
+      },
+      type: "array"
+    }
+  },
+  required: ["biomarkers"],
+  title: "Laboratory report extraction",
+  type: "object"
+};
+
+// src/llm-client.ts
+function buildPrompt(text, allowed) {
+  return [
+    "Extract the laboratory results from the report below.",
+    "",
+    "Return JSON matching this schema, and nothing else:",
+    JSON.stringify(LAB_EXTRACTION_SCHEMA),
+    "",
+    "Use only LOINC codes from this list:",
+    allowed,
+    "",
+    "REPORT:",
+    text
+  ].join("\n");
+}
+function stripFence(raw) {
+  const fenced = /```(?:json)?\s*([\s\S]*?)```/.exec(raw);
+  return (fenced?.[1] ?? raw).trim();
+}
+async function extractWithModel(text, options) {
+  const { apiKey, baseUrl, model, responseFormat, timeoutMs = 3e5 } = options;
+  const allowed = findBiomarkersInText(text).filteredReference;
+  const startedAt = Date.now();
+  const formatBody = (mode2) => JSON.stringify({
+    messages: [{ content: buildPrompt(text, allowed), role: "user" }],
+    model,
+    ...mode2 === "json_object" ? { response_format: { type: "json_object" } } : {},
+    ...mode2 === "json_schema" ? {
+      response_format: {
+        json_schema: { name: "lab_extraction", schema: LAB_EXTRACTION_SCHEMA, strict: true },
+        type: "json_schema"
+      }
+    } : {},
+    temperature: 0
+  });
+  const post = async (mode2) => fetch(`${baseUrl.replace(/\/$/, "")}/chat/completions`, {
+    body: formatBody(mode2),
+    headers: {
+      "content-type": "application/json",
+      ...apiKey ? { authorization: `Bearer ${apiKey}` } : {}
+    },
+    method: "POST",
+    signal: AbortSignal.timeout(timeoutMs)
+  });
+  const mode = responseFormat ?? "auto";
+  let response = await post(mode === "auto" ? "json_schema" : mode);
+  if (!response.ok && mode === "auto" && response.status >= 400 && response.status < 500) {
+    response = await post("none");
+  }
+  if (!response.ok) {
+    throw new Error(`${String(response.status)} de ${baseUrl}: ${await response.text()}`);
+  }
+  const body = await response.json();
+  const raw = body.choices?.[0]?.message?.content ?? "";
+  const tookMs = Date.now() - startedAt;
+  try {
+    return { payload: JSON.parse(stripFence(raw)), raw, tookMs };
+  } catch {
+    throw new Error(`O modelo n\xE3o devolveu JSON analis\xE1vel. Resposta crua:
+${raw.slice(0, 500)}`);
+  }
+}
+
+// src/cli/commands/extract.ts
+var DEFAULT_BASE_URL = "http://localhost:1234/v1";
+async function extract(args, _json, options = {}) {
+  const model = typeof options.model === "string" ? options.model : void 0;
+  if (!model) {
+    exitWithError2("Informe o modelo com --model. Exemplo: --model qwen3.5-9b");
+  }
+  const baseUrl = typeof options["base-url"] === "string" ? options["base-url"] : DEFAULT_BASE_URL;
+  const keyEnv = typeof options["api-key-env"] === "string" ? options["api-key-env"] : void 0;
+  const apiKey = keyEnv ? process.env[keyEnv] : void 0;
+  if (keyEnv && !apiKey) {
+    exitWithError2(`A vari\xE1vel de ambiente ${keyEnv} est\xE1 vazia.`);
+  }
+  const rf = options["response-format"];
+  const modos = ["auto", "json_object", "json_schema", "none"];
+  if (rf !== void 0 && (typeof rf !== "string" || !modos.includes(rf))) {
+    exitWithError2(`--response-format aceita ${modos.join(", ")}.`);
+  }
+  const responseFormat = rf;
+  const text = await getInput3(args[0]);
+  try {
+    const result = await extractWithModel(text, { apiKey, baseUrl, model, responseFormat });
+    process.stderr.write(`modelo respondeu em ${String(result.tookMs)}ms
+`);
+    outputJson3(result.payload);
+  } catch (err) {
+    exitWithError2(err instanceof Error ? err.message : String(err));
+  }
+}
+
 // src/cli/commands/find.ts
-import { formatTable, getInput as getInput2, outputJson as outputJson2, outputText as outputText2 } from "@precisa-saude/fhir/cli-utils";
+import { formatTable as formatTable2, getInput as getInput4, outputJson as outputJson4, outputText as outputText3 } from "@precisa-saude/fhir/cli-utils";
 async function find(args, json) {
-  const text = await getInput2(args[0]);
+  const text = await getInput4(args[0]);
   const result = findBiomarkersInText(text);
   if (json) {
-    outputJson2(result);
+    outputJson4(result);
     return;
   }
   if (result.matches.length === 0) {
-    outputText2("Nenhum biomarcador encontrado no texto.");
+    outputText3("Nenhum biomarcador encontrado no texto.");
     return;
   }
   const rows = result.matches.map((m) => [
@@ -411,13 +754,19 @@ async function find(args, json) {
     m.confidence.toFixed(2),
     String(m.position)
   ]);
-  outputText2(formatTable(["C\xF3digo", "LOINC", "Match", "Confian\xE7a", "Posi\xE7\xE3o"], rows));
-  outputText2(
+  outputText3(formatTable2(["C\xF3digo", "LOINC", "Match", "Confian\xE7a", "Posi\xE7\xE3o"], rows));
+  outputText3(
     `
 Encontrados: ${result.stats.matchedCount} de ${result.stats.totalPatterns} padr\xF5es (${result.stats.scanTimeMs}ms)`
   );
 }
 
+// src/cli/commands/schema.ts
+import { outputJson as outputJson5 } from "@precisa-saude/fhir/cli-utils";
+async function schema(_args, _json) {
+  outputJson5(LAB_EXTRACTION_SCHEMA);
+}
+
 // src/cli/index.ts
 var HELP = `fhir-ocr \u2014 CLI do @precisa-saude/fhir-ocr-utils
 
@@ -426,6 +775,13 @@ Uso: fhir-ocr <comando> [op\xE7\xF5es]
 Comandos:
   find [arquivo]          Encontrar biomarcadores em texto OCR
   codes [arquivo]         Extrair c\xF3digos de biomarcadores encontrados no texto
+  schema                  Imprimir o contrato de sa\xEDda esperado do modelo
+  extract [arquivo]       Mandar o laudo a um modelo compat\xEDvel com OpenAI
+                          (--model, --base-url, --api-key-env,
+                          --response-format, se precisar for\xE7ar um modo)
+  check <saida.json>      Conferir a sa\xEDda de um modelo contra o contrato
+                          e contra a ancoragem (--source <laudo.txt>).
+                          Com --convert, imprime o envelope do fhir-bio
 
 Flags globais:
   --json                  Sa\xEDda em formato JSON
@@ -435,21 +791,33 @@ Flags globais:
 L\xEA de stdin quando nenhum arquivo \xE9 fornecido.
 `;
 var COMMANDS = {
+  check,
   codes,
-  find
+  extract,
+  find,
+  schema
 };
 async function main() {
   const { positionals, values } = parseArgs({
     allowPositionals: true,
     options: {
+      // `check` precisa do texto que foi ao modelo. Declarado aqui porque o
+      // `parseArgs` roda uma vez só, no topo, e opção não declarada vira
+      // booleana e joga o valor nos posicionais.
+      "api-key-env": { type: "string" },
+      "base-url": { type: "string" },
+      convert: { default: false, type: "boolean" },
       help: { default: false, short: "h", type: "boolean" },
       json: { default: false, type: "boolean" },
+      model: { type: "string" },
+      "response-format": { type: "string" },
+      source: { type: "string" },
       version: { default: false, short: "v", type: "boolean" }
     },
     strict: false
   });
   if (values.version) {
-    process.stdout.write(`${"0.25.1"}
+    process.stdout.write(`${"0.26.0"}
 `);
     return;
   }
@@ -460,9 +828,9 @@ async function main() {
   }
   const handler = COMMANDS[command];
   if (!handler) {
-    exitWithError(`Comando desconhecido: ${command}
+    exitWithError3(`Comando desconhecido: ${command}
 Use --help para ver os comandos dispon\xEDveis.`);
   }
-  await handler(rest, Boolean(values.json));
+  await handler(rest, Boolean(values.json), values);
 }
-main().catch((err) => exitWithError(err.message));
+main().catch((err) => exitWithError3(err.message));