Heimdallr

Heimdallr is open-source infrastructure for radiological image operations. It receives DICOM studies and API submissions, prepares selected series for deterministic processing, converts DICOM to NIfTI, orchestrates TotalSegmentator-backed segmentation, computes quantitative metrics, tracks queue state in SQLite, and delivers generated artifacts through operational dashboards, DICOM egress, outbound HTTP events, and final API callbacks.

The name references Heimdall, the vigilant Norse guardian, reflecting this stack's role as an operational watch layer for imaging intake, queues, segmentation, metrics, and artifact delivery.

The stack runs as multiple Python 3.14 entrypoints over one maintained package, heimdallr/. Host-specific configuration is created from versioned config/*.example.json files and kept local. Mutable study artifacts live under runtime/, while queue and case state are persisted in database/dicom.db.

Heimdallr owns the imaging infrastructure layer. Clinical report drafting, LLM/NLP workflows, prompt engineering, and proprietary intelligence belong in Asha or another explicit consumer. Generated outputs are deterministic infrastructure artifacts for qualified review, not autonomous clinical decisions.

Current State

• phase: structural baseline established / validation-oriented operations
• runtime principal: Python >=3.14,<3.15, single .venv
• primary entrypoints:
  • python -m heimdallr.control_plane
  • python -m heimdallr.intake
  • python -m heimdallr.prepare
  • python -m heimdallr.segmentation
  • python -m heimdallr.metrics
  • python -m heimdallr.dicom_egress
  • python -m heimdallr.integration.dispatch
  • python -m heimdallr.integration.delivery
  • python -m heimdallr.space_manager
  • python -m heimdallr.resource_monitor
  • python -m heimdallr.tui
• critical external dependencies:
  • DICOM peers/PACS for C-STORE intake and outbound C-STORE
  • HTTP/API clients for ZIP upload, external job submission, outbound events, and final delivery callbacks
  • dcm2niix for conversion
  • TotalSegmentator for segmentation tasks
  • SQLite filesystem access for queue and case state
  • host supervision (systemd, launchd, skuld, or equivalent)

System Overview

Component Maturity

Component	Real status	Notes
heimdallr.intake	operational	DICOM C-STORE SCP with idle study handoff and duplicate suppression state.
heimdallr.prepare	operational, complex hotspot	ZIP spool watcher, DICOM scan, metadata extraction, conversion, phase detection, queue enqueue.
heimdallr.segmentation	operational, dependency-heavy hotspot	Runs TotalSegmentator tasks from host-local profile; depends on binary/license/GPU or CPU capacity.
heimdallr.metrics	operational, mixed production/experimental surface	Production-facing jobs are enabled through config/metrics_pipeline.example.json; experimental jobs must stay opt-in.
heimdallr.dicom_egress	operational	Queue-driven C-STORE SCU with retry and compression fallback.
heimdallr.integration.dispatch	operational if configured	Delivers patient-identified API events to configured HTTP destinations.
heimdallr.integration.delivery	operational if configured	Sends terminal case.completed or case.failed API callbacks for external submissions.
heimdallr.control_plane	operational	FastAPI dashboard, /upload ingress, /jobs submission API, patient/results API, PDF export. Built-in auth is not present.
heimdallr.tui	operational support tool	Reads SQLite/process state for live operations.
heimdallr.space_manager	operational guardrail	Purges completed study artifacts when configured disk, count, or age retention limits are exceeded.
heimdallr.resource_monitor	operational telemetry	Samples service and case memory state into SQLite.

Repository Layout

Heimdallr/
├── heimdallr/                  # Main package and all production entrypoints
├── config/                     # Versioned JSON defaults and host-local examples
├── database/                   # SQLite schema and database documentation
├── docs/                       # Architecture, contracts, operations, decisions, API
├── desktop/                    # Planned macOS menu bar app, Go daemon, and packaging track
├── scripts/                    # Operational and retroactive maintenance utilities
├── static/                     # Dashboard frontend and branding assets
├── tests/                      # unittest-based coverage for core workers/jobs
├── bin/                        # Bundled conversion/DICOM helper binaries and notices
├── runtime/                    # Mutable runtime state, ignored by Git
├── PROJECT_GATE.md             # Repository existence and boundary gate
├── CHANGELOG.md                # Human-readable project change history
└── AGENTS.md                   # Collaboration protocol for agents and maintainers

External integration code is canonical under heimdallr/integration/:

• integration/dispatch/: outbound JSON event dispatch.
• integration/delivery/: final callback package delivery.
• integration/submissions.py: /jobs submission sidecar contract.
• integration/docs/: consumer-facing contracts for external applications.

Quick Start

1. Clone

2. Prepare environment

python3.14 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
pip install -r requirements.txt

All long-running services should use the same interpreter: .venv/bin/python.

3. Configure

cp config/segmentation_pipeline.example.json config/segmentation_pipeline.json
cp config/metrics_pipeline.example.json config/metrics_pipeline.json
cp config/integration_dispatch.example.json config/integration_dispatch.json
cp config/integration_delivery.example.json config/integration_delivery.json
cp config/dicom_egress.example.json config/dicom_egress.json
cp config/presentation.example.json config/presentation.json
cp config/space_manager.example.json config/space_manager.json
cp config/resource_monitor.example.json config/resource_monitor.json

Only example files are versioned. The concrete host-local files above are ignored by Git. Secrets and host-specific values must be injected by the host environment, not by .env files.

For licensed TotalSegmentator tasks:

.venv/bin/totalseg_set_license -l YOUR_LICENSE_KEY

or inject TOTALSEGMENTATOR_LICENSE through host supervision.

4. Run

.venv/bin/python -m heimdallr.control_plane
.venv/bin/python -m heimdallr.prepare
.venv/bin/python -m heimdallr.segmentation
.venv/bin/python -m heimdallr.metrics
.venv/bin/python -m heimdallr.intake
.venv/bin/python -m heimdallr.dicom_egress
.venv/bin/python -m heimdallr.integration.dispatch
.venv/bin/python -m heimdallr.integration.delivery
.venv/bin/python -m heimdallr.space_manager
.venv/bin/python -m heimdallr.resource_monitor

Run each resident service under its own terminal or supervisor unit. The TUI is optional:

.venv/bin/python -m heimdallr.tui

For a compact case queue view:

.venv/bin/python -m heimdallr.tui.simple

The compact queue TUI shows the 20 most recent studies in the upper queue list, numbered 01, 02, and so on. Press q to exit, r to refresh, pNN to prioritize a visible queued study, or xNN to cancel one, for example p10 or x04. In the processed table, Pipeline is the sum of active prepare, segmentation, and metrics elapsed times; Duration is the end-to-end elapsed time when recorded by the pipeline.

Configuration

Configuration is centralized in heimdallr/shared/settings.py plus JSON files under config/.

Entry	Type	Required	Origin	Example
HEIMDALLR_SERVER_PORT	env	no	host	8001
HEIMDALLR_DICOM_PORT	env	no	host	11114
HEIMDALLR_INTAKE_PIPELINE_CONFIG	env/file	no	repo or host	config/intake_pipeline.json
HEIMDALLR_SEGMENTATION_PIPELINE_CONFIG	env/file	yes for segmentation	host-local	config/segmentation_pipeline.json
HEIMDALLR_METRICS_PIPELINE_CONFIG	env/file	yes for metrics	host-local	config/metrics_pipeline.json
HEIMDALLR_DICOM_EGRESS_CONFIG	env/file	yes for egress	host-local	config/dicom_egress.json
HEIMDALLR_INTEGRATION_DISPATCH_CONFIG	env/file	no	host-local	config/integration_dispatch.json
HEIMDALLR_INTEGRATION_DELIVERY_CONFIG	env/file	no	host-local	config/integration_delivery.json
TOTALSEGMENTATOR_LICENSE	env	task-dependent	host secret	injected by supervisor

See docs/OPERATIONS.md for the full runtime and restart model.

Contracts and Boundaries

Canonical contracts are documented in docs/CONTRACTS.md. High-value references:

• inbound DICOM studies grouped by StudyInstanceUID
• ZIP study payloads accepted by /upload and external /jobs API submissions
• per-job series-selection overrides for external /jobs submissions
• study directory state under runtime/studies/<case_id>/
• metadata/id.json and metadata/resultados.json
• queue tables in database/dicom.db
• outbound DICOM artifacts, outbound API events, and external delivery callbacks

API details remain in docs/API.md. Database details remain in database/README.md.

Validation

Minimum structural validation:

python3 scripts/check_project_gate.py
python3 scripts/project_doctor.py
python3 scripts/project_doctor.py --audit-config

Python syntax validation:

.venv/bin/python -m compileall heimdallr scripts tests

Relevant unit coverage can be run with:

.venv/bin/python -m unittest discover -s tests

Full end-to-end smoke requires a known non-PHI study payload, DICOM peer configuration, conversion binaries, TotalSegmentator readiness, and enough compute capacity. Do not treat unit tests as proof of clinical readiness.

Large smoke datasets are host-local and ignored under runtime/test_datasets/. Use scripts/anonymize_dicom_zip.py to create a metadata-anonymized DICOM ZIP for local tests. The helper does not OCR-scrub burned-in pixel text, so generated fixtures must not be published or committed.

For Thor GPU smoke, use ignored host-local config/segmentation_pipeline.json generated from config/segmentation_pipeline.gpu.example.json. The default config/segmentation_pipeline.example.json is CPU-first and is not appropriate for timing large Thor segmentation runs.

Governance

Resource	Location
Project gate	PROJECT_GATE.md
Agent protocol	AGENTS.md
Architecture	docs/ARCHITECTURE.md
Contracts	docs/CONTRACTS.md
Operations	docs/OPERATIONS.md
Desktop track	docs/DESKTOP.md
Runtime requirements	docs/RUNTIME_REQUIREMENTS.md
Decisions	docs/DECISIONS.md
API contracts	docs/API.md
Database schema notes	database/README.md
Security policy	.github/SECURITY.md
Third-party notices	NOTICE.md

License

Heimdallr is distributed under the Apache License 2.0.

Third-party components carry additional licensing requirements. In particular, TotalSegmentator requires a valid license for commercial use. Review NOTICE.md before production deployment.