README.md

---
title: RustVital-AMD
emoji: 🏥
colorFrom: blue
colorTo: purple
sdk: docker
pinned: true
---

<div align="center">
  <img src="https://img.shields.io/badge/Rust-1.95-dea584?logo=rust&logoColor=white" alt="Rust"/>
  <img src="https://img.shields.io/badge/AMD-ROCm-ED1C24?logo=amd&logoColor=white" alt="AMD ROCm"/>
  <img src="https://img.shields.io/badge/Model-Qwen2.5_7B-615EFF?logo=huggingface&logoColor=white" alt="Qwen2.5"/>
  <img src="https://img.shields.io/badge/Chain-Base_Sepolia-0052FF?logo=ethereum&logoColor=white" alt="Base Sepolia"/>
  <img src="https://img.shields.io/badge/Audit-Filecoin_CID-0090FF?logo=ipfs&logoColor=white" alt="Filecoin CID"/>
</div>

# 🏥 RustVital‑AMD – Zero‑Trust Medical AI Triage Gateway

**Pure Rust • AMD MI300X GPU • Real Web3 Audit Trail**

RustVital‑AMD is a production‑grade, zero‑trust medical triage agent that **never exposes raw patient data to the AI model**. It accepts clinical notes, strips personally identifiable information (PII) before the GPU ever sees them, runs inference on a real **Qwen2.5‑7B** model backed by an **AMD MI300X** GPU, and rehydrates the response so the clinician sees a perfectly normal clinical report. Every triage is cryptographically proven and permanently anchored on‑chain via **Filecoin CID** and **Base Sepolia**.

🚀 **Live Demo:** [Launch on Hugging Face Spaces](https://huggingface.co/spaces/lablab-ai-amd-developer-hackathon/rustvital-amd)

---

## 🧬 Key Features

- **🛡️ Zero‑Trust PII Shield** – Deterministic, pre‑GPU redaction of names, ages, SSN, MRN, insurance IDs, and more.
- **🧠 Real AMD MI300X Inference** – Calls a live vLLM endpoint running Qwen2.5‑7B on ROCm, with graceful CPU fallback.
- **📡 Streaming Agent Observability** – WebSocket + SSE endpoint show every pipeline step in real time.
- **📚 PubMed Enrichment** – Queries NCBI E‑utilities for relevant biomedical literature after each triage.
- **🩻 DICOM Surrogate Redaction** – Demonstrates multi‑modal PII removal from medical imaging headers and burned‑in text.
- **🔐 Cryptographic Audit** – A ZK‑simulated proof of correct redaction is generated and verified on every request.
- **⛓️ Blockchain Immutability** – Each triage produces a Filecoin CID and an on‑chain transaction on Base Sepolia (via alloy‑rs).
- **🏥 Consortium Attestations** – Simulates three independent hospital attestations, creating a decentralised trust model.
- **⚙️ Federated Fine‑Tuning Trigger** – Exposes an endpoint that launches a LoRA fine‑tuning job on MI300X, using only redacted data.
- **🎨 Professional Dark UI** – Built with HTMX + Alpine.js + Tailwind CSS, served from Axum with no JavaScript build step.

---

## 🔄 How It Works

```
┌───────────────┐      ┌─────────────────────┐      ┌───────────────────────┐
│  Clinician    │      │    RustVital-AMD     │      │     AMD MI300X GPU     │
│  (Browser)    │      │     (Axum Server)    │      │    (vLLM + ROCm HIP)   │
└───────┬───────┘      └──────────┬──────────┘      └───────────┬───────────┘
        │  Submit consent form     │                             │
        │────────────────────────►│                             │
        │                         │  (1) PII Shield              │
        │                         │  Redact PHI from note        │
        │                         │  Generate ZK‑style proof    │
        │                         │                             │
        │                         │  (2) Send redacted prompt    │
        │                         │─────────────────────────────►│
        │                         │                             │ Run Qwen2.5‑7B
        │                         │◄─────────────────────────────│
        │                         │  (3) Clinical synthesis      │
        │                         │                             │
        │                         │  (4) Enrich with PubMed      │
        │                         │  (5) Compute CID + anchor    │
        │                         │      on Base Sepolia         │
        │                         │  (6) Simulate consortium      │
        │                         │      attestations            │
        │                         │                             │
        │◄────────────────────────│  (7) Return rehydrated result│
        │  View real report       │                             │
        │  (PII never revealed)   │                             │
```

---

## 🛠️ Technology Stack

| Layer               | Technology                          |
|---------------------|-------------------------------------|
| **Language**        | Rust (edition 2021)                 |
| **Web Framework**   | Axum + Tower + Tokio                |
| **Inference**       | vLLM (OpenAI‑compatible) on AMD ROCm|
| **LLM**             | Qwen2.5‑7B‑Instruct                  |
| **PII Shield**      | Custom regex engine (deterministic)  |
| **Crypto**          | SHA‑256, ECDSA (k256), ZK‑simulated |
| **Blockchain**      | alloy‑rs → Base Sepolia testnet     |
| **CID**             | cid + sha2 → Filecoin‑compatible    |
| **Medical APIs**    | NCBI E‑utilities (PubMed)           |
| **UI**              | HTMX + Alpine.js + Tailwind CSS     |
| **Observability**   | WebSocket + Server‑Sent Events      |
| **Deployment**      | Docker, Hugging Face Spaces         |

---

## 📋 Use Cases

### 🚑 Emergency Room Triage
A clinician pastes a raw ambulance report. The system redacts patient identity, runs the case through the MI300X, and instantly returns a structured clinical assessment with PubMed references – all while **maintaining HIPAA compliance** and **creating an immutable legal audit trail**.

### 🏥 Multi‑Hospital Consortium
Three independent hospitals can run RustVital‑AMD nodes. After each triage, they attest to the correctness of the redaction proof. The on‑chain record shows consensus, giving regulators and insurers **cryptographic proof that PII was never exposed**.

### 📊 Continuous Federated Learning
Hospitals trigger fine‑tuning jobs on their own AMD GPUs using only **de‑identified logs**. The model improves without any raw patient data leaving the gateway. The system logs every training event, creating a **fully auditable model lineage** on‑chain.

---

## ⚙️ Quick Start (Local Development)

### Prerequisites
- Rust 1.90+ (stable‑toolchain)
- An AMD MI300X instance running vLLM (or the [Hugging Face Space](https://huggingface.co/spaces/lablab-ai-amd-developer-hackathon/rustvital-amd) for immediate testing)
- Base Sepolia wallet (optional, for on‑chain transactions)

### 1. Clone the repository
```bash
git clone https://huggingface.co/spaces/lablab-ai-amd-developer-hackathon/rustvital-amd
cd rustvital-amd
```

### 2. Configure environment
Create a `.env` file:
```env
VLLM_URL=http://129.212.188.154:8000/v1/chat/completions
PUBMED_EMAIL=you@example.com
PRIVATE_KEY=your_base_sepolia_private_key_hex
PORT=7860
```

### 3. Build & Run
```bash
cargo build --release
cargo run
```
The server will start on `http://localhost:7860`. Open the URL in your browser.

### 4. Connect to real GPU
If you have a droplet running vLLM, expose it with Cloudflare Tunnel:
```bash
cloudflared tunnel --url http://localhost:8000
```
Then update `VLLM_URL` with the generated `https://*.trycloudflare.com/v1/chat/completions` address.

---

## 📡 API Endpoints

| Method | Path                      | Description |
|--------|---------------------------|-------------|
| `GET`  | `/`                       | Serves the interactive UI |
| `GET`  | `/health`                 | Liveness check (`healthy`) |
| `GET`  | `/status`                 | GPU status, model info, triage count |
| `POST` | `/triage/html`            | Form‑encoded triage request (returns HTML) |
| `POST` | `/triage`                 | JSON triage request (`TriageRequest` → `TriageResponse`) |
| `GET`  | `/triage/stream`          | SSE stream of agent events (Shield → Triage → Audit) |
| `GET`  | `/agents/status`          | WebSocket for real‑time agent states |
| `POST` | `/dicom/redact`           | Upload a DICOM file for metadata / burned‑in text redaction |
| `GET`  | `/medical/enrich`         | Fetch PubMed evidence for a given clinical note |
| `POST` | `/trigger-federated-tune` | Launch a simulated federated LoRA fine‑tuning job |
| `GET`  | `/federation/round`       | Show current federated learning round and nodes |
| `GET`  | `/dashboard`              | HTML fragment of recent triage history |
| `GET`  | `/history`               | JSON list of all triage records |

---

## ☁️ Deployment

The project is containerised with Docker. A pre‑built image is automatically deployed to Hugging Face Spaces on every push.

### Dockerfile (production)
```dockerfile
FROM rust:1.95-slim-bookworm AS builder
RUN apt-get update && apt-get install -y pkg-config libssl-dev && rm -rf /var/lib/apt/lists/*
WORKDIR /app
COPY Cargo.toml Cargo.lock* ./
COPY src src
COPY static static
COPY contracts contracts
RUN cargo build --release

FROM debian:bookworm-slim
RUN apt-get update && apt-get install -y ca-certificates && rm -rf /var/lib/apt/lists/*
COPY --from=builder /app/target/release/rustvital-amd /usr/local/bin/rustvital-amd
EXPOSE 7860
ENV PORT=7860
CMD ["rustvital-amd"]
```

### Hugging Face Space Secrets
Set these in **Settings → Secrets**:

| Key | Value |
|-----|-------|
| `VLLM_URL` | `https://*.trycloudflare.com/v1/chat/completions` |
| `PUBMED_EMAIL` | Your email for NCBI rate limits |
| `PRIVATE_KEY` | Base Sepolia hex private key (without `0x`) |

---

## 🏆 Hackathon Tracks

- **AI Agents & Agentic Workflows** (main)
- **Fine‑Tuning on AMD GPUs** (LoRA on MI300X)
- **Hugging Face Challenge** (Space deployed)
- **Qwen Challenge** (Qwen2.5‑7B via vLLM)
- **Build in Public** (updates on [X/Twitter](https://x.com/MoonloungeBrain))

---

## 🤝 Contributing

This project was built solo for the AMD Developer Hackathon (May 2026). Contributions are welcome via pull requests. Please discuss major changes first in the [Hugging Face Community tab](https://huggingface.co/spaces/lablab-ai-amd-developer-hackathon/rustvital-amd/discussions).

---

## 📜 License

MIT License – see the `LICENSE` file (if present) or the [Hugging Face Space page](https://huggingface.co/spaces/lablab-ai-amd-developer-hackathon/rustvital-amd) for details.

---

**Built with ❤️, Rust, and AMD ROCm for the AMD Developer Hackathon 2026.**
```