# CLARA — MCP Server (backend)

Backend pentru **CLARA**, sistem hibrid de diagnosticare radiologică pulmonară.
Expune un model **ViT-B/16** fine-tuned pe CheXpert (14 patologii), explicabilitate
**LRP-ViT**, segmentare promptabilă **LRP-to-SAM2**, **RAG** clinic, generare de raport
și **4 agent skills MCP**, totul cu **securitate agentică în 4 straturi**.

> ⚠️ Instrument de **augmentare**, nu de înlocuire a radiologului. Output asistat de AI,
> de validat de medic.

## Stack

| Componentă | Tehnologie |
|---|---|
| API + MCP | FastAPI + fastmcp (REST și MCP coexistente) |
| Pipeline asincron | Celery + Redis (progres prin SSE) |
| Bază de date | PostgreSQL + pgvector (audit log + index RAG) |
| CV | PyTorch 2.3 + transformers + peft |
| Orchestrare | Docker Compose |
| Frontend | Next.js (separat: `../clara-radiology-dashboard`) |

## Structura proiectului

```
clara-mcp-server/
├── app/
│   ├── main.py            # FastAPI: montează REST + MCP
│   ├── config.py          # setări (pydantic-settings)
│   ├── api/               # POST /analyze, GET /stream/{job_id}, scheme
│   ├── cv_engine/         # model, preprocess, LRP-ViT, LRP-to-SAM2, inference
│   ├── rag/               # embedder, knowledge base, retriever, TAM
│   ├── mcp/               # server fastmcp + cele 4 skills
│   ├── security/          # sanitize, prompt guard, guardrails, audit log
│   ├── tasks/             # Celery app + pipeline asincron
│   ├── db/                # SQLAlchemy engine + modele ORM
│   └── llm/               # generare raport radiologic
├── weights/               # vit_lora_chexpert.pt (montat ca volum)
├── scripts/init_db.sql    # pgvector + tabele
├── demo/                  # imagine demo pentru apărare
├── tests/test_e2e.py
├── Dockerfile
├── docker-compose.yml
└── requirements.txt
```

## Pornire rapidă (`docker compose up`)

```bash
cp .env.example .env          # completează OPENAI_API_KEY (opțional)
# pune modelul în weights/vit_lora_chexpert.pt  (deja copiat dacă ai folosit scriptul)
docker compose up --build
```

Servicii disponibile după pornire:
- API + docs OpenAPI: http://localhost:8000/docs
- Endpoint MCP: http://localhost:8000/mcp
- Postgres: `localhost:5432`, Redis: `localhost:6379`

## API REST (rezumat)

| Metodă | Rută | Descriere |
|---|---|---|
| `POST` | `/analyze` | Trimite o radiografie, creează un job asincron |
| `GET` | `/stream/{job_id}` | Progres în timp real (SSE) + rezultat final |
| `GET` | `/health` | Status model + dependențe |

## Cele 4 agent skills (MCP)

1. **ExecuteVisionInference** — clasificare ViT + LRP + LRP-to-SAM2
2. **QueryClinicalKnowledge** — RAG ierarhic pe baza de cunoștințe clinică
3. **SynthesizeMedicalReport** — raport radiologic via LLM
4. **EscalateToHumanExpert** — decizie conservatoare de escalare

## Securitate agentică (4 straturi)

1. Sanitizare PII la ingestie (Presidio / regex fallback)
2. Izolarea contextului în prompt (delimitare XML, context = date, nu comenzi)
3. Validarea output-ului (Guardrails / heuristici anti-halucinație și anti-injecție)
4. Audit log imutabil cu lanț de hash-uri (Postgres)

## Note pentru demonstrația live

- **SAM2** are *fallback* clasic (GrabCut) dacă pachetul Meta nu e instalat.
- **BiomedCLIP** are *fallback* la `sentence-transformers` dacă nu se încarcă.
- Fără `OPENAI_API_KEY`, raportul revine la promptul structurat TAM (rulează oricum).

---

*Status implementare: Pas 6/7 — backend complet (CV + REST/SSE + Celery + MCP + RAG + securitate) + integrare frontend (api.ts, SSE, /audit/recent, lrp_map_b64 + report în pipeline). Urmează test e2e + screenshot-uri.*