Rename Space card to HelloFibro

README.md

@@ -0,0 +1,1055 @@
+---
+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>