Heltig

Heltig is a non‑diagnostic DICOM Metadata QA & PACS‑Readiness platform. It ingests anonymized imaging studies (ZIP of DICOM), parses metadata only, reconstructs the patient → study → series → instance hierarchy, runs a deterministic QA rules engine, and returns an explainable readiness verdict — Ready / Needs Review / Blocked — per study, with audit‑friendly evidence exports, a versioned REST API, and an operator dashboard.

⚕️ Non‑diagnostic operational QA · anonymized / synthetic data only · not certified medical software. See docs/intended-use-statement.md.

Why it exists: imaging teams hit avoidable failures — missing identifiers, duplicate SOP/series/study objects, broken hierarchies — during PACS/VNA migration and interoperability work, and discover them too late. Heltig shifts that detection left, stamping each study Ready / Needs Review / Blocked before ingestion. Sibling project: FHIRgate applies the same readiness‑gate pattern to HL7 v2 → FHIR (ISiK) conformance.

Current Scope

• FastAPI backend
• PostgreSQL-ready SQLAlchemy persistence layer
• /health endpoint
• /api/v1/jobs/upload ZIP ingestion endpoint
• /api/v1/jobs/upload/async durable queued ZIP ingestion endpoint
  • idempotent replay protection
• safe ZIP extraction with zip-slip protection
• metadata-only DICOM parsing using pydicom
• job, uploaded file, patient, study, series, and instance persistence
• hierarchy reconstruction with missing-UID fallback handling
• deterministic QA rules engine with persisted rule and finding records
• persisted readiness classification per study
• study and finding investigation endpoints with filters
• JSON and HTML study report endpoints
• Streamlit dashboard shell for operator workflows
• lightweight DICOMweb-style metadata export
• lightweight ImagingStudy-like summary export
• optional API-key authentication and RBAC (admin, qa_operator, reviewer)
• optional OIDC authentication mode with role mapping and hybrid fallback
• audit event persistence for auth/report/export/purge/ops actions
• ops metrics and audit endpoints
• SIEM-friendly NDJSON audit export
• retention purge endpoint for uploads/staging/report rows
• DICOMweb pull connector endpoint for external metadata ingestion
• optional Redis queue backend (DB queue remains supported)
• production compose profile and backup/restore scripts
• study-level finding counters
• validation, demo, and release-readiness documentation
• synthetic sample dataset generator for repeatable demos
• pytest test suite for health, ZIP handling, parser behavior, upload flow, hierarchy persistence, rules persistence, investigation APIs, report endpoints, and interoperability exports

Project Layout

app/
  api/
  config/
  dicom_parser/
  exports/
  ingest/
  persistence/
  reporting/
dashboard/
docs/
scripts/
tests/
data/

Reviewer Quick Start

1. Install dependencies: python3 -m pip install -r requirements.txt
2. Start PostgreSQL: docker compose up -d db
3. Start the API: uvicorn app.main:app --reload
4. Generate sample datasets: python3 scripts/generate_sample_datasets.py
5. Run automated async demo flow: python3 scripts/run_demo_async_flow.py
6. Open http://localhost:8000/docs
7. Optionally open the demo dashboard at http://localhost:8501
8. Optional dedicated worker: python3 scripts/run_ingestion_worker.py
9. Optional validation evidence snapshot: python3 scripts/generate_validation_evidence.py --reruns 2
10. Optional full audit pack: python3 scripts/run_audit_pack.py

You can also upload manually through Swagger:

• POST /api/v1/jobs/upload for in-request processing
• POST /api/v1/jobs/upload/async for queued worker processing
  • duplicate async replay (same ZIP + same filename) reuses the existing job reference

Documentation Map

• Product summary: docs/product-overview.md
• Data handling policy: docs/data-handling-policy.md
• Security posture note: docs/security-posture-note.md
• Intended use statement: docs/intended-use-statement.md
• Technical hardening checklist: docs/technical-hardening-checklist.md
• M10 completion report: docs/m10-completion-report.md
• Limitations closure plan: docs/limitations-closure-plan.md
• Limitations acceptance matrix: docs/limitations-acceptance-matrix.md
• Architecture: docs/architecture.md
• API guide: docs/api-guide.md
• Production runbook: docs/production-runbook-v03.md
• Conformance statement: docs/conformance-statement-v03.md
• DICOMweb connector runbook: docs/dicomweb-integration-runbook.md
• Ops integrations guide: docs/ops-integrations-guide.md
• Validation evidence pack: docs/validation-evidence-pack-v03.md
• Security pack v2: docs/security-pack-v2.md
• Incident response runbook: docs/incident-response-runbook.md
• Key management runbook: docs/key-management-runbook.md
• Security questionnaire template: docs/security-questionnaire-template-v2.md
• Audit master checklist: docs/audit-master-checklist-v1.md
• Rule catalog: docs/rule-catalog.md
• Interoperability boundaries: docs/interoperability.md
• Validation plan: docs/validation-plan.md
• Traceability matrix: docs/traceability-matrix.md
• Risks and limitations: docs/risk-and-limitations.md
• Market & competition (2026): docs/market-usefulness-and-competition-2026.md
• 2026+ relevance brief: docs/relevance-2026-and-beyond.md
• Demo flow: docs/demo-script.md
• Release checklist: docs/release-checklist.md

Local Setup

1. Create a virtual environment.
2. Install dependencies from requirements.txt.
3. Copy .env.example to .env if needed.
4. Start PostgreSQL with docker compose up -d db.
5. Run the API with uvicorn app.main:app --reload.
6. Optionally run the dashboard with streamlit run dashboard/streamlit_app.py.
7. Optional dedicated worker loop: python3 scripts/run_ingestion_worker.py

Stop services when not demoing:

• stop API/dashboard: Ctrl+C in each terminal
• stop PostgreSQL container: docker compose stop db

Environment

Important variables:

• DATABASE_URL
• STORAGE_ROOT
• AUTO_CREATE_DB
• API_V1_PREFIX
• APP_SUBTITLE
• PUBLIC_API_BASE_URL
• QUEUE_AUTO_DRAIN_ON_UPLOAD
• QUEUE_BACKEND
• REDIS_URL
• QUEUE_WORKER_BATCH_SIZE
• QUEUE_MAX_ATTEMPTS
• QUEUE_RETRY_DELAY_SECONDS
• QUEUE_POLL_INTERVAL_SECONDS
• AUTH_ENABLED
• AUTH_MODE
• AUTH_API_KEYS
• AUTH_OIDC_ISSUER
• AUTH_OIDC_AUDIENCE
• AUTH_OIDC_JWKS_URL
• AUTH_ALLOW_API_KEY_FALLBACK
• OPS_WEBHOOK_URL
• OPS_WEBHOOK_AUTH_HEADER
• OPS_WEBHOOK_AUTH_TOKEN
• RETENTION_DAYS_UPLOADS
• RETENTION_DAYS_STAGING
• RETENTION_DAYS_REPORTS

Defaults are documented in .env.example.

Test Commands

pytest

If dependencies are not installed yet, install them first:

python3 -m pip install -r requirements.txt

Operational Boundary

This project is for operational DICOM/PACS workflow QA only. It is not diagnostic software and must not be used for diagnosis, triage, treatment recommendation, or clinical decision-making.