Spaces:

T0X1N
/

Agentic-RagBot

Sleeping

App Files Files Community

Agentic-RagBot / docs /archive /CLI_CHATBOT_USER_GUIDE.md

Nikhil Pravin Pise

refactor: major repository cleanup and bug fixes

6dc9d46 about 1 month ago

preview code

raw

history blame contribute delete

12.3 kB

CLI Chatbot User Guide

Interactive Chat Interface for MediGuard AI RAG-Helper

Date: November 23, 2025
Status: ✅ FULLY IMPLEMENTED AND OPERATIONAL

🎯 Quick Start

Run the Chatbot

python scripts/chat.py

First Time Setup

Make sure you have:

✅ Ollama running: ollama serve

✅ Models pulled:

ollama pull llama3.1:8b-instruct
ollama pull qwen2:7b

✅ Vector store created: python src/pdf_processor.py (if not already done)

💬 How to Use

Example Conversations

Example 1: Basic Biomarker Input

You: My glucose is 185 and HbA1c is 8.2

🔍 Analyzing your input...
✅ Found 2 biomarkers: Glucose, HbA1c
🧠 Predicting likely condition...
✅ Predicted: Diabetes (85% confidence)
📚 Consulting medical knowledge base...
   (This may take 15-25 seconds...)

🤖 RAG-BOT:
======================================================================
Hi there! 👋
Based on your biomarkers, I analyzed your results.

🔴 **Primary Finding:** Diabetes
   Confidence: 85%

⚠️ **IMPORTANT SAFETY ALERTS:**
   • Glucose: CRITICAL: Glucose is 185.0 mg/dL, above critical threshold
     → SEEK IMMEDIATE MEDICAL ATTENTION

[... full analysis ...]

Example 2: Multiple Biomarkers

You: hemoglobin 10.5, RBC 3.8, MCV 78, platelets 180000

✅ Found 4 biomarkers: Hemoglobin, RBC, MCV, Platelets
🧠 Predicting likely condition...
✅ Predicted: Anemia (72% confidence)

Example 3: With Patient Context

You: I'm a 52 year old male, glucose 185, cholesterol 235, HDL 38

✅ Found 3 biomarkers: Glucose, Cholesterol, HDL
✅ Patient context: age=52, gender=male

📋 Available Commands

`help` - Show Biomarker List

Displays all 24 supported biomarkers organized by category.

You: help

📋 Supported Biomarkers (24 total):

🩸 Blood Cells:
  • Hemoglobin, Platelets, WBC, RBC, Hematocrit, MCV, MCH, MCHC

🔬 Metabolic:
  • Glucose, Cholesterol, Triglycerides, HbA1c, LDL, HDL, Insulin, BMI

❤️ Cardiovascular:
  • Heart Rate, Systolic BP, Diastolic BP, Troponin, C-reactive Protein

🏥 Organ Function:
  • ALT, AST, Creatinine

`example` - Run Demo Case

Runs a complete example of a Type 2 Diabetes patient with 11 biomarkers.

You: example

📋 Running Example: Type 2 Diabetes Patient
   52-year-old male with elevated glucose and HbA1c

🔄 Running analysis...
[... full RAG workflow execution ...]

`quit` - Exit Chatbot

Exits the interactive session gracefully.

You: quit

👋 Thank you for using MediGuard AI. Stay healthy!

🩺 Supported Biomarkers (24 Total)

Blood Cells (8)

Biomarker	Aliases	Example Input
Hemoglobin	HGB, HB	"hemoglobin 13.5"
Platelets	PLT	"platelets 220000"
WBC	White Blood Cells	"WBC 7500"
RBC	Red Blood Cells	"RBC 4.8"
Hematocrit	HCT	"hematocrit 42"
MCV	Mean Corpuscular Volume	"MCV 85"
MCH	Mean Corpuscular Hemoglobin	"MCH 29"
MCHC	-	"MCHC 34"

Metabolic (8)

Biomarker	Aliases	Example Input
Glucose	Blood Sugar	"glucose 140"
Cholesterol	Total Cholesterol	"cholesterol 220"
Triglycerides	Trig	"triglycerides 180"
HbA1c	A1C, Hemoglobin A1c	"HbA1c 7.5"
LDL	LDL Cholesterol	"LDL 160"
HDL	HDL Cholesterol	"HDL 45"
Insulin	-	"insulin 18"
BMI	Body Mass Index	"BMI 28.5"

Cardiovascular (5)

Biomarker	Aliases	Example Input
Heart Rate	HR, Pulse	"heart rate 85"
Systolic BP	Systolic, SBP	"systolic 145"
Diastolic BP	Diastolic, DBP	"diastolic 92"
Troponin	-	"troponin 0.05"
C-reactive Protein	CRP	"CRP 8.5"

Organ Function (3)

Biomarker	Aliases	Example Input
ALT	Alanine Aminotransferase	"ALT 45"
AST	Aspartate Aminotransferase	"AST 38"
Creatinine	-	"creatinine 1.1"

🎨 Input Formats Supported

The chatbot accepts natural language input in various formats:

Format 1: Conversational

My glucose is 140 and my HbA1c is 7.5

Format 2: List Style

Hemoglobin 11.2, platelets 180000, cholesterol 235

Format 3: Structured

glucose=185, HbA1c=8.2, HDL=38, triglycerides=210

Format 4: With Context

I'm 52 years old male, glucose 185, cholesterol 235

Format 5: Mixed

Blood test results: glucose is 140, my HbA1c came back at 7.5%, and cholesterol is 220

🔍 How It Works

1. Biomarker Extraction (LLM)

Uses llama3.1:8b-instruct to extract biomarkers from natural language
Normalizes biomarker names (e.g., "A1C" → "HbA1c")
Extracts patient context (age, gender, BMI)

2. Disease Prediction (LLM)

Uses qwen2:7b to predict disease based on biomarker patterns
Returns: disease name, confidence score, probability distribution
Fallback: Rule-based prediction if LLM fails

3. RAG Workflow Execution

Runs complete 6-agent workflow:
1. Biomarker Analyzer
2. Disease Explainer (RAG)
3. Biomarker-Disease Linker (RAG)
4. Clinical Guidelines (RAG)
5. Confidence Assessor
6. Response Synthesizer

4. Conversational Formatting

Converts technical JSON → friendly text
Emoji indicators
Safety alerts highlighted
Clear structure with sections

💾 Saving Reports

After each analysis, you'll be asked:

💾 Save detailed report to file? (y/n):

If you choose y:

Report saved to: data/chat_reports/report_Diabetes_YYYYMMDD_HHMMSS.json
Contains: Input biomarkers + Complete analysis JSON
Can be reviewed later or shared with healthcare providers

⚠️ Important Notes

Minimum Requirements

At least 2 biomarkers needed for analysis
More biomarkers = more accurate predictions

System Requirements

RAM: 2GB minimum (2.5-3GB recommended)
Ollama: Must be running (ollama serve)
Models: llama3.1:8b-instruct, qwen2:7b

Limitations

Not a Medical Device - For educational/informational purposes only
No Real ML Model - Uses LLM-based prediction (not trained ML model)
Standard Units Only - Enter values in standard medical units
Manual Entry - Must type biomarkers (no PDF upload yet)

🐛 Troubleshooting

Issue 1: "Failed to initialize system"

Cause: Ollama not running or models not available

Solution:

# Start Ollama
ollama serve

# Pull required models
ollama pull llama3.1:8b-instruct
ollama pull qwen2:7b

Issue 2: "I couldn't find any biomarker values"

Cause: LLM couldn't extract biomarkers from input

Solution:

Use clearer format: "glucose 140, HbA1c 7.5"
Type help to see biomarker names
Check spelling

Issue 3: "Analysis failed: Ollama call failed"

Cause: Insufficient system memory or Ollama timeout

Solution:

Close other applications
Restart Ollama
Try again with fewer biomarkers

Issue 4: Unicode/Emoji Display Issues

Solution: Already handled! Script automatically sets UTF-8 encoding.

📊 Example Output Structure

Hi there! 👋
Based on your biomarkers, I analyzed your results.

🔴 **Primary Finding:** Diabetes
   Confidence: 87%

⚠️ **IMPORTANT SAFETY ALERTS:**
   • Glucose: CRITICAL: Glucose is 185.0 mg/dL
     → SEEK IMMEDIATE MEDICAL ATTENTION

🔍 **Why this prediction?**
   • **Glucose** (185.0 mg/dL): Significantly elevated...
   • **HbA1c** (8.2%): Poor glycemic control...

✅ **What You Should Do:**
   1. Consult healthcare provider immediately
   2. Bring lab results to appointment

🌱 **Lifestyle Recommendations:**
   1. Follow balanced diet
   2. Regular physical activity
   3. Monitor blood sugar

ℹ️ **Important:** This is AI-assisted analysis, NOT medical advice.
   Please consult a healthcare professional.

🚀 Performance

Metric	Typical Value
Biomarker Extraction	3-5 seconds
Disease Prediction	2-3 seconds
RAG Workflow	15-25 seconds
Total Time	~20-30 seconds

🔮 Future Features (Planned)

Phase 2 Enhancements

Multi-turn conversations - Answer follow-up questions
PDF lab report upload - Extract from scanned reports
Unit conversion - Support mg/dL ↔ mmol/L
Trend tracking - Compare with previous results
Voice input - Speak biomarkers instead of typing

Phase 3 Enhancements

Web interface - Browser-based chat
Real ML model integration - Professional disease prediction
Multi-language support - Spanish, Chinese, etc.

📚 Technical Details

Architecture

User Input (Natural Language)
    ↓
extract_biomarkers() [llama3.1:8b]
    ↓
predict_disease_llm() [qwen2:7b]
    ↓
create_guild().run() [6 agents, RAG, LangGraph]
    ↓
format_conversational()
    ↓
Conversational Output

Files

Main Script: scripts/chat.py (~620 lines)
Config: config/biomarker_references.json
Reports: data/chat_reports/*.json

Dependencies

langchain_community - LLM interfaces
langchain_core - Prompts
Existing src/ modules - Core RAG system

✅ Validation

Tested Scenarios

✅ Diabetes patient (glucose, HbA1c elevated)
✅ Anemia patient (low hemoglobin, MCV)
✅ Heart disease indicators (cholesterol, troponin)
✅ Minimal input (2 biomarkers)
✅ Invalid input handling
✅ Help command
✅ Example command
✅ Report saving
✅ Graceful exit

🎓 Best Practices

For Accurate Results

Provide at least 3-5 biomarkers for reliable analysis
Include key indicators for the condition you suspect
Mention patient context (age, gender) when relevant
Use standard medical units (mg/dL for glucose, % for HbA1c)

Safety

Always consult a doctor - This is NOT medical advice
Don't delay emergency care - Critical alerts require immediate attention
Share reports with healthcare providers - Save and bring JSON reports

📞 Support

Questions?

Review documentation: docs/CLI_CHATBOT_IMPLEMENTATION_PLAN.md
Check system verification: docs/SYSTEM_VERIFICATION.md
See project overview: README.md

Issues?

Check Ollama is running: ollama list
Verify models are available
Review error messages carefully

📝 Example Session

PS> python scripts/chat.py

======================================================================
🤖 MediGuard AI RAG-Helper - Interactive Chat
======================================================================

Welcome! I can help you understand your blood test results.

You can:
  1. Describe your biomarkers (e.g., 'My glucose is 140, HbA1c is 7.5')
  2. Type 'example' to see a sample diabetes case
  3. Type 'help' for biomarker list
  4. Type 'quit' to exit

======================================================================

🔧 Initializing medical knowledge system...
✅ System ready!

You: my glucose is 185 and HbA1c is 8.2

🔍 Analyzing your input...
✅ Found 2 biomarkers: Glucose, HbA1c
🧠 Predicting likely condition...
✅ Predicted: Diabetes (85% confidence)
📚 Consulting medical knowledge base...
   (This may take 15-25 seconds...)

🤖 RAG-BOT:
======================================================================
[... full conversational response ...]
======================================================================

💾 Save detailed report to file? (y/n): y
✅ Report saved to: data/chat_reports/report_Diabetes_20251123_071530.json

You can:
  • Enter more biomarkers for a new analysis
  • Type 'quit' to exit

You: quit

👋 Thank you for using MediGuard AI. Stay healthy!

Status: ✅ FULLY OPERATIONAL
Version: 1.0
Last Updated: November 23, 2025

MediGuard AI RAG-Helper - Making medical insights accessible through conversation 🏥💬

CLI Chatbot User Guide

Interactive Chat Interface for MediGuard AI RAG-Helper

🎯 Quick Start

Run the Chatbot

First Time Setup

💬 How to Use

Example Conversations

Example 1: Basic Biomarker Input

Example 2: Multiple Biomarkers

Example 3: With Patient Context

📋 Available Commands

help - Show Biomarker List

example - Run Demo Case

quit - Exit Chatbot

🩺 Supported Biomarkers (24 Total)

Blood Cells (8)

Metabolic (8)

Cardiovascular (5)

Organ Function (3)

🎨 Input Formats Supported

Format 1: Conversational

Format 2: List Style

Format 3: Structured

Format 4: With Context

Format 5: Mixed

🔍 How It Works

1. Biomarker Extraction (LLM)

2. Disease Prediction (LLM)

3. RAG Workflow Execution

4. Conversational Formatting

💾 Saving Reports

⚠️ Important Notes

Minimum Requirements

System Requirements

Limitations

🐛 Troubleshooting

Issue 1: "Failed to initialize system"

Issue 2: "I couldn't find any biomarker values"

Issue 3: "Analysis failed: Ollama call failed"

Issue 4: Unicode/Emoji Display Issues

📊 Example Output Structure

🚀 Performance

🔮 Future Features (Planned)

Phase 2 Enhancements

Phase 3 Enhancements

📚 Technical Details

Architecture

Files

Dependencies

✅ Validation

Tested Scenarios

🎓 Best Practices

For Accurate Results

Safety

📞 Support

Questions?

Issues?

📝 Example Session

`help` - Show Biomarker List

`example` - Run Demo Case

`quit` - Exit Chatbot