Skip to content

Update README.md #6

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Ciprian-LocalPulse wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Update README.md #6

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
220 changes: 144 additions & 76 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,53 +1,98 @@
# MedIntelOS

<div align="center">

[![CI](https://github.com/Ciprian-LocalPulse/MedIntelOS/actions/workflows/ci.yml/badge.svg)](https://github.com/Ciprian-LocalPulse/MedIntelOS/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Python](https://img.shields.io/badge/Python-3.11%2B-3776AB.svg)](pyproject.toml)
[![FHIR](https://img.shields.io/badge/FHIR-R5%205.0.0-E34F26.svg)](https://hl7.org/fhir/R5/)

MedIntelOS is an open-source reference implementation for experimenting with
health-data interoperability, clinical decision-support workflows, federated
model aggregation, tamper-evident audit records, and patient-consent contracts.
**Alpha · Educational · Open Source**

*Health-data interoperability · Clinical decision support · Federated learning · Tamper-evident audit · Patient consent*

</div>

---

MedIntelOS is an open-source reference implementation for experimenting with health-data interoperability, clinical decision-support workflows, federated model aggregation, tamper-evident audit records, and patient-consent contracts.

The repository is intentionally honest about its maturity: it is an **alpha,
educational system**, not a production EHR, not a complete FHIR implementation,
not a medical device, and not evidence of regulatory compliance.
> ⚠️ **Alpha, educational system** — not a production EHR, not a complete FHIR implementation, not a medical device, and not evidence of regulatory compliance.

![Conceptual MedIntelOS stack visualization](assets/medintelos-stack-visualization.png)
---

> **Concept illustration:** The labels and interfaces shown above communicate the
> long-term product vision. They do not represent implemented functionality,
> clinical validation, security certification, or regulatory compliance.
## Architecture

```
┌─────────────────────────────────────────────────────────────┐
│ MedIntelOS │
│ │
│ ┌──────────┐ ┌──────────────────────────────────┐ │
│ │EHR Client│────▶│ FastAPI Boundary │ │
│ └──────────┘ │ │ │
│ │ ┌──────────┐ ┌──────────────┐ │ │
│ ┌──────────┐ │ │ API Key │ │ CDS Hooks + │ │ │
│ │ Patient │─┐ │ │ Auth │ │ CDSS Rules │ │ │
│ └──────────┘ │ │ └──────────┘ └──────────────┘ │ │
│ │ │ ┌──────────┐ ┌──────────────┐ │ │
│ ┌────────────┴┐ │ │ FHIR R5 │ │ Audit Log │ │ │
│ │ Institution │ │ │ Repository│ │ (SHA-256 │ │ │
│ └─────────────┘ │ │ │ │ hash chain) │ │ │
│ │ │ └──────────┘ └──────────────┘ │ │
│ ▼ └──────────────────────────────────┘ │
│ ┌──────────────┐ │
│ │ Consent │ ◀── Smart Contracts (Solidity) │
│ │ Manager │ │
│ └──────────────┘ │
│ │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ Federated Learning Layer │ │
│ │ Site A ──┐ │ │
│ │ Site B ──┼──▶ Coordinator ──▶ Global Model │ │
│ │ Site C ──┘ │ │
│ └──────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
```

> See [Architecture](docs/ARCHITECTURE.md), [Threat Model](docs/THREAT_MODEL.md), and [Deployment Guide](docs/DEPLOYMENT.md) for the full technical detail.

---

## Implemented Scope

| Area | Included | Important boundary |
|---|---|---|
| FHIR R5 | JSON builders, in-memory CRUD, search subset, version IDs, ETags, CapabilityStatement | Not a conformance-tested or persistent FHIR server |
| CDS Hooks | Discovery and `patient-view` service endpoint | Uses a project-specific prefetch context; rules are not clinically validated |
| CDSS | qSOFA, NEWS2, AKI rule, CHA2DS2-VASc helper, threshold and medication examples | Educational rules only; drug knowledge base is deliberately small |
| Federated learning | Weighted aggregation, callback-based participant updates, DP noise experiment, outlier detection | No cryptographic secure aggregation or formal privacy accountant |
| Audit | In-memory SHA-256 hash chain | Tamper-evident in one process, not durable or independently anchored |
| Consent | Solidity consent and audit contracts plus Hardhat tests | Identity, legal authority, erasure, governance, and key custody remain off-chain |
| Operations | Docker, Compose, CI, linting, tests, API docs | Production infrastructure is outside this repository |
| **FHIR R5** | JSON builders, in-memory CRUD, search subset, version IDs, ETags, CapabilityStatement | Not a conformance-tested or persistent FHIR server |
| **CDS Hooks** | Discovery and `patient-view` service endpoint | Uses a project-specific prefetch context; rules are not clinically validated |
| **CDSS** | qSOFA, NEWS2, AKI rule, CHA2DS2-VASc helper, threshold and medication examples | Educational rules only; drug knowledge base is deliberately small |
| **Federated Learning** | Weighted aggregation, callback-based participant updates, DP noise experiment, outlier detection | No cryptographic secure aggregation or formal privacy accountant |
| **Audit** | In-memory SHA-256 hash chain | Tamper-evident in one process, not durable or independently anchored |
| **Consent** | Solidity consent and audit contracts plus Hardhat tests | Identity, legal authority, erasure, governance, and key custody remain off-chain |
| **Operations** | Docker, Compose, CI, linting, tests, API docs | Production infrastructure is outside this repository |

## Architecture
---

## Request Flow

```mermaid
flowchart LR
Client["EHR / research client"] --> API["FastAPI boundary"]
API --> Auth["API-key authentication"]
API --> CDS["CDS Hooks + CDSS rules"]
API --> FHIR["FHIR R5 reference repository"]
API --> Audit["Hash-chained audit log"]
Sites["Federated participants"] --> FL["Aggregation coordinator"]
FL --> Model["Experimental global model"]
Patient["Patient / authorized proxy"] --> Contract["Consent smart contracts"]
Institution["Verified institution"] --> Contract
```
Request
│
▼
┌────────────┐ ┌────────────┐ ┌──────────────┐
│ FastAPI │───▶│ API Key │───▶│ Route │
│ Boundary │ │ Auth │ │ Handler │
└────────────┘ └────────────┘ └──────┬───────┘
│
┌──────────────────────┼──────────────────────┐
│ │ │
▼ ▼ ▼
┌────────────┐ ┌────────────┐ ┌────────────┐
│ FHIR R5 │ │ CDS Hooks │ │ Audit │
│ Repository │ │ + CDSS │ │ Chain │
└────────────┘ └────────────┘ └────────────┘
```

See [Architecture](docs/ARCHITECTURE.md), [Threat Model](docs/THREAT_MODEL.md),
and [Deployment Guide](docs/DEPLOYMENT.md) for the technical detail.
---

## Repository Layout

Expand All @@ -66,6 +111,8 @@ docs/ Architecture, threat model, and deployment notes
examples/ Synthetic requests only
```

---

## Quick Start

### Python
Expand All @@ -81,12 +128,14 @@ uvicorn medintelos.api.app:app --reload --port 8080

On Linux or macOS, use `export MEDINTELOS_API_KEY=...` instead.

Open:
**Available endpoints:**

- Swagger UI: `http://localhost:8080/docs`
- ReDoc: `http://localhost:8080/redoc`
- Health: `http://localhost:8080/health`
- FHIR metadata: `http://localhost:8080/fhir/R5/metadata`
| Endpoint | Description |
|---|---|
| `http://localhost:8080/docs` | Swagger UI |
| `http://localhost:8080/redoc` | ReDoc |
| `http://localhost:8080/health` | Health check |
| `http://localhost:8080/fhir/R5/metadata` | FHIR metadata |

### Docker

Expand All @@ -96,6 +145,8 @@ cp .env.example .env
docker compose up --build
```

---

## API Examples

Create a synthetic FHIR Patient:
Expand All @@ -116,15 +167,11 @@ curl -X POST http://localhost:8080/api/v1/cdss/evaluate \
--data @examples/cdss-request.json
```

The result is shaped as CDS Hooks cards plus a namespaced `_medintelos` section
containing rule details. Optional fields are omitted where the integration path
requires stricter CDS Hooks conformance.
The result is shaped as CDS Hooks cards plus a namespaced `_medintelos` section containing rule details.

## Federated Learning Example
---

The coordinator accepts an application-provided update callback. Network
transport, participant authentication, signatures, model serialization, secure
aggregation, and privacy accounting must be supplied by the deployment.
## Federated Learning Example

```python
import numpy as np
Expand Down Expand Up @@ -153,22 +200,35 @@ coordinator = FederatedCoordinator(
)
```

> Network transport, participant authentication, signatures, model serialization, secure aggregation, and privacy accounting must be supplied by the deployment.

---

## Smart Contracts

```bash
npm install
npm test
```

The deployment sequence is:
**Deployment sequence:**

1. Deploy `MedIntelOSAuditLedger` with the zero address.
2. Deploy `MedIntelOSConsentManager` with the ledger address.
3. Call `setConsentManager` on the ledger.
4. Register and independently verify institution identities.
```
1. Deploy MedIntelOSAuditLedger ──▶ with zero address
│
▼
2. Deploy MedIntelOSConsentManager ──▶ with ledger address
│
▼
3. Call setConsentManager on ledger
│
▼
4. Register + independently verify institution identities
```

> ⚠️ Never put PHI, names, identifiers, clinical notes, or raw FHIR resources on a public blockchain. Even hashes can create linkage and retention risks.

Never put PHI, names, identifiers, clinical notes, or raw FHIR resources on a
public blockchain. Even hashes can create linkage and retention risks.
---

## Quality Checks

Expand All @@ -178,37 +238,49 @@ pytest
mypy src/medintelos
```

The GitHub Actions workflow runs Python linting and tests. Contract tests run in
a separate CI job.
The GitHub Actions workflow runs Python linting and tests. Contract tests run in a separate CI job.

## Security and Privacy
---

- The demo API uses a static API key so the authentication boundary is visible.
- Production deployments need OIDC/OAuth 2.0, short-lived credentials, scopes,
tenant isolation, KMS-backed secrets, TLS, rate limits, and durable audit data.
- The in-memory FHIR store loses all data at process exit and must never hold PHI.
- Logs avoid request bodies, but operators must validate the entire observability path.
- Report vulnerabilities according to [SECURITY.md](SECURITY.md).
## Security & Privacy

## Standards Position
| Concern | Current (demo) | Production requirement |
|---|---|---|
| Authentication | Static API key | OIDC/OAuth 2.0, short-lived credentials, scopes |
| Secrets | Env variable | KMS-backed secrets |
| Data storage | In-memory (lost at exit) | Durable store — **never hold PHI** |
| Transport | HTTP | TLS everywhere |
| Audit | In-process log | Durable, independently anchored |
| Observability | Bodies excluded from logs | Validate entire observability path |

- FHIR Release 5 is published as version 5.0.0 by HL7.
- The project follows the CDS Hooks discovery and service interaction shape.
- It does not claim SMART App Launch support, profile validation, terminology
validation, Bulk Data, subscriptions, XML support, or FHIR certification.
Report vulnerabilities according to [SECURITY.md](SECURITY.md).

Primary references:
---

## Standards Position

| Standard | Status |
|---|---|
| FHIR Release 5 (v5.0.0) | Reference implementation — not conformance-tested |
| CDS Hooks | Discovery and service interaction shape |
| SMART App Launch | ❌ Not supported |
| Profile / terminology validation | ❌ Not supported |
| Bulk Data / Subscriptions / XML | ❌ Not supported |

**Primary references:**
- [HL7 FHIR R5](https://hl7.org/fhir/R5/)
- [CDS Hooks stable specifications](https://cds-hooks.hl7.org/)
- [SMART App Launch](https://hl7.org/fhir/smart-app-launch/)
- [HHS HIPAA Security Rule summary](https://www.hhs.gov/hipaa/for-professionals/security/laws-regulations/)

---

## Contributing

Read [CONTRIBUTING.md](CONTRIBUTING.md). Clinical behavior changes require a
published source, explicit assumptions, boundary tests, and a reviewer who can
assess the clinical and human-factors impact.
Read [CONTRIBUTING.md](CONTRIBUTING.md). Clinical behavior changes require a published source, explicit assumptions, boundary tests, and a reviewer who can assess the clinical and human-factors impact.

---

## 💖 Support & Donations

MedIntelOS is free and open-source forever. If this project helps your hospital, clinic, or research institution, please consider supporting continued development:
Expand Down Expand Up @@ -249,14 +321,10 @@ MedIntelOS is free and open-source forever. If this project helps your hospital,
| **Bitcoin (BTC)** | `bc1qf3yy0w8z37rwavxpu38wem3yffpanw7wzj32qj` |
| **Ethereum (ETH)** | `0x27d9a6a5b8507e6031bb044319410da96222d402` |

Every contribution — no matter how small — directly funds:
- New AI model development and clinical validation
- Security audits and penetration testing
- Documentation and clinical training materials
- Hospital pilot deployments in underserved regions
Every contribution — no matter how small — directly funds new AI model development, security audits, documentation, and hospital pilot deployments in underserved regions.

---

## License

Code is available under the [MIT License](LICENSE). The license does not remove
the medical, legal, privacy, security, or regulatory responsibilities described
in [MEDICAL_DISCLAIMER.md](MEDICAL_DISCLAIMER.md).
Code is available under the [MIT License](LICENSE). The license does not remove the medical, legal, privacy, security, or regulatory responsibilities described in [MEDICAL_DISCLAIMER.md](MEDICAL_DISCLAIMER.md).
Loading