You can deploy this model and start earning money today!

grasant/
hellofibro

Views

No views yet

logo

AI-powered support companion for people living with fibromyalgia

Features • Demo • Quick Start • Tech Stack • Architecture • Workflows

Python

Gradio

Claude

📖 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, which incorporate Google's HAI-DEF Terms of Use and 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:

User Input → User types message + optional file upload
File Processing → Extract text from PDF/DOCX/CSV/images
Context Building → Add medication/appointment context + file hints
Session Management → Retrieve/create conversation session
LLM Request → Send to Claude via OpenRouter with streaming
Response Processing → Extract medication commands, clean response
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)

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:

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 file for details.

💜 Acknowledgments

Built with love for the fibromyalgia community 💜
AI powered by Anthropic Claude via OpenRouter
UI framework by Gradio
Inspired by the strength and resilience of fibromyalgia warriors

💜 Made with empathy for warriors living with fibromyalgia

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

⬆ Back to Top

grasant/hellofibro

📖 About

Why HelloFibro?

🎬 Demo

✨ Features

💬 Empathetic AI Chat

💊 Medication Management

⚠️ Missed Dose Notification

📅 Appointment Management

📎 File Analysis

🧠 Medical Intelligence Layer

Reasoning Modes

Medical Knowledge Base

Automatic Factor Detection

🌍 Multi-Language Support

🎨 Premium Design

🛠️ Tech Stack

Core Technologies

Document Processing

Development Tools

Dependencies Overview

🏗️ Architecture

System Overview

Component Details

1. Main Interface (app/main.py)

2. Chat Handler (app/chat.py)

3. LLM Agent (app/llm_agent.py)

4. Medical Intelligence Services (app/services/)

5. Multi-Agent System (app/agents/)

6. FHIR Patient Profile (app/schemas/patient.py)

7. Medication Reminder (app/reminders.py)

8. Appointment Reminder (app/appointments.py)

9. Internationalization (app/i18n.py)

10. Configuration (app/config.py)

11. Data Models (models/schemas.py)

Directory Structure

🔄 Workflows

Chat Conversation Flow

Medication Management Flow

Appointment Management Flow

File Processing Flow

🚀 Quick Start

Prerequisites

Installation

Using Docker

Using Make (Recommended)

Access the App

⚙️ Configuration

Supported Languages

Supported Models

🧪 Testing

Test Categories

Medical Intelligence Tests

🔒 Security & Privacy

Important Notes

⚠️ Medical Disclaimer

Clinical Guidelines Compliance

🤝 Contributing

Development Setup

Code Style

Commit Messages

📜 License

💜 Acknowledgments

💜 Made with empathy for warriors living with fibromyalgia

grasant/
hellofibro

1. Main Interface (`app/main.py`)

2. Chat Handler (`app/chat.py`)

3. LLM Agent (`app/llm_agent.py`)

4. Medical Intelligence Services (`app/services/`)

5. Multi-Agent System (`app/agents/`)

6. FHIR Patient Profile (`app/schemas/patient.py`)

7. Medication Reminder (`app/reminders.py`)

8. Appointment Reminder (`app/appointments.py`)

9. Internationalization (`app/i18n.py`)

10. Configuration (`app/config.py`)

11. Data Models (`models/schemas.py`)