Rename Space card to HelloFibro

c6204f8 verified 13 days ago

42.4 kB

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