README.md

---
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
---

<p align="center">
<img width="250" height="250" alt="logo" src="https://github.com/user-attachments/assets/c2ad2088-729e-4257-9793-2f96f49053b0" />
</p>

<p align="center">
  <strong>AI-powered support companion for people living with fibromyalgia</strong>
</p>

<p align="center">
  <a href="#-features">Features</a> •
  <a href="#-demo">Demo</a> •
  <a href="#-quick-start">Quick Start</a> •
  <a href="#-tech-stack">Tech Stack</a> •
  <a href="#-architecture">Architecture</a> •
  <a href="#-workflows">Workflows</a>
</p>

<p align="center">
  <img src="https://img.shields.io/badge/Python-3.10+-3776AB?style=for-the-badge&logo=python&logoColor=white" alt="Python">
  <img src="https://img.shields.io/badge/Gradio-6.0-FF7C00?style=for-the-badge&logo=gradio&logoColor=white" alt="Gradio">
  <img src="https://img.shields.io/badge/Claude-Sonnet_4-191919?style=for-the-badge&logo=anthropic&logoColor=white" alt="Claude">

</p>

<p align="center">
  <img src="https://img.shields.io/badge/UI-Art_Deco_Inspired-8B0000?style=flat-square" alt="Art Deco">
  <img src="https://img.shields.io/badge/Accessibility-WCAG_AA-D4AF37?style=flat-square" alt="WCAG AA">
  <img src="https://img.shields.io/badge/Languages-21_Supported-white?style=flat-square" alt="21 Languages">
</p>

---

## 📖 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

---


<div align="center">

### 💜 Made with empathy for warriors living with fibromyalgia

*Your experience is valid. You are not alone. Your strength inspires us.*

---

**[⬆ Back to Top](#-hellofibro)**

</div>