.env.template

# FACT System Environment Configuration Template
# ============================================
# 
# Instructions:
# 1. Copy this file to .env
# 2. Replace all placeholder values with your actual configuration
# 3. Never commit .env with real API keys to version control
#
# For production deployments, create environment-specific files:
# - .env.local (local development)
# - .env.staging (staging environment) 
# - .env.production (production environment)

# =============================================================================
# REQUIRED API KEYS (Must be configured before system startup)
# =============================================================================

# Anthropic Claude API Key (REQUIRED)
# Format: sk-ant-api03-[alphanumeric string]
# Get from: https://console.anthropic.com/
# Validation: System will validate format on startup
ANTHROPIC_API_KEY=your_anthropic_api_key_here

# Arcade AI API Key (REQUIRED)
# Format: arc_[alphanumeric string] 
# Get from: https://arcade-ai.com/dashboard
# Validation: System will validate format on startup
ARCADE_API_KEY=your_arcade_api_key_here

# =============================================================================
# OPTIONAL API KEYS
# =============================================================================

# OpenAI API Key (Optional - for extended LLM capabilities)
# Format: sk-proj-[alphanumeric string]
# Get from: https://platform.openai.com/api-keys
# Uncomment to enable OpenAI integration
# OPENAI_API_KEY=your_openai_api_key_here

# Encryption Key (Optional - for sensitive data encryption)
# Generate with: python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
# Uncomment to enable data encryption
# ENCRYPTION_KEY=your_base64_encoded_encryption_key_here

# Cache Encryption Key (Optional - for cache encryption)
# Generate with: python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
# Uncomment to enable cache encryption
# CACHE_ENCRYPTION_KEY=your_base64_encoded_cache_encryption_key_here

# =============================================================================
# SYSTEM CONFIGURATION
# =============================================================================

# Arcade AI Service Configuration
# Default: https://api.arcade-ai.com
ARCADE_BASE_URL=https://api.arcade-ai.com

# Database Configuration
# Path: Relative to project root or absolute path
# Default: data/fact_demo.db
DATABASE_PATH=data/fact_demo.db

# Claude Model Configuration
# Options: claude-3-5-sonnet-20241022, claude-3-haiku-20240307, claude-3-opus-20240229
# Default: claude-3-5-sonnet-20241022
CLAUDE_MODEL=claude-3-5-sonnet-20241022

# System Prompt (Optional override)
# Default: "You are a deterministic finance assistant. When uncertain, request data via tools."
SYSTEM_PROMPT=You are a deterministic finance assistant. When uncertain, request data via tools.

# Request Configuration
# MAX_RETRIES: Range 1-10, Default: 3
MAX_RETRIES=3
# REQUEST_TIMEOUT: Range 5-300 seconds, Default: 30
REQUEST_TIMEOUT=30

# Logging Configuration
# Options: DEBUG, INFO, WARNING, ERROR
# Default: INFO
LOG_LEVEL=INFO

# =============================================================================
# CACHE CONFIGURATION
# =============================================================================

# Cache Settings
# CACHE_PREFIX: Alphanumeric + underscore, Length 1-50
CACHE_PREFIX=fact_v1

# CACHE_MIN_TOKENS: Range 1-1000 tokens, Default: 50
CACHE_MIN_TOKENS=50

# CACHE_MAX_SIZE: Format [number][KMGT]B, Range 1MB-10GB, Default: 100MB
CACHE_MAX_SIZE=100MB

# CACHE_TTL_SECONDS: Range 60-86400 seconds, Default: 3600 (1 hour)
CACHE_TTL_SECONDS=3600

# Performance targets in milliseconds
# CACHE_HIT_TARGET_MS: Default: 50.0
CACHE_HIT_TARGET_MS=50.0
# CACHE_MISS_TARGET_MS: Default: 200.0
CACHE_MISS_TARGET_MS=200.0

# =============================================================================
# SECURITY CONFIGURATION
# =============================================================================

# Security Modes
# DEBUG_MODE: Enable debug features (false for production)
DEBUG_MODE=false
# STRICT_MODE: Enable strict validation (true for production)
STRICT_MODE=true
# ENFORCE_HTTPS: Require HTTPS connections (true for production)
ENFORCE_HTTPS=true

# Rate Limiting
# RATE_LIMITING_ENABLED: Enable rate limiting (true for production)
RATE_LIMITING_ENABLED=true
# Rate limits per minute
RATE_LIMIT_USER_PER_MINUTE=60
RATE_LIMIT_TOOL_PER_MINUTE=30
RATE_LIMIT_AUTH_PER_MINUTE=5

# Input Validation
# VALIDATION_MAX_STRING_LENGTH: Maximum input string length
VALIDATION_MAX_STRING_LENGTH=10000
# VALIDATION_ALLOW_HTML: Allow HTML in inputs (false for security)
VALIDATION_ALLOW_HTML=false
# VALIDATION_ALLOW_JAVASCRIPT: Allow JavaScript in inputs (false for security)
VALIDATION_ALLOW_JAVASCRIPT=false

# Security Logging
# LOG_SECURITY_EVENTS: Enable security event logging
LOG_SECURITY_EVENTS=true
# SECURITY_LOG_LEVEL: Security log level (INFO, WARNING, ERROR)
SECURITY_LOG_LEVEL=INFO
# SECURITY_LOG_RETENTION_DAYS: Days to retain security logs
SECURITY_LOG_RETENTION_DAYS=90
# ENABLE_INTRUSION_DETECTION: Enable intrusion detection
ENABLE_INTRUSION_DETECTION=true

# =============================================================================
# AUTHENTICATION CONFIGURATION (Optional)
# =============================================================================

# OAuth Configuration (Uncomment if using OAuth authentication)
# AUTH_TOKEN_LIFETIME: Token lifetime in seconds
# AUTH_TOKEN_LIFETIME=3600
# OAUTH_CLIENT_ID: OAuth client ID from provider
# OAUTH_CLIENT_ID=your_oauth_client_id_here
# OAUTH_CLIENT_SECRET: OAuth client secret from provider
# OAUTH_CLIENT_SECRET=your_oauth_client_secret_here
# OAUTH_REDIRECT_URI: OAuth redirect URI
# OAUTH_REDIRECT_URI=https://your-app.com/auth/callback

# =============================================================================
# NETWORK SECURITY CONFIGURATION
# =============================================================================

# CORS Configuration (Uncomment for web deployments)
# CORS_ALLOWED_ORIGINS: Comma-separated list of allowed origins
# CORS_ALLOWED_ORIGINS=https://your-frontend.com,https://your-app.com

# Network Security
# BLOCK_PRIVATE_IPS: Block requests to private IP ranges
BLOCK_PRIVATE_IPS=true
# BLOCK_LOCALHOST: Block requests to localhost
BLOCK_LOCALHOST=true

# =============================================================================
# DEVELOPMENT CONFIGURATION
# =============================================================================

# Development flags (Set to true only in development environments)
# DEV_MODE: Enable development mode
# DEV_MODE=false
# DEV_SKIP_API_VALIDATION: Skip API key validation (development only)
# DEV_SKIP_API_VALIDATION=false
# DEV_MOCK_EXTERNAL_APIS: Use mock APIs instead of real ones
# DEV_MOCK_EXTERNAL_APIS=false

# =============================================================================
# MONITORING CONFIGURATION (Optional)
# =============================================================================

# Performance Monitoring
# ENABLE_PERFORMANCE_MONITORING: Enable performance metrics collection
# ENABLE_PERFORMANCE_MONITORING=true
# METRICS_COLLECTION_INTERVAL: Metrics collection interval in seconds
# METRICS_COLLECTION_INTERVAL=60

# Health Check Configuration
# HEALTH_CHECK_INTERVAL: Health check interval in seconds
# HEALTH_CHECK_INTERVAL=300
# HEALTH_CHECK_TIMEOUT: Health check timeout in seconds
# HEALTH_CHECK_TIMEOUT=30

# =============================================================================
# CONFIGURATION VALIDATION RULES
# =============================================================================
#
# API Key Patterns (validated on startup):
# - ANTHROPIC_API_KEY: ^sk-ant-api03-[A-Za-z0-9_-]+$
# - ARCADE_API_KEY: ^arc_[A-Za-z0-9_-]+$
# - OPENAI_API_KEY: ^sk-proj-[A-Za-z0-9_-]+$
#
# Required Parameters:
# - ANTHROPIC_API_KEY: Must be present and valid
# - ARCADE_API_KEY: Must be present and valid
#
# Parameter Ranges:
# - MAX_RETRIES: 1-10
# - REQUEST_TIMEOUT: 5-300 seconds
# - CACHE_TTL_SECONDS: 60-86400 seconds
# - CACHE_MIN_TOKENS: 1-1000
# - CACHE_MAX_SIZE: 1MB-10GB
# - VALIDATION_MAX_STRING_LENGTH: 1-100000
#
# =============================================================================
# USAGE EXAMPLES
# =============================================================================
#
# 1. Basic Setup (Minimum Required):
#    ANTHROPIC_API_KEY=sk-ant-api03-your-actual-key-here
#    ARCADE_API_KEY=arc_your-actual-key-here
#
# 2. Production Setup:
#    - All required keys
#    - STRICT_MODE=true
#    - ENFORCE_HTTPS=true
#    - LOG_LEVEL=WARNING
#    - Enable rate limiting and security features
#
# 3. Development Setup:
#    - Required keys
#    - DEBUG_MODE=true
#    - LOG_LEVEL=DEBUG
#    - Relaxed security settings
#
# =============================================================================
# TROUBLESHOOTING
# =============================================================================
#
# Common Issues:
# 1. "Missing required configuration keys"
#    - Ensure ANTHROPIC_API_KEY and ARCADE_API_KEY are set
#    - Check for typos in variable names
#
# 2. "Invalid API key format"
#    - Verify key format matches the expected pattern
#    - Check for extra whitespace or special characters
#
# 3. "Configuration validation failed"
#    - Check parameter ranges and types
#    - Verify file paths are accessible
#
# 4. "Service connectivity failed"
#    - Check network connectivity
#    - Verify API endpoints are accessible
#    - Confirm API keys are valid and active
#
# Validation Commands:
# - python -m src.core.cli validate
# - python scripts/validate_system.py
#
# For detailed documentation, see:
# - docs/configuration-requirements-specification.md
# - docs/2_installation_setup.md
#
# =============================================================================