Spaces:

ruslanmv
/

MediBot

Running

App Files Files Community

MediBot / docs /ADMIN.md

github-actions[bot]

Deploy MedOS Global from ef736eb7

cb6a2d8 about 1 month ago

preview code

raw

history blame contribute delete

22 kB

MedOS Admin Guide

Complete guide for deploying, configuring, and managing the MedOS platform.

Architecture Overview
Deployment Guide
Admin Panel
LLM Provider Setup
Email (SMTP) Configuration
Medicine Scanner Setup
Nearby Finder Setup
Environment Variables Reference
Troubleshooting

Architecture Overview

MedOS runs as 3 independent HuggingFace Spaces + an optional Vercel frontend:

┌─────────────────────────────────────────────────────────────┐
│                    User's Browser                           │
│                                                             │
│  Vercel (optional)              OR    HuggingFace Space     │
│  ai-medical-chabot.com               huggingface.co/spaces/ │
│  Frontend only                        ruslanmv/MediBot      │
│  /api/proxy/* → MediBot              Full app (FE + BE)     │
└──────────┬──────────────────────────────┬───────────────────┘
           │                              │
           ▼                              ▼
┌─────────────────────────────────────────────────────────────┐
│  MediBot Space (ruslanmv/MediBot)                           │
│  Next.js 14 + SQLite                                        │
│                                                             │
│  /api/chat     → LLM providers (Llama, Qwen, Gemma, etc.)  │
│  /api/auth/*   → User auth (register, login, verify)        │
│  /api/nearby   → Proxy to MetaEngine-Nearby                 │
│  /api/scan     → Proxy to Medicine-Scanner                  │
│  /api/admin/*  → Admin panel APIs                           │
│  /api/health   → Health check                               │
└──────────┬──────────────────────┬───────────────────────────┘
           │                      │
           ▼                      ▼
┌──────────────────────┐  ┌──────────────────────┐
│  Medicine-Scanner     │  │  MetaEngine-Nearby   │
│  (Gradio SDK)         │  │  (Gradio SDK)        │
│                       │  │                      │
│  Qwen2.5-VL-72B      │  │  OpenStreetMap       │
│  Image → JSON         │  │  Overpass API        │
│                       │  │  Nominatim geocoder  │
└───────────────────────┘  └──────────────────────┘

Deployment Guide

Prerequisites

HuggingFace account with write token
(Optional) Vercel account for custom domain
(Optional) SMTP credentials for email verification

Required Tokens

Token	Purpose	How to Create
HF_TOKEN (write)	Deploy Spaces, manage secrets	huggingface.co/settings/tokens → Fine-grained → Repo write
HF_TOKEN_INFERENCE	Medicine Scanner AI inference	Create here → Check "Make calls to Inference Providers"

Deploy MediBot (Main App)

This is the core application — chat, health tracker, auth, admin panel.

# 1. Set your HuggingFace token
export HF_TOKEN=hf_your_write_token_here

# 2. Deploy (assembles web/ + backend, rewrites API paths, pushes)
bash 9-HuggingFace-Global/scripts/deploy-hf.sh

# 3. Verify
curl https://ruslanmv-medibot.hf.space/api/health
# → {"status":"ok"}

What it does:

Copies 9-HuggingFace-Global/ (backend) as the base
Overlays web/ (frontend components, hooks, styles)
Rewrites /api/proxy/ → /api/ in all frontend files
Force-pushes to ruslanmv/MediBot HF Space

After deployment, set these secrets in the Space settings:

Secret	Value	Required?
`HF_TOKEN`	Your HF token (for LLM inference)	Yes
`HF_TOKEN_INFERENCE`	Token with inference permissions	For scanner proxy
`NEARBY_URL`	`https://ruslanmv-metaengine-nearby.hf.space`	Default works
`SCANNER_URL`	`https://ruslanmv-medicine-scanner.hf.space`	Default works
`DB_PATH`	`/data/medos.db`	Default works

Deploy Medicine Scanner

AI-powered medicine label reader using Qwen2.5-VL-72B.

export HF_TOKEN=hf_your_write_token_here
bash 11-Medicine-Scanner/deploy-scanner.sh

# Verify
curl https://ruslanmv-medicine-scanner.hf.space/api/health
# → {"status":"ok","service":"medicine-scanner"}

After deployment, set this secret in Space settings:

Secret	Value	Required?
`HF_TOKEN`	Token with "Make calls to Inference Providers" permission	Yes

Test the scanner:

curl -X POST https://ruslanmv-medicine-scanner.hf.space/api/scan \
  -F "image=@photo_of_medicine.jpg"

Deploy MetaEngine Nearby Finder

Finds pharmacies and doctors using OpenStreetMap.

export HF_TOKEN=hf_your_write_token_here
bash 12-MetaEngine-Nearby/deploy-nearby.sh

# Verify
curl https://ruslanmv-metaengine-nearby.hf.space/api/health
# → {"status":"ok","service":"nearby-finder"}

No secrets needed — uses free OpenStreetMap APIs.

Test the finder:

curl -X POST https://ruslanmv-metaengine-nearby.hf.space/api/search \
  -H "Content-Type: application/json" \
  -d '{"lat": 40.7128, "lon": -74.006, "entity_type": "pharmacy", "limit": 5}'

Deploy Vercel Frontend (Optional)

For custom domains (e.g., ai-medical-chabot.com):

Go to vercel.com → Import Git Repository
Root Directory: web
Framework: Next.js
Environment Variables:

Variable	Value
`NEXT_PUBLIC_BACKEND_URL`	`https://ruslanmv-medibot.hf.space`

Click Deploy
Add custom domain in Vercel → Settings → Domains

The Vercel frontend is a thin proxy — all API calls go to the MediBot Space.

Admin Panel

How to Access

Go to your MedOS instance (HF Space or Vercel URL)
Log in with the default admin account:
- Email: admin@medos.health
- Password: admin123456
Change the password immediately after first login
The Admin section appears in the desktop sidebar (bottom, under Tools)

Admin Panel Tabs

Overview

Platform statistics at a glance:

Total users, verified users, admin count
Health records count, chat sessions count
Active sessions (logged-in users)
Health data breakdown by type (medications, vitals, etc.)
Registration trend chart (last 30 days)

Users

User management:

Search by email or display name
Paginated list (20 users per page)
Per-user info: email, verification status, health records count, chat count
Reset Password: Set a temporary password for a user (invalidates all sessions)
Delete User: Admin-only, requires email confirmation, CASCADE deletes all data

LLM

Test all AI model providers:

Click "Test All Providers" to test 12 models in parallel
Shows status (green/red), latency (ms), response preview
Summary: total/online/offline counts
Explains the routing fallback chain

Current model cascade (tested and verified):

Model	Size	Provider
Llama 3.3 70B :sambanova	70B	SambaNova
Llama 3.3 70B :together	70B	Together
Llama 3.3 70B (auto)	70B	Auto-routed
Qwen 2.5 72B	72B	Auto-routed
Qwen3 235B (MoE)	235B	Auto-routed
Gemma 3 27B	27B	Auto-routed
Llama 3.1 70B	70B	Auto-routed
Qwen3 32B	32B	Auto-routed
DeepSeek V3	671B	Auto-routed

If all models fail, the system falls back to 15 pre-cached medical FAQ responses (always works, even offline).

Email

SMTP configuration for email verification and password reset:

Field	Description	Example
SMTP Host	Mail server hostname	`smtp.gmail.com`
SMTP Port	Usually 587 (TLS) or 465 (SSL)	`587`
SMTP Username	Your email account	`medos@yourdomain.com`
SMTP Password	App password (not your login password)	`xxxx xxxx xxxx xxxx`
From Email	Sender display name + email	`MedOS <noreply@medos.health>`
Recovery Email	Support contact for users	`support@medos.health`

Gmail setup:

Go to myaccount.google.com/apppasswords
Generate an app password
Use your Gmail as SMTP username, app password as SMTP password
Host: smtp.gmail.com, Port: 587

If SMTP is not configured: Verification codes are logged to the console (visible in Space logs). This is fine for development but not production.

Server

Server-side configuration:

Setting	Description	Default
Default Preset	Default AI model for new users	`free-best`
Ollama Base URL	Local Ollama server (if running)	`http://localhost:11434`
HF Default Model	Default model for HF Inference	`meta-llama/Llama-3.3-70B-Instruct`
Application URL	Public URL (used in emails)	`https://ruslanmv-medibot.hf.space`
Allowed Origins	CORS origins (comma-separated)	Your Vercel URL

Changes are saved to /data/medos-config.json and persist across restarts.

LLM Provider Setup

How the AI Chat Works

When a user sends a message:

1. Emergency triage (19 patterns, instant) — bypasses LLM entirely
2. RAG context (medical knowledge base, 23 topics)
3. System prompt (WHO/CDC/NHS guidelines, user's language + country)
4. LLM provider chain:
   a. OllaBridge (if configured) — custom gateway
   b. HuggingFace Inference — 9-model cascade
   c. Cached FAQ (always works) — 15 pre-built answers

HuggingFace Token Requirements

The HF_TOKEN secret on the MediBot Space needs "Make calls to Inference Providers" permission:

Go to huggingface.co/settings/tokens
Create a Fine-grained token
Check "Make calls to Inference Providers"
Copy the token
Set it as HF_TOKEN in MediBot Space settings

Testing LLM Health

From the Admin Panel: Admin → LLM tab → "Test All Providers"

From the command line:

HF_TOKEN=hf_xxx python scripts/check-llm-health.py

Output:

  OK   Llama-3.3-70B-Instruct                640ms  OK
  OK   Qwen2.5-72B-Instruct                 1366ms  OK
  OK   Qwen3-235B-A22B                      1785ms  OK
  OK   gemma-3-27b-it                        951ms  OK
  FAIL Llama-3.3-70B-Instruct:sambanova     2549ms  402 Payment Required

Summary: 12/13 models online (1 degraded)

Adding a Custom OllaBridge Gateway

If you run your own LLM server:

# Set in HF Space settings
OLLABRIDGE_URL=https://your-server.com
OLLABRIDGE_API_KEY=sk-your-key

OllaBridge is tried FIRST in the fallback chain, before HuggingFace.

Email (SMTP) Configuration

Quick Setup (Gmail)

Enable 2FA on your Google account
Generate an app password: myaccount.google.com/apppasswords
In MedOS Admin → Email tab:
- Host: smtp.gmail.com
- Port: 587
- User: your.email@gmail.com
- Password: (the app password from step 2)
- From: MedOS <your.email@gmail.com>
Click Save Configuration

Other Providers

Provider	Host	Port
Gmail	`smtp.gmail.com`	587
Outlook	`smtp.office365.com`	587
SendGrid	`smtp.sendgrid.net`	587
AWS SES	`email-smtp.us-east-1.amazonaws.com`	587
Mailgun	`smtp.mailgun.org`	587

What Emails Are Sent

Email	When	Expiry
Verification code	User registers	15 minutes
Password reset code	User clicks "Forgot password"	1 hour
Welcome email	After email verification	N/A

Dev Mode (No SMTP)

If SMTP is not configured, all verification codes are logged to the console. Check Space logs:

[EMAIL] To: user@example.com
[EMAIL] Subject: MedOS — verify your email
[EMAIL] Body: Your verification code is: 847291

Medicine Scanner Setup

How the Scanner Works on Each Platform

Platform	Behavior
Desktop (Chrome/Firefox/Edge)	Live webcam preview inside modal with viewfinder overlay. User positions medicine, clicks "Capture". Falls back to file upload if webcam not available.
Android	Opens native camera app directly. Photo is sent to AI immediately.
iPhone/iPad	Opens native camera app directly. Same as Android.

Webcam Permissions

For the desktop webcam to work:

The site must be served over HTTPS (required by browsers for getUserMedia)
User must allow camera access when prompted
Permissions-Policy: camera=(self) header is already set

Token Requirements

The Medicine Scanner Space needs a HuggingFace token with "Make calls to Inference Providers" permission (same as LLM chat).

Set it as HF_TOKEN in the Medicine-Scanner Space settings.

Models Used

Model	Purpose	Fallback
Qwen/Qwen2.5-VL-72B-Instruct	Primary (best quality)	→
google/gemma-3-27b-it	Fallback	N/A

How It Works

User takes photo → MedOS frontend
    → POST /api/scan (MediBot proxy)
    → POST /api/scan (Scanner Space)
    → Encode image as base64
    → Send to Qwen2.5-VL-72B with extraction prompt
    → Parse JSON response
    → Return: name, dose, form, category, expiry, instructions

Nearby Finder Setup

No Configuration Needed

MetaEngine-Nearby uses free APIs — no tokens or secrets required:

OpenStreetMap Overpass API — pharmacy/doctor location data
Nominatim — geocoding (city name → coordinates) and reverse geocoding

How It Works

User enters location → MedOS frontend
    → POST /api/nearby (MediBot proxy)
    → POST /gradio_api/call/search_ui (MetaEngine Space)
    → Query Overpass API for pharmacies/doctors within radius
    → Calculate distance, ETA (walk/drive)
    → Generate Google Maps directions URLs
    → Return sorted results

Overpass API Limits

Free, no API key
Rate limit: ~10,000 requests/day (shared)
Timeout: 25 seconds per query
If Overpass is slow, results may be empty — retry helps

Environment Variables Reference

MediBot Space

Variable	Required	Default	Description
`HF_TOKEN`	Yes	—	HuggingFace token (inference + write)
`DB_PATH`	No	`/data/medos.db`	SQLite database path
`ADMIN_EMAIL`	No	`admin@medos.health`	Default admin email
`ADMIN_PASSWORD`	No	`admin123456`	Default admin password
`SMTP_HOST`	No	—	SMTP server hostname
`SMTP_PORT`	No	`587`	SMTP port
`SMTP_USER`	No	—	SMTP username
`SMTP_PASS`	No	—	SMTP password
`FROM_EMAIL`	No	`MedOS <noreply@medos.health>`	Sender email
`APP_URL`	No	`https://ruslanmv-medibot.hf.space`	Public URL
`ALLOWED_ORIGINS`	No	`*`	CORS allowed origins
`NEARBY_URL`	No	`https://ruslanmv-metaengine-nearby.hf.space`	Nearby finder URL
`SCANNER_URL`	No	`https://ruslanmv-medicine-scanner.hf.space`	Scanner URL
`HF_TOKEN_INFERENCE`	No	—	Inference token for scanner proxy
`OLLABRIDGE_URL`	No	—	Custom OllaBridge gateway URL
`OLLABRIDGE_API_KEY`	No	—	OllaBridge API key
`DEFAULT_PRESET`	No	`free-best`	Default AI model preset

Medicine Scanner Space

Variable	Required	Default	Description
`HF_TOKEN`	Yes	—	Token with inference permissions

MetaEngine Nearby Space

No environment variables needed. Uses free OpenStreetMap APIs.

Vercel Frontend

Variable	Required	Default	Description
`NEXT_PUBLIC_BACKEND_URL`	Yes	`https://ruslanmv-medibot.hf.space`	MediBot Space URL

Troubleshooting

"All models failed" in chat

Go to Admin → LLM tab → Test All Providers
If all models show red: your HF_TOKEN doesn't have inference permissions
Fix: Create a new token at huggingface.co/settings/tokens
Update the HF_TOKEN secret in MediBot Space settings

Medicine Scanner shows "Scan failed"

Check the Scanner Space is running: visit huggingface.co/spaces/ruslanmv/Medicine-Scanner
If sleeping, any request will wake it (takes ~30 seconds)
Check HF_TOKEN secret is set with inference permissions

Nearby search returns no results

Check MetaEngine Space is running: visit huggingface.co/spaces/ruslanmv/MetaEngine-Nearby
Overpass API may be slow — retry after a few seconds
Try a different location (some areas have fewer OSM entries)

Chat returns 504 on Vercel (ai-medical-chabot.com)

This happens when the MediBot Space is sleeping and the Vercel proxy times out waiting for it to wake.

Fixes:

vercel.json sets maxDuration: 60 (increased from 30s)
If still timing out, wake MediBot first: visit huggingface.co/spaces/ruslanmv/MediBot and wait ~30s
For always-on, upgrade the MediBot HF Space to a paid plan

Why it happens:

Vercel proxy → MediBot (sleeping, 30s cold start) → LLM (5-10s) = 40s total
Vercel free tier allows max 60s per function call

Desktop webcam not working in scanner

Ensure the site is served over HTTPS (browsers block getUserMedia on HTTP)
User must click "Allow" on the camera permission prompt
If webcam is blocked, the scanner shows "Upload photo" as fallback
Check browser settings: Settings → Privacy → Camera → allow your domain

Email verification codes not received

Check Admin → Email tab — is SMTP configured?
If not configured, codes appear in Space logs (Container tab)
For Gmail: use an app password, not your login password
Check spam folder

Space shows "Building" or "Error"

Check Space logs at huggingface.co/spaces/ruslanmv/SpaceName → Logs tab
Common issues:
- Missing HF_TOKEN secret → auth errors
- Dependency conflict → check requirements.txt
- Port mismatch → ensure app runs on port 7860

Admin panel not visible

You must be logged in as an admin user
Default admin: admin@medos.health / admin123456
The Admin section only appears in the desktop sidebar (not mobile drawer for security)
If the admin account doesn't exist, restart the Space (it auto-seeds on startup)

HF Space goes to sleep

Free-tier HF Spaces sleep after ~15 minutes of inactivity.

Any request wakes them automatically (~30-60 seconds)
The MedOS frontend shows "waking up" status during this time
For always-on, upgrade to a paid HF Space plan

Database reset

If you need to reset the database:

Delete the persistent storage in Space settings
Restart the Space
The database will be recreated with a fresh admin account

GitHub Actions (CI/CD)

Automated deployment is configured via GitHub workflows:

Workflow	Trigger	Space
`deploy-medibot.yml`	Push to `main` (changes in `9-HuggingFace-Global/` or `web/`)	MediBot
`deploy-medicine-scanner.yml`	Push to `main` (changes in `11-Medicine-Scanner/`)	Medicine-Scanner
`deploy-metaengine-nearby.yml`	Push to `main` (changes in `12-MetaEngine-Nearby/`)	MetaEngine-Nearby
`ci-medos-global.yml`	Push to any branch	Runs 88 tests + build

GitHub Secrets Required

Set these in GitHub → Settings → Secrets → Actions:

Secret	Value
`HF_TOKEN`	HuggingFace write token
`HF_USERNAME`	`ruslanmv` (your HF username)
`HF_TOKEN_INFERENCE`	Token with inference permissions (for scanner)

Manual Deployment

All Spaces can also be deployed manually:

# MediBot
HF_TOKEN=hf_xxx bash 9-HuggingFace-Global/scripts/deploy-hf.sh

# Medicine Scanner
HF_TOKEN=hf_xxx bash 11-Medicine-Scanner/deploy-scanner.sh

# MetaEngine Nearby
HF_TOKEN=hf_xxx bash 12-MetaEngine-Nearby/deploy-nearby.sh

Security Notes

Default admin password MUST be changed after first login
HF_TOKEN should have minimal required permissions
Rate limiting is active on login (10/min) and register (5/min)
Account deletion is admin-only (prevents data destruction attacks)
Health data is stored in SQLite with CASCADE deletes
CSP headers restrict script/connect sources
All auth cookies are httpOnly with SameSite=Lax

Last updated: April 2026 MedOS v1.0 — Free & Open Source

MedOS Admin Guide

Table of Contents

Architecture Overview

Deployment Guide

Prerequisites

Required Tokens

Deploy MediBot (Main App)

Deploy Medicine Scanner

Deploy MetaEngine Nearby Finder

Deploy Vercel Frontend (Optional)

Admin Panel

How to Access

Admin Panel Tabs

Overview

Users

LLM

Email

Server

LLM Provider Setup

How the AI Chat Works

HuggingFace Token Requirements

Testing LLM Health

Adding a Custom OllaBridge Gateway

Email (SMTP) Configuration

Quick Setup (Gmail)

Other Providers

What Emails Are Sent

Dev Mode (No SMTP)

Medicine Scanner Setup

How the Scanner Works on Each Platform

Webcam Permissions

Token Requirements

Models Used

How It Works

Nearby Finder Setup

No Configuration Needed

How It Works

Overpass API Limits

Environment Variables Reference

MediBot Space

Medicine Scanner Space

MetaEngine Nearby Space

Vercel Frontend

Troubleshooting

"All models failed" in chat

Medicine Scanner shows "Scan failed"

Nearby search returns no results

Chat returns 504 on Vercel (ai-medical-chabot.com)

Desktop webcam not working in scanner

Email verification codes not received

Space shows "Building" or "Error"

Admin panel not visible

HF Space goes to sleep

Database reset

GitHub Actions (CI/CD)

GitHub Secrets Required

Manual Deployment

Security Notes