README.md

metadata

title: HBV AI Assistant - Patient Selection System
emoji: 🏥
colorFrom: blue
colorTo: green
sdk: docker
pinned: false
app_port: 7860

HBV AI Assistant - Patient Selection System

A specialized AI-powered clinical decision support system for hepatologists and healthcare professionals managing Hepatitis B Virus (HBV) patients. The system evaluates patient eligibility for treatment according to SASLT 2021 guidelines and provides evidence-based recommendations.

🎯 Features

Core Capabilities

• Patient Eligibility Assessment: Evaluates HBV patients for treatment eligibility based on SASLT 2021 guidelines
• Evidence-Based Guidance: Provides treatment recommendations according to authoritative medical guidelines
• Comprehensive Input Validation: Validates patient data including HBV DNA levels, ALT levels, fibrosis stage, and more
• Treatment Options: Recommends preferred regimens (ETV, TDF, TAF) based on patient profile
• AI-Powered Chat: Interactive AI bot for exploring guideline recommendations
• JSON API: RESTful POST endpoint for programmatic integration

Technical Features

• FastAPI Backend: High-performance async API
• Structured Input/Output: Well-defined schemas for patient data and eligibility results
• Real-time Processing: Fast eligibility determination
• Authentication: Secure session-based authentication
• Rate Limiting: Built-in API rate limiting
• CORS Support: Cross-origin resource sharing enabled

🚀 Deployment

Live API

The API is deployed at: http://127.0.0.1:7860

Quick Start

1. Access the API:

   • API Docs: http://127.0.0.1:7860/docs
   • Health Check: http://127.0.0.1:7860/health

2. Submit Patient Data:

   • Use the POST /assess endpoint to evaluate patient eligibility
   • Provide patient information according to the input schema
   • Receive eligibility determination and treatment recommendations

Deploy Your Own Instance

See DEPLOYMENT.md for detailed deployment instructions.

📚 API Endpoints

Health & Status

• GET / - API information
• GET /health - Health check

HBV Patient Assessment

• POST /assess - Evaluate patient eligibility for HBV treatment using structured data
• POST /assess/text - Text-based patient assessment (provide clinical notes in free text format)
  • Input: Patient data (sex, age, HBV DNA, ALT, fibrosis stage, etc.)
  • Output: Eligibility status and treatment recommendations

AI Chat

• POST /ask - Ask guideline-related questions with optional patient context

  • Input:
    • query (string): The question or message
    • session_id (string, optional): Session identifier for conversation history
    • patient_context (object, optional): Patient data for context-aware responses
    • assessment_result (object, optional): Previous assessment results for reference

• POST /ask/stream - Streaming chat responses with optional patient context

  • Input: Same as /ask endpoint
  • Output: Stream of text chunks for real-time display

💻 Local Development

Prerequisites

• Python 3.11+
• OpenAI API key (optional, for AI chat feature)

Setup

1. Clone the repository:

git clone https://github.com/your-repo/hbv-ai-assistant.git
cd hbv-ai-assistant

2. Install dependencies:

pip install -r requirements.txt

3. Configure environment variables:

cp .env.example .env
# Edit .env with your API keys

4. Run the application:

python app.py

5. Access the application:
   • API: http://localhost:7860
   • Docs: http://localhost:7860/docs
   • Test the /assess endpoint with patient data

🔧 Configuration

Environment Variables

See .env.example for all configuration options:

• OPENAI_API_KEY: Your OpenAI API key (optional, for AI chat)
• PORT: Server port (default: 7860)
• ALLOWED_ORIGINS: CORS allowed origins

Authentication

Default credentials (change in production):

• Username: admin
• Password: admin123

Update in api/routers/auth.py or via environment variables.

📖 Usage Examples

Assessing Patient Eligibility

import requests

# Login
response = requests.post(
    "http://127.0.0.1:7860/auth/login",
    json={"username": "admin", "password": "admin123"}
)
cookies = response.cookies

# Assess patient eligibility
patient_data = {
    "sex": "Male",
    "age": 45,
    "pregnancy_status": "Not pregnant",
    "hbsag_status": "Positive",
    "duration_hbsag_months": 12,
    "hbv_dna_level": 50000,
    "hbeag_status": "Positive",
    "alt_level": 60,
    "fibrosis_stage": "F2-F3",
    "necroinflammatory_activity": "A2",
    "extrahepatic_manifestations": False,
    "coinfections": [],
    "family_history_cirrhosis_hcc": False
}

response = requests.post(
    "http://127.0.0.1:7860/assess",
    json=patient_data,
    cookies=cookies
)
result = response.json()
print(f"Eligible: {result['eligible']}")
print(f"Recommendations: {result['recommendations']}")

🏗️ Architecture

Components

• FastAPI Backend: RESTful API with async support
• Eligibility Engine: Evaluates patient data against SASLT 2021 criteria
• AI Chat (Optional): LangChain-powered conversational interface for guideline exploration
• Validation Layer: Ensures data integrity and completeness

Assessment Logic

The system evaluates patients based on SASLT 2021 criteria:

1. HBV DNA > 2,000 IU/mL + ALT > ULN + moderate necroinflammation/fibrosis (≥F2 or ≥A2)
2. Cirrhosis (F4) with any detectable HBV DNA
3. HBV DNA > 20,000 IU/mL + ALT > 2×ULN regardless of fibrosis
4. Age > 30 with HBeAg-positive chronic infection (normal ALT, high HBV DNA)
5. Family history of HCC/cirrhosis + HBV DNA > 2,000 + ALT > ULN
6. Extrahepatic manifestations

📊 Response Format

The API returns:

• Eligibility Status: Eligible / Not Eligible
• Guideline Recommendations: Specific criteria met and treatment options
• Treatment Choices: Preferred regimens (ETV, TDF, TAF)

Example Response:

{
  "eligible": true,
  "recommendations": "Patient meets SASLT 2021 criteria: HBV DNA > 2,000 IU/mL, ALT > ULN, and fibrosis stage F2-F3 (Grade A)",
  "treatment_options": ["ETV", "TDF", "TAF"],
  "guideline": "SASLT 2021"
}

🔒 Security

• Session-based authentication
• Rate limiting (100 requests/minute)
• CORS protection
• Input validation
• Secure cookie handling

📝 License

[Add your license here]

🤝 Contributing

Contributions are welcome! Please read the contributing guidelines first.

📧 Support

For issues or questions:

• Check the DEPLOYMENT.md guide
• Review API docs at /docs
• Open an issue on GitHub

🙏 Acknowledgments

Built with:

• FastAPI
• Pydantic
• Python 3.11+
• SASLT 2021 Guidelines