samuveljohnson1416/multi-model-ai-agent-for-automated-health-diagnostics

Purpose and Runtime Topology

Health Diagnostics AI Agent ingests blood-work reports, extracts and normalizes laboratory values, produces risk-oriented interpretation, persists report history, and supports contextual user chat. It is deployed as independently scalable FastAPI and Streamlit services, with Render provisioning defined in render.yaml and service containers in Dockerfile.backend and Dockerfile.frontend.

Application Entry Points

The backend API is assembled and launched through backend/main.py; route modules expose health, report, analysis, and chat capabilities under backend/routes/health.py, backend/routes/reports.py, backend/routes/analyze.py, and backend/routes/chat.py. The Streamlit client begins at frontend/app.py, with page-level workflows in frontend/pages/upload.py, frontend/pages/dashboard.py, frontend/pages/history.py, and frontend/pages/chat.py.

Report Ingestion and Extraction

Upload/analysis requests enter the API route layer and are orchestrated by backend/services/analysis_service.py. Format-specific handling is split between OCR extraction in backend/services/ocr_service.py and structured-content parsing in backend/services/parser_service.py. This boundary supports PDFs/images as OCR inputs and JSON/CSV as structured inputs before a common blood-parameter model is produced.

Validation and Clinical Interpretation

Parsed measurements are validated by backend/services/validator_service.py and represented through models such as backend/models/blood_parameter.py and backend/models/report.py. Domain logic then normalizes units (backend/domain/unit_converter.py), compares values with maintained ranges (backend/domain/reference_ranges.py, backend/data/reference_ranges.json), calculates risk (backend/domain/risk_calculator.py), and creates report-level interpretation (backend/domain/report_interpreter.py).

AI Analysis and Conversation

The LLM boundary is centralized in backend/services/llm_service.py, preventing route and domain layers from directly depending on an AI provider. backend/services/chat_service.py uses that capability to answer questions grounded in report context; chat request/state schemas reside in backend/models/chat.py. Provider credentials are environment-driven through backend/config.py and .env.example (including the documented Groq integration).

Persistence and Historical Comparisons

Database access follows a repository boundary: backend/db/client.py owns Supabase connectivity and backend/db/repository.py encapsulates data operations. Report and health representations in backend/models/report.py and backend/models/health.py form the persistence-facing contract. This enables the history UI to retrieve prior reports and supports multi-report trend comparison without coupling frontend pages to Supabase.

Frontend-to-Backend Boundary

Streamlit pages call the FastAPI service through frontend/api_client.py, configured by frontend/config.py; session-scoped UI state is managed in frontend/session.py. The frontend does not implement diagnostic logic: upload submits source material, dashboard renders analysis, history presents persisted reports, and chat sends conversational requests. API_BASE_URL provides the deployment boundary between separately hosted services.