OncoCore AI Clinical Validator

Краткое описание

OncoCore Clinical Validator — гибридный AI inference service для клинического аудита онкологических кейсов.

Сервис принимает текст врача или структурированный Patient JSON, извлекает Patient Schema через multi-provider AI pipeline и проверяет данные через deterministic rule engine.

Модель предназначена для AI-assisted clinical audit: она помогает проверить, соответствует ли выбранная стратегия лечения формализованным клиническим правилам.

Основной pipeline

Doctor text / Patient JSON
        ↓
YandexGPT extraction, if available
        ↓
OpenRouter / Qwen2.5
        ↓
Local ML extractor
        ↓
Fallback rule-based extractor
        ↓
Patient Schema validation
        ↓
Rule Engine
        ↓
Compliance Scoring
        ↓
Validation Report

Что делает модель

Сервис выполняет следующие шаги:

1. Принимает свободный текст врача или структурированный Patient JSON.

2. Извлекает ключевые клинические признаки:

- diagnosis;

- stage;

- biomarkers;

- performed_tests;

- current_therapy;

- line_of_therapy;

- comorbidities.

1. Приводит данные к внутренней Patient Schema.

2. Проверяет данные через rule engine.

3. Рассчитывает compliance_score и risk_level.

4. Возвращает список найденных нарушений и summary.

Основной endpoint

POST /analyze/text

Пример входа

{
  "text": "Пациент 65 лет. Диагноз: NSCLC IV стадии. EGFR positive. Выполнены CT_CHEST, EGFR_TEST и ALK_TEST. Назначен OSIMERTINIB в первой линии терапии."
}

Пример выхода

{
  "status": "success",
  "mode": "doctor",
  "compliance_score": 100,
  "risk_level": "low",
  "summary": {
    "critical": 0,
    "major": 0,
    "minor": 0
  },
  "ai_powered": true,
  "violations": [],
  "structured_patient": {
    "diagnosis": "NSCLC",
    "stage": "IV",
    "biomarkers": {
      "EGFR": "positive"
    },
    "performed_tests": [
      "ALK_TEST",
      "CT_CHEST",
      "EGFR_TEST"
    ],
    "current_therapy": [
      "OSIMERTINIB"
    ],
    "line_of_therapy": 1,
    "comorbidities": []
  },
  "extraction_source": "open_source_llm_extractor"
}

Архитектура

Решение включает:

- FastAPI backend;

- Docker-ready запуск;

- Patient Schema validation;

- deterministic rule engine;

- compliance scoring;

- OpenRouter / Qwen2.5 extractor;

- local ML extractor;

- fallback rule-based extractor;

- synthetic golden demo cases;

- assert-based тесты.

Поддерживаемые источники извлечения данных

Для endpoint /analyze/text используется устойчивый multi-provider pipeline:

1. YandexGPT extraction, if available
2. OpenRouter / Qwen2.5 through OpenAI-compatible endpoint
3. Local ML extractor
4. Fallback rule-based extractor

Если внешний LLM недоступен, сервис не падает, а автоматически использует локальный ML extractor. Если локальный ML extractor также недоступен, используется fallback rule-based extractor.

Основные файлы проекта

src/
├── api.py                  # FastAPI endpoints
├── models.py               # Patient Schema
├── engine.py               # Rule-based validation engine
├── scoring.py              # Compliance scoring
├── service.py              # Report generation pipeline
├── ai_service.py           # External AI extraction / explanation layer
├── ml_extractor.py         # Local ML extraction runtime
└── oss_llm_extractor.py    # Open-source LLM endpoint provider

data/
├── rules.json              # Clinical validation rules
├── error_weights.json      # Weights for scoring
├── normalized_codes.json   # Normalized codes and dictionaries
├── tests.json              # MVP test cases
└── demo_cases.json         # Golden synthetic demo cases

models/
├── local_text_extractor.joblib
└── model_metadata.json

Запуск локально

1. Установка зависимостей

pip install -r requirements.txt

2. Запуск API

uvicorn src.api:app --host 0.0.0.0 --port 8000

После запуска:

http://localhost:8000
http://localhost:8000/docs
http://localhost:8000/health

Запуск через Docker

docker compose up --build

Проверка:

GET http://localhost:8000/health
POST http://localhost:8000/analyze/text

Остановка:

docker compose down

Environment variables

Для OpenRouter / Qwen2.5 используется OpenAI-compatible endpoint.

Пример `.env`:

OSS_LLM_ENABLED=true
OSS_LLM_PROVIDER=openai_compatible
OSS_LLM_BASE_URL=https://openrouter.ai/api/v1
OSS_LLM_API_KEY=your_openrouter_key_here
OSS_LLM_MODEL=qwen/qwen-2.5-7b-instruct
OSS_LLM_TIMEOUT=90

Реальные секреты не должны попадать в Git и публичные архивы.

Запрещено публиковать:

.env
api_key.txt
env.yaml
.git_old
*.key
*.pem
*.secret

Проверка

Проект проверен локально и через Docker.

Основные проверки:

python run_tests.py
python -m json.tool data/demo_cases.json
docker compose up --build

Результат тестов:

All tests passed: 6/6

Также подготовлены golden synthetic demo cases в файле:

data/demo_cases.json

Версия

v1.1.0-mvp

В этой версии добавлена поддержка OpenRouter / Qwen2.5 через OpenAI-compatible endpoint.

Ограничения

Сервис не ставит диагноз, не назначает лечение и не заменяет врача.

Он используется как AI-assisted audit / validation tool для поддержки проверки медицинской документации.

Текущий MVP сфокусирован на NSCLC и synthetic/demo cases. Rule engine работает только с формализованными правилами, включёнными в текущую версию проекта.

Responsible use

Результаты сервиса должны интерпретироваться специалистом.

Сервис предназначен для демонстрации clinical audit pipeline и не должен использоваться как единственный источник клинического решения.

Теги: гравитация, healthcare, oncology, NLP, clinical-audit, qwen, fastapi