### Docker Quick Start: Setup and Build

Source: https://github.com/medvoice-research/medvoice-service/blob/main/README.md

Configures environment variables by copying an example file and installs project dependencies using 'make'. This is the initial setup step for running the service with Docker.

```bash
# Configure environment
cp .env.example .env
# Edit .env with your HF_TOKEN

# Install dependencies
make install

# Build and start all services
make build
```

--------------------------------

### Environment Setup with Docker Compose

Source: https://github.com/medvoice-research/medvoice-service/blob/main/docs/DOCKER.md

Initializes the environment by copying an example configuration file and prompts for necessary Hugging Face token setup. This is crucial for accessing pre-trained models used in the application.

```bash
# Copy the example environment file
cp .env.example .env

# Edit .env file with your HF_TOKEN
nano .env
```

--------------------------------

### CPU-Only Docker Compose Setup

Source: https://github.com/medvoice-research/medvoice-service/blob/main/docs/DOCKER.md

Commands to start, view logs, and stop all services for a CPU-only Docker Compose environment. This setup is recommended for development and testing purposes.

```bash
# Start all services (API, Worker, and Temporal server)
docker-compose up -d

# View logs
docker-compose logs -f

# Stop services
docker-compose down
```

--------------------------------

### GPU-Accelerated Docker Compose Setup

Source: https://github.com/medvoice-research/medvoice-service/blob/main/docs/DOCKER.md

Commands to start, view logs, and stop services using a specific Docker Compose file for GPU acceleration. This is suitable for production workloads requiring higher performance.

```bash
# Start with GPU support
docker-compose -f docker-compose.gpu.yaml up -d

# View logs
docker-compose -f docker-compose.gpu.yaml logs -f

# Stop services
docker-compose -f docker-compose.gpu.yaml down
```

--------------------------------

### Production Deployment Commands

Source: https://github.com/medvoice-research/medvoice-service/blob/main/docs/DOCKER.md

Essential Docker Compose commands for production deployments, including GPU setup, checking service status, monitoring resource usage, and updating services.

```bash
# GPU production setup
docker-compose -f docker-compose.gpu.yaml up -d

# Check service health
docker-compose ps

# Monitor resource usage
docker stats

# Update and restart services
docker-compose pull
docker-compose up -d
```

--------------------------------

### Configuration: Environment Variables (.env)

Source: https://github.com/medvoice-research/medvoice-service/blob/main/docs/DOCKER.md

Example of essential environment variables for configuring the WhisperX-FastAPI application, including Hugging Face token and general environment settings. These variables control secrets and runtime behavior.

```bash
# Required
HF_TOKEN=your_huggingface_token_here

# Environment
ENVIRONMENT=development
LOG_LEVEL=INFO
```

--------------------------------

### Development Workflow Commands

Source: https://github.com/medvoice-research/medvoice-service/blob/main/docs/DOCKER.md

Common Docker Compose commands for a development workflow, including building images, starting services in the foreground, restarting specific services, viewing logs, and executing commands within containers.

```bash
# Build images without cache
docker-compose build --no-cache

# Start in foreground (see logs directly)
docker-compose up

# Restart specific service
docker-compose restart whisperx-api

# View specific service logs
docker-compose logs -f whisperx-worker

# Execute commands inside running container
docker-compose exec whisperx-api bash
```

--------------------------------

### Configuration: GPU Overrides

Source: https://github.com/medvoice-research/medvoice-service/blob/main/docs/DOCKER.md

Demonstrates how to override default runtime configurations for GPU usage by setting environment variables. This allows dynamic adjustment of compute resources.

```bash
DEVICE=cuda
COMPUTE_TYPE=float16
```

--------------------------------

### Configuration: Runtime Defaults (config.yaml)

Source: https://github.com/medvoice-research/medvoice-service/blob/main/docs/DOCKER.md

Illustrates default runtime settings for WhisperX, such as the model to use, language, compute device, and computation type. These can be overridden on a per-request basis.

```yaml
whisperx:
  model: base      # tiny, base, small, medium, large-v3
  language: en     # en, vi, zh, yue
  device: cpu      # cpu, cuda
  compute_type: int8  # int8, float16, float32
```

--------------------------------

### Docker Quick Start: Access Services

Source: https://github.com/medvoice-research/medvoice-service/blob/main/README.md

Provides the URLs to access the different services (API, Temporal UI, Web UI) after they have been built and started using Docker.

```bash
# Access services
# API: http://localhost:8000/docs
# Temporal UI: http://localhost:8233
# Web UI: http://localhost:8501
```

--------------------------------

### Log Monitoring Commands

Source: https://github.com/medvoice-research/medvoice-service/blob/main/docs/DOCKER.md

Commands for monitoring logs across all services or for specific services, including options for timestamps and displaying the last N lines.

```bash
# All services
docker-compose logs -f

# Specific service with timestamps
docker-compose logs -f -t whisperx-api

# Last N lines
docker-compose logs --tail=100 whisperx-worker
```

--------------------------------

### Install System Dependencies (macOS)

Source: https://github.com/medvoice-research/medvoice-service/blob/main/README.md

Installs necessary system packages for audio processing and development on macOS using Homebrew.

```bash
brew install ffmpeg pkg-config make
```

--------------------------------

### Maintenance Commands

Source: https://github.com/medvoice-research/medvoice-service/blob/main/docs/DOCKER.md

Utility commands for maintaining the Docker environment, such as cleaning up unused resources, backing up model caches, and checking Docker disk usage.

```bash
# Clean up stopped containers and unused images
docker-compose down --rmi local
docker system prune -f

# Backup model cache (optional)
docker run --rm -v whisperx-huggingface-cache:/data -v $(pwd):/backup alpine tar czf /backup/model-cache-backup.tar.gz -C /data .

# View volume usage
docker system df -v
```

--------------------------------

### Configuration: Scaling Workers

Source: https://github.com/medvoice-research/medvoice-service/blob/main/docs/DOCKER.md

Shows how to configure the number of replicas for the WhisperX worker service within the Docker Compose file. Increasing replicas allows for handling more concurrent requests.

```yaml
# In docker-compose.yaml under whisperx-worker service
deploy:
  replicas: 3  # Increase this number
```

--------------------------------

### Local Development: Start Full Application

Source: https://github.com/medvoice-research/medvoice-service/blob/main/README.md

Starts the entire MedVoice application locally, including the FastAPI backend, Temporal workflows, and Streamlit web interface, without using Docker.

```bash
# Configure environment
cp .env.example .env

# Install dependencies
make install

# Start full application (FastAPI + Temporal + Streamlit)
make dev
```

--------------------------------

### Install Python Package Manager (uv)

Source: https://github.com/medvoice-research/medvoice-service/blob/main/README.md

Installs the 'uv' Python package manager, a fast alternative to pip, using a curl script.

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

--------------------------------

### Development Commands: Non-Docker Services

Source: https://github.com/medvoice-research/medvoice-service/blob/main/README.md

Commands to start individual services or the full application without using Docker, useful for local development.

```bash
# Start services without Docker
make dev              # Full application (API + Temporal + Streamlit)
make server           # FastAPI only
make worker           # Temporal + worker
make web              # Web UI only
```

--------------------------------

### Medical RAG Setup: LM Studio Configuration

Source: https://github.com/medvoice-research/medvoice-service/blob/main/README.md

Steps to set up the Medical RAG feature using LM Studio, including downloading models and configuring the environment file.

```bash
# Install LM Studio (https://lmstudio.ai/)

# Download models
# - MedAlpaca-7B or Meditron-7B (generation)
# - nomic-embed-text-v1.5 (embeddings)

# Configure .env
cp .env.example .env

# Start LM Studio server
# Local Server tab → Select model → Start Server
```

--------------------------------

### Development Commands: Docker Services

Source: https://github.com/medvoice-research/medvoice-service/blob/main/README.md

Common Docker commands for managing MedVoice services, including building, starting, and stopping all services.

```bash
# Start services with Docker
make build            # Build all services
make up               # Start all services
make down             # Stop all services
```

--------------------------------

### Real-time Database Logging Examples

Source: https://github.com/medvoice-research/medvoice-service/blob/main/docs/adr/007-patient-database-architecture.md

Illustrates sample log messages showing database insertions and queries, including patient name, hash, workflow ID, and file path for tracking purposes.

```text
DB INSERT: John Michael Smith (02935fa8) -> whisperx-wf-pt_02935fa8-...
   File: /tmp/uploads/audio_02935fa8_...
   Total mappings in DB: 1

DB QUERY: patient_hash=02935fa8 -> Found 1 workflows
```

--------------------------------

### Readiness Check with Dependencies

Source: https://context7.com/medvoice-research/medvoice-service/llms.txt

Verifies if all dependencies, including the Temporal server, are connected and ready for requests.

```APIDOC
## GET /health/ready

### Description
Verifies if all dependencies, including the Temporal server, are connected and ready.

### Method
GET

### Endpoint
/health/ready

### Parameters
#### Query Parameters
None

#### Request Body
None

### Response
#### Success Response (200)
- **status** (string) - Indicates the readiness status, e.g., "ok" or "error".
- **temporal** (string) - The connection status to the Temporal server, e.g., "connected" or "disconnected".
- **message** (string) - A message describing the readiness status or any issues.

#### Response Example (Healthy)
```json
{
  "status": "ok",
  "temporal": "connected",
  "message": "Application is ready to accept requests"
}
```

#### Response Example (Unhealthy)
```json
{
  "status": "error",
  "temporal": "disconnected",
  "message": "Application is not ready: Connection refused"
}
```
```

--------------------------------

### GET /medical/search-similar

Source: https://context7.com/medvoice-research/medvoice-service/llms.txt

Performs a vector similarity search to find consultations with similar content.

```APIDOC
## GET /medical/search-similar

### Description
Find consultations with similar content using vector similarity search across the medical document store.

### Method
GET

### Endpoint
`/medical/search-similar`

### Parameters
#### Query Parameters
- **query_text** (string) - Required - The text to search for similar consultations.
- **patient_id_encrypted** (string) - Required - The encrypted patient ID.
- **limit** (integer) - Optional - The maximum number of results to return (default is 10).

### Request Example
```bash
curl -X GET "http://localhost:8000/medical/search-similar" \
  -G \
  --data-urlencode "query_text=patient with chronic lower back pain and numbness in legs" \
  --data-urlencode "patient_id_encrypted=f8a9b2c1" \
  --data-urlencode "limit=5"
```

### Response
#### Success Response (200)
- **query** (string) - The original search query text.
- **results** (array) - An array of similar consultations found.
  - **consultation_id** (string) - The ID of the consultation.
  - **patient_id_encrypted** (string) - The encrypted patient ID.
  - **encounter_date** (string) - The encounter date.
  - **similarity_score** (number) - The similarity score.
  - **transcript_preview** (string) - A preview of the consultation transcript.
- **result_count** (integer) - The total number of results found.
- **searched_at** (string) - The timestamp when the search was performed.

#### Response Example
```json
{
  "query": "patient with chronic lower back pain and numbness in legs",
  "results": [
    {
      "consultation_id": "cons_xyz789",
      "patient_id_encrypted": "f8a9b2c1",
      "encounter_date": "2024-01-10",
      "similarity_score": 0.92,
      "transcript_preview": "Patient reports persistent lower back pain..."
    }
  ],
  "result_count": 1,
  "searched_at": "2024-01-15T14:30:22+07:00"
}
```
```

--------------------------------

### Readiness Check with Dependencies

Source: https://context7.com/medvoice-research/medvoice-service/llms.txt

Verifies if the application and its critical dependencies, such as the Temporal server, are connected and ready to accept requests. It can return healthy or unhealthy status.

```bash
curl "http://localhost:8000/health/ready"

# Response (healthy)
{
  "status": "ok",
  "temporal": "connected",
  "message": "Application is ready to accept requests"
}

# Response (unhealthy)
{
  "status": "error",
  "temporal": "disconnected",
  "message": "Application is not ready: Connection refused"
}
```

--------------------------------

### GET /medical/patient/{patient_id_encrypted}/consultations

Source: https://context7.com/medvoice-research/medvoice-service/llms.txt

Retrieves a patient's consultation history with pagination support.

```APIDOC
## GET /medical/patient/{patient_id_encrypted}/consultations

### Description
Retrieve all consultations for a specific patient with pagination support.

### Method
GET

### Endpoint
`/medical/patient/{patient_id_encrypted}/consultations`

### Parameters
#### Path Parameters
- **patient_id_encrypted** (string) - Required - The encrypted ID of the patient.

#### Query Parameters
- **limit** (integer) - Optional - The maximum number of consultations to return per page (default is 10).
- **offset** (integer) - Optional - The number of consultations to skip (for pagination, default is 0).

### Request Example
```bash
curl -X GET "http://localhost:8000/medical/patient/f8a9b2c1/consultations?limit=10&offset=0"
```

### Response
#### Success Response (200)
- **patient_id_encrypted** (string) - The encrypted patient ID.
- **consultations** (array) - A list of the patient's consultations.
  - **consultation_id** (string) - The ID of the consultation.
  - **encounter_date** (string) - The date of the encounter.
  - **provider_id** (string) - The ID of the provider.
- **count** (integer) - The total number of consultations returned in this response.
- **limit** (integer) - The limit applied for this request.
- **offset** (integer) - The offset applied for this request.

#### Response Example
```json
{
  "patient_id_encrypted": "f8a9b2c1",
  "consultations": [
    {
      "consultation_id": "cons_abc123def456",
      "encounter_date": "2024-01-15",
      "provider_id": "DR001"
    },
    {
      "consultation_id": "cons_xyz789",
      "encounter_date": "2024-01-10",
      "provider_id": "DR002"
    }
  ],
  "count": 2,
  "limit": 10,
  "offset": 0
}
```
```

--------------------------------

### Get Model Cache Status

Source: https://context7.com/medvoice-research/medvoice-service/llms.txt

Retrieves statistics and memory usage for all cached models, including transcription, alignment, and diarization.

```APIDOC
## GET /cache/status

### Description
Retrieve statistics and memory usage for all cached models including transcription, alignment, and diarization.

### Method
GET

### Endpoint
/cache/status

### Parameters
#### Query Parameters
None

#### Request Body
None

### Response
#### Success Response (200)
- **transcription_cache** (object) - Statistics for the transcription cache.
  - **hits** (integer) - Number of cache hits.
  - **misses** (integer) - Number of cache misses.
  - **memory_mb** (integer) - Memory usage in MB.
- **alignment_cache** (object) - Statistics for the alignment cache.
  - **hits** (integer) - Number of cache hits.
  - **misses** (integer) - Number of cache misses.
  - **memory_mb** (integer) - Memory usage in MB.
- **diarization_cache** (object) - Statistics for the diarization cache.
  - **hits** (integer) - Number of cache hits.
  - **misses** (integer) - Number of cache misses.
  - **memory_mb** (integer) - Memory usage in MB.

#### Response Example
```json
{
  "transcription_cache": {"hits": 45, "misses": 12, "memory_mb": 2048},
  "alignment_cache": {"hits": 38, "misses": 10, "memory_mb": 512},
  "diarization_cache": {"hits": 30, "misses": 8, "memory_mb": 1024}
}
```
```

--------------------------------

### GET /temporal/workflow/{workflow_id}

Source: https://context7.com/medvoice-research/medvoice-service/llms.txt

Query the status of an active or completed speech-to-text workflow using the workflow ID returned from transcription requests.

```APIDOC
## GET /temporal/workflow/{workflow_id}

### Description
Query the status of an active or completed speech-to-text workflow using the workflow ID returned from transcription requests.

### Method
GET

### Endpoint
/temporal/workflow/{workflow_id}

### Parameters
#### Path Parameters
- **workflow_id** (string) - Required - The ID of the workflow to check.

### Request Example
```bash
# Get workflow status
curl "http://localhost:8000/temporal/workflow/whisperx-wf-pt_a1b2c3d4-20240115_143022123456-ef12"
```

### Response
#### Success Response (200)
- **workflow_id** (string) - The ID of the workflow.
- **status** (string) - The current status of the workflow (e.g., 'RUNNING', 'COMPLETED', 'FAILED').

#### Response Example
```json
# Response for running workflow
{
  "workflow_id": "whisperx-wf-pt_a1b2c3d4-20240115_143022123456-ef12",
  "status": "RUNNING"
}

# Response for completed workflow
{
  "workflow_id": "whisperx-wf-pt_a1b2c3d4-20240115_143022123456-ef12",
  "status": "COMPLETED"
}
```
```

--------------------------------

### Run Pytest with Markers

Source: https://github.com/medvoice-research/medvoice-service/blob/main/tests/README.md

Demonstrates how to execute specific sets of tests using pytest markers. This allows for targeted test execution based on predefined categories like 'integration' or excluding 'slow' tests.

```bash
uv run python -m pytest -m integration
uv run python -m pytest -m "not slow"
```

--------------------------------

### Neo4j Docker Deployment Configuration

Source: https://github.com/medvoice-research/medvoice-service/blob/main/docs/adr/008-knowledge-graph-integration.md

Configuration for deploying Neo4j in a Docker container, including memory settings, authentication, resource limits, volume mounts, and port mappings. This setup is recommended for the MedVoice service.

```yaml
services:
  neo4j:
    image: neo4j:latest
    container_name: medical-kg-neo4j
    environment:
      # Heap memory (same initial and max to prevent fragmentation)
      - NEO4J_server_memory_heap_initialSize=4G
      - NEO4J_server_memory_heap_maxSize=4G
      
      # Page cache (adjust based on data size)
      - NEO4J_server_memory_pagecache_size=8G
      
      # Transaction memory limit
      - NEO4J_dbms_memory_transaction_total_max=2G
      
      # Authentication (change in production)
      - NEO4J_AUTH=neo4j/your-secure-password
    
    # Docker resource limits
    deploy:
      resources:
        limits:
          cpus: '8'
          memory: 16G
        reservations:
          cpus: '4'
          memory: 12G
    
    volumes:
      - ./neo4j-data:/data
      - ./neo4j-logs:/logs
    
    ports:
      - "7474:7474"  # HTTP
      - "7687:7687"  # Bolt protocol

```

--------------------------------

### Calculate Patient Confidence (Two-Speaker Test Case)

Source: https://github.com/medvoice-research/medvoice-service/blob/main/docs/adr/006-speaker-identification-heuristic.md

Example calculation for Patient confidence in a two-speaker scenario. This formula applies a multiplier to the doctor's confidence score.

```pseudocode
Patient (B) confidence = 0.95 × 0.9
```