🏥 VaultCare

Secure, Autonomous Voice-Based Medical Appointment Scheduler

VaultCare is a hackathon-ready MVP that demonstrates how to build a voice-based medical appointment scheduler where Protected Health Information (PHI) never enters the LLM. The system treats all LLM reasoning as untrusted compute and proves PHI isolation through comprehensive compliance replay.

---

🎯 Security Thesis

Core Principle: Treat all LLM/planner operations as untrusted compute.

1. PHI Detection & Tokenization: All PHI is detected and tokenized BEFORE any LLM or planner call
2. Untrusted Compute: LLM and orchestration planner never see raw PHI, calendar credentials, or email payloads
3. Trusted Execution: PHI resolution happens only inside VaultService during isolated, audited operations
4. Proof of Isolation: System exposes verifiable proof that phi_exposed_to_llm = false

---

🛠️ Sponsor Tools Integration

VaultCare explicitly integrates 4 sponsor tools to demonstrate production-ready capabilities:

1. 🎙️ ElevenLabs - Voice Interface

Purpose: Natural voice interaction for medical appointment scheduling

Integration:

• STT (Speech-to-Text): Converts patient voice input to text
• TTS (Text-to-Speech): Converts assistant responses to natural speech
• Fallback: Text-only mode if API key missing

Code Location: server/elevenlabs_client.py

Usage in Demo:

# Voice input processing
voice_result = elevenlabs_client.speech_to_text(audio_data)
user_text = voice_result["text"]

# Voice output generation
audio_response = elevenlabs_client.text_to_speech(assistant_text)
# Returns base64-encoded audio for playback

API Key: Set ELEVENLABS_API_KEY in .env

---

2. 🤖 Yutori API - Agentic Orchestration

Purpose: Multi-step execution planning and autonomous agent coordination

Integration:

• Generates 10-step execution plan for appointment booking
• Tracks progress through conversation flow
• Coordinates tool calls and decision points
• Never receives raw PHI (only tokens)

Code Location: server/yutori_client.py

10-Step Plan:

1. Greet and identify intent
2. Gather patient info (tokenize PHI)
3. Retrieve clinic info from database
4. Gather scheduling constraints
5. Find available slots (deterministic engine)
6. User selects slot
7. Book appointment (trusted execution)
8. Create calendar events (trusted execution)
9. Send notifications (trusted execution)
10. Confirm completion

Usage in Demo:

# Generate execution plan
plan = yutori_client.generate_plan(
    intent="schedule_appointment",
    context={"clinic_id": "clinic_001"},
    conversation_history=messages,
    trace_id=trace_id
)

# Plan stored in audit log and visible in Retool compliance replay

API Key: Set YUTORI_API_KEY in .env (uses stub if missing)

---

3. 📊 Macroscope - Observability & Tracing

Purpose: Complete observability with decision replay and PHI isolation verification

Integration:

• OpenTelemetry-style tracing with trace_id per session
• Logs every agent step, policy decision, vault operation
• Tracks LLM calls with PHI exposure verification
• Provides timeline replay for compliance audit

Code Location: server/macroscope_client.py

Trace Types:

• TRACE_START / TRACE_END: Operation boundaries
• SPAN_*: Sub-operations (agent steps, LLM calls, vault ops)
• DECISION: Decision points with reasoning
• POLICY_CHECK: Policy enforcement events
• VAULT_*: Tokenization and resolution operations
• LLM_CALL: LLM invocations with PHI check

Usage in Demo:

# Start trace
trace_id = macroscope.start_trace(session_id, "chat_turn")

# Log decision
macroscope.log_decision(
    trace_id=trace_id,
    decision_point="slot_selection",
    decision="slot_0042",
    reasoning={"score": 95.0, "reasons": ["Available soon", "Morning slot"]}
)

# Verify PHI isolation
verification = macroscope.verify_phi_isolation(trace_id)
# Returns: {"phi_exposed_to_llm": false, "verification_status": "PASS"}

Visible in: Retool compliance replay shows complete Macroscope trace timeline

---

4. 🔧 Retool - Governance & Compliance UI

Purpose: Control plane, governance dashboard, and compliance replay interface

Integration:

• Live session monitoring
• Comprehensive compliance replay
• Token resolution (RBAC-protected)
• System health metrics
• Audit log visualization

Code Location: server/retool_endpoints.py

Endpoints:

GET /retool/sessions

Lists all sessions with metadata (turn count, appointment count, token count)

GET /retool/session/{session_id}

Detailed session view with conversation, appointments, audit trail, PHI tokens

GET /retool/compliance/{session_id} ⭐ KEY FEATURE

Complete compliance replay bundle proving phi_exposed_to_llm=false

Returns:

{
  "compliance_status": "PASS",
  "phi_exposed_to_llm": false,
  "transcript": {
    "turns": [
      {
        "turn": 1,
        "user": "My name is [NAME_TOKEN]",
        "assistant": "Thank you..."
      }
    ]
  },
  "tokens_created": {
    "tokens": ["tok_name_abc", "tok_dob_xyz"],
    "note": "Token values encrypted and never exposed to LLM"
  },
  "yutori_plans": {
    "plans": [
      {
        "plan_id": "plan_abc123",
        "steps": [
          /* 10-step execution plan */
        ],
        "current_step": 5
      }
    ]
  },
  "macroscope_traces": {
    "traces": [
      {
        "trace_id": "trace_123",
        "timeline": [
          /* Complete event timeline */
        ],
        "phi_verification": { "phi_exposed_to_llm": false, "status": "PASS" }
      }
    ]
  },
  "security_guarantees": {
    "phi_tokenized_before_llm": true,
    "phi_never_in_llm_payload": true,
    "tokens_encrypted_at_rest": true,
    "resolution_requires_rbac": true,
    "audit_log_complete": true
  }
}

POST /retool/resolve_token

RBAC-protected token resolution (requires clinic_staff or compliance_admin role)

GET /retool/stats

System-wide statistics and health metrics

Usage: Point Retool dashboard to these endpoints for real-time governance

---

🏗️ Architecture

┌─────────────────────────────────────────────────────────────┐
│                    VaultCare Architecture                    │
│                                                              │
│  ┌──────────────┐                                           │
│  │ ElevenLabs   │ ◄── Voice Input (STT)                     │
│  │ Voice API    │ ──► Voice Output (TTS)                    │
│  └──────┬───────┘                                           │
│         │                                                    │
│         ▼                                                    │
│  ┌──────────────┐                                           │
│  │ PHI Gateway  │ ◄── Detect & Tokenize BEFORE any AI      │
│  └──────┬───────┘                                           │
│         │                                                    │
│         ▼                                                    │
│  ┌──────────────┐                                           │
│  │ Yutori API   │ ◄── Generate 10-step execution plan      │
│  │ (Planning)   │     (Receives tokens, not raw PHI)       │
│  └──────┬───────┘                                           │
│         │                                                    │
│         ▼                                                    │
│  ┌──────────────┐                                           │
│  │ Orchestrator │ ◄── Execute plan steps                    │
│  │ + LLM        │     (Sanitized text only)                 │
│  └──────┬───────┘                                           │
│         │                                                    │
│         ▼                                                    │
│  ┌──────────────┐                                           │
│  │ Macroscope   │ ◄── Trace every decision                  │
│  │ (Tracing)    │     Verify PHI isolation                  │
│  └──────┬───────┘                                           │
│         │                                                    │
│         ▼                                                    │
│  ┌──────────────┐                                           │
│  │ Retool UI    │ ◄── Compliance replay                     │
│  │ (Governance) │     Proves phi_exposed=false              │
│  └──────────────┘                                           │
└─────────────────────────────────────────────────────────────┘

---

📋 Database Schema

-- Sessions
CREATE TABLE sessions (
    session_id TEXT PRIMARY KEY,
    clinic_id TEXT NOT NULL,
    status TEXT DEFAULT 'active',
    created_at TEXT NOT NULL,
    updated_at TEXT NOT NULL
);

-- PHI Vault (Encrypted)
CREATE TABLE phi_vault (
    token TEXT PRIMARY KEY,
    phi_type TEXT NOT NULL,
    encrypted_value BLOB NOT NULL,
    data_key BLOB NOT NULL,
    clinic_id TEXT NOT NULL,
    purpose TEXT NOT NULL,
    created_at TEXT NOT NULL,
    expires_at TEXT,
    accessed_count INTEGER DEFAULT 0,
    last_accessed_at TEXT
);

-- Audit Log (Macroscope traces stored here)
CREATE TABLE audit_log (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    trace_id TEXT NOT NULL,
    session_id TEXT,
    event_type TEXT NOT NULL,
    event_data TEXT NOT NULL,
    timestamp TEXT NOT NULL,
    user_role TEXT,
    clinic_id TEXT
);

-- Conversation Turns
CREATE TABLE conversation_turns (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    session_id TEXT NOT NULL,
    trace_id TEXT NOT NULL,
    turn_number INTEGER NOT NULL,
    user_text_raw TEXT NOT NULL,
    user_text_sanitized TEXT NOT NULL,
    assistant_text TEXT NOT NULL,
    tokens_created TEXT,
    llm_payload TEXT,
    timestamp TEXT NOT NULL
);

-- Doctors
CREATE TABLE doctors (
    doctor_id TEXT PRIMARY KEY,
    name TEXT NOT NULL,
    email TEXT NOT NULL,
    specialties TEXT,
    clinic_id TEXT NOT NULL
);

-- Doctor Availability
CREATE TABLE doctor_availability (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    provider_id TEXT NOT NULL,
    provider_name TEXT NOT NULL,
    start_time TEXT NOT NULL,
    end_time TEXT NOT NULL,
    duration_minutes INTEGER NOT NULL,
    status TEXT DEFAULT 'available',
    clinic_id TEXT NOT NULL,
    booked_at TEXT,
    created_at TEXT DEFAULT CURRENT_TIMESTAMP
);

-- Appointments
CREATE TABLE appointments (
    appointment_id TEXT PRIMARY KEY,
    session_id TEXT,
    provider_id TEXT NOT NULL,
    slot_id TEXT,
    patient_name_token TEXT NOT NULL,
    dob_token TEXT NOT NULL,
    contact_token TEXT,
    appointment_time TEXT NOT NULL,
    clinic_id TEXT NOT NULL,
    status TEXT DEFAULT 'confirmed',
    created_at TEXT NOT NULL
);

-- Calendar Events (Mock)
CREATE TABLE calendar_events (
    event_id TEXT PRIMARY KEY,
    owner_type TEXT NOT NULL,
    owner_id TEXT NOT NULL,
    summary TEXT NOT NULL,
    start_time TEXT NOT NULL,
    end_time TEXT NOT NULL,
    created_at TEXT NOT NULL
);

-- Emails (Mock)
CREATE TABLE emails (
    email_id TEXT PRIMARY KEY,
    to_addr TEXT NOT NULL,
    from_addr TEXT NOT NULL,
    subject TEXT NOT NULL,
    body TEXT NOT NULL,
    sent_at TEXT NOT NULL
);

---

🚀 Quick Start

Prerequisites

• Python 3.8+
• pip

1. Clone and Setup

cd server
pip install -r requirements.txt

2. Configure Environment

Create server/.env:

# Core Security
MASTER_KEY=0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
DEV_AUTH_BYPASS=true

# LLM (Groq)
GROQ_API_KEY=your-groq-api-key

# Sponsor Tools (optional, use stubs if missing)
ELEVENLABS_API_KEY=your-elevenlabs-key
YUTORI_API_KEY=your-yutori-key
# Macroscope uses local implementation (no key needed)

# Service Mode
USE_REAL_SERVICES=false

3. Seed Demo Data

cd server
python seed_sponsor_demo.py

Seeds:

• 2 clinics (Bay Area Medical Center, Downtown Health Associates)
• 6 doctors (3 per clinic)
• 456 availability slots (7 days, morning & afternoon)

4. Start Server

cd server
./run.sh

Server starts at http://localhost:8000

API docs at http://localhost:8000/docs

5. Open Frontend

# In another terminal
cd client
python -m http.server 3000

Frontend at http://localhost:3000

---

🎬 3-Minute Demo Script

Objective: Prove PHI never enters LLM while autonomously booking an appointment

Setup (30 seconds)

1. Open browser to http://localhost:3000/voice-scheduler.html
2. Open second tab to http://localhost:8000/docs (Retool endpoints)
3. Ensure server is running with all sponsor tools initialized

Demo Flow (2 minutes)

Step 1: Voice Interaction (30 seconds)

USER: "Hi, I need to schedule an appointment"
SYSTEM: [ElevenLabs TTS] "Hello! I'm here to help. May I have your name please?"

USER: "My name is John Doe, date of birth January 15, 1990"
SYSTEM: [PHI Gateway detects and tokenizes]
        [Yutori generates 10-step plan]
        [Macroscope starts trace]
        [ElevenLabs TTS] "Thank you John. What type of appointment do you need?"

USER: "I need an annual checkup"
SYSTEM: [Yutori advances to step 5: find_available_slots]
        [Availability engine finds mutual times]
        [ElevenLabs TTS] "I found several available times. How about Tuesday at 9:30 AM with Dr. Sarah Chen?"

USER: "That works for me"
SYSTEM: [Yutori executes steps 7-10: book, calendar, email, confirm]
        [Calendar adapter creates events]
        [Email adapter sends confirmations]
        [ElevenLabs TTS] "Perfect! Your appointment is confirmed for Tuesday at 9:30 AM with Dr. Chen. You'll receive a confirmation email shortly."

Step 2: Compliance Replay (60 seconds)

Navigate to http://localhost:8000/docs → /retool/compliance/{session_id}

Show:

1. Sanitized Transcript: User input shows [NAME_TOKEN] and [DOB_TOKEN], not raw PHI
2. Yutori Plan: 10-step execution plan with current progress
3. Macroscope Traces: Complete timeline showing:
   • PHI tokenization events
   • LLM calls (all with contains_phi: false)
   • Policy checks
   • Vault operations
   • Decision points
4. Security Verification: phi_exposed_to_llm: false, verification_status: PASS

Step 3: Token Resolution (30 seconds)

Use /retool/resolve_token endpoint:

POST /retool/resolve_token
{
  "token": "tok_name_abc123",
  "reason": "compliance_audit"
}

Show:

• Requires RBAC (clinic_staff or compliance_admin role)
• Returns decrypted value only to authorized users
• All resolutions logged in audit trail

Key Proof Points:

✅ ElevenLabs provides natural voice interface ✅ Yutori orchestrates multi-step autonomous booking ✅ Macroscope traces every decision with PHI isolation proof ✅ Retool shows comprehensive compliance replay ✅ PHI never entered LLM (verified in traces)

---

📡 Core API Endpoints

Chat & Scheduling

# Start conversation
POST /chat/turn
{
  "user_text": "Hi, I need an appointment",
  "clinic_id": "clinic_001"
}

# Continue conversation
POST /chat/turn
{
  "user_text": "My name is John Doe, DOB 1990-01-15",
  "session_id": "abc123"
}

Retool Governance

# List all sessions
GET /retool/sessions

# Get session details
GET /retool/session/{session_id}

# Get compliance replay (KEY ENDPOINT)
GET /retool/compliance/{session_id}

# Resolve token (RBAC required)
POST /retool/resolve_token
{
  "token": "tok_name_abc123",
  "reason": "compliance_audit"
}

# System stats
GET /retool/stats

Voice Interface

# Speech to text
POST /voice/stt
{
  "audio_base64": "...",
  "format": "mp3"
}

# Text to speech
POST /voice/tts
{
  "text": "Your appointment is confirmed"
}

---

🔒 Security Guarantees

1. PHI Tokenization Before LLM

• All PHI detected using regex patterns
• Tokenized using envelope encryption
• Tokens replace raw PHI before any LLM call
• Verified: Check user_text_sanitized in conversation_turns table

2. Untrusted Compute Isolation

• LLM and Yutori planner never receive raw PHI
• Calendar credentials never exposed to agents
• Email payloads constructed in isolated service
• Verified: Check Macroscope LLM_CALL events for contains_phi: false

3. Trusted Execution for PHI Resolution

• Token resolution only in VaultService
• Requires RBAC (clinic_staff or compliance_admin)
• All resolutions logged in audit trail
• Verified: Check audit_log for VAULT_RESOLVE events

4. Comprehensive Audit Trail

• Every operation logged with trace_id
• Macroscope provides decision replay
• Retool compliance replay proves PHI isolation
• Verified: GET /retool/compliance/{session_id}

---

🧪 Testing

Test Compliance Replay

# Start a conversation
curl -X POST http://localhost:8000/chat/turn \
  -H "Content-Type: application/json" \
  -d '{"user_text": "Hi, I need an appointment", "clinic_id": "clinic_001"}'

# Get session_id from response, then:
curl http://localhost:8000/retool/compliance/{session_id} | jq .

# Verify:
# - phi_exposed_to_llm: false
# - yutori_plans: present
# - macroscope_traces: present with PHI verification
# - security_guarantees: all true

Test Voice Interface

# Test TTS
curl -X POST http://localhost:8000/voice/tts \
  -H "Content-Type: application/json" \
  -d '{"text": "Your appointment is confirmed"}' | jq .

# Returns audio_base64 or text fallback

---

📦 Repository Structure

/server
  ├── main.py                    # FastAPI app
  ├── config.py                  # Environment configuration
  ├── db.py                      # SQLite database
  ├── auth.py                    # RBAC with Auth0 JWT
  ├── phi_gateway.py             # PHI detection & tokenization
  ├── vault_service.py           # Tokenize, resolve, execute
  ├── kms_mock.py                # Envelope encryption (AWS KMS-ready)
  ├── yutori_client.py           # Yutori API wrapper + stub
  ├── macroscope_client.py       # Macroscope tracing client
  ├── elevenlabs_client.py       # ElevenLabs voice client
  ├── orchestrator.py            # Multi-agent orchestration
  ├── availability_engine.py     # Deterministic time matching
  ├── scheduler_adapter.py       # Mock doctors & slots
  ├── calendar_adapter.py        # Mock calendar writes
  ├── email_adapter.py           # Mock email sending
  ├── policy.py                  # Prompt injection defense
  ├── retool_endpoints.py        # Retool governance API
  ├── observability.py           # Logging & tracing
  └── seed_sponsor_demo.py       # Seed demo data

/client
  ├── index.html                 # Landing page
  ├── scheduler.html             # Text-based scheduler
  ├── voice-scheduler.html       # Voice-enabled scheduler
  └── dashboard.html             # Admin dashboard

---

🎯 Sponsor Tool Visibility Checklist

ElevenLabs ✅

• Client implementation (elevenlabs_client.py)
• STT/TTS endpoints in API
• Voice-enabled frontend (voice-scheduler.html)
• Fallback to text mode if no API key
• Console message on startup

Yutori ✅

• Client implementation (yutori_client.py)
• 10-step plan generation
• Plans stored in audit log
• Visible in Retool compliance replay
• Stub fallback if no API key
• Console message on startup

Macroscope ✅

• Client implementation (macroscope_client.py)
• Trace every operation with trace_id
• PHI isolation verification
• Decision replay capability
• Visible in Retool compliance replay
• Console message on startup

Retool ✅

• Dedicated endpoints (/retool/*)
• Session listing and details
• Compliance replay with all sponsor tool data
• RBAC token resolution
• System statistics
• UI-friendly JSON responses

---

🚀 Production Deployment

AWS Architecture

┌─────────────────────────────────────────────────────────────┐
│                      AWS Production                          │
│                                                              │
│  ┌──────────────┐         ┌──────────────┐                 │
│  │ API Gateway  │────────►│ Lambda/ECS   │                 │
│  └──────────────┘         │ (FastAPI)    │                 │
│                            └──────┬───────┘                 │
│                                   │                          │
│                    ┌──────────────┼──────────────┐          │
│                    │              │              │          │
│             ┌──────▼─────┐ ┌─────▼──────┐ ┌────▼─────┐   │
│             │ RDS         │ │ KMS        │ │ Secrets  │   │
│             │ (Postgres)  │ │ (Real)     │ │ Manager  │   │
│             └─────────────┘ └────────────┘ └──────────┘   │
│                                                              │
│  ┌──────────────┐         ┌──────────────┐                 │
│  │ CloudWatch   │         │ S3           │                 │
│  │ (Logs)       │         │ (Backups)    │                 │
│  └──────────────┘         └──────────────┘                 │
└─────────────────────────────────────────────────────────────┘

Swap Points

1. Database: SQLite → RDS Postgres (change database_url in config)
2. KMS: MockKMS → AWS KMS (set use_real_services=true)
3. Auth: Dev bypass → Auth0 (set AUTH0_DOMAIN and AUTH0_AUDIENCE)
4. Calendar: Mock → Google Calendar API (set GOOGLE_SERVICE_ACCOUNT_JSON)
5. Email: Mock → SendGrid (set SENDGRID_API_KEY)

---

📝 License

MIT License - Built for hackathon demonstration

---

🙏 Acknowledgments

Sponsor Tools:

• ElevenLabs - Natural voice interface
• Yutori - Agentic orchestration and planning
• Macroscope - Observability and decision replay
• Retool - Governance and compliance UI

Built with ❤️ for secure healthcare scheduling