# Patient Avatar System - Setup and Operations Guide

## Overview

This guide covers how to start, run, and stop the Patient Avatar System that provides AI-powered video avatar interactions with patient context from FHIR.

---

## Prerequisites

### Required Software
- Python 3.11+
- Node.js (for serving HTML files, or use Python's http.server)
- Git

### Required Services
- MCP FHIR Server (running on port 8082)
- LiveAvatar API credentials
- LiveKit credentials
- Anthropic API key

---

## Initial Setup (One-Time)

### 1. Install Python Dependencies

```bash
cd /Users/tarun/Elume\ Agents/elume-mcp-fhir/livekit-agent/server

# Create virtual environment if it doesn't exist
python3 -m venv .venv

# Activate virtual environment
source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt
```

### 2. Configure Environment Variables

Edit the `.env` file:

```bash
cd /Users/tarun/Elume\ Agents/elume-mcp-fhir/livekit-agent/server
nano .env
```

Required variables:
```bash
# LiveKit Configuration
LIVEKIT_URL=wss://elume-m5h938q1.livekit.cloud
LIVEKIT_API_KEY=your-livekit-api-key
LIVEKIT_API_SECRET=your-livekit-secret

# LiveAvatar Configuration
LIVEAVATAR_API_KEY=your-liveavatar-api-key

# Anthropic API (for patient context)
ANTHROPIC_API_KEY=your-anthropic-api-key

# Voice Services
DEEPGRAM_API_KEY=your-deepgram-key
CARTESIA_API_KEY=your-cartesia-key

# MCP FHIR Server
LANGCARE_MCP_URL=http://localhost:8080/mcp
LANGCARE_API_KEY=langcare-local-dev
```

Also update the root `.env` file:

```bash
cd /Users/tarun/Elume\ Agents/elume-mcp-fhir
nano .env
```

```bash
ANTHROPIC_API_KEY=your-anthropic-api-key
ELUME_MCP_URL=http://localhost:8082/mcp
ELUME_MCP_TOKEN=test-token-123
```

### 3. Create Call Logs Directory

```bash
mkdir -p /Users/tarun/Elume\ Agents/elume-mcp-fhir/call_logs
```

---

## Starting the System

### Step 1: Start MCP FHIR Server

**Check if it's already running:**
```bash
curl http://localhost:8082/health
```

If not running, start it:
```bash
# Navigate to MCP server directory and start it
# (Adjust path based on your MCP server location)
cd /Users/tarun/Elume\ Agents/elume-mcp-fhir/mcp-server
python server.py
```

### Step 2: Start the API Server

Open a new terminal window:

```bash
cd /Users/tarun/Elume\ Agents/elume-mcp-fhir/livekit-agent/server

# Activate virtual environment
source .venv/bin/activate

# Start the API server
python api.py
```

**Expected output:**
```
INFO:     Started server process [12345]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)
```

**Verify it's running:**
```bash
curl http://localhost:8000/health
```

Expected response:
```json
{"status":"ok","avatar_id":"5dd4d830-957a-419f-9334-0dc4399ada5d"}
```

### Step 3: Start the Web Server

Open another terminal window:

```bash
cd /Users/tarun/Elume\ Agents/elume-mcp-fhir/liveavatar

# Start HTTP server on port 3000
python3 -m http.server 3000
```

**Expected output:**
```
Serving HTTP on 0.0.0.0 port 3000 (http://0.0.0.0:3000/) ...
```

### Step 4: Verify All Services

Run this quick check:

```bash
# Check API Server
curl -s http://localhost:8000/health | python3 -m json.tool

# Check Web Server
curl -s -o /dev/null -w "%{http_code}" http://localhost:3000/test-avatar.html

# Check MCP Server
curl -s http://localhost:8082/health
```

All should return successful responses.

---

## Using the System

### Option 1: Diagnostics Page (Recommended First)

Open in your browser:
```
http://localhost:3000/test-diagnostics.html
```

**What to test:**
1. ✅ API Server connection - should show green
2. ✅ LiveAvatar SDK - should show green
3. Click "Test Microphone" - speak and watch the level bar
4. Click "Test Speaker" - you should hear a beep
5. Click "Test Session Creation" - should succeed
6. Click "Test with Patient ID" - tests patient context loading

### Option 2: Full Avatar Session

**Without patient context:**
```
http://localhost:3000/test-avatar.html
```

**With patient context (using default patient ID):**
```
http://localhost:3000/test-avatar.html?patient_id=69c2792581e99ae3d62b8954
```

**Steps:**
1. Click "Start Session"
2. Grant microphone permission when prompted
3. Wait for avatar video to appear
4. Speak to the avatar
5. Avatar will respond with voice
6. Click "End Session" when done
7. Call log will be saved automatically

### Option 3: Custom Patient ID

Replace the patient ID in the URL:
```
http://localhost:3000/test-avatar.html?patient_id=YOUR_PATIENT_ID
```

---

## Monitoring and Logs

### View API Server Logs

**Real-time logs:**
```bash
tail -f /tmp/api_server.log
```

**Check for errors:**
```bash
grep ERROR /tmp/api_server.log
```

**Check patient context loading:**
```bash
grep "Fetching patient context" /tmp/api_server.log
```

### View Call Logs

```bash
# List all call logs
ls -lh /Users/tarun/Elume\ Agents/elume-mcp-fhir/call_logs/

# View a specific call log
cat /Users/tarun/Elume\ Agents/elume-mcp-fhir/call_logs/call_69c2792581e99ae3d62b8954_*.json | python3 -m json.tool
```

### Check Running Processes

```bash
# Check API server
ps aux | grep "api.py" | grep -v grep

# Check web server
ps aux | grep "http.server" | grep -v grep

# Check MCP server
ps aux | grep "8082" | grep -v grep
```

---

## Stopping the System

### Method 1: Graceful Shutdown (Recommended)

**Stop API Server:**
- Go to the terminal running `api.py`
- Press `Ctrl+C`

**Stop Web Server:**
- Go to the terminal running `http.server`
- Press `Ctrl+C`

**Stop MCP Server:**
- Go to the terminal running the MCP server
- Press `Ctrl+C`

### Method 2: Force Stop

**Stop API Server:**
```bash
ps aux | grep "api.py" | grep -v grep | awk '{print $2}' | xargs kill
```

**Stop Web Server:**
```bash
ps aux | grep "http.server.*3000" | grep -v grep | awk '{print $2}' | xargs kill
```

**Stop MCP Server:**
```bash
# Find and kill process on port 8082
lsof -ti:8082 | xargs kill
```

### Method 3: Kill All at Once

```bash
# Stop all related processes
pkill -f "api.py"
pkill -f "http.server.*3000"
lsof -ti:8082 | xargs kill
```

### Verify Everything is Stopped

```bash
# Check if ports are free
lsof -i:8000  # Should return nothing
lsof -i:3000  # Should return nothing
lsof -i:8082  # Should return nothing

# Check processes
ps aux | grep -E "(api.py|http.server|8082)" | grep -v grep
```

---

## Restarting the System

### Quick Restart (All Services)

```bash
# Stop everything
pkill -f "api.py"
pkill -f "http.server.*3000"

# Wait a moment
sleep 2

# Start API server in background
cd /Users/tarun/Elume\ Agents/elume-mcp-fhir/livekit-agent/server
source .venv/bin/activate
nohup python api.py > /tmp/api_server.log 2>&1 &

# Start web server in background
cd /Users/tarun/Elume\ Agents/elume-mcp-fhir/liveavatar
nohup python3 -m http.server 3000 > /tmp/web_server.log 2>&1 &

# Verify
sleep 2
curl http://localhost:8000/health
curl -s -o /dev/null -w "%{http_code}" http://localhost:3000/test-avatar.html
```

### Restart Only API Server

```bash
# Stop
pkill -f "api.py"
sleep 2

# Start
cd /Users/tarun/Elume\ Agents/elume-mcp-fhir/livekit-agent/server
source .venv/bin/activate
python api.py > /tmp/api_server.log 2>&1 &

# Verify
curl http://localhost:8000/health
```

---

## Troubleshooting

### API Server Won't Start

**Check if port 8000 is in use:**
```bash
lsof -i:8000
```

**Kill the process using port 8000:**
```bash
lsof -ti:8000 | xargs kill
```

**Check for missing dependencies:**
```bash
cd /Users/tarun/Elume\ Agents/elume-mcp-fhir/livekit-agent/server
source .venv/bin/activate
python -c "import httpx, fastapi, anthropic, mcp"
```

### Web Server Won't Start

**Check if port 3000 is in use:**
```bash
lsof -i:3000
```

**Use a different port:**
```bash
python3 -m http.server 8080
# Then access: http://localhost:8080/test-avatar.html
```

### Avatar Video Not Loading

**Check LiveAvatar credentials:**
```bash
cd /Users/tarun/Elume\ Agents/elume-mcp-fhir/livekit-agent/server
grep LIVEAVATAR_API_KEY .env
```

**Check browser console:**
- Open browser DevTools (F12)
- Look for errors in Console tab
- Check Network tab for failed requests

### Microphone Not Working

**Check browser permissions:**
- Chrome: Settings → Privacy and security → Site Settings → Microphone
- Safari: Preferences → Websites → Microphone
- Firefox: Preferences → Privacy & Security → Permissions → Microphone

**Test microphone separately:**
```
http://localhost:3000/test-diagnostics.html
```
Click "Test Microphone" button

### Patient Context Not Loading

**Check Anthropic API key:**
```bash
cd /Users/tarun/Elume\ Agents/elume-mcp-fhir/livekit-agent/server
grep ANTHROPIC_API_KEY .env
```

**Check MCP server:**
```bash
curl http://localhost:8082/health
```

**Check API logs:**
```bash
tail -50 /tmp/api_server.log | grep -A 10 "Fetching patient"
```

### Call Logs Not Saving

**Check directory exists:**
```bash
ls -ld /Users/tarun/Elume\ Agents/elume-mcp-fhir/call_logs
```

**Check permissions:**
```bash
touch /Users/tarun/Elume\ Agents/elume-mcp-fhir/call_logs/test.txt
rm /Users/tarun/Elume\ Agents/elume-mcp-fhir/call_logs/test.txt
```

---

## Running in Production

### Using systemd (Linux)

Create service files:

**API Server Service:**
```bash
sudo nano /etc/systemd/system/avatar-api.service
```

```ini
[Unit]
Description=Avatar API Server
After=network.target

[Service]
Type=simple
User=tarun
WorkingDirectory=/Users/tarun/Elume Agents/elume-mcp-fhir/livekit-agent/server
Environment="PATH=/Users/tarun/Elume Agents/elume-mcp-fhir/livekit-agent/server/.venv/bin"
ExecStart=/Users/tarun/Elume Agents/elume-mcp-fhir/livekit-agent/server/.venv/bin/python api.py
Restart=always

[Install]
WantedBy=multi-user.target
```

**Enable and start:**
```bash
sudo systemctl enable avatar-api
sudo systemctl start avatar-api
sudo systemctl status avatar-api
```

### Using Docker (Recommended for Production)

Create `Dockerfile`:

```dockerfile
FROM python:3.11-slim

WORKDIR /app

COPY livekit-agent/server/requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY livekit-agent/server/ .

EXPOSE 8000

CMD ["python", "api.py"]
```

**Build and run:**
```bash
docker build -t avatar-api .
docker run -d -p 8000:8000 --env-file .env avatar-api
```

---

## Quick Reference Commands

### Start Everything
```bash
# Terminal 1: API Server
cd /Users/tarun/Elume\ Agents/elume-mcp-fhir/livekit-agent/server && source .venv/bin/activate && python api.py

# Terminal 2: Web Server
cd /Users/tarun/Elume\ Agents/elume-mcp-fhir/liveavatar && python3 -m http.server 3000
```

### Stop Everything
```bash
pkill -f "api.py" && pkill -f "http.server.*3000"
```

### Check Status
```bash
curl http://localhost:8000/health && curl -s -o /dev/null -w "%{http_code}\n" http://localhost:3000/test-avatar.html
```

### View Logs
```bash
tail -f /tmp/api_server.log
```

### Test Avatar
```
http://localhost:3000/test-avatar.html?patient_id=69c2792581e99ae3d62b8954
```

---

## Support and Maintenance

### Regular Maintenance

**Weekly:**
- Check disk space for call logs
- Review error logs
- Test avatar functionality

**Monthly:**
- Update dependencies
- Rotate API keys if needed
- Archive old call logs

### Backup Important Files

```bash
# Backup configuration
cp /Users/tarun/Elume\ Agents/elume-mcp-fhir/livekit-agent/server/.env ~/.backup/

# Backup call logs
tar -czf call_logs_backup_$(date +%Y%m%d).tar.gz /Users/tarun/Elume\ Agents/elume-mcp-fhir/call_logs/
```

### Update Dependencies

```bash
cd /Users/tarun/Elume\ Agents/elume-mcp-fhir/livekit-agent/server
source .venv/bin/activate
pip install --upgrade -r requirements.txt
```

---

## Contact and Resources

- **Project Directory:** `/Users/tarun/Elume Agents/elume-mcp-fhir`
- **API Server:** `http://localhost:8000`
- **Web Interface:** `http://localhost:3000`
- **Call Logs:** `/Users/tarun/Elume Agents/elume-mcp-fhir/call_logs/`
- **Documentation:** `/Users/tarun/Elume Agents/elume-mcp-fhir/liveavatar/`

---

## Appendix: Port Reference

| Service | Port | Protocol | Purpose |
|---------|------|----------|---------|
| API Server | 8000 | HTTP | FastAPI backend |
| Web Server | 3000 | HTTP | HTML/JS frontend |
| MCP FHIR | 8082 | HTTP | FHIR data access |
| LiveKit | 443 | WSS | Video streaming |
| LiveAvatar | 443 | HTTPS | Avatar service |