.env.example

# ============================================================================
# Knowledge Graph System - Environment Configuration
# ============================================================================
# Copy this file to .env and fill in your actual values
# Never commit .env to version control
# ============================================================================

# ----------------------------------------------------------------------------
# Development Mode (ADR-041)
# ----------------------------------------------------------------------------
# Controls where configuration is loaded from:
#   DEVELOPMENT_MODE=true  → Use .env configuration (development, quick iteration)
#   DEVELOPMENT_MODE=false → Use database configuration (production, runtime updates)
#
# This affects ALL runtime configuration:
#   - AI provider selection (OpenAI, Anthropic)
#   - Model selection (gpt-4o, claude-sonnet-4)
#   - Embedding configuration (local vs OpenAI)
#   - API keys (if providers need them)
#
# Production workflow (DEVELOPMENT_MODE=false):
#   1. Configure via API: POST /admin/extraction/config, POST /admin/embedding/config
#   2. Store API keys: POST /admin/keys/{provider}
#   3. Configuration loaded from database on API startup
#   4. Switch providers/models without editing .env
#
# Development workflow (DEVELOPMENT_MODE=true):
#   1. Edit .env file directly
#   2. Restart API to apply changes
#   3. Database configuration is IGNORED (logged as warning)
#   4. Faster iteration during development
#
# Default: false (production mode)
# DEVELOPMENT_MODE=false

# ----------------------------------------------------------------------------
# Web Hostname Configuration (Production deployments)
# ----------------------------------------------------------------------------
# The public hostname for web access. Used to configure:
#   - OAuth redirect URIs
#   - API URL for frontend
#   - OAuth client registration
#
# Examples:
#   WEB_HOSTNAME=localhost:3000          # Local development
#   WEB_HOSTNAME=kg.broccoli.house       # Production with DNS
#   WEB_HOSTNAME=192.168.1.82            # Production with IP
#
# Default: localhost:3000
WEB_HOSTNAME=localhost:3000

# ----------------------------------------------------------------------------
# AI Provider Configuration (Used only if DEVELOPMENT_MODE=true)
# ----------------------------------------------------------------------------
# When DEVELOPMENT_MODE=false, these settings are IGNORED and loaded from database
# ----------------------------------------------------------------------------
# AI provider to use: "openai" or "anthropic" (default: openai)
AI_PROVIDER=openai

# OpenAI Configuration
# OPENAI_API_KEY=your-openai-key-here
# Optional: Override default models
# OPENAI_EXTRACTION_MODEL=gpt-4o                    # Options: gpt-4o, gpt-4o-mini, o1-preview, o1-mini
# OPENAI_EMBEDDING_MODEL=text-embedding-3-small     # Options: text-embedding-3-small, text-embedding-3-large

# Anthropic Configuration (optional - only needed if AI_PROVIDER=anthropic)
# ANTHROPIC_API_KEY=your-anthropic-key-here
# ANTHROPIC_EXTRACTION_MODEL=claude-sonnet-4-20250514  # Options: claude-sonnet-4-20250514, claude-3-opus-20240229
# Note: Anthropic uses OpenAI for embeddings, so OPENAI_API_KEY is still required

# Mock Provider Configuration (for testing - no API keys required)
# Set AI_PROVIDER=mock to use deterministic mock responses
# Useful for: unit tests, integration tests, development without LLM API costs
# MOCK_MODE=default  # Options: default, simple (minimal concepts), complex (rich graph), empty (no concepts)

# ----------------------------------------------------------------------------
# PostgreSQL + Apache AGE Database Configuration
# ----------------------------------------------------------------------------
# PostgreSQL connection details
POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_DB=knowledge_graph
POSTGRES_USER=admin
POSTGRES_PASSWORD=password

# ----------------------------------------------------------------------------
# Garage Object Storage Configuration (ADR-057)
# ----------------------------------------------------------------------------
# Garage: S3-compatible object storage with cooperative governance
# Replaced MinIO after March 2025 Enterprise edition trap ($96k/year)
#
# Credentials are stored encrypted in database (ADR-031)
# Configure via: ./scripts/setup/initialize-platform.sh (option 7)
#
# Only endpoint configuration is stored in .env:
GARAGE_S3_ENDPOINT=http://garage:3900
GARAGE_REGION=garage
GARAGE_BUCKET=kg-storage
# RPC secret for Garage cluster coordination (generate with: openssl rand -hex 32)
GARAGE_RPC_SECRET=CHANGE_THIS_TO_A_RANDOM_SECRET_KEY

# Optional: PostgreSQL performance tuning (for docker-compose.yml)
# POSTGRES_SHARED_BUFFERS=512MB
# POSTGRES_WORK_MEM=64MB
# POSTGRES_MAINTENANCE_WORK_MEM=256MB
# POSTGRES_MAX_PARALLEL_WORKERS=4

# ----------------------------------------------------------------------------
# Token Cost Configuration (USD per 1M tokens)
# ----------------------------------------------------------------------------
# Used for cost estimation in ingestion summary
# Update these when pricing changes

# OpenAI Extraction Models (average of input/output for mixed workloads)
TOKEN_COST_GPT4O=6.25              # GPT-4o: $2.50 input + $10.00 output avg
TOKEN_COST_GPT4O_MINI=0.375        # GPT-4o-mini: $0.15 input + $0.60 output avg
TOKEN_COST_O1_PREVIEW=30.00        # o1-preview: $15 input + $60 output avg
TOKEN_COST_O1_MINI=5.50            # o1-mini: $3 input + $12 output avg

# Anthropic Extraction Models (average of input/output)
TOKEN_COST_CLAUDE_SONNET_4=9.00    # Claude Sonnet 4: $3 input + $15 output avg

# OpenAI Embedding Models
TOKEN_COST_EMBEDDING_SMALL=0.02    # text-embedding-3-small
TOKEN_COST_EMBEDDING_LARGE=0.13    # text-embedding-3-large

# ----------------------------------------------------------------------------
# API Server Configuration
# ----------------------------------------------------------------------------
# Queue type: "postgresql" (default, ADR-024) or "inmemory" (testing only)
# PostgreSQL queue provides:
# - MVCC concurrency (no write locks)
# - Connection pooling
# - JSONB native support
# - Atomic transactions with graph operations
QUEUE_TYPE=postgresql

# Legacy SQLite job queue (only for testing/development)
# Not recommended for production - use PostgreSQL instead
# JOB_DB_PATH=data/jobs.db

# ----------------------------------------------------------------------------
# Job Scheduler Configuration (ADR-014)
# ----------------------------------------------------------------------------
# How often to run cleanup tasks (in seconds, default: 3600 = 1 hour)
JOB_CLEANUP_INTERVAL=3600

# Cancel unapproved jobs after this many hours (default: 24)
JOB_APPROVAL_TIMEOUT=24

# Delete completed/cancelled jobs after this many hours (default: 48)
JOB_COMPLETED_RETENTION=48

# Delete failed jobs after this many hours (default: 168 = 7 days)
JOB_FAILED_RETENTION=168

# ----------------------------------------------------------------------------
# Concurrency & Rate Limiting Configuration
# ----------------------------------------------------------------------------
# IMPORTANT: Rate limiting is now configured per-provider in the database!
# Configure via API: PATCH /admin/extraction/config/{provider}
# Migration 018 adds: max_concurrent_requests, max_retries columns
#
# Database defaults (migration 018):
# - OpenAI: 8 concurrent requests, 8 retries
# - Anthropic: 4 concurrent requests, 8 retries
# - Ollama: 1 concurrent request, 3 retries
#
# These environment variables are FALLBACKS only (used if database config missing)

# Maximum concurrent ingestion jobs (default: 4)
# This limits how many jobs run simultaneously across ALL providers
# Lower values (2-3) reduce overall system load
# Higher values (4-6) increase throughput
MAX_CONCURRENT_JOBS=4

# Maximum concurrent threads per provider (default: 32)
# Safety limit to prevent misconfiguration and resource exhaustion
# Per-provider limits are capped at this value
# Typical values: 16-64 depending on system resources
# MAX_CONCURRENT_THREADS=32

# Per-provider concurrency fallbacks (only used if database config missing)
# These are overridden by database configuration after migration 018
# OPENAI_MAX_CONCURRENT=8
# ANTHROPIC_MAX_CONCURRENT=4
# OLLAMA_MAX_CONCURRENT=1

# Per-provider retry fallbacks (only used if database config missing)
# SDK uses exponential backoff: 1s, 2s, 4s, 8s, 16s, 32s, 64s (~127s total)
# OPENAI_MAX_RETRIES=8
# ANTHROPIC_MAX_RETRIES=8

# ----------------------------------------------------------------------------
# Authentication Configuration (ADR-054 - OAuth 2.0)
# ----------------------------------------------------------------------------
# OAuth Signing Key (REQUIRED - generate with: openssl rand -hex 32)
# This key is used to sign and validate OAuth 2.0 access tokens
# NEVER commit this to version control - it's in .gitignore
#
# Development: Run ./scripts/setup/initialize-platform.sh to generate this automatically
# Production: Use Docker/Podman secrets (see docker-compose.yml secrets section)
#   - Code checks /run/secrets/oauth_signing_key first (ADR-031)
#   - Falls back to OAUTH_SIGNING_KEY env var if secret not found
OAUTH_SIGNING_KEY=CHANGE_THIS_TO_A_RANDOM_SECRET_KEY

# OAuth Access Token Expiration (in minutes, default: 60)
# How long OAuth access tokens remain valid before requiring refresh
ACCESS_TOKEN_EXPIRE_MINUTES=60

# Note: To initialize authentication on first run, execute:
#   ./scripts/setup/initialize-platform.sh
# This will:
#   - Prompt for admin password (with strength validation)
#   - Generate OAUTH_SIGNING_KEY and save to .env
#   - Create admin user in database with bcrypt-hashed password
#   - Configure AI provider and embedding provider
#
# Authentication uses OAuth 2.0 Authorization Code flow with PKCE (ADR-054)
# All API access requires OAuth tokens - no legacy authentication methods

# ----------------------------------------------------------------------------
# Encryption Configuration (ADR-031 - Encrypted API Key Storage)
# ----------------------------------------------------------------------------
# Master Encryption Key (REQUIRED - encrypts AI provider API keys at rest)
# Uses Fernet symmetric encryption (cryptography library)
# NEVER commit this to version control - it's in .gitignore
# WARNING: If you regenerate this key, all existing encrypted API keys become unreadable
#
# Development: Auto-generated by ./operator/lib/init-secrets.sh
# Production: Use Docker/Podman secrets (see docker-compose.yml secrets section)
#   - Code checks /run/secrets/encryption_key first (ADR-031)
#   - Falls back to ENCRYPTION_KEY env var if secret not found
# ENCRYPTION_KEY=<auto-generated-fernet-key>
#
# Manual generation (if needed):
#   python3 -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"

# Internal Service Authorization Token (REQUIRED - authorizes services to access encrypted keys)
# Uses secure random token (base64-encoded)
# NEVER commit this to version control - it's in .gitignore
#
# Development: Auto-generated by ./operator/lib/init-secrets.sh
# Production: Use Docker/Podman secrets (see docker-compose.yml secrets section)
#   - Code checks /run/secrets/internal_key_service_secret first (ADR-031)
#   - Falls back to INTERNAL_KEY_SERVICE_SECRET env var if secret not found
# INTERNAL_KEY_SERVICE_SECRET=<auto-generated-token>
#
# Manual generation (if needed):
#   python3 -c "import base64, secrets; print(base64.urlsafe_b64encode(secrets.token_bytes(32)).decode())"

# ----------------------------------------------------------------------------
# AMD GPU / ROCm Configuration (Optional)
# ----------------------------------------------------------------------------
# Only set these if you need to override default ROCm behavior.
# WARNING: Empty values break ROCm - either set a valid value or don't set at all!
#
# HSA_OVERRIDE_GFX_VERSION: Override GPU architecture detection
# Use when ROCm doesn't properly detect your GPU architecture.
# Example for RX 6700 XT (gfx1030 but may need 10.3.0):
# HSA_OVERRIDE_GFX_VERSION=10.3.0
#
# ROCR_VISIBLE_DEVICES: Limit which GPUs are visible to ROCm
# Comma-separated list of GPU indices (0, 1, 2, etc.)
# Example to use only first GPU:
# ROCR_VISIBLE_DEVICES=0
#
# ROCM_VERSION: ROCm wheel version for docker-compose.gpu-amd.yml
# Only used with GPU_MODE=amd (ROCm wheels, not host ROCm)
# Options: rocm60, rocm61 (default: rocm60)
# ROCM_VERSION=rocm60

# ----------------------------------------------------------------------------
# Optional: Advanced Configuration
# ----------------------------------------------------------------------------
# Uncomment and configure as needed

# Embedding model configuration
# EMBEDDING_MODEL=text-embedding-3-small
# EMBEDDING_DIMENSIONS=1536

# LLM model configuration
# LLM_MODEL=claude-3-5-sonnet-20241022

# Logging level (DEBUG, INFO, WARNING, ERROR)
# LOG_LEVEL=INFO