@precisa-saude/fhir-ocr-utils 0.33.0 → 0.35.0

package/README.md

@@ -103,6 +103,12 @@ por código, o de maior confiança.
 `position` é o índice no texto normalizado (sem acentos, minúsculas, espaços
 horizontais colapsados), não no texto OCR original.
 
+Quando o biomarcador tem códigos LOINC por método e o texto afirma o método
+perto do exame, o casamento traz `methodLoinc` e `methodCue`. A decisão é da
+varredura; o `validateExtraction` troca o código por método que o modelo
+devolver pelo que a varredura achou, ou pelo código sem método. Ver
+[código LOINC por método](../../docs/biomarcadores.md#código-loinc-por-método).
+
 #### Confiança
 
 `match.confidence` reflete a qualidade do casamento — nome completo ao lado de

package/dist/cli.js

@@ -169,6 +169,87 @@ var STARTS_WITH_PERCENT = /^ ?(?:\( ?% ?\)|%|[-+]?\d+(?:[.,]\d+)? ?%)/;
 function followedByPercent(code, after) {
   return WHOLE_BODY_MASS_CODES.has(code) && STARTS_WITH_PERCENT.test(after);
 }
+var SKINFOLD_SITE_CODES = /* @__PURE__ */ new Set([
+  "SkinfoldAbdominal",
+  "SkinfoldChest",
+  "SkinfoldMidaxillary",
+  "SkinfoldSubscapular",
+  "SkinfoldSuprailiac",
+  "SkinfoldThigh",
+  "SkinfoldTriceps"
+]);
+var GIRTH_CONTEXT_PATTERNS = [
+  /\bcircumference\b/,
+  /\bcircunferencias?\b/,
+  /\bperimetros?\b/,
+  /\bgirth\b/
+];
+var SKINFOLD_CONTEXT_PATTERNS = [/\bdobras?\b/, /\bskin ?folds?\b/, /\bpregas?\b/];
+var CENTIMETRE_VALUE = /\d\s*(?:,\d+\s*)?cm\b/;
+function hasGirthContext(line) {
+  if (SKINFOLD_CONTEXT_PATTERNS.some((re) => re.test(line))) {
+    return false;
+  }
+  return GIRTH_CONTEXT_PATTERNS.some((re) => re.test(line)) || CENTIMETRE_VALUE.test(line);
+}
+
+// src/method-variant.ts
+import { getDefinitionByCode } from "@precisa-saude/fhir";
+var METHOD_CUE_LINES_BELOW = 6;
+function findMethodVariant(code, position, lines, otherAnchorLines, normalizedText, matchesCue) {
+  const variants = getDefinitionByCode(code)?.methodVariants?.filter(
+    (v) => v.cues.en.length > 0 || v.cues.pt.length > 0
+  );
+  if (!variants || variants.length === 0) return void 0;
+  const index = lines.findIndex((l) => l.start <= position && position <= l.end);
+  if (index === -1) return void 0;
+  const window = [];
+  if (index > 0 && !otherAnchorLines.has(index - 1)) window.push(index - 1);
+  window.push(index);
+  for (let i = index + 1; i < lines.length && i <= index + METHOD_CUE_LINES_BELOW; i += 1) {
+    if (otherAnchorLines.has(i)) break;
+    window.push(i);
+  }
+  const text = window.map((i) => normalizedText.slice(lines[i].start, lines[i].end)).join("\n");
+  const found = variants.flatMap((variant) => {
+    const cue = [...variant.cues.pt, ...variant.cues.en].find((c) => matchesCue(text, c));
+    return cue ? [{ cue, loinc: variant.loinc }] : [];
+  });
+  return found.length === 1 ? found[0] : void 0;
+}
+function recordAnchorLine(anchoredLineStarts, lineStart, entries) {
+  const codes2 = anchoredLineStarts.get(lineStart) ?? /* @__PURE__ */ new Set();
+  for (const entry of entries) codes2.add(entry.code);
+  anchoredLineStarts.set(lineStart, codes2);
+}
+function attachMethodVariants(matches, normalizedText, anchoredLineStarts, matchesCue) {
+  const lines = [];
+  for (let start = 0; start <= normalizedText.length; ) {
+    const end = normalizedText.indexOf("\n", start);
+    lines.push({ end: end === -1 ? normalizedText.length : end, start });
+    if (end === -1) break;
+    start = end + 1;
+  }
+  for (const match of matches) {
+    const otherAnchorLines = /* @__PURE__ */ new Set();
+    lines.forEach((line, i) => {
+      const codes2 = anchoredLineStarts.get(line.start);
+      if (codes2 && [...codes2].some((c) => c !== match.code)) otherAnchorLines.add(i);
+    });
+    const variant = findMethodVariant(
+      match.code,
+      match.position,
+      lines,
+      otherAnchorLines,
+      normalizedText,
+      matchesCue
+    );
+    if (variant) {
+      match.methodLoinc = variant.loinc;
+      match.methodCue = variant.cue;
+    }
+  }
+}
 
 // src/anchor.ts
 var CONFIDENCE_VALUE_ADJACENT = 1;
@@ -249,29 +330,6 @@ var GENETIC_CONTEXT_PATTERNS = [
   /\bhomozigot/,
   /\bsequence change\b/
 ];
-var SKINFOLD_SITE_CODES = /* @__PURE__ */ new Set([
-  "SkinfoldAbdominal",
-  "SkinfoldChest",
-  "SkinfoldMidaxillary",
-  "SkinfoldSubscapular",
-  "SkinfoldSuprailiac",
-  "SkinfoldThigh",
-  "SkinfoldTriceps"
-]);
-var GIRTH_CONTEXT_PATTERNS = [
-  /\bcircumference\b/,
-  /\bcircunferencias?\b/,
-  /\bperimetros?\b/,
-  /\bgirth\b/
-];
-var SKINFOLD_CONTEXT_PATTERNS = [/\bdobras?\b/, /\bskin ?folds?\b/, /\bpregas?\b/];
-var CENTIMETRE_VALUE = /\d\s*(?:,\d+\s*)?cm\b/;
-function hasGirthContext(line) {
-  if (SKINFOLD_CONTEXT_PATTERNS.some((re) => re.test(line))) {
-    return false;
-  }
-  return GIRTH_CONTEXT_PATTERNS.some((re) => re.test(line)) || CENTIMETRE_VALUE.test(line);
-}
 var DIGIT_PATTERN = /\d/;
 var cachedUnitTokens = null;
 function getUnitTokens() {
@@ -444,6 +502,7 @@ function findBiomarkersInText(ocrText) {
   const normalizedText = normalize(ocrText);
   const bestByCode = /* @__PURE__ */ new Map();
   const contexts = /* @__PURE__ */ new Map();
+  const anchoredLineStarts = /* @__PURE__ */ new Map();
   const candidates = [
     ...collectCandidates(normalizedText),
     ...collectWrappedCandidates(normalizedText)
@@ -466,6 +525,7 @@ function findBiomarkersInText(ocrText) {
     if (genetic) {
       continue;
     }
+    recordAnchorLine(anchoredLineStarts, lineStart, candidate.entries);
     const before = normalizedText.slice(lineStart, candidate.start);
     const after = normalizedText.slice(candidate.end, lineEnd);
     for (const entry of candidate.entries) {
@@ -497,6 +557,12 @@ function findBiomarkersInText(ocrText) {
       }
     }
   }
+  attachMethodVariants(
+    bestByCode.values(),
+    normalizedText,
+    anchoredLineStarts,
+    (text, cue) => buildNamePattern(normalize(cue).trim()).test(text)
+  );
   const matches = Array.from(bestByCode.values()).sort((a, b) => a.position - b.position);
   const scanTimeMs = Date.now() - startTime;
   return {
@@ -514,7 +580,7 @@ function getMatchedCodes(result) {
 }
 
 // src/extraction-to-lab-result.ts
-import { loincToCode } from "@precisa-saude/fhir";
+import { loincToCode, methodVariantOf } from "@precisa-saude/fhir";
 function flagFor(b) {
   if (typeof b.value !== "number") return "";
   if (typeof b.referenceMax === "number" && b.value > b.referenceMax) return "H";
@@ -533,6 +599,9 @@ function extractionToLabResult(biomarkers, options = {}) {
         biomarkerCode: code,
         biomarkerName: b.name,
         flag: flagFor(b),
+        // O código por método já passou pela varredura no validador; aqui só
+        // atravessa, e só quando é variante declarada do biomarcador.
+        ...b.loinc && methodVariantOf(code, b.loinc) ? { methodLoinc: b.loinc } : {},
         ...typeof b.referenceMax === "number" ? { referenceMax: b.referenceMax } : {},
         ...typeof b.referenceMin === "number" ? { referenceMin: b.referenceMin } : {},
         reportId,
@@ -556,7 +625,7 @@ function extractionToLabResult(biomarkers, options = {}) {
 }
 
 // src/extraction-validator.ts
-import { loincToCode as loincToCode2 } from "@precisa-saude/fhir";
+import { codeToLoinc, getDefinitionByCode as getDefinitionByCode2, loincToCode as loincToCode2 } from "@precisa-saude/fhir";
 
 // src/reference-bound.ts
 var ATE = /(?:<|≤|<=|menor\s+que|menor\s+ou\s+igual|abaixo\s+de|at[ée]|under|less\s+than)\s*[:=]?\s*$/iu;
@@ -617,6 +686,13 @@ function allowedKeys(anchors) {
   }
   return allowed;
 }
+function withScannedMethod(biomarker, anchors) {
+  const code = biomarker.loinc ? loincToCode2(biomarker.loinc) : void 0;
+  if (!code || !getDefinitionByCode2(code)?.methodVariants?.length) return biomarker;
+  const scanned = anchors.matches.find((m) => m.code === code)?.methodLoinc;
+  const loinc = scanned ?? codeToLoinc(code);
+  return loinc && loinc !== biomarker.loinc ? { ...biomarker, loinc } : biomarker;
+}
 function validateExtraction(raw, options = {}) {
   const { anchors } = options;
   if (!isRecord(raw)) {
@@ -668,7 +744,7 @@ function validateExtraction(raw, options = {}) {
         continue;
       }
     }
-    accepted.push(placeSingleBound(biomarker));
+    accepted.push(placeSingleBound(anchors ? withScannedMethod(biomarker, anchors) : biomarker));
   }
   return {
     accepted,
@@ -1017,7 +1093,7 @@ async function main() {
     strict: false
   });
   if (values.version) {
-    process.stdout.write(`${"0.33.0"}
+    process.stdout.write(`${"0.35.0"}
 `);
     return;
   }

package/dist/index.cjs

@@ -153,6 +153,87 @@ var STARTS_WITH_PERCENT = /^ ?(?:\( ?% ?\)|%|[-+]?\d+(?:[.,]\d+)? ?%)/;
 function followedByPercent(code, after) {
   return WHOLE_BODY_MASS_CODES.has(code) && STARTS_WITH_PERCENT.test(after);
 }
+var SKINFOLD_SITE_CODES = /* @__PURE__ */ new Set([
+  "SkinfoldAbdominal",
+  "SkinfoldChest",
+  "SkinfoldMidaxillary",
+  "SkinfoldSubscapular",
+  "SkinfoldSuprailiac",
+  "SkinfoldThigh",
+  "SkinfoldTriceps"
+]);
+var GIRTH_CONTEXT_PATTERNS = [
+  /\bcircumference\b/,
+  /\bcircunferencias?\b/,
+  /\bperimetros?\b/,
+  /\bgirth\b/
+];
+var SKINFOLD_CONTEXT_PATTERNS = [/\bdobras?\b/, /\bskin ?folds?\b/, /\bpregas?\b/];
+var CENTIMETRE_VALUE = /\d\s*(?:,\d+\s*)?cm\b/;
+function hasGirthContext(line) {
+  if (SKINFOLD_CONTEXT_PATTERNS.some((re) => re.test(line))) {
+    return false;
+  }
+  return GIRTH_CONTEXT_PATTERNS.some((re) => re.test(line)) || CENTIMETRE_VALUE.test(line);
+}
+
+// src/method-variant.ts
+
+var METHOD_CUE_LINES_BELOW = 6;
+function findMethodVariant(code, position, lines, otherAnchorLines, normalizedText, matchesCue) {
+  const variants = _optionalChain([_fhir.getDefinitionByCode.call(void 0, code), 'optionalAccess', _ => _.methodVariants, 'optionalAccess', _2 => _2.filter, 'call', _3 => _3(
+    (v) => v.cues.en.length > 0 || v.cues.pt.length > 0
+  )]);
+  if (!variants || variants.length === 0) return void 0;
+  const index = lines.findIndex((l) => l.start <= position && position <= l.end);
+  if (index === -1) return void 0;
+  const window = [];
+  if (index > 0 && !otherAnchorLines.has(index - 1)) window.push(index - 1);
+  window.push(index);
+  for (let i = index + 1; i < lines.length && i <= index + METHOD_CUE_LINES_BELOW; i += 1) {
+    if (otherAnchorLines.has(i)) break;
+    window.push(i);
+  }
+  const text = window.map((i) => normalizedText.slice(lines[i].start, lines[i].end)).join("\n");
+  const found = variants.flatMap((variant) => {
+    const cue = [...variant.cues.pt, ...variant.cues.en].find((c) => matchesCue(text, c));
+    return cue ? [{ cue, loinc: variant.loinc }] : [];
+  });
+  return found.length === 1 ? found[0] : void 0;
+}
+function recordAnchorLine(anchoredLineStarts, lineStart, entries) {
+  const codes = _nullishCoalesce(anchoredLineStarts.get(lineStart), () => ( /* @__PURE__ */ new Set()));
+  for (const entry of entries) codes.add(entry.code);
+  anchoredLineStarts.set(lineStart, codes);
+}
+function attachMethodVariants(matches, normalizedText, anchoredLineStarts, matchesCue) {
+  const lines = [];
+  for (let start = 0; start <= normalizedText.length; ) {
+    const end = normalizedText.indexOf("\n", start);
+    lines.push({ end: end === -1 ? normalizedText.length : end, start });
+    if (end === -1) break;
+    start = end + 1;
+  }
+  for (const match of matches) {
+    const otherAnchorLines = /* @__PURE__ */ new Set();
+    lines.forEach((line, i) => {
+      const codes = anchoredLineStarts.get(line.start);
+      if (codes && [...codes].some((c) => c !== match.code)) otherAnchorLines.add(i);
+    });
+    const variant = findMethodVariant(
+      match.code,
+      match.position,
+      lines,
+      otherAnchorLines,
+      normalizedText,
+      matchesCue
+    );
+    if (variant) {
+      match.methodLoinc = variant.loinc;
+      match.methodCue = variant.cue;
+    }
+  }
+}
 
 // src/anchor.ts
 var CONFIDENCE_VALUE_ADJACENT = 1;
@@ -187,7 +268,7 @@ function getNamesByHead() {
   return cachedNamesByHead;
 }
 function startsWithCatalogName(text) {
-  const head = _optionalChain([/^[\p{L}\p{N}]+/u, 'access', _ => _.exec, 'call', _2 => _2(text), 'optionalAccess', _3 => _3[0]]);
+  const head = _optionalChain([/^[\p{L}\p{N}]+/u, 'access', _4 => _4.exec, 'call', _5 => _5(text), 'optionalAccess', _6 => _6[0]]);
   if (!head) {
     return false;
   }
@@ -233,29 +314,6 @@ var GENETIC_CONTEXT_PATTERNS = [
   /\bhomozigot/,
   /\bsequence change\b/
 ];
-var SKINFOLD_SITE_CODES = /* @__PURE__ */ new Set([
-  "SkinfoldAbdominal",
-  "SkinfoldChest",
-  "SkinfoldMidaxillary",
-  "SkinfoldSubscapular",
-  "SkinfoldSuprailiac",
-  "SkinfoldThigh",
-  "SkinfoldTriceps"
-]);
-var GIRTH_CONTEXT_PATTERNS = [
-  /\bcircumference\b/,
-  /\bcircunferencias?\b/,
-  /\bperimetros?\b/,
-  /\bgirth\b/
-];
-var SKINFOLD_CONTEXT_PATTERNS = [/\bdobras?\b/, /\bskin ?folds?\b/, /\bpregas?\b/];
-var CENTIMETRE_VALUE = /\d\s*(?:,\d+\s*)?cm\b/;
-function hasGirthContext(line) {
-  if (SKINFOLD_CONTEXT_PATTERNS.some((re) => re.test(line))) {
-    return false;
-  }
-  return GIRTH_CONTEXT_PATTERNS.some((re) => re.test(line)) || CENTIMETRE_VALUE.test(line);
-}
 var DIGIT_PATTERN = /\d/;
 var cachedUnitTokens = null;
 function getUnitTokens() {
@@ -428,6 +486,7 @@ function findBiomarkersInText(ocrText) {
   const normalizedText = normalize(ocrText);
   const bestByCode = /* @__PURE__ */ new Map();
   const contexts = /* @__PURE__ */ new Map();
+  const anchoredLineStarts = /* @__PURE__ */ new Map();
   const candidates = [
     ...collectCandidates(normalizedText),
     ...collectWrappedCandidates(normalizedText)
@@ -450,6 +509,7 @@ function findBiomarkersInText(ocrText) {
     if (genetic) {
       continue;
     }
+    recordAnchorLine(anchoredLineStarts, lineStart, candidate.entries);
     const before = normalizedText.slice(lineStart, candidate.start);
     const after = normalizedText.slice(candidate.end, lineEnd);
     for (const entry of candidate.entries) {
@@ -481,6 +541,12 @@ function findBiomarkersInText(ocrText) {
       }
     }
   }
+  attachMethodVariants(
+    bestByCode.values(),
+    normalizedText,
+    anchoredLineStarts,
+    (text, cue) => buildNamePattern(normalize(cue).trim()).test(text)
+  );
   const matches = Array.from(bestByCode.values()).sort((a, b) => a.position - b.position);
   const scanTimeMs = Date.now() - startTime;
   return {
@@ -591,6 +657,9 @@ function extractionToLabResult(biomarkers, options = {}) {
         biomarkerCode: code,
         biomarkerName: b.name,
         flag: flagFor(b),
+        // O código por método já passou pela varredura no validador; aqui só
+        // atravessa, e só quando é variante declarada do biomarcador.
+        ...b.loinc && _fhir.methodVariantOf.call(void 0, code, b.loinc) ? { methodLoinc: b.loinc } : {},
         ...typeof b.referenceMax === "number" ? { referenceMax: b.referenceMax } : {},
         ...typeof b.referenceMin === "number" ? { referenceMin: b.referenceMin } : {},
         reportId,
@@ -675,6 +744,13 @@ function allowedKeys(anchors) {
   }
   return allowed;
 }
+function withScannedMethod(biomarker, anchors) {
+  const code = biomarker.loinc ? _fhir.loincToCode.call(void 0, biomarker.loinc) : void 0;
+  if (!code || !_optionalChain([_fhir.getDefinitionByCode.call(void 0, code), 'optionalAccess', _7 => _7.methodVariants, 'optionalAccess', _8 => _8.length])) return biomarker;
+  const scanned = _optionalChain([anchors, 'access', _9 => _9.matches, 'access', _10 => _10.find, 'call', _11 => _11((m) => m.code === code), 'optionalAccess', _12 => _12.methodLoinc]);
+  const loinc = _nullishCoalesce(scanned, () => ( _fhir.codeToLoinc.call(void 0, code)));
+  return loinc && loinc !== biomarker.loinc ? { ...biomarker, loinc } : biomarker;
+}
 function validateExtraction(raw, options = {}) {
   const { anchors } = options;
   if (!isRecord(raw)) {
@@ -726,7 +802,7 @@ function validateExtraction(raw, options = {}) {
         continue;
       }
     }
-    accepted.push(placeSingleBound(biomarker));
+    accepted.push(placeSingleBound(anchors ? withScannedMethod(biomarker, anchors) : biomarker));
   }
   return {
     accepted,
@@ -761,7 +837,7 @@ function buildPrompt(text, allowed) {
 }
 function stripFence(raw) {
   const fenced = /```(?:json)?\s*([\s\S]*?)```/.exec(raw);
-  return (_nullishCoalesce(_optionalChain([fenced, 'optionalAccess', _4 => _4[1]]), () => ( raw))).trim();
+  return (_nullishCoalesce(_optionalChain([fenced, 'optionalAccess', _13 => _13[1]]), () => ( raw))).trim();
 }
 async function extractWithModel(text, options) {
   const { apiKey, baseUrl, headers = {}, model, responseFormat, timeoutMs = 3e5 } = options;
@@ -801,7 +877,7 @@ async function extractWithModel(text, options) {
     throw new Error(`${String(response.status)} de ${baseUrl}: ${await response.text()}`);
   }
   const body = await response.json();
-  const raw = _nullishCoalesce(_optionalChain([body, 'access', _5 => _5.choices, 'optionalAccess', _6 => _6[0], 'optionalAccess', _7 => _7.message, 'optionalAccess', _8 => _8.content]), () => ( ""));
+  const raw = _nullishCoalesce(_optionalChain([body, 'access', _14 => _14.choices, 'optionalAccess', _15 => _15[0], 'optionalAccess', _16 => _16.message, 'optionalAccess', _17 => _17.content]), () => ( ""));
   const tookMs = Date.now() - startedAt;
   try {
     return { payload: JSON.parse(stripFence(raw)), raw, tookMs };