Endocrinologists spend 45 of every 60 appointment minutes on administrative work — reviewing charts, dictating notes, coding visits, and cross-referencing drug databases. Only 15 minutes reach the patient. For complex diabetes patients on 6+ medications with CKD staging, CGM data, and multiple comorbidities, that ratio is even worse.

Margin provides three things that no existing tool combines:

1. Pre-visit intelligence — A spoken patient brief (real-time TTS via Deepgram Aura 2) generated from the full patient record before the doctor enters the room.

2. Real-time safety — A two-layer verification system (patient-record matching + external guideline grounding via RAG) that flags allergy conflicts, dose violations, and guideline deviations before any output reaches the clinician.

3. Structured care plans — Five-section care plans generated with retrieved evidence from ADA 2025, KDIGO, and FDA DailyMed, evaluated by 5 parallel AI evaluators and scored on a 0–100 quality scale.

• Pre-visit spoken brief — Synthesizes HbA1c, CGM metrics, medications, lab trends, and pending items into a bulleted summary, read aloud via Deepgram Aura 2 (aura-2-luna-en)
• Live voice Q&A — Ask follow-up questions via Deepgram nova-2-medical STT; answers are grounded against the patient record and spoken back in real-time
• Auto-save clinical notes — Notes are saved to Redis every 4 seconds; never lose work
• Guideline-grounded care plans — RAG over ADA 2025 / KDIGO / FDA DailyMed, with 5-section structured output
• ICD-10 + CPT billing suggestions — CMS-validated codes with national average reimbursement
• Walk-in patient registration — Real-time registration with atomic MR number generation

• Layer 1 — Patient-record verification: allergy conflicts, dosage cross-checking against patient medications, CGM interpretation bounds, CKD dose contraindications
• Layer 2 — External-source verification: RAG-sourced guideline citations that must support every recommendation
• 5 clinical evaluators — Medication accuracy (35%), completeness (20%), guideline adherence (25%), billing code support (10%), plain-language readability (10%)
• Self-correction loop — If Layer 1/2 flags exist, the care plan regenerates once; both versions are logged to a correction dataset for future fine-tuning

• Sentry — Full distributed tracing across browser + backend; 5 tracked transactions with p95 latency alerts; 10% session replay (100% on errors); ad-blocker bypass via tunnel endpoint
• Arize Phoenix — OpenTelemetry instrumentation on all Claude calls via AnthropicInstrumentor(); RAG retrieval spans; quality scores logged as Arize metrics

• Redis Cloud — Sole persistence layer (30+ key patterns, 8h–30d TTL tiers)
• Redis 8.0 vectorset — Native ANN vector search (no RediSearch module) at 1024 dimensions
• Fetch.ai uAgents — 3-agent multi-agent system (Orchestrator + Knowledge + Brief agents) for Agentverse ACP integration
• APScheduler — Background refresh: CGM every 5 min, labs every 2 hours, adherence every 4 hours, device metrics every hour
• FDA DailyMed — Live drug information fallback (free, no API key required)

Doctor opens Margin → selects patient from today's schedule
        ↓
[Orchestrator Agent] reads full patient record from Redis
        ↓
[Knowledge Agent] runs 4–5 parallel RAG queries against
 ADA 2025 + KDIGO + FDA DailyMed vector index (Redis 8.0 vectorset)
        ↓
[Brief Agent] calls Claude Sonnet 4.6 → generates spoken brief
        ↓
[Safety Layer 1] verifies against patient record (allergies, doses, CGM bounds)
        ↓
Deepgram Aura 2 reads brief aloud while doctor enters room
        ↓
Doctor speaks notes → Deepgram nova-2-medical transcribes in real-time
        ↓
[Care Plan Agent] retrieves 12 guideline chunks (4 parallel queries)
  + fetches drug info from FDA DailyMed for up to 5 medications
        ↓
Claude Sonnet 4.6 generates 5-section structured care plan
        ↓
[Safety Layer 2] verifies care plan against guidelines
  → if flags exist, regenerates once, logs correction to dataset
        ↓
5 parallel evaluators score: medication accuracy, completeness,
  guideline adherence, billing support, readability → quality score 0–100
        ↓
Claude Haiku suggests ICD-10 + CPT billing codes (cached 24h)
        ↓
Visit data archived to Redis (30-day TTL) for continuity

┌─────────────────────────────────────────────────────┐
│                     BROWSER                          │
│   React 18 + TypeScript + Vite + TailwindCSS        │
│   Deepgram WebSocket (STT)  │  Sentry Replay        │
└───────────────┬─────────────────────────────────────┘
                │ HTTPS/REST + Sentry trace headers
┌───────────────▼─────────────────────────────────────┐
│              FASTAPI BACKEND (Python)                │
│   16 endpoints  │  Uvicorn ASGI  │  APScheduler     │
│   ThreadPoolExecutor (_rag_pool ×8, _verify_pool ×4)│
└──┬──────────┬──────────┬──────────┬─────────────────┘
   │          │          │          │
   ▼          ▼          ▼          ▼
Redis     Claude      Deepgram    Arize Phoenix
Cloud    Sonnet 4.6   Aura 2 TTS  (OTLP traces)
(vectorset  Haiku
 + JSON    (billing)
 + cache)
   │          │
   ▼          ▼
Voyage AI  FDA DailyMed        Fetch.ai Agentverse
embeddings  (drug info)         (3 uAgents)

• Corpus: 227 medical guideline chunks (ADA 2025 Standards of Care, KDIGO kidney guidelines, FDA DailyMed)
• Embedding model: Voyage AI voyage-3 (1024 dimensions, ~200ms per call)
• Vector store: Redis 8.0 native vectorset (VADD / VSIM / VGETATTR) — no RediSearch module required
• Query strategy: 4–5 parallel semantic queries via asyncio.gather + ThreadPoolExecutor
• Result: Top 12 deduplicated chunks ranked by cosine similarity score

• Orchestrator (port 8010, mailbox=True): Entry point for Agentverse ACP messages; parses patient name, coordinates pipeline
• Knowledge Agent (port 8011): Runs RAG via LangChain + FAISS, returns GuidelineChunk[]
• Brief Agent (port 8013): Calls Claude to generate the patient brief, returns ACP ChatMessage
• Protocol: ACP ChatMessage (uagents_core.contrib.protocols.chat)

Layer 1 — Patient Record Check (rule-based, no LLM)
├── Allergy conflict detection (medications vs. allergy list + physician exceptions)
├── Dosage cross-validation (Claude output vs. patient medication record)
├── CGM interpretation bounds (flag if output contradicts CGM data)
└── CKD dosing rules (eGFR-based contraindication detection)

Layer 2 — External Source Check (citation-based)
├── RAG-sourced guideline citations must support each recommendation
├── FDA DailyMed drug interaction cross-check
└── Flags: type (hallucination/warning/critical), severity, suggested correction

Quality Score = Σ (weight × pass_rate) × 100

Medication Accuracy:     35%  (Claude Haiku evaluator)
Guideline Adherence:     25%  (Claude Haiku evaluator)
Completeness:            20%  (Claude Haiku evaluator)
Billing Code Support:    10%  (Claude Haiku evaluator)
Plain Language:          10%  (Claude Haiku evaluator)

All 5 evaluators run in parallel via ThreadPoolExecutor. Results logged to Arize Phoenix. Score < 60 triggers a Sentry quality alert.

• Python 3.9+
• Node.js 18+
• Redis Cloud account (or local Redis Stack with vector support)
• API keys: Anthropic, Deepgram, Voyage AI, Arize, Sentry

git clone https://github.com/your-org/margin.git
cd margin

cd backend
python -m venv venv
source venv/bin/activate      # Windows: venv\Scripts\activate
pip install -r requirements.txt
cp .env.example .env
# Edit .env with your API keys

cd frontend
npm install
cp .env.example .env.local
# Edit .env.local with your API keys

cd backend
python scripts/embed_medical_sources.py

This embeds 227 medical guideline chunks into your Redis 8.0 vectorset. Takes ~2 minutes.

# AI
ANTHROPIC_API_KEY=sk-ant-...
VOYAGE_API_KEY=pa-...

# Voice
DEEPGRAM_API_KEY=...

# Observability
ARIZE_API_KEY=ak-...
ARIZE_SPACE_ID=...
PHOENIX_COLLECTOR_ENDPOINT=https://app.phoenix.arize.com/v1/traces
SENTRY_DSN=https://...@ingest.us.sentry.io/...

# Data
REDIS_URL=redis://default:PASSWORD@host:PORT

# Agents
AGENT_SEED_PHRASE=margin_orchestrator_seed_2026

# Deployment
PUBLIC_BACKEND_URL=https://YOUR-APP.onrender.com
ALLOWED_ORIGINS=https://YOUR-APP.onrender.com,http://localhost:5173

VITE_API_URL=http://localhost:8000
VITE_DEEPGRAM_API_KEY=your-deepgram-key
VITE_SENTRY_DSN=https://...@ingest.us.sentry.io/...

cd backend
source venv/bin/activate
uvicorn main:app --reload --port 8000

On startup the backend will:

• Seed mock patient data into Redis (pipeline batch)
• Create the Redis 8.0 vectorset index (margin_medical_vs)
• Register Arize Phoenix OTLP endpoint (background thread)
• Start APScheduler (CGM refresh every 5 min, labs every 2h, adherence every 4h, devices every 1h)
• Start uAgents Bureau (Orchestrator port 8010, Knowledge port 8011, Brief port 8013)

cd frontend
npm run dev

Opens at http://localhost:3000. The Vite proxy forwards /api/* to http://localhost:8000.

cd backend
python multi_agent.py

Evaluations run automatically on every POST /api/care-plan call. The response includes quality_score (0–100) and eval_results (5 evaluator verdicts).

curl -X POST http://localhost:8000/api/care-plan \
  -H "Content-Type: application/json" \
  -d '{"session_id": "your-session", "patient_id": "maria-santos"}'

cd backend
python scripts/embed_medical_sources.py

margin/
├── backend/
│   ├── main.py                    # FastAPI app, 16+ endpoints, startup logic
│   ├── multi_agent.py             # Fetch.ai uAgents (Orchestrator, Knowledge, Brief)
│   ├── scheduler.py               # APScheduler (CGM, labs, adherence, devices)
│   ├── requirements.txt
│   ├── models/
│   │   ├── patient.py             # Pydantic models: Patient, CGMData, Appointment, etc.
│   │   └── requests.py            # API request/response types
│   ├── services/
│   │   ├── claude_service.py      # Claude API (Sonnet 4.6 + Haiku)
│   │   ├── redis_service.py       # All Redis read/write operations
│   │   ├── vector_service.py      # Redis 8.0 vectorset: VADD/VSIM/VGETATTR
│   │   ├── arize_service.py       # 2-layer verification + 5 parallel evaluators
│   │   ├── cgm_simulator.py       # Physiological CGM data generator
│   │   ├── tts_service.py         # Deepgram Aura 2 TTS
│   │   ├── medical_sources_service.py  # FDA DailyMed API client
│   │   ├── langchain_rag_service.py    # LangChain + FAISS (Agentverse path)
│   │   └── external_apis_service.py    # Dexcom/Withings/FHIR stubs
│   ├── data/
│   │   ├── mock_patients.py       # 3 demo patients (Robert Chen, Maria Santos, James Wilson)
│   │   ├── mock_cgm_data.py       # CGM simulation parameters
│   │   ├── mock_lab_data.py       # Lab reference values
│   │   ├── mock_adherence_data.py # Medication adherence metrics
│   │   ├── mock_schedule.py       # Dynamic clinic schedule generator
│   │   ├── icd10_codes.json       # CMS ICD-10 code database
│   │   ├── cpt_codes.json         # CMS CPT codes + national averages
│   │   └── drug_interactions.json # Drug interaction reference
│   └── scripts/
│       └── embed_medical_sources.py   # One-time vectorset seeding (227 chunks)
└── frontend/
    ├── package.json
    ├── vite.config.ts             # Dev server + /api proxy to port 8000
    └── src/
        ├── main.tsx               # Sentry init + React entry point
        ├── App.tsx                # Root component: 5-view state machine
        ├── types/index.ts         # TypeScript interfaces
        ├── api/marginApi.ts       # Axios client: 14 typed API functions
        ├── components/
        │   ├── Dashboard.tsx      # Schedule + patient selection
        │   ├── BriefChat.tsx      # Pre-visit brief + voice Q&A
        │   ├── NoteEditor.tsx     # Clinical note editor (auto-save 4s)
        │   ├── CarePlanDocument.tsx    # 5-section care plan renderer
        │   ├── BillingCodes.tsx   # ICD-10 / CPT selector
        │   ├── EndOfDaySummary.tsx     # Quality scorecard + tomorrow preview
        │   ├── WalkInForm.tsx     # New patient registration
        │   ├── ArizeAlert.tsx     # Safety flag/warning banner
        │   ├── CGMPanel.tsx       # CGM graph + TIR/GMI/CV metrics
        │   └── LoginPage.tsx      # Demo authentication
        └── hooks/
            ├── useSession.ts      # Session UUID management
            └── useDeepgram.ts     # Deepgram STT WebSocket + TTS playback

Full interactive docs available at http://localhost:8000/docs (Swagger UI).

• Age 67, HbA1c 8.2% (worsening), CKD Stage 3a (eGFR 58), new Semaglutide start
• Demonstrates: CKD dosing alerts, new medication counseling, nephropathy monitoring plan, Penicillin allergy check

• Age 54, HbA1c 6.8% (stable), FreeStyle Libre 3, overnight CGM dips to 42 mg/dL
• Demonstrates: CGM live panel, TIR graph, allergy exception (NSAIDs → Ibuprofen physician-approved), hypoglycemia management plan

• Age 38, HbA1c 7.1% (improving), Dexcom G7 + Control-IQ, elevated TSH
• Demonstrates: Pump + CGM integration, post-meal spike management, thyroid medication, endocrinology referral

1. Select Maria Santos → brief auto-generates and plays aloud
2. Ask "What was her lowest glucose overnight?" → answer spoken back in under 2 seconds
3. Type clinical note → auto-saves every 4 seconds
4. Click "Generate Care Plan" → 5-section plan with quality score
5. Click "Suggest Billing Codes" → ICD-10 + CPT with reimbursement estimates

# Set all environment variables in Render dashboard
# Build command:
pip install -r requirements.txt
# Start command:
uvicorn main:app --host 0.0.0.0 --port $PORT

# Build command:
npm run build
# Output directory:
dist/
# Set VITE_API_URL to your Render backend URL

• Authentication: Demo uses dummy auth — no JWT, no role-based access. Production requires a full auth layer.
• CGM & Device Data: Dexcom, Abbott LibreView, and Withings integrations are production stubs — demo runs on physiologically accurate simulation.
• FHIR / EHR: Lab data comes from mock seed — Epic/Cerner FHIR integration is stubbed.
• No Docker: Docker Compose is not yet configured — requires manual dependency setup.
• Single-tenant: Session model is designed for single-doctor demo; multi-tenant requires tenant-scoped Redis key namespacing.
• HIPAA: Demo is not HIPAA-compliant — no PHI encryption at rest, no audit logging, no BAA on third-party services.

• Epic + Cerner FHIR integration (labs, medications, problem list)
• Real Dexcom Clarity + Abbott LibreView CGM API integration
• Multi-provider support (tenant-scoped Redis namespacing)
• HIPAA-compliant infrastructure (AWS HIPAA, encryption at rest, audit log)
• Docker Compose for local development
• Fine-tuning pipeline from correction dataset (margin:corrections:dataset)
• Streaming care plan generation (token-by-token UI)
• Patient portal (care plan + education delivery to patient)
• Prescription assistant (e-prescribing integration)
• HEDIS + MIPS quality measure auto-reporting