msk_admin/Lumina-MSK
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

update the codebase poc ver1

Browse Source
This commit is contained in:
DatTT127
2026-07-07 15:54:17 +07:00
parent fed5f277f4
commit 1622dc8fc5
452 changed files with 83999 additions and 66328 deletions
Download Patch File Download Diff File Expand all files Collapse all files

77
workspace/sprint_1_2/CODEBASE/backend/spec/agent_tools_contract.md Normal file
View File

@@ -0,0 +1,77 @@
# Agent Tools BFF Contract
Base path: `/api/v1/agent/tools`
## POST /exa/search
Proxies Exa `/search` with server-held `EXA_API_KEY`.
**Request**
```json
{
"query": "synovitis grading power doppler",
"type": "auto",
"numResults": 10,
"includeDomains": ["pubmed.ncbi.nlm.nih.gov"],
"session_id": "sess-001"
}
```
**Response**
```json
{
"hits": [
{
"id": "…",
"url": "https://…",
"title": "…",
"highlights": ["…"],
"publishedDate": "…",
"score": 0.92
}
],
"requestId": "…"
}
```
## POST /supabase/query
Allowlisted RPC only. Embedding computed server-side.
**Request**
```json
{
"rpc": "match_semantic_chunks",
"args": {
"query_text": "synovitis grade 2 knee ultrasound",
"match_count": 5,
"filter_book_ids": ["mor", "oho"]
},
"session_id": "sess-001"
}
```
**Response**
```json
{
"rpc": "match_semantic_chunks",
"rows": [
{
"chunk_id": "uuid",
"content": "…",
"book_id": "mor",
"parent_title": "…",
"similarity": 0.88
}
]
}
```
## References
- Exa: https://docs.exa.ai/reference/search-api-guide-for-coding-agents
- Supabase schema: [`knowledge/spec/pg_semantic_vector_db/supabase_schema.md`](../../knowledge/spec/pg_semantic_vector_db/supabase_schema.md)

151
workspace/sprint_1_2/CODEBASE/backend/spec/backend-spec.md
View File

@@ -1,47 +1,122 @@
# Backend Specification
## Purpose
Orchestrates API routers, role checks, Socratic circuit-breaker state evaluations, and coordinates ML inference, telemetry collection, and data persistence.
## Code‑base Tree View (implementation)
## Owner
Core Backend Team
```
backend/
├─ api/ # FastAPI routers (expose HTTP endpoints)
│ ├─ auth_api.py
│ ├─ patient_api.py
│ ├─ session_api.py
│ ├─ analysis_api.py
│ ├─ safety_api.py
│ ├─ notification_api.py
│ ├─ settings_api.py
│ ├─ ingestion_api.py
│ ├─ telemetry_api.py
├─ routers/ # Cloud LLM API routers
│ ├─ cloud_orchestrate.py # POST /api/cloud-orchestrate → Gemini proxy
│ └─ cloud_consult.py # POST /api/cloud-consult + GET /stream → MedGemma proxy
├─ services/ # Cloud LLM Gateway business logic
│ └─ cloud_llm_gateway.py # Routes Gemini/MedGemma based on task_type + consult_mode
├─ implementation/ # Deep modules (seams) – each provides a small interface
│ ├─ auth/ # Auth Module
│ │ ├─ __init__.py
│ │ └─ service.py # login, logout, refresh, me, update_me
│ ├─ patient/ # Patient Module
│ │ ├─ __init__.py
│ │ └─ service.py
│ ├─ session/ # Session & Frame handling
│ │ ├─ __init__.py
│ │ ├─ service.py
│ │ └─ frame_storage.py # S3 adapter
│ ├─ analysis_jobs/ # Async analysis orchestration
│ │ ├─ __init__.py
│ │ ├─ service.py
│ │ └─ triton_client.py # gRPC wrapper
│ ├─ safety/ # Internal safety stack
│ │ ├─ __init__.py
│ │ ├─ gradcam.py
│ │ ├─ rationale.py
│ │ ├─ circuit_breaker.py
│ │ ├─ socratic_chat.py
│ │ ├─ drift_check.py
│ │ ├─ rag_evidence.py
│ │ ├─ activations.py
│ │ └─ annotations.py
│ ├─ notification/ # Notification Module
│ │ ├─ __init__.py
│ │ └─ service.py
│ ├─ settings/ # User settings module
│ │ ├─ __init__.py
│ │ └─ service.py
│ ├─ ingestion_history/ # Ingestion history module
│ │ ├─ __init__.py
│ │ └─ service.py
│ ├─ telemetry/ # Telemetry & anomaly reporting
│ │ ├─ __init__.py
│ │ └─ service.py
│ └─ adapters/ # Low‑level adapters used by modules
│ ├─ s3_adapter.py # Generic S3 wrapper
│ ├─ triton_adapter.py # Adapter toward the Triton serving module hosted on Modal (KServe v2 HTTP / binary inference)
│ ├─ llm_adapter.py
│ └─ bert_adapter.py
└─ main.py # FastAPI app entry point, wires routers to modules
```
## Boundary
FastAPI server, API routers, authentication middleware, circuit breaker engine, report generator, RAG coordinator, RAG-Referee (BERT), ledger logger, and connections to Postgres + pgvector, S3 (MinIO), Redis, Triton, ladybugDB.
## Internal Design
- Built with FastAPI (Python) and Uvicorn for async HTTP server.
- Authentication middleware validates JWT tokens and enforces RBAC (roles: RO_RADIOLOGIST, RO_THERAPIST).
- Socratic circuit-breaker engine monitors interaction telemetry (hover duration, decision time, override magnitude) and triggers safety dialogs.
- Clinical Report Engine uses ReportLab to generate bilingual PDF reports per Circular 46/2018/TT-BYT.
- RAG Coordinator orchestrates Retrieval-Augmented Generation: dense vector lookup in pgvector (PostgreSQL HNSW), graph traversal in ladybugDB, mandatory pre-generation retrieval, prompt enrichment, LLM generation on browser WebLLM (GemmaE2B) or cloud Vertex AI (MedGemma via NFR-16a), and hallucination guarding via BERT RAG-Referee.
- NLP Scrubber (Microsoft Presidio): re-verifies client edge redaction, refines residual PII, and returns error if unresolvable.
- Ledger Logger appends immutable, cryptographically chained audit logs to Postgres via triggers preventing UPDATE/DELETE.
- Connections: Postgres + pgvector (via SQLAlchemy), S3 (via boto3), Redis (via redis-py), Triton (via gRPC — CV + EmbeddingGemma only), ladybugDB (via in-process C++ bindings).
- Model weights loaded at startup from internal registry; cached in memory.
- API endpoints layered: public clinical (sessions, analysis, reports, feedback) and internal/local safety (explanations, safety, drift, RAG, activations, annotations, ground-truth, escalation, morphology, telemetry).
## Interface Contract
See `bento/backend/spec/interface-contract.md`.
## Overview
The backend is a **FastAPI** application that orchestrates several **deep modules**. Each module presents a **seam** (the module’s public interface) that callers – the FastAPI router – use. Below is the module map, its **interface**, **implementation**, and the external **services** it depends on.
## Consumers
- frontend
| Module | Interface (public API) | Implementation | External Services (dependencies) |
|--------|------------------------|----------------|-----------------------------------|
| **Auth Module** | `login`, `logout`, `refresh`, `me`, `update_me` | JWT handling, password hashing, session store | PostgreSQL (`users` table), Redis (optional token blacklist) |
| **Patient Module** | CRUD for patients, list sessions, ingestion history | ORM models, business rules | PostgreSQL (`patients`, `sessions`, `ingestion_history`) |
| **Session Module** | Create session, add frames, retrieve, patch review | Transactional management, validation | PostgreSQL (`sessions`, `frames`), S3 adapter (frame storage) |
| **Frame Storage Adapter** | `store_frame`, `generate_presigned_url` | Modal‑based S3 client wrapper | AWS S3 (object store) |
| **Analysis Jobs Module** | `submit_job`, `job_status`, `job_steps` | Async job scheduler, Triton inference HTTP client, result aggregator | Triton inference server (KServe v2 HTTP, Modal serverless endpoint), PostgreSQL (`analysis_jobs`), S3 (artifact storage) |
| **Safety Module** | GradCAM, rationale, circuit‑breaker, Socratic chat, drift check, RAG evidence, activations, annotations, escalation, telemetry | Calls to local LLM/RAG/BERT services, post‑processing utilities | Local LLM container, BERT drift detector, RAG knowledge base, PostgreSQL (`safety_events`), S3 (heatmaps, masks) |
| **Cloud LLM Gateway Module** | `route_gemini_request`, `route_medgemma_request` | task_type matcher, NFR-16a consent/redaction/audit enforcement, consult_mode state extension, cost guarding | GCP Vertex AI (Gemini), Modal (MedGemma), Redis (consult_mode, consent, rate-limit), PostgreSQL (audit) |
| **Agent Tools Module** | `exa_search`, `supabase_query` | Exa web search proxy, Supabase allowlisted RPC, PHI-safe audit logging | Exa API, Supabase (`knowledge` schema), EmbeddingGemma (embedder TBD) |
| **Notification Module** | List, mark‑read, set preferences | Simple DB queries, push service stub | PostgreSQL (`notifications`), optional WebSocket push service |
| **Settings Module** | Get/patch user settings | DB reads/writes | PostgreSQL (`user_settings`) |
| **Ingestion History Module** | List uploads, get details | Query on `ingestion_history` table | PostgreSQL, S3 (original DICOM/frame) |
| **Telemetry Module** | Anomaly reporting | Write to telemetry tables, async queue | PostgreSQL (`telemetry`), optional analytics pipeline |
## Breaking-change Policy
See `bento/backend/spec/interface-contract.md`.
## Design Principles Applied
- **Depth**: Each module hides complex orchestration (e.g., Triton gRPC, S3 multipart upload) behind a small, well‑defined interface.
- **Seams**: Interfaces live in `backend/api/<module>_api.py`; adapters implement them in `backend/services/<module>_service.py`.
- **Deletion Test**: Removing any module concentrates its complexity inside callers, confirming the module’s value.
- **Locality**: All error handling, logging, and retry logic resides inside the module implementation, giving callers a clean contract.
- **Leverage**: Callers (FastAPI routes) only need to know request/response shapes; the module provides the full workflow.
## References
- NFR-7 (Real-Time UI Screen Refresh ≤200ms)
- NFR-10 (Generative Safety Guardrails)
- NFR-11 (Frontline Usability & Training)
- UC-48376 (Load Patient Scan Session)
- UC-47988 (Review Suggested Synovitis Grade)
- UC-25776 (Generate GradCAM & CoT Explanation Panel)
- UC-02423 (Log High-Trust Concur Block)
- UC_Q2_* (All Quadrant 2 safety workflows)
- UC_Q3_* (All Quadrant 3 subservience workflows)
- UC_Q4_* (All Quadrant 4 double-blind workflows)
- SOFTWARE_SYSTEM_DESIGN_FR_25.md (Sections 1.2, 2.1-2.6)
- SOLUTION_ARCHITECTURE_SPEC.md (Sections 2.1-2.6)
- DATA_ENGINEERING_SPEC.md (Sections 4-12 for domain objects)
- CI_CD_DEPLOYMENT_PIPELINE.md (Section 9.2 for docker-compose)
## Module Dependency Graph (Mermaid)
```mermaid
graph TD;
Auth --> DB[PostgreSQL];
Patient --> DB;
Session --> DB;
Session --> S3[AWS S3];
AnalysisJobs --> Triton[KServe v2 HTTP Triton = Modal Serverless];
AnalysisJobs --> DB;
AnalysisJobs --> S3;
Safety --> LLM[Local LLM];
Safety --> BERT[Drift Detector];
Safety --> RAG[Local RAG];
Safety --> DB;
Safety --> S3;
CloudLLM --> Gemini[GCP Vertex AI Gemini];
CloudLLM --> MedGemma[Modal MedGemma];
CloudLLM --> Redis;
CloudLLM --> DB;
CloudLLM --> CostGuard[MedGemma Usage Counter];
Notification --> DB;
Settings --> DB;
IngestionHistory --> DB;
IngestionHistory --> S3;
Telemetry --> DB;
```
---
*Generated for AI‑navigability and testability.*

128
workspace/sprint_1_2/CODEBASE/backend/spec/interface-contract.md
View File

@@ -1,46 +1,98 @@
# Backend Interface Contract
# Interface Contract Catalog
## Purpose
Orchestrates API routers, role checks, Socratic circuit-breaker state evaluations, and coordinates ML inference, telemetry collection, and data persistence.
This document enumerates every public **API contract** (HTTP endpoint) defined in `API_CONTRACT_DRAFT.md` and maps it to the **seam** (module) that fulfills it, together with the **external services** that the module interacts with.
## Owner
Core Backend Team
## 0. Health & Model Registry (Infrastructure / Analysis Jobs Module)
| Method | Path | Interface Function | Dependencies |
|--------|------|-------------------|--------------|
| GET | /api/v1/health | `system.health() -> HealthStatus` | All backend dependencies |
| GET | /api/v1/model-registry | `analysis.list_registered_models() -> ModelCatalog` | Triton (Modal serverless), S3 (model artifacts) |
| POST | /api/v1/models/register | `analysis.register_model(model_id: str, file: Binary) -> RegistrationResult` | S3 (model storage), Modal (serverless provisioning) |
## Provides
- api endpoints (session management, frame upload, analysis jobs, reporting, feedback, safety endpoints)
- model inference orchestration (dispatches to Triton, aggregates results)
- telemetry collection (edge-based behavioral summaries, audit logs)
- data persistence coordination (writes to Postgres, S3, Redis)
## 1. Authentication Endpoints (Auth Module)
| Method | Path | Interface Function | Dependencies |
|--------|------|-------------------|--------------|
| POST | /api/v1/auth/login | `auth.login(username: str, password: str) -> JWT` | PostgreSQL (users), bcrypt, optional Redis blacklist |
| POST | /api/v1/auth/logout | `auth.logout(token: str) -> None` | Redis (token revocation) |
| POST | /api/v1/auth/refresh | `auth.refresh(refresh_token: str) -> JWT` | PostgreSQL, Redis |
| GET | /api/v1/users/me | `auth.me(token: str) -> UserProfile` | PostgreSQL |
| PATCH | /api/v1/users/me | `auth.update_me(token: str, updates: dict) -> UserProfile` | PostgreSQL |
## Consumes
- data:storage-spec (Postgres DB, S3 object store, Redis cache)
- ml:inference-spec (Triton server for angle, inflammation, segmentation, severity)
- knowledge:guideline-spec (Qdrant vector DB, ladybugDB graph DB for grounded explanations)
## 2. Patient Management (Patient Module)
| Method | Path | Interface Function | Dependencies |
|--------|------|-------------------|--------------|
| GET | /api/v1/patients | `patient.list(user_id: str) -> List[Patient]` | PostgreSQL |
| POST | /api/v1/patients | `patient.create(data: dict) -> Patient` | PostgreSQL |
| GET | /api/v1/patients/{patient_id} | `patient.get(id: str) -> Patient` | PostgreSQL |
| GET | /api/v1/patients/{patient_id}/sessions | `patient.list_sessions(id: str) -> List[Session]` | PostgreSQL |
| GET | /api/v1/patients/{patient_id}/history | `patient.ingestion_history(id: str) -> List[IngestionRecord]` | PostgreSQL, S3 |
## Consumers
- frontend
## 3. Notification Endpoints (Notification Module)
| Method | Path | Interface Function | Dependencies |
|--------|------|-------------------|--------------|
| GET | /api/v1/notifications | `notification.list(user_id: str, filters: dict) -> List[Notification]` | PostgreSQL |
| PATCH | /api/v1/notifications/{notification_id}/read | `notification.mark_read(id: str) -> None` | PostgreSQL |
| POST | /api/v1/notifications/preferences | `notification.set_preferences(user_id: str, prefs: dict) -> None` | PostgreSQL |
## Not Directly Consumable
- data internals (Postgres tables, S3 object layout, Redis keys)
- ml internals (Triton model details, GPU kernels)
- knowledge internals (Qdrant vectors, ladybugDB graph)
## 4. Settings & Preferences (Settings Module)
| Method | Path | Interface Function | Dependencies |
|--------|------|-------------------|--------------|
| GET | /api/v1/settings | `settings.get(user_id: str) -> Settings` | PostgreSQL |
| PATCH | /api/v1/settings | `settings.update(user_id: str, updates: dict) -> Settings` | PostgreSQL |
## Breaking-change Policy
- API versioning via path (e.g., /api/v1/).
- Backward compatibility maintained for one minor version.
- Deprecation notices issued in release notes.
- Model interface changes (input/output tensors) require version bump.
## 5. Ingestion History (Ingestion History Module)
| Method | Path | Interface Function | Dependencies |
|--------|------|-------------------|--------------|
| GET | /api/v1/ingestion-history | `ingestion.list(user_id: str) -> List[Record]` | PostgreSQL, S3 |
| GET | /api/v1/ingestion-history/{record_id} | `ingestion.get(id: str) -> RecordDetail` | PostgreSQL, S3 |
## References
- NFR-7 (Real-Time UI Screen Refresh ≤200ms)
- NFR-10 (Generative Safety Guardrails)
- NFR-11 (Frontline Usability & Training)
- UC-48376 (Load Patient Scan Session)
- UC-47988 (Review Suggested Synovitis Grade)
- UC-25776 (Generate GradCAM & CoT Explanation Panel)
- UC-02423 (Log High-Trust Concur Block)
- UC_Q2_* (All Quadrant 2 safety workflows)
- UC_Q3_* (All Quadrant 3 subservience workflows)
- UC_Q4_* (All Quadrant 4 double-blind workflows)
- SOFTWARE_SYSTEM_DESIGN_FR_25.md (Sections 1.2, 2.1-2.6)
- SOLUTION_ARCHITECTURE_SPEC.md (Sections 2.1-2.6)
## 6. Clinical Workflow Endpoints (Session & Analysis Modules)
| Method | Path | Interface Function | Module | Dependencies |
|--------|------|-------------------|--------|--------------|
| POST | /api/v1/sessions | `session.create(user_id: str, patient_id: str) -> Session` | Session Module | PostgreSQL |
| GET | /api/v1/sessions/{session_id} | `session.get(id: str) -> SessionDetail` | Session Module | PostgreSQL |
| POST | /api/v1/sessions/{session_id}/frames | `session.add_frame(id: str, file: UploadFile) -> FrameMeta` | Session Module (via Frame Storage Adapter) | S3, PostgreSQL |
| PATCH | /api/v1/sessions/{session_id}/review | `session.patch_review(id: str, review: dict) -> Session` | Session Module | PostgreSQL |
| POST | /api/v1/analysis-jobs | `analysis.submit(session_id: str, params: dict) -> JobID` | Analysis Jobs Module | Triton, PostgreSQL, S3 |
| GET | /api/v1/analysis-jobs/{job_id} | `analysis.status(job_id: str) -> JobStatus` | Analysis Jobs Module | PostgreSQL |
| GET | /api/v1/analysis-jobs/{job_id}/steps | `analysis.steps(job_id: str) -> List[Step]` | Analysis Jobs Module | PostgreSQL |
| POST | /api/v1/reports | `report.create(session_id: str, payload: dict) -> ReportID` | Session Module | PostgreSQL, S3 |
| POST | /api/v1/reports/{report_id}/sign | `report.sign(id: str, signature: dict) -> Report` | Session Module | PostgreSQL |
| POST | /api/v1/reports/{report_id}/emr-sync | `report.sync_emr(id: str) -> SyncResult` | Session Module | External EMR connector (REST) |
| POST | /api/v1/sessions/{session_id}/feedback | `safety.submit_correction(session_id: str, correction: dict) -> None` | Safety Module | PostgreSQL, async analytics pipeline |
| POST | /api/v1/analysis | `analysis.submit_sync(session_id: str, params: dict) -> JobResult` | Analysis Jobs Module | Triton, PostgreSQL, S3 |
| POST | /api/v1/sessions/{session_id}/persist | `session.persist(session_id: str, review: dict) -> PersistResult` | Session Module | PostgreSQL, S3 |
| POST | /api/v1/sessions/{session_id}/export-pdf | `session.export_pdf(session_id: str, params: dict) -> ExportResult` | Session Module | S3 |
| POST | /api/v1/sessions/{session_id}/scrub-validate | `session.scrub_validate(session_id: str, metadata: dict) -> ScrubResult` | Session Module | - |
| GET | /api/v1/analysis-jobs/{job_id}/stream | `analysis.stream(job_id: str) -> SSE[StepEvent]` | Analysis Jobs Module | - |
## 8. Cloud LLM Orchestration (Cloud LLM Gateway)
| Method | Path | Interface Function | Dependencies |
|--------|------|-------------------|--------------|
| POST | /api/v1/cloud-orchestrate | `cloud_llm_gateway.route_gemini_request(payload, user_id) -> dict` | Vertex AI (Gemini), Redis (consult_mode, consent), audit log |
| POST | /api/v1/cloud-consult | `cloud_llm_gateway.route_medgemma_request(payload, user_id) -> dict` | Modal MedGemma, Redis (consult_mode, consent), audit log |
| GET | /api/v1/cloud-consult/stream | `cloud_llm_gateway.route_medgemma_request(payload, user_id) -> SSE[chunk]` | Modal MedGemma streaming, Redis, audit log |
## 9. Internal/Local Safety Endpoints (Safety Module)
| Method | Path | Interface Function | Dependencies |
|--------|------|-------------------|--------------|
| POST | /api/v1/sessions/{session_id}/explanations/gradcam | `safety.gradcam(session_id: str) -> HeatmapURL` | Triton (model output), S3 (store heatmap) |
| POST | /api/v1/sessions/{session_id}/explanations/rationale | `safety.rationale(session_id: str) -> Text` | Local LLM service |
| POST | /api/v1/sessions/{session_id}/safety/circuit-breaker | `safety.circuit_break(session_id: str, flag: bool) -> None` | PostgreSQL |
| POST | /api/v1/sessions/{session_id}/chat/socratic | `safety.socratic_chat(session_id: str, prompt: str) -> ChatResponse` | Local LLM, PostgreSQL |
| POST | /api/v1/sessions/{session_id}/drift/check | `safety.drift_check(session_id: str) -> DriftResult` | BERT (Drift Detector) |
| POST | /api/v1/sessions/{session_id}/rag/evidence | `safety.rag_evidence(session_id: str) -> EvidenceList` | Local RAG |
| POST | /api/v1/sessions/{session_id}/activations | `safety.activations(session_id: str, params: dict) -> ActivationMeta` | Triton, S3 |
| POST | /api/v1/sessions/{session_id}/annotations/artifacts | `safety.upload_artifact(session_id: str, file: UploadFile) -> ArtifactMeta` | S3 |
| POST | /api/v1/sessions/{session_id}/ground-truth | `safety.ground_truth(session_id: str, label: dict) -> None` | PostgreSQL |
| POST | /api/v1/sessions/{session_id}/escalation | `safety.escalate(session_id: str, reason: str) -> EscalationTicket` | PostgreSQL, external ticketing stub |
| POST | /api/v1/sessions/{session_id}/annotations/morphology | `safety.morphology(session_id: str, annotation: dict) -> None` | PostgreSQL |
| POST | /api/v1/sessions/{session_id}/telemetry/anomalies | `telemetry.anomaly(session_id: str, data: dict) -> None` | PostgreSQL, async analytics pipeline |
| POST | /api/v1/safety/guardrail-check | `safety.guardrail_check(session_id: str, prompt: str, score: float) -> GuardrailResult` | Safety Module | - |
| GET | /api/v1/sessions/{session_id}/chat/stream | `safety.chat_stream(session_id: str) -> SSE[ChatEvent]` | Safety Module | - |
---
**Notation**: each row describes the **seam** (module) that implements the endpoint. Callers only need to know the request/response signature; the module encapsulates all orchestration, giving high **leverage** and good **testability**.
*Generated to aid AI‑navigability and automated test generation.*