.env.example

# Aetherra AI Operating System - Environment Configuration
# Copy this file to .env and fill in your actual values

# ===== REQUIRED AI API KEYS =====
# At least one AI provider is required for core functionality

# OpenAI API Key (GPT models)
# Get from: https://platform.openai.com/account/api-keys
OPENAI_API_KEY=your_openai_api_key_here

# Anthropic API Key (Claude models)
# Get from: https://console.anthropic.com/
ANTHROPIC_API_KEY=your_anthropic_api_key_here

# Google AI API Key (Gemini models)
# Get from: https://aistudio.google.com/app/apikey
GOOGLE_API_KEY=your_google_api_key_here

# ===== OPTIONAL INTEGRATIONS =====
# These are optional but enable additional features

# Discord Bot Token (internal Aetherra Labs bot; not required for public builds)
# Get from: https://discord.com/developers/applications
#DISCORD_TOKEN=your_discord_bot_token_here

# Telegram Bot Token (for Telegram integration)
# Get from: https://t.me/BotFather
TELEGRAM_BOT_TOKEN=your_telegram_bot_token_here

# ===== AETHERRA CONFIGURATION =====
# Core system configuration

# Environment (development, production)
AETHERRA_ENV=development

# Debug mode (true/false)
DEBUG=true

# Web interface host and port
WEB_HOST=127.0.0.1
WEB_PORT=8686

# Hub server (Flask-based hub)
HUB_HOST=127.0.0.1
HUB_PORT=3001

# HUI FastAPI server (optional)
HUI_HOST=127.0.0.1
HUI_PORT=8888

# ===== DATABASE CONFIGURATION =====
# Database settings (optional - SQLite is default)

# SQLite database path (default: ./aetherra.db)
DATABASE_URL=sqlite:///aetherra.db

# Redis connection (optional - for caching)
# REDIS_URL=redis://localhost:6379/0

# MongoDB connection (optional - for document storage)
# MONGODB_URL=mongodb://localhost:27017/aetherra

# ===== LOGGING CONFIGURATION =====
# Logging settings

# Log level (DEBUG, INFO, WARNING, ERROR, CRITICAL)
LOG_LEVEL=INFO

# Log file path (optional - logs to console if not set)
# LOG_FILE=logs/aetherra.log

# ===== SECURITY SETTINGS =====
# Security and encryption settings

# Secret key for session management (generate a random string)
SECRET_KEY=your_secret_key_here_change_this_in_production

# JWT secret (for API authentication)
JWT_SECRET=your_jwt_secret_here_change_this_in_production

# AI Developer API (Hub) security
# Profile controls production-safe defaults (production enforces stricter behavior)
# Set to 'production' on real deployments; leave as 'development' locally.
AETHERRA_PROFILE=development

# Developer AI HTTP APIs (disabled by default). Enable explicitly if needed.
# In production, token requirement defaults to on; set a token below.
AETHERRA_AI_API_ENABLED=0
AETHERRA_AI_API_STREAM=0
# In development, you may leave this 0; in production set to 1 and configure a token.
AETHERRA_AI_API_REQUIRE_TOKEN=0
# AETHERRA_AI_API_TOKEN=change_me_strong_token

# Optional inbound network allowlist for AI APIs. Comma-separated hostnames/IPs.
# In production profile, when unset, only localhost is allowed by default.
# Example: AETHERRA_NETWORK_ALLOWLIST=localhost,127.0.0.1,*.corp.example.com
# AETHERRA_NETWORK_ALLOWLIST=

# Hot Module Reload (HMR) policy controls (enforced in production)
# In production, HMR requires strict mode ON and a non-empty allowed sources list.
# Defaults below are safe local development examples.
# Strict mode required for HMR in production (1 to require)
AETHERRA_HMR_STRICT=1
# Allowed web origins that may request HMR (comma-separated). Example local dev UIs:
AETHERRA_HMR_ALLOWED_SOURCES=http://localhost:3000,http://127.0.0.1:3000
# Audit log rotation defaults (bytes per file, number of backups)
# Security policy defaults by profile
# In production profile:
# - Capabilities are deny-by-default (same as setting AETHERRA_REQUIRE_CAPABILITIES=1)
# - Network policy strict mode is enabled (same as setting AETHERRA_NET_STRICT=1)
# - A default outbound allowlist is assumed if no policy file is present:
#     localhost, 127.0.0.1, .aetherra.dev
# To extend, create ~/.aetherra/policy/net_policy.json or set env:
#   AETHERRA_NET_STRICT=1
#   (policy) { "allow_domains": ["api.example.com", ".corp.example"], "deny_domains": ["bad.tld"] }
AETHERRA_HMR_AUDIT_MAX_BYTES=5242880
AETHERRA_HMR_AUDIT_MAX_BACKUPS=3

# ===== QFAC (Quantum / Hybrid Memory Policy) =====
# Requested mode: classical | hybrid | quantum
# AETHERRA_QFAC_MODE=classical
# Policy: enforce (downgrade if gates fail) | shadow (report only) | off
# AETHERRA_QFAC_POLICY=enforce
# Backend selection (simulator|qiskit|ionq|aws_braket|azure|custom)
# AETHERRA_QFAC_BACKEND=simulator
# Mark backend validated (required for hybrid/quantum in enforce mode)
# AETHERRA_QFAC_VALIDATED=0
# Optional live coherence metrics (fallback if service metrics absent)
# AETHERRA_QFAC_COHERENCE_EMA=0.90
# Thresholds (soft gate / hard deny)
# AETHERRA_QFAC_GATE_MIN=0.85
# AETHERRA_QFAC_HARD_MIN=0.75

# ===== STORM Memory System =====
# Enable STORM memory features; when in shadow mode STORM runs alongside baseline and returns baseline outputs
# Turn off shadow mode (0) to engage hybrid recall paths directly
AETHERRA_MEMORY_STORM=1
AETHERRA_STORM_SHADOW_MODE=1

# ===== Night Cycle Scheduling =====
# Explicit timezone required in prod/staging (guard metric fails otherwise)
# AETHERRA_NIGHT_TZ=UTC
# Or pin to UTC without specifying a zone
# AETHERRA_NIGHT_UTC=1
# Optional stagger jitter seconds
# AETHERRA_NIGHT_STAGGER_MAX_SEC=120

# ===== SSE Streaming Controls =====
# Replay buffer (events & age)
# AETHERRA_SSE_REPLAY_MAX_EVENTS=50
# AETHERRA_SSE_REPLAY_MAX_AGE_S=120
# Soft timeout (graceful final if engine idle)
# AETHERRA_STREAM_SOFT_TIMEOUT_S=15
# Artificial engine wait (ms) for test pacing
# AETHERRA_ENGINE_WAIT_MS=0

# ===== Scratchpad & Evidence Privacy =====
# Default scratchpad_policy is redacted if omitted; persisted exposure requires capability gating.
# (No dedicated env; documented for operator awareness.)

# ===== Key Management =====
# Provide master key to decrypt encrypted keys.json layout
# AETHERRA_KEYS_MASTER=change_me_master_key_material
# (keys.json will include __encrypted__ flag when encryption active)

# ===== Unsafe Overrides (DO NOT USE IN PROD) =====
# AETHERRA_PROD_UNSAFE_ALLOW=1
# AETHERRA_ALLOW_UNBOUNDED=1

# ===== PERFORMANCE SETTINGS =====
# Performance and resource settings

# Maximum memory usage for AI operations (in MB)
MAX_MEMORY_MB=2048

# Number of worker processes
WORKER_PROCESSES=4

# Request timeout (in seconds)
REQUEST_TIMEOUT=300

# ===== FEATURE FLAGS =====
# Enable/disable specific features

# Enable quantum memory features
ENABLE_QUANTUM_MEMORY=true

# Enable neural interface
ENABLE_NEURAL_INTERFACE=true

# Enable self-organizing system
ENABLE_SELF_ORGANIZING=true

# Enable web interface
ENABLE_WEB_INTERFACE=true

# ===== DEVELOPMENT SETTINGS =====
# Development-only settings

# Enable hot reload for development
HOT_RELOAD=true

# Enable detailed error messages
DETAILED_ERRORS=true

# Enable profiling
ENABLE_PROFILING=false

# ===== NOTES =====
# - Never commit your actual .env file to version control
# - Keep your API keys secure and rotate them regularly
# - Use strong, unique secret keys for production
# - Set AETHERRA_ENV=production for production deployments