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

package/dist/index.d.cts

@@ -55,4 +55,263 @@ declare function findBiomarkersInText(ocrText: string): AnchorResult;
  */
 declare function getMatchedCodes(result: AnchorResult): string[];
 
-export { type AnchorMatch, type AnchorResult, CONFIDENCE_AMBIGUOUS, CONFIDENCE_NAME_ONLY, CONFIDENCE_VALUE_ADJACENT, findBiomarkersInText, getMatchedCodes };
+/**
+ * Contrato de saída para extração de laudo por modelo.
+ *
+ * Este é o **contrato de interoperabilidade**, e não um prompt. Ele descreve a
+ * forma do JSON que qualquer modelo precisa devolver para o resto do toolkit
+ * conseguir conferir e converter o resultado. Não diz como pedir isso ao
+ * modelo, não traz instrução de comportamento e não depende de fornecedor:
+ * quem usa liga do jeito que a plataforma dele permitir (saída estruturada,
+ * gramática, tool use ou simples prompt com validação por cima).
+ *
+ * As descrições são deliberadamente neutras. Regra de comportamento ("nunca
+ * infira", "copie literalmente") é ajuste de prompt, muda de modelo para
+ * modelo e não pertence a um contrato público.
+ *
+ * As descrições são as únicas strings em inglês do pacote, e isso é
+ * deliberado: o schema é contrato de integração lido por quem consome de fora
+ * do Brasil, e uma descrição em pt-BR não ajuda ninguém em Colônia ou Madri.
+ * O resto da documentação segue a regra do ecossistema.
+ *
+ * O campo `sourceText` existe porque é o que torna a conferência possível:
+ * sem o trecho que originou o valor não dá para auditar a extração depois.
+ *
+ * Campo que aceita mais de um tipo usa `anyOf`, e não `type: [...]`. As duas
+ * formas são JSON Schema válido, mas decodificador restrito não engole a
+ * segunda: o LM Studio recusa a geração com `'type' must be a string`. Como o
+ * ponto do contrato é servir a qualquer modelo, vale a forma mais aceita.
+ */
+declare const LAB_EXTRACTION_SCHEMA: {
+    readonly $id: "https://fhir-brasil.dev.br/schemas/lab-extraction.json";
+    readonly $schema: "https://json-schema.org/draft/2020-12/schema";
+    readonly additionalProperties: false;
+    readonly properties: {
+        readonly biomarkers: {
+            readonly description: "The measurements read from the report.";
+            readonly items: {
+                readonly additionalProperties: false;
+                readonly properties: {
+                    readonly confidence: {
+                        readonly description: "Confidence in this reading, from 0 to 1.";
+                        readonly maximum: 1;
+                        readonly minimum: 0;
+                        readonly type: "number";
+                    };
+                    readonly loinc: {
+                        readonly anyOf: readonly [{
+                            readonly type: "string";
+                        }, {
+                            readonly type: "null";
+                        }];
+                        readonly description: "A LOINC code from the allowed list, or null when none of them applies.";
+                    };
+                    readonly name: {
+                        readonly description: "The measurement name as the report prints it.";
+                        readonly type: "string";
+                    };
+                    readonly referenceMax: {
+                        readonly anyOf: readonly [{
+                            readonly type: "number";
+                        }, {
+                            readonly type: "null";
+                        }];
+                        readonly description: "Upper bound of the range printed on the report, or null.";
+                    };
+                    readonly referenceMin: {
+                        readonly anyOf: readonly [{
+                            readonly type: "number";
+                        }, {
+                            readonly type: "null";
+                        }];
+                        readonly description: "Lower bound of the range printed on the report, or null.";
+                    };
+                    readonly sourceText: {
+                        readonly description: "The snippet of the report carrying this measurement and its value.";
+                        readonly type: "string";
+                    };
+                    readonly unit: {
+                        readonly description: "Unit as the report prints it. Empty string when there is none.";
+                        readonly type: "string";
+                    };
+                    readonly value: {
+                        readonly anyOf: readonly [{
+                            readonly type: "number";
+                        }, {
+                            readonly type: "string";
+                        }];
+                        readonly description: "Numeric value, or text for a qualitative result.";
+                    };
+                };
+                readonly required: readonly ["name", "value", "unit", "sourceText", "confidence"];
+                readonly type: "object";
+            };
+            readonly type: "array";
+        };
+    };
+    readonly required: readonly ["biomarkers"];
+    readonly title: "Laboratory report extraction";
+    readonly type: "object";
+};
+/** Uma grandeza como o modelo devolve, antes de qualquer conferência. */
+interface ExtractedBiomarker {
+    confidence: number;
+    loinc?: string | null;
+    name: string;
+    referenceMax?: number | null;
+    referenceMin?: number | null;
+    sourceText: string;
+    unit: string;
+    value: number | string;
+}
+/** O objeto inteiro que o modelo devolve. */
+interface ExtractionPayload {
+    biomarkers: ExtractedBiomarker[];
+}
+
+/**
+ * Converte grandezas já conferidas no envelope que o `fhir-bio convert` come.
+ *
+ * O laudo e o paciente não vêm do modelo: o contrato de extração cobre só as
+ * grandezas. Os dois saem daqui com valores sintéticos e óbvios, na mesma
+ * linha do `fhir-rnds-sandbox`, para a demo rodar de ponta a ponta sem inventar
+ * identidade de ninguém. Quem integra de verdade troca os dois pelo que já tem.
+ */
+interface LabResultEnvelope {
+    observations: {
+        biomarkerCode: string;
+        biomarkerName: string;
+        flag: 'H' | 'L' | '';
+        referenceMax?: number;
+        referenceMin?: number;
+        reportId: string;
+        unit: string;
+        value: number | string;
+    }[];
+    profile: {
+        name: string;
+        userId: string;
+    };
+    report: {
+        collectionDate: string;
+        createdAt: string;
+        overallStatus: 'ANORMAL' | 'NORMAL';
+        processingStatus: 'complete';
+        reportId: string;
+        userId: string;
+    };
+}
+interface ToLabResultOptions {
+    collectionDate?: string;
+    reportId?: string;
+    userId?: string;
+}
+declare function extractionToLabResult(biomarkers: ExtractedBiomarker[], options?: ToLabResultOptions): LabResultEnvelope;
+
+/**
+ * Conferência da saída do modelo contra o contrato e contra a ancoragem.
+ *
+ * São duas checagens, e as duas são determinísticas:
+ *
+ * 1. **Forma.** O objeto bate com `LAB_EXTRACTION_SCHEMA`. Modelo que devolve
+ *    texto solto, campo faltando ou tipo errado é recusado aqui, o que deixa
+ *    a qualidade do modelo virar problema de cobertura e nunca de correção.
+ * 2. **Ancoragem.** O código veio da lista que a varredura liberou. Código que
+ *    o laudo não mencionou é descartado, que é a falha cara: um valor
+ *    plausível pendurado num exame que não estava na página.
+ *
+ * A validação de citação, a correção de código contra nome impresso e a
+ * política de confiança não moram aqui.
+ *
+ * Sem dependência de runtime além do `@precisa-saude/fhir`: a checagem de
+ * forma é escrita à mão porque o schema é pequeno e o pacote não carrega
+ * validador de JSON Schema.
+ */
+/** Por que uma grandeza foi recusada. */
+type RejectionReason = 'not-anchored' | 'schema';
+interface RejectedBiomarker {
+    /** Mensagem legível, já em pt-BR, dizendo o que falhou. */
+    detail: string;
+    /** O que o modelo devolveu, sem alteração, para o consumidor poder logar. */
+    raw: unknown;
+    reason: RejectionReason;
+}
+interface ExtractionValidationResult {
+    accepted: ExtractedBiomarker[];
+    /** Erros do objeto inteiro, quando nem dá para chegar nas grandezas. */
+    errors: string[];
+    rejected: RejectedBiomarker[];
+    /** `true` quando o objeto tem forma válida, mesmo que toda grandeza caia. */
+    valid: boolean;
+}
+interface ValidateExtractionOptions {
+    /**
+     * Resultado da ancoragem sobre o mesmo texto que foi ao modelo. Sem ele a
+     * checagem de ancoragem não roda e só a forma é conferida, que é um modo
+     * deliberadamente mais fraco: serve para inspecionar saída de modelo sem o
+     * laudo em mãos.
+     */
+    anchors?: AnchorResult;
+}
+/**
+ * Confere a saída de um modelo contra o contrato e, quando a ancoragem é
+ * fornecida, contra a lista de códigos que a varredura liberou.
+ */
+declare function validateExtraction(raw: unknown, options?: ValidateExtractionOptions): ExtractionValidationResult;
+/** Só a lista de grandezas aprovadas, para quem não quer o relatório inteiro. */
+declare function acceptedBiomarkers(raw: unknown, options?: ValidateExtractionOptions): ExtractedBiomarker[];
+
+/**
+ * Cliente mínimo para endpoint compatível com OpenAI.
+ *
+ * Isto é **conveniência, não contrato**. O contrato é o
+ * `LAB_EXTRACTION_SCHEMA`, e o toolkit funciona inteiro sem esta função: quem
+ * integra chama o próprio modelo do jeito que a plataforma dele permitir e
+ * entrega o JSON ao `validateExtraction`. Esta função existe para a demo rodar
+ * de uma ponta à outra sem um `curl` no meio.
+ *
+ * `/v1/chat/completions` é o que praticamente todo mundo fala: LM Studio,
+ * Ollama, llama.cpp, vLLM, OpenRouter, OpenAI, e a Anthropic pelo endpoint de
+ * compatibilidade. Por isso não há SDK de fornecedor aqui, e por isso o pacote
+ * continua sem dependência de runtime: `fetch` é do Node.
+ *
+ * A chave **nunca** entra por argumento de linha de comando, só por variável de
+ * ambiente: argumento fica no histórico do shell e na lista de processos.
+ */
+interface ExtractOptions {
+    apiKey?: string;
+    baseUrl: string;
+    model: string;
+    /**
+     * Modo de saída estruturada. O padrão é negociar sozinho.
+     *
+     * Aqui é onde a compatibilidade quebra de verdade: o LM Studio recusa
+     * `json_object` com 400 e só aceita `json_schema`, a OpenAI aceita os dois,
+     * e servidor mais simples não conhece o campo. Como nenhum valor serve a
+     * todos, a primeira tentativa vai com `json_schema` e, se o servidor recusar,
+     * a segunda vai sem nada. Quem quiser fixar um modo passa ele aqui.
+     *
+     * Vale lembrar que isto mexe em **aproveitamento**, não em correção: saída
+     * malformada é recusada pela conferência de qualquer jeito.
+     */
+    responseFormat?: 'auto' | 'json_object' | 'json_schema' | 'none';
+    /** Milissegundos até desistir. Modelo local frio demora para carregar. */
+    timeoutMs?: number;
+}
+interface ExtractResult {
+    /** O JSON que o modelo devolveu, ainda sem conferência nenhuma. */
+    payload: unknown;
+    /** Texto cru da resposta, guardado para quando o parse falha. */
+    raw: string;
+    tookMs: number;
+}
+/**
+ * Manda o laudo e a lista ancorada ao modelo e devolve o que ele respondeu.
+ *
+ * Não confere nada: a saída vai para o `validateExtraction`, que é onde a
+ * ancoragem é cobrada. Separar os dois é proposital, porque é o que deixa
+ * trocar de modelo sem mexer na parte que garante o resultado.
+ */
+declare function extractWithModel(text: string, options: ExtractOptions): Promise<ExtractResult>;
+
+export { type AnchorMatch, type AnchorResult, CONFIDENCE_AMBIGUOUS, CONFIDENCE_NAME_ONLY, CONFIDENCE_VALUE_ADJACENT, type ExtractOptions, type ExtractResult, type ExtractedBiomarker, type ExtractionPayload, type ExtractionValidationResult, LAB_EXTRACTION_SCHEMA, type LabResultEnvelope, type RejectedBiomarker, type RejectionReason, type ToLabResultOptions, type ValidateExtractionOptions, acceptedBiomarkers, extractWithModel, extractionToLabResult, findBiomarkersInText, getMatchedCodes, validateExtraction };

package/dist/index.d.ts

@@ -55,4 +55,263 @@ declare function findBiomarkersInText(ocrText: string): AnchorResult;
  */
 declare function getMatchedCodes(result: AnchorResult): string[];
 
-export { type AnchorMatch, type AnchorResult, CONFIDENCE_AMBIGUOUS, CONFIDENCE_NAME_ONLY, CONFIDENCE_VALUE_ADJACENT, findBiomarkersInText, getMatchedCodes };
+/**
+ * Contrato de saída para extração de laudo por modelo.
+ *
+ * Este é o **contrato de interoperabilidade**, e não um prompt. Ele descreve a
+ * forma do JSON que qualquer modelo precisa devolver para o resto do toolkit
+ * conseguir conferir e converter o resultado. Não diz como pedir isso ao
+ * modelo, não traz instrução de comportamento e não depende de fornecedor:
+ * quem usa liga do jeito que a plataforma dele permitir (saída estruturada,
+ * gramática, tool use ou simples prompt com validação por cima).
+ *
+ * As descrições são deliberadamente neutras. Regra de comportamento ("nunca
+ * infira", "copie literalmente") é ajuste de prompt, muda de modelo para
+ * modelo e não pertence a um contrato público.
+ *
+ * As descrições são as únicas strings em inglês do pacote, e isso é
+ * deliberado: o schema é contrato de integração lido por quem consome de fora
+ * do Brasil, e uma descrição em pt-BR não ajuda ninguém em Colônia ou Madri.
+ * O resto da documentação segue a regra do ecossistema.
+ *
+ * O campo `sourceText` existe porque é o que torna a conferência possível:
+ * sem o trecho que originou o valor não dá para auditar a extração depois.
+ *
+ * Campo que aceita mais de um tipo usa `anyOf`, e não `type: [...]`. As duas
+ * formas são JSON Schema válido, mas decodificador restrito não engole a
+ * segunda: o LM Studio recusa a geração com `'type' must be a string`. Como o
+ * ponto do contrato é servir a qualquer modelo, vale a forma mais aceita.
+ */
+declare const LAB_EXTRACTION_SCHEMA: {
+    readonly $id: "https://fhir-brasil.dev.br/schemas/lab-extraction.json";
+    readonly $schema: "https://json-schema.org/draft/2020-12/schema";
+    readonly additionalProperties: false;
+    readonly properties: {
+        readonly biomarkers: {
+            readonly description: "The measurements read from the report.";
+            readonly items: {
+                readonly additionalProperties: false;
+                readonly properties: {
+                    readonly confidence: {
+                        readonly description: "Confidence in this reading, from 0 to 1.";
+                        readonly maximum: 1;
+                        readonly minimum: 0;
+                        readonly type: "number";
+                    };
+                    readonly loinc: {
+                        readonly anyOf: readonly [{
+                            readonly type: "string";
+                        }, {
+                            readonly type: "null";
+                        }];
+                        readonly description: "A LOINC code from the allowed list, or null when none of them applies.";
+                    };
+                    readonly name: {
+                        readonly description: "The measurement name as the report prints it.";
+                        readonly type: "string";
+                    };
+                    readonly referenceMax: {
+                        readonly anyOf: readonly [{
+                            readonly type: "number";
+                        }, {
+                            readonly type: "null";
+                        }];
+                        readonly description: "Upper bound of the range printed on the report, or null.";
+                    };
+                    readonly referenceMin: {
+                        readonly anyOf: readonly [{
+                            readonly type: "number";
+                        }, {
+                            readonly type: "null";
+                        }];
+                        readonly description: "Lower bound of the range printed on the report, or null.";
+                    };
+                    readonly sourceText: {
+                        readonly description: "The snippet of the report carrying this measurement and its value.";
+                        readonly type: "string";
+                    };
+                    readonly unit: {
+                        readonly description: "Unit as the report prints it. Empty string when there is none.";
+                        readonly type: "string";
+                    };
+                    readonly value: {
+                        readonly anyOf: readonly [{
+                            readonly type: "number";
+                        }, {
+                            readonly type: "string";
+                        }];
+                        readonly description: "Numeric value, or text for a qualitative result.";
+                    };
+                };
+                readonly required: readonly ["name", "value", "unit", "sourceText", "confidence"];
+                readonly type: "object";
+            };
+            readonly type: "array";
+        };
+    };
+    readonly required: readonly ["biomarkers"];
+    readonly title: "Laboratory report extraction";
+    readonly type: "object";
+};
+/** Uma grandeza como o modelo devolve, antes de qualquer conferência. */
+interface ExtractedBiomarker {
+    confidence: number;
+    loinc?: string | null;
+    name: string;
+    referenceMax?: number | null;
+    referenceMin?: number | null;
+    sourceText: string;
+    unit: string;
+    value: number | string;
+}
+/** O objeto inteiro que o modelo devolve. */
+interface ExtractionPayload {
+    biomarkers: ExtractedBiomarker[];
+}
+
+/**
+ * Converte grandezas já conferidas no envelope que o `fhir-bio convert` come.
+ *
+ * O laudo e o paciente não vêm do modelo: o contrato de extração cobre só as
+ * grandezas. Os dois saem daqui com valores sintéticos e óbvios, na mesma
+ * linha do `fhir-rnds-sandbox`, para a demo rodar de ponta a ponta sem inventar
+ * identidade de ninguém. Quem integra de verdade troca os dois pelo que já tem.
+ */
+interface LabResultEnvelope {
+    observations: {
+        biomarkerCode: string;
+        biomarkerName: string;
+        flag: 'H' | 'L' | '';
+        referenceMax?: number;
+        referenceMin?: number;
+        reportId: string;
+        unit: string;
+        value: number | string;
+    }[];
+    profile: {
+        name: string;
+        userId: string;
+    };
+    report: {
+        collectionDate: string;
+        createdAt: string;
+        overallStatus: 'ANORMAL' | 'NORMAL';
+        processingStatus: 'complete';
+        reportId: string;
+        userId: string;
+    };
+}
+interface ToLabResultOptions {
+    collectionDate?: string;
+    reportId?: string;
+    userId?: string;
+}
+declare function extractionToLabResult(biomarkers: ExtractedBiomarker[], options?: ToLabResultOptions): LabResultEnvelope;
+
+/**
+ * Conferência da saída do modelo contra o contrato e contra a ancoragem.
+ *
+ * São duas checagens, e as duas são determinísticas:
+ *
+ * 1. **Forma.** O objeto bate com `LAB_EXTRACTION_SCHEMA`. Modelo que devolve
+ *    texto solto, campo faltando ou tipo errado é recusado aqui, o que deixa
+ *    a qualidade do modelo virar problema de cobertura e nunca de correção.
+ * 2. **Ancoragem.** O código veio da lista que a varredura liberou. Código que
+ *    o laudo não mencionou é descartado, que é a falha cara: um valor
+ *    plausível pendurado num exame que não estava na página.
+ *
+ * A validação de citação, a correção de código contra nome impresso e a
+ * política de confiança não moram aqui.
+ *
+ * Sem dependência de runtime além do `@precisa-saude/fhir`: a checagem de
+ * forma é escrita à mão porque o schema é pequeno e o pacote não carrega
+ * validador de JSON Schema.
+ */
+/** Por que uma grandeza foi recusada. */
+type RejectionReason = 'not-anchored' | 'schema';
+interface RejectedBiomarker {
+    /** Mensagem legível, já em pt-BR, dizendo o que falhou. */
+    detail: string;
+    /** O que o modelo devolveu, sem alteração, para o consumidor poder logar. */
+    raw: unknown;
+    reason: RejectionReason;
+}
+interface ExtractionValidationResult {
+    accepted: ExtractedBiomarker[];
+    /** Erros do objeto inteiro, quando nem dá para chegar nas grandezas. */
+    errors: string[];
+    rejected: RejectedBiomarker[];
+    /** `true` quando o objeto tem forma válida, mesmo que toda grandeza caia. */
+    valid: boolean;
+}
+interface ValidateExtractionOptions {
+    /**
+     * Resultado da ancoragem sobre o mesmo texto que foi ao modelo. Sem ele a
+     * checagem de ancoragem não roda e só a forma é conferida, que é um modo
+     * deliberadamente mais fraco: serve para inspecionar saída de modelo sem o
+     * laudo em mãos.
+     */
+    anchors?: AnchorResult;
+}
+/**
+ * Confere a saída de um modelo contra o contrato e, quando a ancoragem é
+ * fornecida, contra a lista de códigos que a varredura liberou.
+ */
+declare function validateExtraction(raw: unknown, options?: ValidateExtractionOptions): ExtractionValidationResult;
+/** Só a lista de grandezas aprovadas, para quem não quer o relatório inteiro. */
+declare function acceptedBiomarkers(raw: unknown, options?: ValidateExtractionOptions): ExtractedBiomarker[];
+
+/**
+ * Cliente mínimo para endpoint compatível com OpenAI.
+ *
+ * Isto é **conveniência, não contrato**. O contrato é o
+ * `LAB_EXTRACTION_SCHEMA`, e o toolkit funciona inteiro sem esta função: quem
+ * integra chama o próprio modelo do jeito que a plataforma dele permitir e
+ * entrega o JSON ao `validateExtraction`. Esta função existe para a demo rodar
+ * de uma ponta à outra sem um `curl` no meio.
+ *
+ * `/v1/chat/completions` é o que praticamente todo mundo fala: LM Studio,
+ * Ollama, llama.cpp, vLLM, OpenRouter, OpenAI, e a Anthropic pelo endpoint de
+ * compatibilidade. Por isso não há SDK de fornecedor aqui, e por isso o pacote
+ * continua sem dependência de runtime: `fetch` é do Node.
+ *
+ * A chave **nunca** entra por argumento de linha de comando, só por variável de
+ * ambiente: argumento fica no histórico do shell e na lista de processos.
+ */
+interface ExtractOptions {
+    apiKey?: string;
+    baseUrl: string;
+    model: string;
+    /**
+     * Modo de saída estruturada. O padrão é negociar sozinho.
+     *
+     * Aqui é onde a compatibilidade quebra de verdade: o LM Studio recusa
+     * `json_object` com 400 e só aceita `json_schema`, a OpenAI aceita os dois,
+     * e servidor mais simples não conhece o campo. Como nenhum valor serve a
+     * todos, a primeira tentativa vai com `json_schema` e, se o servidor recusar,
+     * a segunda vai sem nada. Quem quiser fixar um modo passa ele aqui.
+     *
+     * Vale lembrar que isto mexe em **aproveitamento**, não em correção: saída
+     * malformada é recusada pela conferência de qualquer jeito.
+     */
+    responseFormat?: 'auto' | 'json_object' | 'json_schema' | 'none';
+    /** Milissegundos até desistir. Modelo local frio demora para carregar. */
+    timeoutMs?: number;
+}
+interface ExtractResult {
+    /** O JSON que o modelo devolveu, ainda sem conferência nenhuma. */
+    payload: unknown;
+    /** Texto cru da resposta, guardado para quando o parse falha. */
+    raw: string;
+    tookMs: number;
+}
+/**
+ * Manda o laudo e a lista ancorada ao modelo e devolve o que ele respondeu.
+ *
+ * Não confere nada: a saída vai para o `validateExtraction`, que é onde a
+ * ancoragem é cobrada. Separar os dois é proposital, porque é o que deixa
+ * trocar de modelo sem mexer na parte que garante o resultado.
+ */
+declare function extractWithModel(text: string, options: ExtractOptions): Promise<ExtractResult>;
+
+export { type AnchorMatch, type AnchorResult, CONFIDENCE_AMBIGUOUS, CONFIDENCE_NAME_ONLY, CONFIDENCE_VALUE_ADJACENT, type ExtractOptions, type ExtractResult, type ExtractedBiomarker, type ExtractionPayload, type ExtractionValidationResult, LAB_EXTRACTION_SCHEMA, type LabResultEnvelope, type RejectedBiomarker, type RejectionReason, type ToLabResultOptions, type ValidateExtractionOptions, acceptedBiomarkers, extractWithModel, extractionToLabResult, findBiomarkersInText, getMatchedCodes, validateExtraction };