---
title: HelloFibro
emoji: π
colorFrom: red
colorTo: yellow
sdk: gradio
sdk_version: 6.15.1
app_file: app.py
python_version: "3.12"
startup_duration_timeout: 1h
suggested_hardware: zero-a10g
short_description: Multimodal fibromyalgia support with MedGemma
models:
- google/medgemma-27b-it
---
AI-powered support companion for people living with fibromyalgia
Features β’
Demo β’
Quick Start β’
Tech Stack β’
Architecture β’
Workflows
---
## π About
**HelloFibro** is an AI assistant designed specifically for people living with fibromyalgia. It provides emotional support, evidence-based information, practical coping strategies, and medication managementβall through a beautiful, accessible interface optimized for those experiencing chronic pain and fatigue.
### Why HelloFibro?
Living with fibromyalgia means dealing with invisible symptoms that others often don't understand. HelloFibro was built with deep empathy and understanding:
- π **Validation First** β Your pain is real. Your experiences matter.
- π§ **Brain Fog Friendly** β Clear, simple interface designed for cognitive challenges
- π **Gentle Design** β Art Deco-inspired aesthetics that are calming, not overwhelming
- π **21 Languages** β Full internationalization with native language support
- π **Privacy Focused** β No data persistence, session-only storage
---
## π¬ Demo
https://github.com/user-attachments/assets/4f57d250-8355-4167-927e-f14fa78e8a6e
The hosted MedGemma version is a research/portfolio demonstration, not a
medical device or healthcare service. Chat access is gated by acceptance of the
[HelloFibro HAI-DEF Demo Use Terms](docs/HAI_DEF_DEMO_TERMS.md), which
incorporate Google's
[HAI-DEF Terms of Use](https://developers.google.com/health-ai-developer-foundations/terms)
and
[Prohibited Use Policy](https://developers.google.com/health-ai-developer-foundations/prohibited-use-policy).
---
## β¨ Features
### π¬ Empathetic AI Chat
The heart of HelloFibroβintelligent, understanding conversations powered by Claude Sonnet 4.
| Feature | Description |
|---------|-------------|
| **Streaming Responses** | Real-time typing effect for natural conversation flow |
| **Fibromyalgia Expertise** | Specialized knowledge about symptoms, triggers, and management |
| **Session Memory** | Remembers context within your conversation |
| **Markdown Support** | Rich formatting for clear, readable responses |
| **Brain Fog Consideration** | Short paragraphs, clear language, patient pacing |
| **Medical Context Awareness** | Automatically detects worsening factors in your messages |
| **EULAR 2016 Compliance** | Recommendations align with EU clinical guidelines |
```
User: Mam dziΕ bardzo silny bΓ³l i nie wiem co robiΔ
HelloFibro: π Bardzo mi przykro, ΕΌe mierzysz siΔ dziΕ z takim silnym bΓ³lem.
To musi byΔ naprawdΔ trudne.
Kilka rzeczy, ktΓ³re mogΔ
pomΓ³c w tej chwili:
β’ ZnajdΕΊ wygodnΔ
pozycjΔ i pozwΓ³l sobie odpoczΔ
Δ
β’ CiepΕy okΕad moΕΌe przynieΕΔ ulgΔ
β’ Spokojne, gΕΔbokie oddychanie...
```
### π Medication Management
Comprehensive medication tracking designed for chronic illness management.
| Feature | Description |
|---------|-------------|
| **Quick Add** | Add medications via chat or form interface |
| **Visual Tracking** | See all medications with taken/pending status |
| **One-Tap Logging** | Mark medications as taken with a single click |
| **Missed Dose Alerts** | Smart notifications for missed doses after 4 AM |
| **Reminder Toggle** | Enable/disable reminders per medication |
| **Adherence Stats** | Track your medication compliance |
#### β οΈ Missed Dose Notification
When you miss a medication dose, HelloFibro will remind you the next morning (after 4:00 AM) with a gentle notification:
| Action | Description |
|--------|-------------|
| **β WziΔty** | Mark as taken late (still counts for adherence) |
| **β PominiΔty** | Register as missed dose |
| **OdrzuΔ** | Dismiss notification without logging |
The notification uses calming amber colors (not aggressive red) following healthcare UX best practices for reduced alert fatigue.
**Supported medication categories:**
- Fibromyalgia/Neuropathic (Pregabalin, Duloxetine, Gabapentin...)
- NSAIDs (Ibuprofen, Ketoprofen, Naproxen...)
- Stronger painkillers (Tramadol, Tapentadol...)
- Muscle relaxants (Tizanidine, Baclofen...)
- Sleep aids (Melatonin, Trazodone...)
- Supplements (Magnesium, Vitamin D3, CBD oil...)
### π
Appointment Management
Track and manage your doctor appointments with smart reminders.
| Feature | Description |
|---------|-------------|
| **Add Appointments** | Schedule visits with doctor name, specialty, date/time, location |
| **Specialty Types** | Pre-defined medical specialties (Rheumatologist, Neurologist, etc.) |
| **Visual Tracking** | See upcoming appointments with status indicators |
| **Smart Reminders** | Optional day-before reminder notifications |
| **Notes** | Add questions and notes for each appointment |
| **Status Indicators** | Today, Soon, Upcoming, Past appointment badges |
**Medical use cases:**
- Schedule rheumatologist follow-ups
- Track physiotherapy sessions
- Prepare questions for specialist visits
- Never miss important appointments
### π File Analysis
Upload and discuss medical documents with AI assistance.
| File Type | Supported Formats | Capabilities |
|-----------|-------------------|--------------|
| **Documents** | PDF, DOCX, DOC | Extract text, find key health info |
| **Spreadsheets** | XLSX, XLS, CSV | Analyze symptoms, patterns, statistics |
| **Text Files** | TXT, MD, JSON, XML, LOG | Parse and explain content |
| **Images** | PNG, JPG, GIF, WEBP | Describe and discuss |
| **Code** | PY, JS, HTML, CSS | Explain and analyze |
**Medical use cases:**
- π Prescription analysis
- π Symptom diary review
- π©Ί Lab results discussion
- π Doctor visit preparation
### π§ Medical Intelligence Layer
Advanced AI-powered medical reasoning system for evidence-based fibromyalgia support.
| Component | Description |
|-----------|-------------|
| **Adaptive Reasoning Router** | Routes queries to appropriate reasoning depth based on complexity |
| **Medical Knowledge Service** | Queries 15+ worsening factors, EULAR guidelines, differential diagnosis |
| **EU Guidelines Validator** | Validates recommendations against EULAR 2016, German S3, UK NICE |
| **FHIR Patient Profile** | HL7 FHIR R4-compliant patient model with ACR 2016 criteria |
| **Agent Council** | Multi-agent system with backtracking exploration for complex cases |
#### Reasoning Modes
| Mode | Complexity | Use Case |
|------|------------|----------|
| **Parallel Short** | < 0.3 | Simple symptom questions, medication lookup |
| **Sequential Medium** | 0.3-0.7 | Symptom pattern analysis, treatment comparison |
| **Deep Sequential** | > 0.7 | Differential diagnosis, treatment-resistant cases |
#### Medical Knowledge Base
- **15 Worsening Factors** with severity scores, mechanisms, and neurotransmitter impacts
- **EULAR 2016 Recommendations** β Strong FOR, Weak FOR, Strong AGAINST
- **German S3 & UK NICE Guidelines** β First-line treatments, contraindications
- **Differential Diagnosis** β Lyme, hypothyroidism, vitamin D deficiency, ACR 2016 criteria
- **Medication Database** β EU/FDA approval status, response rates, contraindications
#### Automatic Factor Detection
The system detects worsening factors mentioned in your messages:
```
User: "I can't sleep and I'm very stressed lately"
Detected Factors:
- sleep_deprivation (sleep, insomnia keywords)
- hpa_axis_dysregulation (stress, anxiety keywords)
β Enhanced response with relevant coping strategies
```
### π Multi-Language Support
Full internationalization with 21 supported languages.
| Region | Languages |
|--------|-----------|
| **Europe** | English (US/UK), Polish, German, Spanish, French, Italian, Dutch, Portuguese, Swedish, Norwegian, Danish |
| **Asia** | Japanese, Korean, Chinese, Thai, Indonesian, Hindi |
| **Middle East** | Arabic, Hebrew, Turkish |
**Features:**
- Language selector in the UI sidebar
- All UI elements fully translated
- Automatic fallback to English for missing translations
- Easy to add new languages via JSON translation files
### π¨ Premium Design
Art Deco-inspired healthcare aesthetic that's both beautiful and functional.
| Design Element | Details |
|----------------|---------|
| **Primary Color** | Deep Crimson `#8B0000` β trust, medical seriousness |
| **Accent Color** | Warm Gold `#D4AF37` β premium, hopeful |
| **Background** | Ivory/Pearl `#FEFEFE` β clean, calming |
| **Typography** | Playfair Display (headings) + DM Sans (body) |
| **Accessibility** | WCAG AA compliant, high contrast for tired eyes |
---
## π οΈ Tech Stack
### Core Technologies
| Component | Technology | Version | Purpose |
|-----------|------------|---------|---------|
| **Runtime** | Python | 3.10+ | Core programming language |
| **Web Framework** | Gradio | 6.0+ | Modern UI with messages format |
| **AI Provider** | OpenRouter | - | LLM API gateway |
| **AI Model** | Claude Sonnet 4 | Latest | Empathetic, intelligent responses |
| **Validation** | Pydantic | 2.11+ | Type-safe data models |
| **Configuration** | pydantic-settings | 2.7+ | Environment management |
| **Medical Standards** | HL7 FHIR R4 | - | Interoperable patient data |
### Document Processing
| Library | Purpose |
|---------|---------|
| **PyMuPDF (fitz)** | PDF text extraction |
| **python-docx** | Word document parsing |
| **pandas** | CSV/Excel data analysis |
| **openpyxl** | Excel XLSX support |
| **xlrd** | Legacy XLS support |
### Development Tools
| Tool | Purpose |
|------|---------|
| **pytest** | Testing framework |
| **pytest-asyncio** | Async test support |
| **black** | Code formatting |
| **ruff** | Fast Python linter |
| **mypy** | Static type checking |
| **loguru** | Beautiful logging |
### Dependencies Overview
```txt
# Core Framework
gradio>=6.0.0
openai>=1.54.0
pydantic>=2.11.0
pydantic-settings>=2.7.0
# Document Processing
PyMuPDF>=1.24.0
python-docx>=1.1.0
pandas>=2.2.0
# Development
pytest>=8.3.0
black>=24.10.0
ruff>=0.8.0
```
---
## ποΈ Architecture
### System Overview
```
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β USER INTERFACE β
β (Gradio 6.0 Web App) β
βββββββββββββββ¬βββββββββββββββββββ¬βββββββββββββββββ¬ββββββββββββββββ€
β Chat UI β Medication UI β File Upload β Quick Actionsβ
ββββββββ¬βββββββ΄βββββββββ¬ββββββββββ΄ββββββββ¬βββββββββ΄ββββββββ¬ββββββββ
β β β β
βΌ βΌ βΌ βΌ
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β APPLICATION LAYER β
β (app/main.py) β
βββββββββββββββ¬βββββββββββββββββββ¬βββββββββββββββββββββββββββββββββ€
β ChatHandler β MedicationReminderβ FileProcessor β
β (chat.py) β (reminders.py) β (main.py) β
ββββββββ¬βββββββ΄βββββββββ¬ββββββββββ΄βββββββββββββββββββββββββββββββββ
β β
βΌ βΌ
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β CORE SERVICES β
βββββββββββββββββββββββββ¬ββββββββββββββββββββββββββββββββββββββββββ€
β LLMAgent β Data Models β
β (agents.py) β (schemas.py) β
β β β
β β’ Async OpenAI SDK β β’ Medication / MedicationLog β
β β’ Streaming support β β’ ConversationSession β
β β’ Error handling β β’ MedicationState β
βββββββββββββ¬ββββββββββββ΄ββββββββββββββββββββββββββββββββββββββββββ
β
βΌ
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β EXTERNAL SERVICES β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€
β OpenRouter API β
β (anthropic/claude-sonnet-4) β
β β
β ββββββββββββββββββββββββββββββββββββ β
β β HTTP/HTTPS + Streaming SSE β β
β β β’ Max 4096 tokens β β
β β β’ Temperature 0.7 β β
β β β’ Async with httpx β β
β ββββββββββββββββββββββββββββββββββββ β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
```
### Component Details
#### 1. Main Interface (`app/main.py`)
- Creates Gradio 6 Blocks interface
- Handles file upload and processing
- Coordinates chat and medication features
- Injects custom CSS styling
#### 2. Chat Handler (`app/chat.py`)
- Manages conversation sessions
- Converts between Gradio 6 messages format and OpenAI API
- Handles streaming and non-streaming responses
- **Detects worsening factors** in user messages
- **Enhances system prompts** with medical context
- **Caches medical context** for performance (60s TTL)
#### 3. LLM Agent (`app/llm_agent.py`)
- Async OpenAI SDK client for OpenRouter
- Loads system prompt from file
- Implements retry logic and error handling
- Supports both streaming and batch responses
#### 4. Medical Intelligence Services (`app/services/`)
| Service | Purpose |
|---------|---------|
| **AdaptiveReasoningRouter** | Routes queries to parallel/sequential/deep modes based on complexity |
| **MedicalKnowledgeService** | 8 query methods for features, guidelines, differential diagnosis |
| **EUGuidelinesValidator** | Validates against EULAR 2016, German S3, UK NICE guidelines |
#### 5. Multi-Agent System (`app/agents/`)
| Agent | Role |
|-------|------|
| **FibroAgentCouncil** | Orchestrates specialized agents with consensus synthesis |
| **SymptomAnalyzer** | Analyzes symptom patterns and severity |
| **TherapyExpert** | Recommends evidence-based treatments |
| **LifestyleCoach** | Provides pacing and lifestyle strategies |
| **RiskAssessor** | Evaluates safety and recommends escalation |
**Exploration Strategies:**
- **Parallel Consensus** β All agents run simultaneously for routine queries
- **Deep Sequential with Backtracking** β DFS-style hypothesis exploration for complex cases
#### 6. FHIR Patient Profile (`app/schemas/patient.py`)
- HL7 FHIR R4 compliant patient resource
- **WPI** (Widespread Pain Index) 0-19
- **SSS** (Symptom Severity Score) 0-12
- **ACR 2016 criteria** automatic calculation
- **PHI masking** for privacy protection
#### 7. Medication Reminder (`app/reminders.py`)
- In-memory medication state management
- LLM command parsing (`[MEDICATION_CMD: ...]`)
- Adherence tracking and statistics
- Pending reminder detection
- **Missed dose detection** (after 4 AM daily check)
- Actions: mark taken late, register missed, dismiss
#### 8. Appointment Reminder (`app/appointments.py`)
- Doctor appointment scheduling and tracking
- Specialty-based categorization
- Day-before reminder system
- Status indicators (Today, Soon, Upcoming, Past)
- LLM command parsing (`[APPOINTMENT_CMD: ...]`)
#### 9. Internationalization (`app/i18n.py`)
- 21 supported languages with JSON translation files
- Dynamic language switching at runtime
- Nested key access with dot notation
- Automatic fallback to English
- `UIStrings` class for type-safe UI text access
#### 10. Configuration (`app/config.py`)
- Pydantic Settings with validation
- Environment variable loading
- Type-safe configuration access
- Default language setting
#### 11. Data Models (`models/schemas.py`)
- Pydantic 2.11 models
- Gradio 6 messages format support
- Medication and logging schemas
### Directory Structure
```
hellofibro/
βββ app/ # Application code
β βββ __init__.py
β βββ main.py # Gradio interface + file processing
β βββ config.py # Pydantic settings
β βββ llm_agent.py # LLM agent (OpenRouter)
β βββ chat.py # Chat session management + medical context
β βββ prompts.py # LLM prompts and file hints
β βββ i18n.py # Internationalization service (21 languages)
β βββ security.py # Input sanitization + HIPAA audit
β βββ reminders.py # Medication system
β βββ appointments.py # Appointment management
β β
β βββ agents/ # π Multi-agent system
β β βββ __init__.py
β β βββ council.py # FibroAgentCouncil with backtracking
β β
β βββ schemas/ # π Medical data schemas
β β βββ __init__.py
β β βββ patient.py # FHIR R4 patient profile + ACR 2016
β β
β βββ services/ # π Medical intelligence services
β βββ __init__.py
β βββ reasoning_router.py # Adaptive chain-of-thought scaling
β βββ medical_knowledge.py # Knowledge base queries
β βββ eu_guidelines_validator.py # EULAR/S3/NICE compliance
β
βββ models/ # Data models
β βββ __init__.py
β βββ schemas.py # Pydantic schemas
β
βββ data/ # Static data
β βββ prompts/
β β βββ system_prompt.txt # AI personality definition
β βββ translations/ # UI translations (21 languages)
β β βββ en-US.json # English (US)
β β βββ pl.json # Polish
β β βββ de.json # German
β β βββ ... # 18 more languages
β βββ features.json # 15 worsening factors
β βββ metrics.json # 8 evaluation metrics
β βββ guidelines.json # EU clinical guidelines
β βββ reasoning_config.json # Reasoning mode configuration
β
βββ static/ # Web assets
β βββ logo.png # App logo
β βββ custom.css # Premium styling (1100+ lines)
β
βββ resources/ # Design resources
β βββ hellofibro_logo.png # Original logo
β βββ style.css # Reference styles
β βββ hellofibro-gradio6-modern.md
β
βββ tests/ # Test suite
β βββ __init__.py
β βββ conftest.py # Pytest fixtures (incl. medical)
β βββ test_chat.py # Chat tests
β βββ test_agents.py # Agent tests
β βββ test_reminders.py # Medication tests
β βββ test_missed_doses.py # Missed dose notification tests
β βββ test_config.py # Config tests
β βββ test_e2e.py # End-to-end tests
β βββ test_medical_layer.py # π Medical services unit tests
β βββ test_medical_integration.py # π Medical integration tests
β
βββ .env # Environment config (create this)
βββ .env.example # Example environment file
βββ requirements.txt # Python dependencies
βββ Makefile # Development commands
βββ Dockerfile # Container definition
βββ docker-compose.yml # Container orchestration
βββ pyproject.toml # Project metadata
βββ BRANDING_GUIDE.md # Design system documentation
βββ IMPLEMENTATION_PLAN.md # Development roadmap
βββ README.md # This file
```
---
## π Workflows
### Chat Conversation Flow
```
βββββββββββββββ βββββββββββββββ βββββββββββββββ
β User β β Gradio UI β β ChatHandler β
β Input βββββββΆβ (main.py) βββββββΆβ (chat.py) β
βββββββββββββββ βββββββββββββββ ββββββββ¬βββββββ
β
βΌ
βββββββββββββββ βββββββββββββββ βββββββββββββββ
β Streaming ββββββββ LLMAgent ββββββββ Session β
β Response β β (agents.py) β β History β
βββββββββββββββ ββββββββ¬βββββββ βββββββββββββββ
β
βΌ
βββββββββββββββββ
β OpenRouter β
β Claude API β
βββββββββββββββββ
```
**Step-by-step:**
1. **User Input** β User types message + optional file upload
2. **File Processing** β Extract text from PDF/DOCX/CSV/images
3. **Context Building** β Add medication/appointment context + file hints
4. **Session Management** β Retrieve/create conversation session
5. **LLM Request** β Send to Claude via OpenRouter with streaming
6. **Response Processing** β Extract medication commands, clean response
7. **UI Update** β Stream response to chat interface
### Medication Management Flow
```
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β USER ACTIONS β
ββββββββββββββββ¬βββββββββββββββ¬ββββββββββββββββ¬ββββββββββββββββ€
β "Dodaj lek β Click "Add β Click "Take" β "WziΔ
Εem β
β X 100mg" β Medication" β Button β pregabalinΔ" β
ββββββββ¬ββββββββ΄βββββββ¬ββββββββ΄ββββββββ¬ββββββββ΄ββββββββ¬ββββββββ
β β β β
βΌ βΌ βΌ βΌ
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β PROCESSING LAYER β
βββββββββββββββββββββββ¬ββββββββββββββββββββββββββββββββββββββββ€
β LLM generates: β Direct UI Handler: β
β [MEDICATION_CMD: β add_medication_ui() β
β ADD: X|100mg|...] β mark_taken_ui() β
ββββββββββββ¬βββββββββββ΄ββββββββββββββββ¬ββββββββββββββββββββββββ
β β
βΌ βΌ
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β MedicationReminder (reminders.py) β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€
β β’ add_medication() β’ mark_taken() β
β β’ remove_medication() β’ get_medications_for_display() β
β β’ get_today_status() β’ process_llm_medication_command() β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β
βΌ
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β MedicationState β
β (In-memory storage with Pydantic models) β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
```
**LLM Command Format:**
```python
# Adding medication via chat
[MEDICATION_CMD: ADD: Pregabalina|150mg|21:00|wieczorem|na bΓ³l neuropatyczny]
# Removing medication
[MEDICATION_CMD: REMOVE: Pregabalina]
# Marking as taken
[MEDICATION_CMD: TAKEN: Pregabalina]
# Listing all medications
[MEDICATION_CMD: LIST:]
```
### Appointment Management Flow
```
+---------------+ +------------------+ +-------------------+
| USER ACTIONS | | PROCESSING LAYER | | AppointmentReminder|
+---------------+ +------------------+ +-------------------+
| | |
v v v
"Add visit" LLM generates: add_appointment()
Click Form [APPOINTMENT_CMD: ADD: ...] get_appointments()
Click Card OR remove_appointment()
| Direct UI Handler |
+--------->----------------------->---------------+
|
v
+-------------------+
| AppointmentState |
| (In-memory) |
+-------------------+
```
**LLM Command Format:**
```python
# Adding appointment via chat
[APPOINTMENT_CMD: ADD: Dr. Smith|Rheumatologist|2025-01-15|10:00|ABC Clinic|bring test results]
# Removing appointment
[APPOINTMENT_CMD: REMOVE: Dr. Smith]
# Listing all appointments
[APPOINTMENT_CMD: LIST:]
```
### File Processing Flow
```
βββββββββββββββ ββββββββββββββββββββ βββββββββββββββ
β File Upload βββββββΆβ process_uploaded βββββββΆβ Type Check β
β (User) β β _file() β β & Validate β
βββββββββββββββ ββββββββββββββββββββ ββββββββ¬βββββββ
β
βββββββββββββββββββββββββββββββββββΌββββββββββββββββββ
β β β
βΌ βΌ βΌ
βββββββββββββββ βββββββββββββββ βββββββββββββββ
β PDF (fitz) β β DOCX/DOC β β CSV/XLSX β
β extract_pdf β β extract_docxβ β pandas read β
β _text() β β _text() β β β
ββββββββ¬βββββββ ββββββββ¬βββββββ ββββββββ¬βββββββ
β β β
βββββββββββββββββ¬ββββββββββββββββ΄βββββββββββββββββββ
β
βΌ
βββββββββββββββββββ
β Content + Hint β
β for LLM Context β
ββββββββββ¬βββββββββ
β
βΌ
βββββββββββββββββββ
β Enhanced Chat β
β Message β
βββββββββββββββββββ
```
**Supported File Processing:**
| Type | Library | Max Size | Features |
|------|---------|----------|----------|
| PDF | PyMuPDF | 15MB | Multi-page, page markers |
| DOCX | python-docx | 15MB | Paragraphs + tables |
| XLSX/XLS | pandas + openpyxl | 15MB | Multi-sheet, statistics |
| CSV | pandas | 15MB | Headers, stats preview |
| TXT/MD/JSON | Built-in | 50KB | UTF-8 with fallback |
| Images | Base64 | 15MB | Vision model support |
---
## π Quick Start
### Prerequisites
- **Python 3.10+** installed
- **OpenRouter API key** ([Get one here](https://openrouter.ai))
### Installation
```bash
# 1. Clone the repository
git clone https://github.com/hellofibro/hellofibro.git
cd hellofibro
# 2. Create virtual environment
python -m venv venv
# Windows
.\venv\Scripts\activate
# macOS/Linux
source venv/bin/activate
# 3. Install dependencies
pip install -r requirements.txt
# 4. Create environment file
cp .env.example .env
# Edit .env and add your OPENROUTER_API_KEY
# 5. Run the application
python -m app.main
```
### Using Docker
```bash
# Build and run with Docker Compose
docker-compose up --build -d
# View logs
docker-compose logs -f
# Stop the container
docker-compose down
```
**Container Status:**
```
NAME IMAGE STATUS PORTS
hellofibro hellofibro-hellofibro Up (running) 0.0.0.0:7860->7860/tcp
```
**With API Key (Production):**
```bash
# Windows PowerShell
$env:OPENROUTER_API_KEY="sk-or-v1-your-key-here"
docker-compose up -d
# Linux/macOS
export OPENROUTER_API_KEY="sk-or-v1-your-key-here"
docker-compose up -d
# Or create .env file first
echo "OPENROUTER_API_KEY=sk-or-v1-your-key-here" > .env
docker-compose up -d
```
**Demo Mode (No API Key):**
Without an API key, the app runs in demo mode with pre-defined responses:
```bash
docker-compose up -d
# Logs will show: "Running in DEMO MODE - API calls disabled"
```
**Manual Docker Build:**
```bash
# Build image
docker build -t hellofibro .
# Run with environment variable
docker run -p 7860:7860 -e OPENROUTER_API_KEY=sk-or-v1-xxx hellofibro
# Or with .env file
docker run -p 7860:7860 --env-file .env hellofibro
```
**Docker Compose Configuration:**
The `docker-compose.yml` includes:
- Health checks (every 30s)
- Resource limits (2 CPU, 2GB RAM)
- Automatic restart policy
- Environment variable passthrough
### Using Make (Recommended)
```bash
make setup # Create venv + install dependencies
make run # Start the application
make test # Run all tests
make lint # Check code quality
make format # Format code with black
make clean # Remove cache files
```
### Access the App
```
π Open http://localhost:7860 in your browser
```
---
## βοΈ Configuration
Create a `.env` file in the project root:
```env
# Required - Your OpenRouter API key
OPENROUTER_API_KEY=sk-or-v1-your-api-key-here
# Optional - Model selection (defaults shown)
OPENROUTER_MODEL=anthropic/claude-sonnet-4
OPENROUTER_BASE_URL=https://openrouter.ai/api/v1
# Optional - Model parameters
MODEL_MAX_TOKENS=4096
MODEL_TEMPERATURE=0.7
# Optional - Application settings
APP_TITLE=HelloFibro
APP_HOST=0.0.0.0
APP_PORT=7860
# Optional - Feature flags
DEBUG_MODE=false # Set to true to test missed dose notifications anytime
STREAM_RESPONSES=true
LOG_LEVEL=INFO
# Optional - Internationalization
DEFAULT_LANGUAGE=pl # Default UI language (pl, en-US, de, es, fr, etc.)
```
### Supported Languages
| Code | Language | Native Name |
|------|----------|-------------|
| `en-US` | English (US) | English (US) |
| `en-GB` | English (UK) | English (UK) |
| `pl` | Polish | Polski |
| `de` | German | Deutsch |
| `es` | Spanish | Espanol |
| `fr` | French | Francais |
| `it` | Italian | Italiano |
| `nl` | Dutch | Nederlands |
| `pt` | Portuguese | Portugues |
| `sv` | Swedish | Svenska |
| `no` | Norwegian | Norsk |
| `da` | Danish | Dansk |
| `ja` | Japanese | Nihongo |
| `ko` | Korean | Hangugeo |
| `zh` | Chinese | Zhongwen |
| `ar` | Arabic | Al-Arabiyyah |
| `he` | Hebrew | Ivrit |
| `hi` | Hindi | Hindi |
| `th` | Thai | Phasa Thai |
| `tr` | Turkish | Turkce |
| `id` | Indonesian | Bahasa Indonesia |
### Supported Models
Any OpenRouter-compatible model works. Recommended options:
| Model | ID | Best For |
|-------|-----|----------|
| **Claude Sonnet 4** | `anthropic/claude-sonnet-4` | Best quality (default) |
| **Claude 3.5 Sonnet** | `anthropic/claude-3.5-sonnet` | Fast, excellent |
| **GPT-4o** | `openai/gpt-4o` | Alternative |
| **Claude 3 Haiku** | `anthropic/claude-3-haiku` | Budget-friendly |
---
## π§ͺ Testing
```bash
# Run all tests
pytest tests/ -v
# Run with coverage
pytest tests/ --cov=app --cov=models
# Run specific test file
pytest tests/test_chat.py -v
# Run async tests only
pytest tests/ -v -k "async"
```
### Test Categories
| File | Tests |
|------|-------|
| `test_config.py` | Settings validation, API key format |
| `test_agents.py` | LLM agent, streaming, error handling |
| `test_chat.py` | Session management, message processing |
| `test_reminders.py` | Medication CRUD, logging, commands |
| `test_missed_doses.py` | Missed dose detection, actions |
| `test_language_selection.py` | i18n service, language switching |
| `test_e2e.py` | End-to-end integration tests |
| `test_medical_layer.py` | Medical services unit tests |
| `test_medical_integration.py` | End-to-end medical integration |
### Medical Intelligence Tests
```bash
# Run medical layer tests specifically
pytest tests/test_medical_layer.py -v
pytest tests/test_medical_integration.py -v
# Run all tests including medical
pytest tests/ -v --tb=short
```
**Tested Components:**
- MedicalKnowledgeService queries (features, guidelines, differential)
- EUGuidelinesValidator (therapy validation, contraindications)
- AdaptiveReasoningRouter (complexity assessment, mode routing)
- FibroPatientProfile (ACR 2016, PHI masking, FHIR export)
- ChatHandler medical context integration
- FibroAgentCouncil parallel/deep modes
---
## π Security & Privacy
HelloFibro is designed with privacy as a core principle:
| Aspect | Implementation |
|--------|----------------|
| **Data Storage** | Session-only, in-memory (no persistence) |
| **API Keys** | Stored in `.env`, never logged or transmitted |
| **User Data** | Not stored, not tracked, not shared |
| **Conversations** | Cleared on session end |
| **Medications** | In-memory only (MVP) |
| **File Uploads** | Processed in memory, not stored |
| **PHI Protection** | π FHIR patient profiles support PHI masking |
| **Medical Data** | π No patient data persisted, session-only |
### Important Notes
- β
HTTPS recommended for production
- β
API key validation at startup
- β
No PII collection or storage
- β οΈ Future versions may add optional persistence with encryption
---
## β οΈ Medical Disclaimer
> **HelloFibro is NOT a substitute for professional medical advice.**
This AI assistant provides general support and information only:
| β HelloFibro Does NOT | β
HelloFibro Does |
|------------------------|-------------------|
| Diagnose conditions | Provide emotional support |
| Prescribe medications | Track prescribed medications |
| Replace healthcare providers | Help prepare for doctor visits |
| Provide emergency advice | Offer coping strategies |
| Make treatment decisions | Share general fibromyalgia info |
| Provide dosage advice | Reference EULAR/S3/NICE guidelines |
### Clinical Guidelines Compliance
HelloFibro references established clinical guidelines for informational purposes:
| Guideline | Year | Scope |
|-----------|------|-------|
| **EULAR 2016** | 2016 | European League Against Rheumatism |
| **German S3** | 2017 | German Association of Scientific Medical Societies |
| **UK NICE** | 2021 | UK National Institute for Health and Care Excellence |
| **ACR 2016** | 2016 | American College of Rheumatology diagnostic criteria |
**Always consult qualified healthcare professionals for medical decisions.**
---
## π€ Contributing
Contributions are welcome! Please follow these guidelines:
### Development Setup
```bash
# 1. Fork and clone
git clone https://github.com/YOUR_USERNAME/hellofibro.git
cd hellofibro
# 2. Create branch
git checkout -b feature/your-feature
# 3. Install dev dependencies
pip install -r requirements.txt
# 4. Make changes and test
make test
make lint
# 5. Format code
make format
# 6. Commit and push
git commit -m "feat: add amazing feature"
git push origin feature/your-feature
# 7. Open Pull Request
```
### Code Style
- **Formatting**: Black (line length 88)
- **Linting**: Ruff
- **Type Hints**: Required for all functions
- **Docstrings**: Required for public APIs
### Commit Messages
Follow [Conventional Commits](https://www.conventionalcommits.org/):
```
feat: add new medication reminder feature
fix: resolve chat history persistence issue
docs: update README with architecture diagram
style: format code with black
refactor: extract file processing to separate module
test: add tests for medication commands
```
---
## π License
This project is licensed under the **MIT License** - see the [LICENSE](LICENSE) file for details.
---
## π Acknowledgments
- Built with love for the fibromyalgia community π
- AI powered by [Anthropic Claude](https://anthropic.com) via [OpenRouter](https://openrouter.ai)
- UI framework by [Gradio](https://gradio.app)
- Inspired by the strength and resilience of fibromyalgia warriors
---
### π Made with empathy for warriors living with fibromyalgia
*Your experience is valid. You are not alone. Your strength inspires us.*
---
**[β¬ Back to Top](#-hellofibro)**