nodae_bridge 1.0.5__tar.gz

nodae_bridge-1.0.5/PKG-INFO

@@ -0,0 +1,221 @@
+Metadata-Version: 2.4
+Name: nodae_bridge
+Version: 1.0.5
+Summary: Nodae BYOM SDK — NodaeBridge and NodaeModelAdapter for sponsor containers
+Author-email: Intheris Health <intheris.health@gmail.com>
+License-Expression: LicenseRef-Proprietary
+Project-URL: Homepage, https://www.intheris-health.com
+Keywords: federated-learning,healthcare,BYOM,nodae
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: pandas>=1.5
+Requires-Dist: pyarrow>=12.0
+Requires-Dist: pydantic>=2.0
+
+# nodae_bridge
+
+**Nodae BYOM SDK v1.0.4** — the bridge between your ML model and the [Nodae federated healthcare platform](https://www.intheris-health.com) by Intheris Health.
+
+## Overview
+
+`nodae_bridge` is the Python package your Docker container uses when participating in federated training or inference across hospital sites. It provides:
+
+- **`NodaeBridge`** — file-based I/O helpers (`/data` → `/output`)
+- **`NodaeModelAdapter`** — the interface your model class must implement
+- **`run.py`** — the container entrypoint dispatcher (`python -m nodae_bridge.run`)
+
+Core principle: **algorithms travel, data stays local.** Patient data never leaves the hospital; your container receives a privacy-safe DataFrame and returns only model weights or aggregate statistics.
+
+## Installation
+
+```bash
+pip install nodae_bridge
+```
+
+Minimum Python version: **3.10**. Add it alongside your ML framework in your Dockerfile:
+
+```dockerfile
+RUN pip install nodae_bridge scikit-learn   # or torch, xgboost, etc.
+```
+
+## Quick Start
+
+```python
+from nodae_bridge import NodaeModelAdapter, ModelSpec, TrainingConfig, LocalTrainResult, InferenceResult
+import pandas as pd
+
+class MyModel(NodaeModelAdapter):
+
+    def get_model_spec(self) -> ModelSpec:
+        return ModelSpec(
+            model_id="my-model-v1",
+            name="My Federated Model",
+            version="1.0.0",
+            input_columns=["age", "length_of_stay", "drg_weight"],
+            output_names=["risk_score"],
+            min_samples=50,
+        )
+
+    def initialize(self, config: dict) -> None:
+        pass
+
+    def get_weights(self) -> bytes:
+        return b""
+
+    def set_weights(self, weights: bytes) -> None:
+        pass
+
+    def local_train(self, data: pd.DataFrame, round_number: int, config: TrainingConfig) -> LocalTrainResult:
+        return LocalTrainResult(weights=self.get_weights(), sample_count=len(data), loss=0.0)
+
+    def local_inference(self, data: pd.DataFrame) -> InferenceResult:
+        return InferenceResult(prediction_distribution={"low": len(data)}, sample_count=len(data))
+```
+
+Your `Dockerfile`:
+
+```dockerfile
+FROM python:3.11-slim
+WORKDIR /app
+RUN pip install nodae_bridge torch --index-url https://download.pytorch.org/whl/cpu
+COPY model.py .
+CMD ["python", "-m", "nodae_bridge.run"]
+```
+
+## Data Schema
+
+Your container receives local patient data at `/data/input.parquet` as a privacy-safe DataFrame. No PII is ever exposed.
+
+| Column | Type | Description |
+|--------|------|-------------|
+| `patient_id` | str | Anonymized SHA-256 hash |
+| `age` | int | Computed from DOB |
+| `gender` | str | MALE / FEMALE / OTHER / UNKNOWN |
+| `admission_type` | str | EMERGENCY / ELECTIVE / TRANSFER / AMBULATORY |
+| `discharge_disposition` | str | HOME / TRANSFER / DECEASED / REHABILITATION |
+| `length_of_stay` | int | Hospitalization days |
+| `primary_diagnosis` | str | ICD-10 code |
+| `num_secondary_diagnoses` | int | Count |
+| `drg_code` | str | SwissDRG code |
+| `drg_weight` | float | DRG cost weight |
+| `num_procedures` | int | Count |
+| `num_medications` | int | Count |
+| `num_lab_results` | int | Count |
+| `insurance_type` | str | Swiss insurance category |
+
+Always call `fillna()` before passing data to your model — not all columns are populated for every patient.
+
+## API Reference
+
+### Core I/O
+
+| Method | Description |
+|--------|-------------|
+| `NodaeBridge.get_data()` | Load `/data/input.parquet` as a DataFrame |
+| `NodaeBridge.get_weights()` | Load global model weights; `b""` on round 0 |
+| `NodaeBridge.get_config()` | Load training/inference config dict |
+| `NodaeBridge.get_site_metadata()` | Convenience wrapper for `config["site_metadata"]` |
+| `NodaeBridge.save_weights(bytes)` | Write updated weights to `/output/weights.bin` (**required**) |
+| `NodaeBridge.save_metrics(dict)` | Write aggregate metrics to `/output/metrics.json` |
+| `NodaeBridge.log(str)` | Print timestamped message to stdout |
+
+### Extended scope (`byom_data_scope="extended"`)
+
+Register with `byom_data_scope="extended"` to receive additional raw data files. Returns empty DataFrame/dict when absent (standard scope), so imports are always safe.
+
+| Method | Returns | Content |
+|--------|---------|---------|
+| `NodaeBridge.get_labs()` | DataFrame | Per-result lab data: `patient_id, loinc_code, test_name, value, unit, flag, date, …` |
+| `NodaeBridge.get_vitals()` | DataFrame | Latest vitals per patient: `bp_systolic, heart_rate, temperature, weight_kg, …` |
+| `NodaeBridge.get_procedures()` | DataFrame | Per-procedure: `patient_id, code, description, date, source` |
+| `NodaeBridge.get_signals()` | dict | Study-specific template signals: `{patient_id: {signal_key: value}}` |
+
+Feature engineering is the container's responsibility — the platform exposes raw data only.
+
+### FHIR scope (`byom_data_scope="fhir"`)
+
+Available when registered with `byom_data_scope="fhir"`. The host writes one FHIR R4 Bundle per cohort patient under `/data/fhir/`. The standard `input.parquet` is always present alongside the bundles.
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `NodaeBridge.list_fhir_patients()` | `list[str]` | Patient IDs (anonymized hashes) with FHIR bundles; reads `index.json` |
+| `NodaeBridge.get_fhir_bundle(patient_id)` | `Optional[dict]` | Full FHIR R4 Bundle dict for one patient, or `None` |
+
+Each bundle contains: `Patient` (age, gender, LOS, DRG — no PHI), `Condition`s (ICD-10 + SNOMED), `Observation`s (LOINC-coded labs and vitals), `Procedure`s (CHOP), `MedicationStatement`s, `AllergyIntolerance`s, a `Basic` resource for template_signals, and an `ImagingStudy` reference when DICOM data is present.
+
+```python
+for pid in NodaeBridge.list_fhir_patients():
+    bundle = NodaeBridge.get_fhir_bundle(pid)
+    entries = {e["resource"]["resourceType"]: e["resource"] for e in bundle["entry"]}
+    # access any field directly — no platform-imposed field selection
+```
+
+### SCAFFOLD (`aggregation_strategy="scaffold"`)
+
+Used when the study uses SCAFFOLD to correct client drift in non-IID populations.
+
+| Method | Description |
+|--------|-------------|
+| `NodaeBridge.get_control_variates()` | Load global control variate from `/data/control_variates.bin`; `b""` when not active |
+| `NodaeBridge.save_control_variate_delta(bytes)` | Write per-site delta to `/output/control_variates.bin` |
+
+`config["scaffold_enabled"]` is `true` when the host has sent a global control variate. If `save_control_variate_delta()` is not called, the aggregator falls back to FedAvg for this site (backward compatible).
+
+### Imaging (`imaging_access=True`)
+
+Available when registered with `imaging_access=True` and the SA host has `BYOM_DICOM_STORE_ENABLED=True`. A read-only DICOM store is mounted at `/data/imaging/`.
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `NodaeBridge.get_imaging()` | `Optional[Path]` | Path to `/data/imaging/`, or `None` if unavailable |
+| `NodaeBridge.list_imaging_series()` | `list[dict]` | Manifest: `patient_id, study_uid, modality, slice_count, path` |
+
+```python
+import pydicom
+from pathlib import Path
+
+base = NodaeBridge.get_imaging()
+for series in NodaeBridge.list_imaging_series():
+    if series["modality"] != "CT":
+        continue
+    slices = sorted((base / series["path"]).glob("*.dcm"))
+    datasets = [pydicom.dcmread(str(s)) for s in slices]
+    # HU windowing, segmentation, feature extraction — container's responsibility
+```
+
+## Changelog
+
+### 1.0.5 (June 2026)
+- Added `list_fhir_patients()`, `get_fhir_bundle()` — FHIR R4 bundle access for `byom_data_scope="fhir"`
+- Added `FHIR_PATH` class constant
+
+### 1.0.4 (June 2026)
+- Added `get_imaging()`, `list_imaging_series()` — DICOM store access
+- Updated `get_site_metadata()` docs to include `imaging.*` keys
+
+### 1.0.3 (June 2026)
+- Added `get_control_variates()`, `save_control_variate_delta()` — SCAFFOLD support
+
+### 1.0.2 (June 2026)
+- Added `get_signals()` — template signal access
+- Added `get_labs()`, `get_vitals()`, `get_procedures()` — extended data scope
+
+### 1.0.1 (June 2026)
+- Added `get_site_metadata()` convenience wrapper
+
+### 1.0.0 (June 2026)
+- Initial release: `NodaeBridge`, `NodaeModelAdapter`, `run.py` entrypoint
+
+## License
+
+Proprietary — Intheris Health. Contact [support@intheris-health.com](mailto:support@intheris-health.com) for access.
+

nodae_bridge-1.0.5/README.md

@@ -0,0 +1,198 @@
+# nodae_bridge
+
+**Nodae BYOM SDK v1.0.4** — the bridge between your ML model and the [Nodae federated healthcare platform](https://www.intheris-health.com) by Intheris Health.
+
+## Overview
+
+`nodae_bridge` is the Python package your Docker container uses when participating in federated training or inference across hospital sites. It provides:
+
+- **`NodaeBridge`** — file-based I/O helpers (`/data` → `/output`)
+- **`NodaeModelAdapter`** — the interface your model class must implement
+- **`run.py`** — the container entrypoint dispatcher (`python -m nodae_bridge.run`)
+
+Core principle: **algorithms travel, data stays local.** Patient data never leaves the hospital; your container receives a privacy-safe DataFrame and returns only model weights or aggregate statistics.
+
+## Installation
+
+```bash
+pip install nodae_bridge
+```
+
+Minimum Python version: **3.10**. Add it alongside your ML framework in your Dockerfile:
+
+```dockerfile
+RUN pip install nodae_bridge scikit-learn   # or torch, xgboost, etc.
+```
+
+## Quick Start
+
+```python
+from nodae_bridge import NodaeModelAdapter, ModelSpec, TrainingConfig, LocalTrainResult, InferenceResult
+import pandas as pd
+
+class MyModel(NodaeModelAdapter):
+
+    def get_model_spec(self) -> ModelSpec:
+        return ModelSpec(
+            model_id="my-model-v1",
+            name="My Federated Model",
+            version="1.0.0",
+            input_columns=["age", "length_of_stay", "drg_weight"],
+            output_names=["risk_score"],
+            min_samples=50,
+        )
+
+    def initialize(self, config: dict) -> None:
+        pass
+
+    def get_weights(self) -> bytes:
+        return b""
+
+    def set_weights(self, weights: bytes) -> None:
+        pass
+
+    def local_train(self, data: pd.DataFrame, round_number: int, config: TrainingConfig) -> LocalTrainResult:
+        return LocalTrainResult(weights=self.get_weights(), sample_count=len(data), loss=0.0)
+
+    def local_inference(self, data: pd.DataFrame) -> InferenceResult:
+        return InferenceResult(prediction_distribution={"low": len(data)}, sample_count=len(data))
+```
+
+Your `Dockerfile`:
+
+```dockerfile
+FROM python:3.11-slim
+WORKDIR /app
+RUN pip install nodae_bridge torch --index-url https://download.pytorch.org/whl/cpu
+COPY model.py .
+CMD ["python", "-m", "nodae_bridge.run"]
+```
+
+## Data Schema
+
+Your container receives local patient data at `/data/input.parquet` as a privacy-safe DataFrame. No PII is ever exposed.
+
+| Column | Type | Description |
+|--------|------|-------------|
+| `patient_id` | str | Anonymized SHA-256 hash |
+| `age` | int | Computed from DOB |
+| `gender` | str | MALE / FEMALE / OTHER / UNKNOWN |
+| `admission_type` | str | EMERGENCY / ELECTIVE / TRANSFER / AMBULATORY |
+| `discharge_disposition` | str | HOME / TRANSFER / DECEASED / REHABILITATION |
+| `length_of_stay` | int | Hospitalization days |
+| `primary_diagnosis` | str | ICD-10 code |
+| `num_secondary_diagnoses` | int | Count |
+| `drg_code` | str | SwissDRG code |
+| `drg_weight` | float | DRG cost weight |
+| `num_procedures` | int | Count |
+| `num_medications` | int | Count |
+| `num_lab_results` | int | Count |
+| `insurance_type` | str | Swiss insurance category |
+
+Always call `fillna()` before passing data to your model — not all columns are populated for every patient.
+
+## API Reference
+
+### Core I/O
+
+| Method | Description |
+|--------|-------------|
+| `NodaeBridge.get_data()` | Load `/data/input.parquet` as a DataFrame |
+| `NodaeBridge.get_weights()` | Load global model weights; `b""` on round 0 |
+| `NodaeBridge.get_config()` | Load training/inference config dict |
+| `NodaeBridge.get_site_metadata()` | Convenience wrapper for `config["site_metadata"]` |
+| `NodaeBridge.save_weights(bytes)` | Write updated weights to `/output/weights.bin` (**required**) |
+| `NodaeBridge.save_metrics(dict)` | Write aggregate metrics to `/output/metrics.json` |
+| `NodaeBridge.log(str)` | Print timestamped message to stdout |
+
+### Extended scope (`byom_data_scope="extended"`)
+
+Register with `byom_data_scope="extended"` to receive additional raw data files. Returns empty DataFrame/dict when absent (standard scope), so imports are always safe.
+
+| Method | Returns | Content |
+|--------|---------|---------|
+| `NodaeBridge.get_labs()` | DataFrame | Per-result lab data: `patient_id, loinc_code, test_name, value, unit, flag, date, …` |
+| `NodaeBridge.get_vitals()` | DataFrame | Latest vitals per patient: `bp_systolic, heart_rate, temperature, weight_kg, …` |
+| `NodaeBridge.get_procedures()` | DataFrame | Per-procedure: `patient_id, code, description, date, source` |
+| `NodaeBridge.get_signals()` | dict | Study-specific template signals: `{patient_id: {signal_key: value}}` |
+
+Feature engineering is the container's responsibility — the platform exposes raw data only.
+
+### FHIR scope (`byom_data_scope="fhir"`)
+
+Available when registered with `byom_data_scope="fhir"`. The host writes one FHIR R4 Bundle per cohort patient under `/data/fhir/`. The standard `input.parquet` is always present alongside the bundles.
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `NodaeBridge.list_fhir_patients()` | `list[str]` | Patient IDs (anonymized hashes) with FHIR bundles; reads `index.json` |
+| `NodaeBridge.get_fhir_bundle(patient_id)` | `Optional[dict]` | Full FHIR R4 Bundle dict for one patient, or `None` |
+
+Each bundle contains: `Patient` (age, gender, LOS, DRG — no PHI), `Condition`s (ICD-10 + SNOMED), `Observation`s (LOINC-coded labs and vitals), `Procedure`s (CHOP), `MedicationStatement`s, `AllergyIntolerance`s, a `Basic` resource for template_signals, and an `ImagingStudy` reference when DICOM data is present.
+
+```python
+for pid in NodaeBridge.list_fhir_patients():
+    bundle = NodaeBridge.get_fhir_bundle(pid)
+    entries = {e["resource"]["resourceType"]: e["resource"] for e in bundle["entry"]}
+    # access any field directly — no platform-imposed field selection
+```
+
+### SCAFFOLD (`aggregation_strategy="scaffold"`)
+
+Used when the study uses SCAFFOLD to correct client drift in non-IID populations.
+
+| Method | Description |
+|--------|-------------|
+| `NodaeBridge.get_control_variates()` | Load global control variate from `/data/control_variates.bin`; `b""` when not active |
+| `NodaeBridge.save_control_variate_delta(bytes)` | Write per-site delta to `/output/control_variates.bin` |
+
+`config["scaffold_enabled"]` is `true` when the host has sent a global control variate. If `save_control_variate_delta()` is not called, the aggregator falls back to FedAvg for this site (backward compatible).
+
+### Imaging (`imaging_access=True`)
+
+Available when registered with `imaging_access=True` and the SA host has `BYOM_DICOM_STORE_ENABLED=True`. A read-only DICOM store is mounted at `/data/imaging/`.
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `NodaeBridge.get_imaging()` | `Optional[Path]` | Path to `/data/imaging/`, or `None` if unavailable |
+| `NodaeBridge.list_imaging_series()` | `list[dict]` | Manifest: `patient_id, study_uid, modality, slice_count, path` |
+
+```python
+import pydicom
+from pathlib import Path
+
+base = NodaeBridge.get_imaging()
+for series in NodaeBridge.list_imaging_series():
+    if series["modality"] != "CT":
+        continue
+    slices = sorted((base / series["path"]).glob("*.dcm"))
+    datasets = [pydicom.dcmread(str(s)) for s in slices]
+    # HU windowing, segmentation, feature extraction — container's responsibility
+```
+
+## Changelog
+
+### 1.0.5 (June 2026)
+- Added `list_fhir_patients()`, `get_fhir_bundle()` — FHIR R4 bundle access for `byom_data_scope="fhir"`
+- Added `FHIR_PATH` class constant
+
+### 1.0.4 (June 2026)
+- Added `get_imaging()`, `list_imaging_series()` — DICOM store access
+- Updated `get_site_metadata()` docs to include `imaging.*` keys
+
+### 1.0.3 (June 2026)
+- Added `get_control_variates()`, `save_control_variate_delta()` — SCAFFOLD support
+
+### 1.0.2 (June 2026)
+- Added `get_signals()` — template signal access
+- Added `get_labs()`, `get_vitals()`, `get_procedures()` — extended data scope
+
+### 1.0.1 (June 2026)
+- Added `get_site_metadata()` convenience wrapper
+
+### 1.0.0 (June 2026)
+- Initial release: `NodaeBridge`, `NodaeModelAdapter`, `run.py` entrypoint
+
+## License
+
+Proprietary — Intheris Health. Contact [support@intheris-health.com](mailto:support@intheris-health.com) for access.
+

nodae_bridge-1.0.5/pyproject.toml

@@ -0,0 +1,38 @@
+[project]
+name = "nodae_bridge"
+version = "1.0.5"
+description = "Nodae BYOM SDK — NodaeBridge and NodaeModelAdapter for sponsor containers"
+readme = "README.md"
+license = "LicenseRef-Proprietary"
+requires-python = ">=3.10"
+authors = [
+  { name = "Intheris Health", email = "intheris.health@gmail.com" },
+]
+keywords = ["federated-learning", "healthcare", "BYOM", "nodae"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Intended Audience :: Science/Research",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Scientific/Engineering :: Artificial Intelligence",
+  "Topic :: Scientific/Engineering :: Medical Science Apps.",
+]
+dependencies = [
+  "pandas>=1.5",
+  "pyarrow>=12.0",
+  "pydantic>=2.0",
+]
+
+[project.urls]
+Homepage = "https://www.intheris-health.com"
+
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["nodae_bridge*"]

nodae_bridge-1.0.5/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

nodae_bridge-1.0.5/src/nodae_bridge/__init__.py

@@ -0,0 +1,28 @@
+"""
+nodae_bridge — Nodae BYOM SDK for sponsor containers.
+
+Quick start::
+
+    from nodae_bridge import NodaeBridge, NodaeModelAdapter
+    from nodae_bridge import ModelSpec, TrainingConfig, LocalTrainResult, InferenceResult
+"""
+
+from .adapter import (
+    ContainerResourceRequirements,
+    InferenceResult,
+    LocalTrainResult,
+    ModelSpec,
+    NodaeModelAdapter,
+    TrainingConfig,
+)
+from .bridge import NodaeBridge
+
+__all__ = [
+    "NodaeBridge",
+    "NodaeModelAdapter",
+    "ModelSpec",
+    "TrainingConfig",
+    "LocalTrainResult",
+    "InferenceResult",
+    "ContainerResourceRequirements",
+]