med-pdf-nmo 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 med-pdf-nmo contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,298 @@
+# med-pdf-nmo
+
+[Русская версия](./README.ru.md)
+
+`med-pdf-nmo` is a browser-first JavaScript/Node.js package that selects the most likely answer, or answer set, for NMO-style medical questions using a source PDF with clinical recommendations.
+
+The runtime is fully local and non-LLM. It does not use ChatGPT, OpenAI, Anthropic, Gemini, HuggingFace inference, transformer models, or any external AI service. The predictor is based on PDF text extraction, normalization, lexical search, structural heuristics, scoring, and evidence snippets from the PDF.
+
+## What It Does
+
+- Accepts a medical recommendations PDF, a question, and answer variants.
+- Extracts PDF text with `pdfjs-dist`.
+- Normalizes Russian medical text, PDF artifacts, Greek letters, numeric references, dosage forms, and common OCR quirks.
+- Scores every answer using local evidence from the PDF.
+- Supports both `single` and `multi` questions.
+- Returns selected answers, confidence, per-answer scores, raw scores, evidence snippets, and PDF metadata.
+- Works in Node.js, browser bundles, and Chrome-extension style environments.
+
+## Current Accuracy
+
+These numbers come from the local keyed validation corpus. They are not a guarantee for every new PDF, but they are the current reference quality after the final test run.
+
+| Dataset | Exact accuracy | Single-answer | Multi-answer exact set |
+| --- | ---: | ---: | ---: |
+| All keyed cases | `73.53%` (`2069/2814`) | `81.17%` (`1573/1938`) | `56.62%` (`496/876`) |
+| Holdout split | `83.79%` (`486/580`) | `87.39%` | `72.92%` |
+| Dev split | `77.14%` (`388/503`) | `83.09%` | `63.64%` |
+
+For `single`, only one exact selected answer is counted as correct. For `multi`, the selected set must exactly match the full expected set, so the metric is naturally stricter.
+
+## Installation
+
+From npm, once published:
+
+```bash
+npm install med-pdf-nmo
+```
+
+Directly from a Git HTTPS URL:
+
+```bash
+npm install git+https://github.com/lKolabrodl/med-pdf-nmo.git#main
+```
+
+Or in `package.json`:
+
+```json
+{
+  "dependencies": {
+    "med-pdf-nmo": "git+https://github.com/lKolabrodl/med-pdf-nmo.git#main"
+  }
+}
+```
+
+When installed from Git, npm runs `prepare`, so the package builds `dist` during installation.
+
+## Browser / React / Chrome Extension
+
+Use the browser entrypoint when your app runs in a browser-like environment:
+
+```ts
+import { answerQuestion } from "med-pdf-nmo/browser";
+
+const result = await answerQuestion(new Uint8Array(pdfData.slice(0)), {
+  question,
+  variants,
+  type: isSingle ? "single" : "multi",
+});
+```
+
+The browser entrypoint bundles and registers PDF.js internally. In normal React, Vite, Webpack, and Chrome-extension usage you do not need to import `pdfjs-dist`, configure `GlobalWorkerOptions.workerSrc`, or pass `pdfjsLib` into every call.
+
+## Browser Script Tag
+
+For direct browser usage, load the IIFE bundle:
+
+```html
+<script src="./dist/med-pdf-nmo.browser.js"></script>
+```
+
+Then call the global object:
+
+```html
+<input id="pdf" type="file" accept="application/pdf" />
+
+<script>
+  document.querySelector("#pdf").addEventListener("change", async (event) => {
+    const file = event.target.files[0];
+
+    const result = await MedPdfNmo.answerQuestion(file, {
+      question: "Question text",
+      variants: ["Answer A", "Answer B", "Answer C"],
+      type: "single"
+    });
+
+    console.log(result.selectedIds, result.selected, result.confidence);
+  });
+</script>
+```
+
+For public GitHub repositories, CDN usage is also possible:
+
+```html
+<script src="https://cdn.jsdelivr.net/gh/lKolabrodl/med-pdf-nmo@main/dist/med-pdf-nmo.browser.js"></script>
+```
+
+## Node.js
+
+```js
+import fs from "node:fs/promises";
+import { answerQuestion } from "med-pdf-nmo";
+
+const pdfBuffer = await fs.readFile("./doc.pdf");
+
+const result = await answerQuestion(pdfBuffer, {
+  question: "Which drug is recommended?",
+  variants: ["Answer A", "Answer B", "Answer C", "Answer D"],
+  type: "single"
+});
+
+console.log(result.selectedIds);
+console.log(result.selected);
+console.log(result.confidence);
+console.log(result.evidence);
+```
+
+In Node.js, the PDF input can be a `Buffer`, `Uint8Array`, `ArrayBuffer`, or URL string.
+
+## API
+
+### `answerQuestion(pdf, options)`
+
+```ts
+const result = await answerQuestion(pdf, {
+  question: "Question text",
+  variants: ["Answer A", "Answer B", "Answer C"],
+  type: "single"
+});
+```
+
+`pdf` can be:
+
+- `File`
+- `Blob`
+- `Buffer`
+- `ArrayBuffer`
+- `Uint8Array`
+- URL string
+- any object with `arrayBuffer()`
+
+`options`:
+
+- `question`: question text.
+- `variants`: answer variants.
+- `answers`: alias for `variants`.
+- `type`: `"single"` or `"multi"`.
+- `mode`: alias for `type`.
+- `cacheKey`: optional PDF text cache key.
+- `pdfjsLib`: optional explicit PDF.js module override.
+
+Variants can be plain strings:
+
+```js
+variants: ["Answer A", "Answer B", "Answer C"]
+```
+
+Or objects with stable IDs:
+
+```js
+variants: [
+  { id: "A", text: "Answer A" },
+  { id: "B", text: "Answer B" },
+  { id: "C", text: "Answer C" }
+]
+```
+
+### Result Shape
+
+```js
+{
+  selected: ["Answer B"],
+  selectedIds: ["B"],
+  mode: "single",
+  confidence: 0.73,
+  scores: [
+    { id: "A", variant: "Answer A", score: 0.12, raw: 0.41 },
+    { id: "B", variant: "Answer B", score: 0.73, raw: 1.92 }
+  ],
+  evidence: [],
+  meta: {},
+  raw: {}
+}
+```
+
+Important fields:
+
+- `selected`: selected answer texts.
+- `selectedIds`: selected answer IDs.
+- `confidence`: relative confidence for the selected answer or set.
+- `scores`: calibrated and raw score per variant.
+- `evidence`: PDF snippets used by the scorer.
+- `raw`: low-level predictor output.
+
+## Multi-Answer Questions
+
+```js
+const result = await answerQuestion(pdfBuffer, {
+  question: "Which statements are correct?",
+  variants: [
+    { id: "A", text: "Statement A" },
+    { id: "B", text: "Statement B" },
+    { id: "C", text: "Statement C" },
+    { id: "D", text: "Statement D" }
+  ],
+  type: "multi"
+});
+```
+
+`selectedIds` will contain all selected answer IDs.
+
+## Low-Level Exports
+
+```js
+import {
+  predict,
+  answerQuestion,
+  setPdfJsLib,
+  clearPredictorCache
+} from "med-pdf-nmo";
+```
+
+- `answerQuestion`: convenient high-level API.
+- `predict`: low-level predictor API.
+- `setPdfJsLib`: explicit PDF.js configuration hook.
+- `clearPredictorCache`: clears the runtime predictor cache.
+
+## CLI
+
+After installation, the package provides:
+
+```bash
+med-pdf-nmo --help
+```
+
+Example:
+
+```bash
+med-pdf-nmo --pdf doc.pdf --question "Question text" --mode single --answer A="Answer A" --answer B="Answer B"
+```
+
+Local development:
+
+```bash
+npm run predict -- --pdf doc.pdf --question "Question text" --mode single --answer A="Answer A" --answer B="Answer B"
+```
+
+## Build
+
+```bash
+npm install
+npm run build
+```
+
+Build outputs:
+
+- `dist/index.js`: main ESM entrypoint.
+- `dist/index.d.ts`: TypeScript declarations.
+- `dist/med-pdf-nmo.browser.js`: browser global bundle with `MedPdfNmo`.
+- `dist/med-pdf-nmo.browser.mjs`: browser ESM bundle with PDF.js included.
+- `dist/browser-shims/*`: browser alias targets for Node built-ins.
+- `dist/cli.js`: CLI entrypoint.
+
+## Development Checks
+
+```bash
+npm test
+npm run typecheck
+npm run build
+npm pack --dry-run
+npm run eval
+npm run eval:holdout
+```
+
+`npm run eval` and `npm run eval:holdout` are development-only quality checks. They read local test PDFs and answer keys to calculate accuracy.
+
+The runtime package API does not read eval files, split files, answer keys, or test fixtures during inference.
+
+## Limitations
+
+- This package is not medical advice and does not replace expert review.
+- Quality depends on how well PDF.js extracts text from a specific PDF.
+- Scanned PDFs without a text layer may require OCR before being passed to the package.
+- The algorithm selects likely answers from PDF evidence, but it cannot guarantee absolute correctness.
+- Runtime inference is non-LLM and does not call external intelligent services.
+
+## License
+
+MIT. See [LICENSE](./LICENSE).

package/README.ru.md

@@ -0,0 +1,298 @@
+# med-pdf-nmo
+
+[English README](./README.md)
+
+`med-pdf-nmo` - browser-first JavaScript/Node.js пакет, который выбирает наиболее вероятный ответ или набор ответов на НМО-вопрос по PDF-файлу с медицинскими или клиническими рекомендациями.
+
+Runtime работает локально и не использует LLM. В inference нет ChatGPT, OpenAI API, Anthropic, Gemini, HuggingFace inference, transformer-моделей или внешних интеллектуальных сервисов. Алгоритм основан на извлечении текста PDF, нормализации, поиске, структурных эвристиках, скоринге и evidence-фрагментах из PDF.
+
+## Что делает пакет
+
+- Принимает PDF медицинских рекомендаций, вопрос и варианты ответа.
+- Извлекает текст из PDF через `pdfjs-dist`.
+- Нормализует русский медицинский текст, PDF-артефакты, греческие буквы, числовые ссылки, дозировки и частые OCR-искажения.
+- Считает score для каждого варианта ответа.
+- Поддерживает `single` и `multi` вопросы.
+- Возвращает выбранные ответы, confidence, score по вариантам, raw score, evidence из PDF и метаданные.
+- Работает в Node.js, browser bundle и Chrome-extension окружениях.
+
+## Текущие метрики
+
+Цифры получены на локальном корпусе PDF-групп с answer key. Это не гарантия качества на любом новом PDF, а текущий ориентир после финального прогона.
+
+| Набор | Exact accuracy | Single-answer | Multi-answer exact set |
+| --- | ---: | ---: | ---: |
+| Все keyed cases | `73.53%` (`2069/2814`) | `81.17%` (`1573/1938`) | `56.62%` (`496/876`) |
+| Holdout split | `83.79%` (`486/580`) | `87.39%` | `72.92%` |
+| Dev split | `77.14%` (`388/503`) | `83.09%` | `63.64%` |
+
+Для `single` правильным считается только точный выбор одного ответа. Для `multi` правильным считается только полное совпадение множества ответов, поэтому multi-метрика строже и обычно ниже.
+
+## Установка
+
+Из npm, когда пакет опубликован:
+
+```bash
+npm install med-pdf-nmo
+```
+
+Напрямую из Git HTTPS URL:
+
+```bash
+npm install git+https://github.com/lKolabrodl/med-pdf-nmo.git#main
+```
+
+Или в `package.json`:
+
+```json
+{
+  "dependencies": {
+    "med-pdf-nmo": "git+https://github.com/lKolabrodl/med-pdf-nmo.git#main"
+  }
+}
+```
+
+При установке из Git npm выполнит `prepare`, поэтому пакет сам соберет `dist`.
+
+## Browser / React / Chrome Extension
+
+Для браузерного окружения используй browser entrypoint:
+
+```ts
+import { answerQuestion } from "med-pdf-nmo/browser";
+
+const result = await answerQuestion(new Uint8Array(pdfData.slice(0)), {
+  question,
+  variants,
+  type: isSingle ? "single" : "multi",
+});
+```
+
+Browser entrypoint уже содержит и регистрирует PDF.js внутри пакета. В обычном React, Vite, Webpack или Chrome-extension коде не нужно отдельно импортировать `pdfjs-dist`, настраивать `GlobalWorkerOptions.workerSrc` или передавать `pdfjsLib` в каждый вызов.
+
+## Подключение через script tag
+
+Для прямого подключения в браузере:
+
+```html
+<script src="./dist/med-pdf-nmo.browser.js"></script>
+```
+
+Глобальный объект:
+
+```html
+<input id="pdf" type="file" accept="application/pdf" />
+
+<script>
+  document.querySelector("#pdf").addEventListener("change", async (event) => {
+    const file = event.target.files[0];
+
+    const result = await MedPdfNmo.answerQuestion(file, {
+      question: "Текст вопроса",
+      variants: ["Ответ A", "Ответ B", "Ответ C"],
+      type: "single"
+    });
+
+    console.log(result.selectedIds, result.selected, result.confidence);
+  });
+</script>
+```
+
+Для публичного GitHub-репозитория можно использовать CDN:
+
+```html
+<script src="https://cdn.jsdelivr.net/gh/lKolabrodl/med-pdf-nmo@main/dist/med-pdf-nmo.browser.js"></script>
+```
+
+## Node.js
+
+```js
+import fs from "node:fs/promises";
+import { answerQuestion } from "med-pdf-nmo";
+
+const pdfBuffer = await fs.readFile("./doc.pdf");
+
+const result = await answerQuestion(pdfBuffer, {
+  question: "Какой препарат показан пациенту?",
+  variants: ["Ответ A", "Ответ B", "Ответ C", "Ответ D"],
+  type: "single"
+});
+
+console.log(result.selectedIds);
+console.log(result.selected);
+console.log(result.confidence);
+console.log(result.evidence);
+```
+
+В Node.js PDF можно передавать как `Buffer`, `Uint8Array`, `ArrayBuffer` или URL-строку.
+
+## API
+
+### `answerQuestion(pdf, options)`
+
+```ts
+const result = await answerQuestion(pdf, {
+  question: "Текст вопроса",
+  variants: ["Ответ A", "Ответ B", "Ответ C"],
+  type: "single"
+});
+```
+
+`pdf` может быть:
+
+- `File`
+- `Blob`
+- `Buffer`
+- `ArrayBuffer`
+- `Uint8Array`
+- URL-строка
+- объект с методом `arrayBuffer()`
+
+`options`:
+
+- `question`: текст вопроса.
+- `variants`: варианты ответа.
+- `answers`: алиас для `variants`.
+- `type`: `"single"` или `"multi"`.
+- `mode`: алиас для `type`.
+- `cacheKey`: необязательный ключ кеша для текста PDF.
+- `pdfjsLib`: необязательная явная передача PDF.js модуля.
+
+Варианты можно передавать строками:
+
+```js
+variants: ["Ответ A", "Ответ B", "Ответ C"]
+```
+
+Или объектами со стабильными ID:
+
+```js
+variants: [
+  { id: "A", text: "Ответ A" },
+  { id: "B", text: "Ответ B" },
+  { id: "C", text: "Ответ C" }
+]
+```
+
+### Результат
+
+```js
+{
+  selected: ["Ответ B"],
+  selectedIds: ["B"],
+  mode: "single",
+  confidence: 0.73,
+  scores: [
+    { id: "A", variant: "Ответ A", score: 0.12, raw: 0.41 },
+    { id: "B", variant: "Ответ B", score: 0.73, raw: 1.92 }
+  ],
+  evidence: [],
+  meta: {},
+  raw: {}
+}
+```
+
+Главные поля:
+
+- `selected`: выбранные тексты ответов.
+- `selectedIds`: ID выбранных ответов.
+- `confidence`: относительная уверенность.
+- `scores`: score по всем вариантам.
+- `evidence`: найденные фрагменты PDF.
+- `raw`: низкоуровневый результат predictor.
+
+## Multi-answer вопросы
+
+```js
+const result = await answerQuestion(pdfBuffer, {
+  question: "Какие утверждения верны?",
+  variants: [
+    { id: "A", text: "Утверждение A" },
+    { id: "B", text: "Утверждение B" },
+    { id: "C", text: "Утверждение C" },
+    { id: "D", text: "Утверждение D" }
+  ],
+  type: "multi"
+});
+```
+
+В `selectedIds` будет массив выбранных ID.
+
+## Низкоуровневые exports
+
+```js
+import {
+  predict,
+  answerQuestion,
+  setPdfJsLib,
+  clearPredictorCache
+} from "med-pdf-nmo";
+```
+
+- `answerQuestion`: удобный высокоуровневый API.
+- `predict`: низкоуровневый predictor API.
+- `setPdfJsLib`: ручная настройка PDF.js.
+- `clearPredictorCache`: очистка runtime-кеша predictor.
+
+## CLI
+
+После установки пакет добавляет команду:
+
+```bash
+med-pdf-nmo --help
+```
+
+Пример:
+
+```bash
+med-pdf-nmo --pdf doc.pdf --question "Текст вопроса" --mode single --answer A="Ответ A" --answer B="Ответ B"
+```
+
+Локально в репозитории:
+
+```bash
+npm run predict -- --pdf doc.pdf --question "Текст вопроса" --mode single --answer A="Ответ A" --answer B="Ответ B"
+```
+
+## Сборка
+
+```bash
+npm install
+npm run build
+```
+
+Сборка создает:
+
+- `dist/index.js`: основной ESM entrypoint.
+- `dist/index.d.ts`: TypeScript-типы.
+- `dist/med-pdf-nmo.browser.js`: браузерный global bundle `MedPdfNmo`.
+- `dist/med-pdf-nmo.browser.mjs`: браузерный ESM bundle с PDF.js внутри.
+- `dist/browser-shims/*`: browser alias targets для Node built-ins.
+- `dist/cli.js`: CLI entrypoint.
+
+## Проверки разработки
+
+```bash
+npm test
+npm run typecheck
+npm run build
+npm pack --dry-run
+npm run eval
+npm run eval:holdout
+```
+
+`npm run eval` и `npm run eval:holdout` - developer tooling. Они читают локальные тестовые PDF и answer key, чтобы посчитать accuracy.
+
+Runtime API пакета во время inference не читает eval-файлы, split-файлы, правильные ответы или тестовые fixtures.
+
+## Ограничения
+
+- Пакет не является медицинским советником и не заменяет эксперта.
+- Качество зависит от того, насколько хорошо PDF.js извлек текст из конкретного PDF.
+- Сканированные PDF без текстового слоя могут потребовать OCR до передачи в пакет.
+- Алгоритм выбирает вероятные ответы по PDF evidence, но не гарантирует абсолютную правильность.
+- Runtime inference не использует LLM и не обращается к внешним интеллектуальным сервисам.
+
+## Лицензия
+
+MIT. Подробнее см. [LICENSE](./LICENSE).

package/dist/bm25.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Документ, сохраненный в поисковом BM25-индексе.
+ *
+ * Чанки predictor добавляют дополнительные метаданные: страницу, тип, текст и id.
+ */
+export type BM25Document = {
+    tokens?: string[];
+    [key: string]: unknown;
+};
+/**
+ * Небольшая реализация BM25 для локального поиска по чанкам PDF.
+ */
+export declare class BM25Index {
+    documents: BM25Document[];
+    k1: number;
+    b: number;
+    docFreq: Map<string, number>;
+    termFreqs: Map<string, number>[];
+    lengths: number[];
+    avgdl: number;
+    /**
+     * Создает индекс для уже токенизированных документов.
+     *
+     * @param documents Документы с необязательными массивами `tokens`.
+     * @param options Параметры настройки BM25.
+     */
+    constructor(documents: BM25Document[], { k1, b }?: {
+        k1?: number;
+        b?: number;
+    });
+    /**
+     * Считает inverse document frequency для одного нормализованного токена.
+     */
+    idf(token: string): number;
+    /**
+     * Считает score токенизированного запроса для одного документа в индексе.
+     */
+    scoreTokens(queryTokens: string[], docIndex: number): number;
+    /**
+     * Ищет по индексу сырой текст или заранее токенизированный запрос.
+     *
+     * @returns Лучшие совпадающие чанки с положительным BM25 score.
+     */
+    search(query: string | string[], { limit }?: {
+        limit?: number;
+    }): any[];
+}