Spaces:
Running
Running
| # RagBot API - Architecture Diagrams | |
| ## System Architecture | |
| ``` | |
| ┌─────────────────────────────────────────────────────────────────┐ | |
| │ RagBot API Server │ | |
| ├─────────────────────────────────────────────────────────────────┤ | |
| │ │ | |
| │ ┌─────────────────┐ ┌──────────────────────────┐ │ | |
| │ │ Cloud LLM API │◄─────────────┤ FastAPI Server │ │ | |
| │ │ (Groq/Gemini) │ LLM Calls │ Port: 8000 │ │ | |
| │ │ │ │ │ │ | |
| │ │ Models: │ │ Endpoints: │ │ | |
| │ │ - LLaMA 3.3-70B│ │ - /api/v1/health │ │ | |
| │ │ - Gemini Flash │ │ - /api/v1/biomarkers │ │ | |
| │ │ (or Ollama) │ │ - /api/v1/analyze/* │ │ | |
| │ └─────────────────┘ └───────────┬──────────────┘ │ | |
| │ │ │ | |
| │ ┌───────────▼──────────────┐ │ | |
| │ │ RagBot Core System │ │ | |
| │ │ (Imported Package) │ │ | |
| │ │ │ │ | |
| │ │ - 6 Specialist Agents │ │ | |
| │ │ - LangGraph Workflow │ │ | |
| │ │ - FAISS Vector Store │ │ | |
| │ │ - 2,609 medical chunks │ │ | |
| │ └──────────────────────────┘ │ | |
| │ │ | |
| └─────────────────────────────────────────────────────────────────┘ | |
| ▲ | |
| │ | |
| HTTP Requests (JSON) | |
| │ | |
| │ | |
| ┌───────────┴────────────┐ | |
| │ Your Backend Server │ | |
| │ (Node.js/Python/etc) │ | |
| │ Port: 3000 │ | |
| │ │ | |
| │ - Receives frontend │ | |
| │ requests │ | |
| │ - Calls RagBot API │ | |
| │ - Returns results │ | |
| └───────────┬────────────┘ | |
| │ | |
| │ | |
| ┌───────────▼────────────┐ | |
| │ Your Frontend │ | |
| │ (React/Vue/etc) │ | |
| │ │ | |
| │ - User inputs data │ | |
| │ - Displays results │ | |
| │ - Shows analysis │ | |
| └────────────────────────┘ | |
| ``` | |
| --- | |
| ## 📡 Request Flow | |
| ### Natural Language Analysis Flow | |
| ``` | |
| User Types: | |
| "My glucose is 185 and HbA1c is 8.2" | |
| │ | |
| ▼ | |
| ┌────────────────────┐ | |
| │ Frontend (React) │ | |
| │ User Interface │ | |
| └─────────┬──────────┘ | |
| │ POST /api/analyze | |
| ▼ | |
| ┌────────────────────┐ | |
| │ Your Backend │ | |
| │ (Express/Flask) │ | |
| └─────────┬──────────┘ | |
| │ POST /api/v1/analyze/natural | |
| ▼ | |
| ┌─────────────────────────────────────┐ | |
| │ RagBot API (FastAPI) │ | |
| │ │ | |
| │ 1. Receive request │ | |
| │ {"message": "glucose 185..."} │ | |
| │ │ | |
| │ 2. Extract biomarkers │ | |
| │ ┌──────────────────┐ │ | |
| │ │ Extraction │ │ | |
| │ │ Service │ │ | |
| │ │ (LLM: llama3.1) │ │ | |
| │ └────────┬─────────┘ │ | |
| │ ▼ │ | |
| │ {"Glucose": 185, "HbA1c": 8.2} │ | |
| │ │ | |
| │ 3. Predict disease │ | |
| │ ┌──────────────────┐ │ | |
| │ │ Rule-based │ │ | |
| │ │ Predictor │ │ | |
| │ └────────┬─────────┘ │ | |
| │ ▼ │ | |
| │ {"disease": "Diabetes", ...} │ | |
| │ │ | |
| │ 4. Run RAG Workflow │ | |
| │ ┌──────────────────┐ │ | |
| │ │ RagBot Service │ │ | |
| │ │ (6 agents) │ │ | |
| │ └────────┬─────────┘ │ | |
| │ ▼ │ | |
| │ Full analysis response │ | |
| │ │ | |
| │ 5. Format response │ | |
| │ - Biomarker flags │ | |
| │ - Safety alerts │ | |
| │ - Recommendations │ | |
| │ - Disease explanation │ | |
| │ - Conversational summary │ | |
| │ │ | |
| └─────────┬───────────────────────────┘ | |
| │ JSON Response | |
| ▼ | |
| ┌────────────────────┐ | |
| │ Your Backend │ | |
| │ Processes data │ | |
| └─────────┬──────────┘ | |
| │ JSON Response | |
| ▼ | |
| ┌────────────────────┐ | |
| │ Frontend │ | |
| │ Displays results │ | |
| └────────────────────┘ | |
| ``` | |
| --- | |
| ## 🔄 Component Interaction | |
| ``` | |
| ┌───────────────────────────────────────────────────┐ | |
| │ FastAPI Application │ | |
| │ (app/main.py) │ | |
| │ │ | |
| │ ┌─────────────────────────────────────────────┐ │ | |
| │ │ Route Handlers │ │ | |
| │ │ │ │ | |
| │ │ /health /biomarkers /analyze/* │ │ | |
| │ │ │ │ │ │ │ | |
| │ └────┼───────────────┼──────────────┼─────────┘ │ | |
| │ │ │ │ │ | |
| │ ▼ ▼ ▼ │ | |
| │ ┌─────────┐ ┌─────────┐ ┌──────────────┐ │ | |
| │ │ Health │ │Biomarker│ │ Analyze │ │ | |
| │ │ Route │ │ Route │ │ Route │ │ | |
| │ └─────────┘ └─────────┘ └──────┬───────┘ │ | |
| │ │ │ | |
| │ ▼ │ | |
| │ ┌─────────────────────┐ │ | |
| │ │ Services Layer │ │ | |
| │ │ │ │ | |
| │ │ ┌───────────────┐ │ │ | |
| │ │ │ Extraction │ │ │ | |
| │ │ │ Service │ │ │ | |
| │ │ └───────┬───────┘ │ │ | |
| │ │ │ │ │ | |
| │ │ ┌───────▼───────┐ │ │ | |
| │ │ │ RagBot │ │ │ | |
| │ │ │ Service │ │ │ | |
| │ │ └───────┬───────┘ │ │ | |
| │ └──────────┼─────────┘ │ | |
| │ │ │ | |
| └─────────────────────────────────────┼───────────┘ | |
| │ | |
| ▼ | |
| ┌────────────────────────┐ | |
| │ RagBot Core System │ | |
| │ (src/workflow.py) │ | |
| │ │ | |
| │ ┌──────────────────┐ │ | |
| │ │ 6 Agent Workflow │ │ | |
| │ │ (LangGraph) │ │ | |
| │ └──────────────────┘ │ | |
| │ │ | |
| │ ┌──────────────────┐ │ | |
| │ │ Vector Store │ │ | |
| │ │ (FAISS) │ │ | |
| │ └──────────────────┘ │ | |
| └────────────────────────┘ | |
| ``` | |
| --- | |
| ## 📊 Data Flow | |
| ### Request → Response Journey | |
| ``` | |
| 1. INPUT (from user) | |
| ┌─────────────────────────────────┐ | |
| │ "My glucose is 185 and HbA1c │ | |
| │ is 8.2, I'm 52 years old" │ | |
| └─────────────────────────────────┘ | |
| │ | |
| ▼ | |
| 2. EXTRACTION (LLM Processing) | |
| ┌─────────────────────────────────┐ | |
| │ Biomarkers: │ | |
| │ - Glucose: 185.0 │ | |
| │ - HbA1c: 8.2 │ | |
| │ Context: │ | |
| │ - age: 52 │ | |
| └─────────────────────────────────┘ | |
| │ | |
| ▼ | |
| 3. PREDICTION (Rule-based) | |
| ┌─────────────────────────────────┐ | |
| │ Disease: Diabetes │ | |
| │ Confidence: 0.87 (87%) │ | |
| │ Probabilities: │ | |
| │ - Diabetes: 87% │ | |
| │ - Heart Disease: 8% │ | |
| │ - Others: 5% │ | |
| └─────────────────────────────────┘ | |
| │ | |
| ▼ | |
| 4. WORKFLOW (6 Agents Execute) | |
| ┌─────────────────────────────────┐ | |
| │ Agent 1: Biomarker Analyzer │ | |
| │ ✓ Validates 2 biomarkers │ | |
| │ ✓ Flags: 2 out of range │ | |
| │ ✓ Alerts: 2 critical │ | |
| └─────────────────────────────────┘ | |
| ┌─────────────────────────────────┐ | |
| │ Agent 2: Disease Explainer (RAG)│ | |
| │ ✓ Retrieved 5 medical docs │ | |
| │ ✓ Citations: 5 sources │ | |
| │ ✓ Pathophysiology explained │ | |
| └─────────────────────────────────┘ | |
| ┌─────────────────────────────────┐ | |
| │ Agent 3: Biomarker Linker (RAG) │ | |
| │ ✓ Linked 2 key drivers │ | |
| │ ✓ Evidence from literature │ | |
| └─────────────────────────────────┘ | |
| ┌─────────────────────────────────┐ | |
| │ Agent 4: Guidelines (RAG) │ | |
| │ ✓ Retrieved 3 guidelines │ | |
| │ ✓ Recommendations: 5 actions │ | |
| └─────────────────────────────────┘ | |
| ┌─────────────────────────────────┐ | |
| │ Agent 5: Confidence Assessor │ | |
| │ ✓ Reliability: MODERATE │ | |
| │ ✓ Evidence: STRONG │ | |
| │ ✓ Limitations: 2 noted │ | |
| └─────────────────────────────────┘ | |
| ┌─────────────────────────────────┐ | |
| │ Agent 6: Response Synthesizer │ | |
| │ ✓ Compiled all findings │ | |
| │ ✓ Structured output │ | |
| │ ✓ Conversational summary │ | |
| └─────────────────────────────────┘ | |
| │ | |
| ▼ | |
| 5. OUTPUT (to user) | |
| ┌─────────────────────────────────┐ | |
| │ Full JSON Response: │ | |
| │ │ | |
| │ - prediction │ | |
| │ - biomarker_flags │ | |
| │ - safety_alerts │ | |
| │ - key_drivers │ | |
| │ - disease_explanation │ | |
| │ - recommendations │ | |
| │ - confidence_assessment │ | |
| │ - agent_outputs │ | |
| │ - conversational_summary │ | |
| │ │ | |
| │ Processing time: 3.5 seconds │ | |
| └─────────────────────────────────┘ | |
| ``` | |
| --- | |
| ## 🎯 API Endpoint Map | |
| ``` | |
| RagBot API Root: http://localhost:8000 | |
| │ | |
| ├── / GET API info | |
| │ | |
| ├── /docs GET Swagger UI | |
| │ | |
| ├── /redoc GET ReDoc | |
| │ | |
| └── /api/v1/ | |
| │ | |
| ├── /health GET System status | |
| │ Returns: { | |
| │ status: "healthy", | |
| │ ollama_status: "connected", | |
| │ vector_store_loaded: true | |
| │ } | |
| │ | |
| ├── /biomarkers GET List all biomarkers | |
| │ Returns: { | |
| │ biomarkers: [...], | |
| │ total_count: 24 | |
| │ } | |
| │ | |
| └── /analyze/ | |
| │ | |
| ├── /natural POST Natural language | |
| │ Input: { | |
| │ message: "glucose 185...", | |
| │ patient_context: {...} | |
| │ } | |
| │ Output: Full analysis | |
| │ | |
| ├── /structured POST Direct biomarkers | |
| │ Input: { | |
| │ biomarkers: {...}, | |
| │ patient_context: {...} | |
| │ } | |
| │ Output: Full analysis | |
| │ | |
| └── /example GET Demo case | |
| Output: Full analysis | |
| ``` | |
| --- | |
| ## 🔌 Integration Points | |
| ``` | |
| ┌────────────────────────────────────────────────┐ | |
| │ Your Application Stack │ | |
| ├────────────────────────────────────────────────┤ | |
| │ │ | |
| │ Frontend (React/Vue/Angular) │ | |
| │ ┌──────────────────────────────────────────┐ │ | |
| │ │ User inputs: "glucose 185, HbA1c 8.2" │ │ | |
| │ │ Button click: "Analyze" │ │ | |
| │ └──────────────┬───────────────────────────┘ │ | |
| │ │ HTTP POST │ | |
| │ ▼ │ | |
| │ Backend (Node.js/Python/Java) │ | |
| │ ┌──────────────────────────────────────────┐ │ | |
| │ │ Endpoint: POST /api/analyze │ │ | |
| │ │ │ │ | |
| │ │ Code: │ │ | |
| │ │ const result = await fetch( │ │ | |
| │ │ 'http://localhost:8000/api/v1/ │ │ | |
| │ │ analyze/natural', │ │ | |
| │ │ {body: {message: userInput}} │ │ | |
| │ │ ); │ │ | |
| │ │ │ │ | |
| │ │ return result.data; │ │ | |
| │ └──────────────┬───────────────────────────┘ │ | |
| │ │ HTTP POST │ | |
| │ ▼ │ | |
| │ ┌──────────────────────────────────────────┐ │ | |
| │ │ RagBot API (localhost:8000) │◄─┼─ This is what we built! | |
| │ │ │ │ | |
| │ │ - Extracts biomarkers │ │ | |
| │ │ - Runs analysis │ │ | |
| │ │ - Returns JSON │ │ | |
| │ └──────────────┬───────────────────────────┘ │ | |
| │ │ JSON Response │ | |
| │ ▼ │ | |
| │ Backend processes and returns to frontend │ | |
| │ │ │ | |
| │ ▼ │ | |
| │ Frontend displays results to user │ | |
| │ │ | |
| └────────────────────────────────────────────────┘ | |
| ``` | |
| --- | |
| ## 💾 File Structure | |
| ``` | |
| api/ | |
| │ | |
| ├── app/ # Application code | |
| │ ├── __init__.py | |
| │ ├── main.py # FastAPI app (entry point) | |
| │ │ | |
| │ ├── models/ # Data schemas | |
| │ │ ├── __init__.py | |
| │ │ └── schemas.py # Pydantic models | |
| │ │ | |
| │ ├── routes/ # API endpoints | |
| │ │ ├── __init__.py | |
| │ │ ├── health.py # Health check | |
| │ │ ├── biomarkers.py # List biomarkers | |
| │ │ └── analyze.py # Analysis endpoints | |
| │ │ | |
| │ └── services/ # Business logic | |
| │ ├── __init__.py | |
| │ ├── extraction.py # Natural language extraction | |
| │ └── ragbot.py # Workflow orchestration | |
| │ | |
| ├── .env # Configuration | |
| ├── .env.example # Template | |
| ├── .gitignore # Git ignore rules | |
| ├── requirements.txt # Python dependencies | |
| ├── Dockerfile # Container image | |
| ├── docker-compose.yml # Deployment config | |
| │ | |
| └── Documentation/ | |
| ├── README.md # Complete guide | |
| ├── GETTING_STARTED.md # Quick start | |
| ├── QUICK_REFERENCE.md # Cheat sheet | |
| └── ARCHITECTURE.md # This file | |
| ``` | |
| --- | |
| **Created:** November 23, 2025 | |
| **Purpose:** Visual guide to RagBot API architecture | |
| **For:** Understanding system design and integration points | |