How leanseefeld/8iadt-tc-fase3-assistente-medico works
Purpose and Runtime Entry Points
A local clinical decision-support system: patient-aware Portuguese chat over Conitec PCDTs, automated clinical alerts, traceable sources, and safety guardrails. run-local.py provisions dependencies, migrations, seed data, and starts the Python backend plus React SPA. Backend application startup is backend/src/assistente_medico_api/main.py; browser startup is frontend/src/main.tsx.
Client/API Boundary
The React/Vite SPA provides dashboard, patient workflows, chat, exams, prescriptions, and alerts. It calls the FastAPI API through domain HTTP clients and consumes streaming chat events through SSE.
• frontend/src/App.tsx
• frontend/src/api/clinicalApi.ts
• frontend/src/api/sseChat.ts
API route modules expose chat, patients, clinical records, prescriptions, catalogs, and alert operations. The chat boundary accepts patient/message context and delivers generated content, sources, operational reasoning, guardrail outcome, and completion events.
• backend/src/assistente_medico_api/api/chat.py
• backend/src/assistente_medico_api/api/patients.py
• backend/src/assistente_medico_api/api/alerts.py
Clinical Persistence and Application Services
SQLite via async SQLModel is the operational record store for patients, exams/attachments, prescriptions, conversations/messages, LLM-call logs, and alerts. Alembic manages schema evolution. API handlers delegate persistence and clinical workflow triggering to repositories/services rather than accessing models directly.
• backend/src/assistente_medico_api/db/engine.py
• backend/src/assistente_medico_api/models/conversation.py
• backend/src/assistente_medico_api/services/clinical_alert_service.py
Chat RAG Graph
The LangGraph chat workflow first loads structured patient context, then routes direct questions or clinical questions requiring retrieval. RAG requests are rewritten/expanded using clinical entities and catalogs, retrieved from Chroma, reranked with retry capability, generated by the LLM, and safety-reviewed. Graph state is the contract between stages.
• backend/src/assistente_medico_api/graph/chat_rag.py
• backend/src/assistente_medico_api/graph/state.py
• backend/src/assistente_medico_api/graph/nodes/
Generation is grounded in patient data, conversation history, and validated PCDT chunks; the guardrail can warn, regenerate, or block unsafe responses.
• backend/src/assistente_medico_api/graph/nodes/generate.py
• backend/src/assistente_medico_api/graph/nodes/guardrail.py
• backend/src/assistente_medico_api/graph/rag_enhancement.py
Clinical Alert Graph
Patient check-in/readmission, vital-sign updates, and completed/critical exams invoke a separate graph. It derives reference and patient-specific PCDT queries, retrieves evidence, assesses alert payloads using deterministic logic and optionally the LLM, then persists deduplicated unresolved alerts. Clinical audit events are emitted alongside assessment.
• backend/src/assistente_medico_api/graph/clinical_alerts.py
• backend/src/assistente_medico_api/graph/alert_nodes/assess.py
• backend/src/assistente_medico_api/services/alert_service.py
RAG Knowledge Build Pipeline
The installable llm package produces the persistent Chroma knowledge base independently of backend request handling: download PCDTs, extract pages, clean content, chunk with clinical metadata, and embed/index. Conitec catalog data supports query expansion and entity resolution. The resulting local index is an explicit runtime dependency, not stored in this tree.
• llm/src/pcdt_ingest/pcdt_download.py
• llm/src/pcdt_ingest/chunk.py
• llm/src/pcdt_ingest/embed.py
Infrastructure, Models, and Observability
Runtime dependencies are Python 3.11+, FastAPI, LangGraph/LangChain, local Ollama chat and embedding models, disk-persisted Chroma, SQLite, and Node 22+ React/Vite. Ollama is the external local model service; optional cross-encoder reranking adds a model dependency. Configuration centralizes service URLs, model names, retrieval constraints, and audit controls.
• backend/src/assistente_medico_api/config.py
• backend/src/assistente_medico_api/graph/llm_client.py
• backend/src/assistente_medico_api/observability/middleware.py
Structured application logs, clinical JSONL audit records, request/user correlation, optional RAG audit, and optional persisted auxiliary LLM calls provide the accountability boundary around clinical outputs.
• backend/src/assistente_medico_api/observability/audit.py
• backend/src/assistente_medico_api/observability/clinical_audit_jsonl.py
• backend/src/assistente_medico_api/services/llm_interaction_log.py
Components 21
Browser client
- React/Vite SPA · Dashboard, patient workflows, chat, exams, prescriptions, and alerts.
frontend/src/App.tsx - Clinical HTTP clients
frontend/src/api/clinicalApi.ts - SSE chat client
frontend/src/api/sseChat.ts
Backend API & records
- FastAPI application
backend/src/assistente_medico_api/main.py - Clinical API routes · Chat, patients, and alerts endpoints.
backend/src/assistente_medico_api/api/chat.py - Clinical services · Persists workflows and triggers alert evaluation.
backend/src/assistente_medico_api/services/clinical_alert_service.py - SQLite clinical records · Patients, records, prescriptions, conversations, LLM logs, and alerts.
backend/src/assistente_medico_api/db/engine.py - Clinical audit trail · Structured logs, correlated requests, JSONL audit, and optional LLM-call persistence.
backend/src/assistente_medico_api/observability/audit.py
Chat RAG workflow
- Chat RAG graph · Stateful routing contract for direct and retrieval-grounded chat.
backend/src/assistente_medico_api/graph/chat_rag.py - Chat graph state
backend/src/assistente_medico_api/graph/state.py - RAG stages · Loads patient context, expands queries, retrieves, reranks, and retries.
- Grounded generation
backend/src/assistente_medico_api/graph/nodes/generate.py - Safety guardrail · Warns, regenerates, or blocks unsafe responses.
backend/src/assistente_medico_api/graph/nodes/guardrail.py
Clinical alert workflow
- Clinical alert graph · Evaluates check-ins, vitals, and completed or critical exams.
backend/src/assistente_medico_api/graph/clinical_alerts.py - Alert assessment · Builds evidence-backed alert payloads.
backend/src/assistente_medico_api/graph/alert_nodes/assess.py - Alert persistence · Deduplicates and persists unresolved alerts.
backend/src/assistente_medico_api/services/alert_service.py
Knowledge build
- Persistent Chroma index · Local PCDT chunks; generated outside the repository tree.
- PCDT ingestion
llm/src/pcdt_ingest/pcdt_download.py - Clinical chunking
llm/src/pcdt_ingest/chunk.py - Embedding and indexing
llm/src/pcdt_ingest/embed.py
Other components
- Local Ollama models · Provides chat and embedding models.
backend/src/assistente_medico_api/graph/llm_client.py
Connections 27
- React/Vite SPA → Clinical HTTP clients: uses
- React/Vite SPA → SSE chat client: streams chat
- Clinical HTTP clients → FastAPI application: HTTP
- SSE chat client → Clinical API routes: SSE
- FastAPI application → Clinical API routes: serves
- Clinical API routes → Clinical services: delegates
- Clinical API routes → Chat RAG graph: chat request
- Clinical services → SQLite clinical records: records
- Clinical services → Clinical alert graph: clinical triggers
- Chat RAG graph → Chat graph state: reads/writes
- Chat RAG graph → RAG stages: routes RAG
- RAG stages → SQLite clinical records: patient context/history
- RAG stages → Persistent Chroma index: retrieves evidence
- RAG stages → Grounded generation: grounded context
- Grounded generation → Local Ollama models: chat inference
- Grounded generation → Safety guardrail: candidate response
- Safety guardrail → Chat RAG graph: allow, retry, or block
- PCDT ingestion → Clinical chunking: extracted PCDTs
- Clinical chunking → Embedding and indexing: clinical chunks
- Embedding and indexing → Persistent Chroma index: persists index
- Clinical alert graph → Alert assessment: evidence assessment
- Alert assessment → Persistent Chroma index: retrieves PCDT evidence
- Alert assessment → Local Ollama models: optional assessment
- Alert assessment → Alert persistence: alert payload
- Alert persistence → SQLite clinical records: deduplicated alerts
- Chat RAG graph → Clinical audit trail: clinical output audit
- Clinical alert graph → Clinical audit trail: clinical audit events