# ============================================================================
# ForensicPathways Environment Configuration - COMPLETE
# ============================================================================
# Copy this file to .env and adjust the values below.
# This file covers ALL environment variables used in the codebase.

# ============================================================================
# 1. CORE APPLICATION SETTINGS (REQUIRED)
# ============================================================================

# Your application's public URL (used for redirects and links)
PUBLIC_BASE_URL=http://localhost:4321

# Application environment
NODE_ENV=development

# Secret key for session encryption (CHANGE IN PRODUCTION!)
AUTH_SECRET=your-secret-key-change-in-production-please

# ============================================================================
# 2. AI SERVICES CONFIGURATION (REQUIRED FOR AI FEATURES)
# ============================================================================

# Main AI Analysis Service (for query processing and recommendations)
# Examples: http://localhost:11434 (Ollama), https://api.mistral.ai, https://api.openai.com
AI_ANALYZER_ENDPOINT=https://api.mistral.ai/v1/chat/completions
AI_ANALYZER_API_KEY=
AI_ANALYZER_MODEL=mistral/mistral-small-latest

# Vector Embeddings Service (for semantic search)
# Leave API_KEY empty for Ollama, use actual key for cloud services
AI_EMBEDDINGS_ENABLED=true
AI_EMBEDDINGS_ENDPOINT=https://api.mistral.ai/v1/embeddings
AI_EMBEDDINGS_API_KEY=
AI_EMBEDDINGS_MODEL=mistral-embed

# ============================================================================
# 3. AI PIPELINE CONFIGURATION (CONTEXT & PERFORMANCE TUNING)
# ============================================================================

# === SIMILARITY SEARCH STAGE ===
# How many similar tools/concepts embeddings search returns as candidates
# 🔍 This is the FIRST filter - vector similarity matching
# Lower = faster, less comprehensive | Higher = slower, more comprehensive
AI_EMBEDDING_CANDIDATES=40

# Minimum similarity score threshold (0.0-1.0)
# Lower = more results but less relevant | Higher = fewer but more relevant
AI_SIMILARITY_THRESHOLD=0.3

# === AI SELECTION STAGE ===
# Maximum tools the AI can select from embedding candidates
# 🤖 This is the SECOND filter - AI intelligent selection
# Should be ≤ AI_EMBEDDING_CANDIDATES
AI_MAX_SELECTED_ITEMS=25

# Maximum tools sent to AI for detailed analysis (micro-tasks)
# 📋 This is the FINAL context size sent to AI models
# Lower = less AI context, faster responses | Higher = more context, slower
AI_MAX_TOOLS_TO_ANALYZE=20

# Maximum concepts sent to AI for background knowledge selection
# 📚 Concepts are smaller than tools, so can be higher
AI_MAX_CONCEPTS_TO_ANALYZE=10

# === CONTEXT FLOW SUMMARY ===
# 1. Vector Search: 111 total tools → AI_EMBEDDING_CANDIDATES (40) most similar
# 2. AI Selection: 40 candidates → AI_MAX_SELECTED_ITEMS (25) best matches  
# 3. AI Analysis: 25 selected → AI_MAX_TOOLS_TO_ANALYZE (20) for micro-tasks
# 4. Final Output: Recommendations based on analyzed subset

# ============================================================================
# 4. AI PERFORMANCE & RATE LIMITING
# ============================================================================

# === USER RATE LIMITS (per minute) ===
# Main queries per user per minute
AI_RATE_LIMIT_MAX_REQUESTS=4

# Total AI micro-task calls per user per minute (across all micro-tasks)
AI_MICRO_TASK_TOTAL_LIMIT=30

# === PIPELINE TIMING ===
# Delay between micro-tasks within a single query (milliseconds)
# Higher = gentler on AI service | Lower = faster responses
AI_MICRO_TASK_DELAY_MS=500

# Delay between queued requests (milliseconds)
AI_RATE_LIMIT_DELAY_MS=2000

# === EMBEDDINGS BATCH PROCESSING ===
# How many embeddings to generate per API call
AI_EMBEDDINGS_BATCH_SIZE=10

# Delay between embedding batches (milliseconds)
AI_EMBEDDINGS_BATCH_DELAY_MS=1000

# ============================================================================
# 5. AI CONTEXT & TOKEN MANAGEMENT
# ============================================================================

# Maximum context tokens to maintain across micro-tasks
# Controls how much conversation history is preserved between AI calls
AI_MAX_CONTEXT_TOKENS=3000

# Maximum tokens per individual AI prompt
# Larger = more context per call | Smaller = faster responses
AI_MAX_PROMPT_TOKENS=1200

# Timeout for individual micro-tasks (milliseconds)
AI_MICRO_TASK_TIMEOUT_MS=25000

# Maximum size of the processing queue
AI_QUEUE_MAX_SIZE=50

# ============================================================================
# 6. AUTHENTICATION & AUTHORIZATION (OPTIONAL)
# ============================================================================

# Enable authentication for different features
AUTHENTICATION_NECESSARY=false
AUTHENTICATION_NECESSARY_CONTRIBUTIONS=false
AUTHENTICATION_NECESSARY_AI=false

# OIDC Provider Settings (only needed if authentication enabled)
OIDC_ENDPOINT=https://your-oidc-provider.com
OIDC_CLIENT_ID=your-client-id
OIDC_CLIENT_SECRET=your-client-secret

# ============================================================================
# 7. FILE UPLOADS - NEXTCLOUD INTEGRATION (OPTIONAL)
# ============================================================================

# Nextcloud server for file uploads (knowledgebase contributions)
# Leave empty to disable file upload functionality
NEXTCLOUD_ENDPOINT=https://your-nextcloud.com

# Nextcloud credentials (app password recommended)
NEXTCLOUD_USERNAME=your-username
NEXTCLOUD_PASSWORD=your-app-password

# Upload directory on Nextcloud (will be created if doesn't exist)
NEXTCLOUD_UPLOAD_PATH=/kb-media

# Public URL base for sharing uploaded files
# Usually your Nextcloud base URL + share path
NEXTCLOUD_PUBLIC_URL=https://your-nextcloud.com/s/

# ============================================================================
# 8. GIT CONTRIBUTIONS - ISSUE CREATION (OPTIONAL)
# ============================================================================

# Git provider: gitea, github, or gitlab
GIT_PROVIDER=gitea

# Repository URL (used to extract owner/name)
# Example: https://git.example.com/owner/forensic-pathways.git
GIT_REPO_URL=https://git.example.com/owner/forensic-pathways.git

# API endpoint for your git provider
# Gitea: https://git.example.com/api/v1
# GitHub: https://api.github.com
# GitLab: https://gitlab.example.com/api/v4
GIT_API_ENDPOINT=https://git.example.com/api/v1

# Personal access token or API token for creating issues
# Generate this in your git provider's settings
GIT_API_TOKEN=your-git-api-token

# ============================================================================
# 9. AUDIT & DEBUGGING (OPTIONAL)
# ============================================================================

# Enable detailed audit trail of AI decision-making
FORENSIC_AUDIT_ENABLED=false

# Audit detail level: minimal, standard, verbose
FORENSIC_AUDIT_DETAIL_LEVEL=standard

# Audit retention time (hours)
FORENSIC_AUDIT_RETENTION_HOURS=24

# Maximum audit entries per request
FORENSIC_AUDIT_MAX_ENTRIES=50

# Enable detailed AI pipeline logging
AI_PIPELINE_DEBUG=false

# Enable performance metrics collection
AI_PERFORMANCE_METRICS=false

# Enable detailed micro-task debugging
AI_MICRO_TASK_DEBUG=false

# ============================================================================
# 10. QUALITY CONTROL & BIAS DETECTION (ADVANCED)
# ============================================================================

# Confidence scoring weights (must sum to 1.0)
CONFIDENCE_EMBEDDINGS_WEIGHT=0.3
CONFIDENCE_CONSENSUS_WEIGHT=0.25
CONFIDENCE_DOMAIN_MATCH_WEIGHT=0.25
CONFIDENCE_FRESHNESS_WEIGHT=0.2

# Confidence thresholds (0-100)
CONFIDENCE_MINIMUM_THRESHOLD=40
CONFIDENCE_MEDIUM_THRESHOLD=60
CONFIDENCE_HIGH_THRESHOLD=80

# Bias detection settings
BIAS_DETECTION_ENABLED=false
BIAS_POPULARITY_THRESHOLD=0.7
BIAS_DIVERSITY_MINIMUM=0.6
BIAS_CELEBRITY_TOOLS=""

# Quality control thresholds
QUALITY_MIN_RESPONSE_LENGTH=50
QUALITY_MIN_SELECTION_COUNT=1
QUALITY_MAX_PROCESSING_TIME_MS=30000

# ============================================================================
# 11. USER INTERFACE DEFAULTS (OPTIONAL)
# ============================================================================

# Default UI behavior (users can override)
UI_SHOW_AUDIT_TRAIL_DEFAULT=false
UI_SHOW_CONFIDENCE_SCORES=true
UI_SHOW_BIAS_WARNINGS=true
UI_AUDIT_TRAIL_COLLAPSIBLE=true

# ============================================================================
# 12. CACHING & PERFORMANCE (OPTIONAL)
# ============================================================================

# Cache AI responses (milliseconds)
AI_RESPONSE_CACHE_TTL_MS=3600000

# Queue cleanup interval (milliseconds)
AI_QUEUE_CLEANUP_INTERVAL_MS=300000

# ============================================================================
# PERFORMANCE TUNING PRESETS
# ============================================================================

# 🚀 FOR FASTER RESPONSES (less comprehensive):
# AI_EMBEDDING_CANDIDATES=20
# AI_MAX_SELECTED_ITEMS=15  
# AI_MAX_TOOLS_TO_ANALYZE=10
# AI_MICRO_TASK_DELAY_MS=200
# AI_MAX_CONTEXT_TOKENS=2000

# 🎯 FOR BETTER QUALITY (more comprehensive):
# AI_EMBEDDING_CANDIDATES=60
# AI_MAX_SELECTED_ITEMS=40
# AI_MAX_TOOLS_TO_ANALYZE=30
# AI_MICRO_TASK_DELAY_MS=800
# AI_MAX_CONTEXT_TOKENS=4000

# 🔋 FOR LOW-POWER SYSTEMS (minimal resources):
# AI_EMBEDDING_CANDIDATES=15
# AI_MAX_SELECTED_ITEMS=10
# AI_MAX_TOOLS_TO_ANALYZE=8
# AI_RATE_LIMIT_MAX_REQUESTS=2
# AI_MICRO_TASK_DELAY_MS=1000

# ============================================================================
# FEATURE COMBINATIONS GUIDE
# ============================================================================

# 📝 BASIC SETUP (AI only):
# - Configure AI_ANALYZER_* and AI_EMBEDDINGS_*
# - Leave authentication, file uploads, and git disabled

# 🔐 WITH AUTHENTICATION:
# - Set AUTHENTICATION_NECESSARY_* to true
# - Configure OIDC_* settings

# 📁 WITH FILE UPLOADS:
# - Configure all NEXTCLOUD_* settings
# - Test connection before enabling in UI

# 🔄 WITH CONTRIBUTIONS:
# - Configure all GIT_* settings
# - Test API token permissions for issue creation

# 🔍 WITH FULL MONITORING:
# - Enable FORENSIC_AUDIT_ENABLED=true
# - Enable AI_PIPELINE_DEBUG=true
# - Configure audit retention and detail level

# ============================================================================
# SETUP CHECKLIST
# ============================================================================
# ✅ 1. Set PUBLIC_BASE_URL to your domain
# ✅ 2. Change AUTH_SECRET to a secure random string  
# ✅ 3. Configure AI endpoints (Ollama: leave API_KEY empty)
# ✅ 4. Start with default AI values, tune based on performance
# ✅ 5. Enable authentication if needed (configure OIDC)
# ✅ 6. Configure Nextcloud if file uploads needed
# ✅ 7. Configure Git provider if contributions needed
# ✅ 8. Test with a simple query to verify pipeline works
# ✅ 9. Enable audit trail for transparency if desired
# ✅ 10. Tune performance settings based on usage patterns
# ============================================================================