Minos Health

Minos

Minos is an explainable settlement intelligence platform for Polish hospital care. It combines versioned medical terminology (Polish ICD-10 and ICD-9 PL) with the NFZ JGP hospital grouping system: the group definitions, point catalogs, and grouper algorithm that determine how Polish hospitals are paid.

In Dante's Inferno, Minos hears each case in full and assigns it to its circle. That is what a DRG grouper does, and this one shows its reasoning.

The repository and command use the short name minos. Minos is the provisional public brand pending trademark counsel review; a registry pre-screen was performed on 2026-08-06 (see decisions).

Product Layers

1. Terminology: icd10-pl and icd9-pl with deterministic, fast search and full source provenance.
2. JGP knowledge base: groups, grouping conditions, directional ICD lists, age and length-of-stay rules, point values, and version-to-version diffs, ingested from NFZ normative acts.
3. Grouper engine: deterministic evaluation of the reviewed supported rules, with points, source-linked traces and bounded near misses. Unsupported rules remain undetermined rather than being guessed into an answer.

Delivery Status (2026-10-19)

The public validation site serves terminology/JGP search, dated group and code pages, the stepped encounter builder at minoshealth.pl/gruper, and a public MCP server for agents at https://minoshealth.pl/mcp (documentation), listed in the official MCP Registry as pl.minoshealth/mcp. The latest recorded verified validation deployment is b0dee0d (activated 2026-10-19T11:42:10Z, bundle 5cea0d5d unchanged) with the patched NGINX 1.31.7 edge base (#197). 2b6e26b activated blue/green API colours earlier that day (#192): no Uptime Kuma down beat, with an accepted ~24-second edge window. Both needed one retry after a rolled-back startup exit (#198). fda0788 (#191) passed all 102 site audit checks. f9a0a72 added MODTAR generation 103, the 2026-10-13 knowledge horizon (#184) and faster API startup (#189); 736ba9f added source filters, sharing and bounded startup readiness, and #171/#172 (088f190) initial source HTML and durable RSK/BAW citations. The schema-10 bundle and release-pinned concept JSON remain available. Reviewed MODTAR binding, governing-act settlement-product exclusions, pinned JGP comparisons and NFZ publication metadata are also live. Deployment evidence records the recovery, API, browser, privacy and exact-digest checks, including the owner-approved one-off startup wait after guarded recovery. This is a dated acceptance record, not a new production inspection.

Startup warm-up reliability (#157), guarded recovery diagnostics (#162), NFZ publication metadata (#92) and concept JSON (#23) are delivered and closed. The no-JS source-catalog and durable RSK/BAW citation slice from PR #171 passed production recovery and public/browser acceptance; source filters, sorting and shareable views followed at 736ba9f (#185), and broader #80 remains open. Bounded startup readiness (#181) passed its first production activation. Actions usage is measured in #174; full CI runs on every push to main again since #272.

The initial golden suite has 9 synthetic and 5 pinned-source derived cases. Practitioner builder acceptance (#158), real ward agreement (#38), and full signed-release/capacity acceptance remain open; open work is tracked in GitHub issues.

Roadmap

Phase	Ships
0 watchers	Daily source watchers, scoped raw snapshot archive, reviewed data-update PRs. Runs before product code because upstream file sets and reused URLs can change without useful validators and prior public bytes may become undiscoverable.
v0.0.1 foundation	Bitemporal store, terminology and JGP knowledge base, search, CLI, read-only HTTP API, anonymous web browser with version diffs.
v0.0.2 grouper	Encounter grouping with points, full rule trace, and near-miss reporting.
v0.0.3 optimizer	What-if simulation framed as coding completeness and rejection prevention.

Drug products, substitutions, reimbursement contracts in PLN, clinical recommendations, and international ICD variants are outside these releases. They may become separately namespaced modules after source and licensing validation. The data model is designed so additional markets (WHO classifications, other DRG systems) arrive as new namespaced terminology systems, grouping schemes, and tariff schedules rather than schema changes.

Architecture

Minos is one Python 3.14 distribution with strict internal package boundaries:

• minos.domain: synchronous domain types, normalization, ranking, and errors;
• minos.store: read-only persistence and indexed search through SQLite/FTS5;
• minos.ingest: hardened source parsing and reproducible artifact builds;
• minos.cli: data build/diff, offline lookup and grouping commands;
• minos.http: bounded FastAPI endpoints and privacy-safe telemetry;
• minos.grouper: versioned grouping engine evaluating encounter facts against rules-as-data.

The validation deployment uses immutable linux/amd64 API, edge, and watcher images. Docker Compose runs the complete stack locally and on a dedicated Mikr.us 3.0 host; Cloudflare Tunnel is its only public ingress. Validation mounts a separately checksum-verified read-only SQLite bundle into the API; the edge image contains the static web artifact. The full signed product-release contract remains #41/#27. Offline CLI distributions bundle the Python runtime and use the same generated database.

The watcher container runs APScheduler and a separate mutable control SQLite database. It stores exact raw bytes and revisioned control-database recovery images in a private Cloudflare R2 bucket (#200). GitHub-hosted Actions build and test the images but do not run production schedules. Collectors in issues #6-#8 emit change records. Reviewed updates use the guarded validation-deploy tool. Unattended selection, activation and detailed incident delivery resumed in #141 on 2026-10-20 and are not yet enabled; #21 is closed as superseded, not delivered. Watcher failure pushes name a fixed failure category, such as source_drift. A host processor judges each new RSK ICD-10 or CZS ICD-9 file against the live bundle every six hours and reports the verdict to a separate Kuma monitor; it activates nothing yet.

Offline minos data diff compares explicitly pinned terminology, catalog and conditions releases in verified bundle directories, with bounded Markdown/JSON reports. See the CLI contract and validation evidence.

The same Mikr.us host also runs self-hosted Uptime Kuma 2.5.5 at status.minoshealth.pl. Its public page is limited to coarse service state; detailed watcher state remains private through minos watcher status, with issue #54 reserved for a future private detailed admin portal. This replaces a paid external monitoring SaaS, not the need for monitoring. Because Kuma shares the host, it cannot detect or notify for a total Mikr.us host, network, or power outage. This limitation is accepted for now.

The initial service remains anonymous. The accepted later client direction is one installable responsive PWA that can synchronize a verified immutable SQLite reference snapshot for offline use. Future individual calculations are authorized and metered online; premium offline calculation is licensed separately to an organization or hospital. Accounts, payments, usage storage, and exact commercial terms are not part of v0.0.1.

See the v0.0.1 documentation for accepted decisions and the implementation plan.

Development

Install the pinned Python runtime and all development tools from a clean checkout:

uv sync --all-groups
uv run minos --version

Ruff, BasedPyright, mypy, and pytest are pinned in uv.lock. Terminal and Neovim integration is documented in CONTRIBUTING.md. Security, correctness, and measured performance are co-equal release requirements. Evidence-based tradeoffs and representative benchmarks are required, while developer convenience follows those requirements. Critical paths receive targeted mutation and integration testing.

Offline reference commands and their bounded JSON/exit-code contract are in offline-search.md. Local full-source and standalone evidence is in the search validation. The website exposes reference search and grouping under the public-validation exception; source redistribution and signed product promotion retain their separate review gates.

The deployed validation Compose stack serves the API and web edge through Cloudflare Tunnel alongside the watchers and Uptime Kuma. The watcher foundation includes an executable UTC scheduler, fenced SQLite control transactions, local and R2 archives, revisioned recovery images, signed trusted-recovery inventories, a read-only watcher status command, preflight commands, a hardened watcher image, bounded local Docker logs, and local Compose. The RSK collector is registered in the runtime, but a fresh control volume must be initialized explicitly before the watcher starts.

Local runtime commands are:

docker compose build watcher
docker compose --profile bootstrap run --rm --no-deps watcher-bootstrap-rsk
docker compose --profile preflight run --rm --no-deps watcher-preflight
docker compose up --detach watcher
docker compose exec --no-TTY watcher /app/.venv/bin/minos watcher status --json
docker compose logs --since 24h --tail 500 --timestamps watcher

Use minos watcher status [SOURCE_ID] --json to inspect one configured source. The status path opens control SQLite read-only. These host-local status and log commands do not detect a complete Mikr.us host, network, or power outage from outside its fault domain.

Uptime Kuma setup and the two-stage public-route bootstrap are documented in the Ansible runbook. The operator created its admin account and 2FA, configured a private status page and paused watcher push monitor, tested a Telegram alert from Kuma, and stored a stopped integrity-checked off-host backup in 1Password on 2026-09-23. An isolated Docker restore of that backup passed against the same pinned image without network or host ports. Two operational gates remain open: the complete empty-host recovery drill (#49) and launch-capacity load acceptance (#42). Load objectives and the measurements so far are in the API load record.

The site reaches the host only through the Cloudflare Tunnel. SSH, the one management path, runs over a Tailscale tailnet with no public listener since 2026-10-23 (#227); the cutover is in the Ansible runbook.

Object storage is one EU-jurisdiction Cloudflare R2 bucket whose lock rules refuse overwrites and deletes; the AWS stacks and their acceptance harness were retired in #200. Mikr.us activation and restore drills remain explicit operator approval gates.

Data

All sources are public. Details, endpoints, and polling procedures live in data sources; the legal analysis lives in data and licensing.

Dataset	Source
JGP group catalog, characteristics, coefficients	Zarządzenia Prezesa NFZ (leczenie szpitalne), via https://baw.nfz.gov.pl
JGP grouper algorithm and procedure ranks	NFZ komunikaty JGP
ICD-9 PL	NFZ dictionary downloads and https://slowniki.nfz.gov.pl
ICD-10 PL	RSK resource HCD 00CD10, https://rsk3.ezdrowie.gov.pl
ICD-11 PL (pre-released) and WHO ICD-10/ICD-11 tables	RSK resource HCD 99ICD1, CC BY-ND 4.0
JGP utilization statistics	https://api.nfz.gov.pl (open data, attribution required)

Source snapshots and generated databases are artifacts, not repository materials, and must not be committed to Git. The repository therefore holds no datasets and no deployment credentials: the test suite runs on synthetic fixtures (uv run pytest), and running the site locally (scripts/run_local_site.py) needs a reference bundle you build from the public sources with the offline commands. Every generated dataset carries source identity, timestamps, checksums, transformation version, attribution, and required notices.

Safety, Compliance, And Privacy

Minos is a reference and settlement-analysis tool, not medical advice, diagnosis, treatment, or a substitute for professional judgement.

The compliance boundary is explicit: Minos supports complete and correct coding of what was actually performed and documented, and prevention of avoidable claim rejections. It must not recommend coding beyond documentation. Grouping results are expressed in points and product codes; contractual PLN amounts depend on payer contracts and are out of scope.

The public service is anonymous. Logs must not contain raw medical search queries, encounter payloads, patient data, prescriptions, credentials, or other personal data. Grouping (from v0.0.2) is stateless: encounter inputs are evaluated and discarded, never stored.

Licensing

Repository software, infrastructure, tests, and documentation are licensed under either Apache-2.0 or MIT, at your option. Dataset artifacts remain under their source terms. NFZ normative acts and their appendices are treated as copyright-exempt official materials under Art. 4 of Polish copyright law (formal legal opinion pending); the RSK Polish ICD-10 resource identifies CC BY-NC-SA 3.0 IGO. See NOTICE.md and data and licensing.

Status

Minos is in active public validation. No version tags or GitHub Releases have been published; exact-digest validation deployments are tracked separately from the full signed product-release gates in #41/#27. See CHANGELOG.md for unreleased changes, SPEC.md for the implementation baseline and GitHub issues for open work.

Contributing

See CONTRIBUTING.md before opening an issue or pull request.