.env.example

# ============================================================================
# Shannon Platform Environment Configuration
# ----------------------------------------------------------------------------
# Copy this file to .env and fill in the values that apply to your deployment.
# Any variable left unset will fall back to the defaults baked into the services.
# Sections are ordered from most commonly used to advanced overrides.
# ============================================================================

# ----------------------------------------------------------------------------
# Core Runtime (required for most deployments)
# ----------------------------------------------------------------------------
ENVIRONMENT=dev                          # dev | staging | prod (affects logging & policy)
DEBUG=false
SERVICE_NAME=shannon-llm-service          # Used by the Python LLM service

# ----------------------------------------------------------------------------
# LLM Provider API Keys (set at least one)
# ----------------------------------------------------------------------------
# NOTE: OPENAI_API_KEY is REQUIRED for memory features (text embeddings).
#       Without it, semantic search and agent memory will be disabled.
#       Shannon will still run, but agents will operate in stateless mode.
OPENAI_API_KEY=

# Additional providers (optional, can be used as primary LLM)
ANTHROPIC_API_KEY=
GOOGLE_API_KEY=
GROQ_API_KEY=
XAI_API_KEY=
# Force xAI (Grok) to use Responses API (recommended). Default false.
XAI_PREFER_RESPONSES=false
DEEPSEEK_API_KEY=
QWEN_API_KEY=
MISTRAL_API_KEY=
AWS_ACCESS_KEY_ID=
AWS_SECRET_ACCESS_KEY=
AWS_REGION=us-east-1                      # Bedrock / other AWS integrations
ZAI_API_KEY=

# Local models via Ollama (OpenAI-compatible)
# API key not required for local Ollama; leave empty.
OLLAMA_API_KEY=
# Override Ollama base URL if not using defaults
OLLAMA_BASE_URL=http://localhost:11434/v1

# ----------------------------------------------------------------------------
# Web Search Providers (optional but recommended)
# ----------------------------------------------------------------------------
WEB_SEARCH_PROVIDER=serpapi                # serpapi | serper | searchapi | google | bing | exa | firecrawl
GOOGLE_SEARCH_API_KEY=
GOOGLE_SEARCH_ENGINE_ID=
SERPER_API_KEY=                          # Serper.dev API key for Google search
SERPAPI_API_KEY=                          # SerpAPI.com API key for Google search
SEARCHAPI_API_KEY=                       # SearchAPI.io API key for multi-engine search
BING_API_KEY=
EXA_API_KEY=
FIRECRAWL_API_KEY=

# Web Fetch Provider (for deep content extraction)
WEB_FETCH_PROVIDER=firecrawl            # firecrawl | exa | python
# - firecrawl(RECOMMENDED for production use): Deep website exploration and deep research
# - exa: semantic extraction, JS rendering (limited multi-page support)
# - python: free, fast, basic (no JS rendering, single page only)



# ----------------------------------------------------------------------------
# Data Stores
# ----------------------------------------------------------------------------
POSTGRES_HOST=postgres
POSTGRES_PORT=5432
POSTGRES_DB=shannon
POSTGRES_USER=shannon
POSTGRES_PASSWORD=shannon
POSTGRES_SSLMODE=disable

REDIS_HOST=redis
REDIS_PORT=6379
REDIS_PASSWORD=
REDIS_TTL_SECONDS=3600
REDIS_ADDR=redis:6379
REDIS_URL=redis://redis:6379

QDRANT_URL=http://qdrant:6333            # Use QDRANT_HOST/QDRANT_PORT instead if preferred
QDRANT_HOST=qdrant
QDRANT_PORT=6333

# Optional dedicated Redis endpoint for LLM caching
LLM_REDIS_URL=

# ----------------------------------------------------------------------------
# Service Endpoints & Configuration Files
# ----------------------------------------------------------------------------
TEMPORAL_HOST=temporal:7233
LLM_SERVICE_URL=http://llm-service:8000
AGENT_CORE_ADDR=agent-core:50051
ADMIN_SERVER=http://orchestrator:8081
ORCHESTRATOR_GRPC=orchestrator:50052
CONFIG_PATH=./config/features.yaml        # Feature flags for orchestrator & agent
MODELS_CONFIG_PATH=./config/models.yaml   # Unified model & pricing configuration
# Optional: override root Shannon config path (orchestrator)
SHANNON_CONFIG_PATH=./config/shannon.yaml
EVENTS_INGEST_URL=http://orchestrator:8081/events
EVENTS_AUTH_TOKEN=
APPROVALS_AUTH_TOKEN=

# ----------------------------------------------------------------------------
# Model Routing & Budgets
# ----------------------------------------------------------------------------
DEFAULT_MODEL_TIER=small                # small | medium | large
COMPLEXITY_MODEL_ID=gpt-5
DECOMPOSITION_MODEL_ID=claude-sonnet-4-5-20250929
MAX_TOKENS=2000
TEMPERATURE=0.7
MAX_TOKENS_PER_REQUEST=10000
MAX_COST_PER_REQUEST=0.50
LLM_DISABLE_BUDGETS=1                   # 1 = orchestrator manages budgets, 0 = enforce in LLM service
HISTORY_WINDOW_MESSAGES=50
HISTORY_WINDOW_DEBUG_MESSAGES=75
WORKFLOW_SYNTH_BYPASS_SINGLE=true      # true = skip synthesis for single result
TOKEN_BUDGET_PER_AGENT=                # Optional cap on per-agent budget (overrides calculated value)
# Note: Task and agent budgets are configured in config/shannon.yaml under session.token_budget_per_task

# ----------------------------------------------------------------------------
# Cache & Rate Limiting
# ----------------------------------------------------------------------------
ENABLE_CACHE=true  # true | false
CACHE_SIMILARITY_THRESHOLD=0.95
RATE_LIMIT_REQUESTS=100
RATE_LIMIT_WINDOW=60
PROVIDER_RATE_CONTROL_ENABLED=false       # Enable provider-specific RPM/TPM rate control
WEB_SEARCH_RATE_LIMIT=120
CALCULATOR_RATE_LIMIT=2000
PYTHON_EXECUTOR_RATE_LIMIT=60
PARTIAL_CHUNK_CHARS=512

# ----------------------------------------------------------------------------
# Tool Execution & Workflow Controls
# ----------------------------------------------------------------------------
TOOL_PARALLELISM=5                        # Concurrent tool executions (1 = sequential)
ENABLE_TOOL_SELECTION=1                 # 1 = planner auto-picks tools, 0 = manual only
PRIORITY_QUEUES=off                    # on | off
STREAMING_RING_CAPACITY=1000
COMPRESSION_TRIGGER_RATIO=0.75
COMPRESSION_TARGET_RATIO=0.375
ENFORCE_TIMEOUT_SECONDS=120
ENFORCE_MAX_TOKENS=32768
ENFORCE_RATE_RPS=20
ENFORCE_CB_ERROR_THRESHOLD=0.5
ENFORCE_CB_WINDOW_SECONDS=30
ENFORCE_CB_MIN_REQUESTS=20
ENFORCE_RATE_REDIS_URL=                 # Optional: Redis URL for distributed rate limiting
ENFORCE_RATE_REDIS_PREFIX=rate:         # Redis key prefix when using distributed limiter
ENFORCE_RATE_REDIS_TTL=60               # TTL (seconds) for distributed limiter keys

# ----------------------------------------------------------------------------
# Approvals & Security
# ----------------------------------------------------------------------------
APPROVAL_ENABLED=false                 # true enables human-in-the-loop approvals
APPROVAL_COMPLEXITY_THRESHOLD=0.5
APPROVAL_DANGEROUS_TOOLS=file_system,code_execution
APPROVAL_TIMEOUT_SECONDS=7200
JWT_SECRET=development-only-secret-change-in-production
GATEWAY_SKIP_AUTH=1

# ----------------------------------------------------------------------------
# Templates
# ----------------------------------------------------------------------------
TEMPLATE_FALLBACK_ENABLED=false         # true enables fallback to AI if a template run fails
CONTINUOUS_LEARNING_ENABLED=false       # enable learning-based strategy recommendations
TEMPLATES_PATH=./config/workflows:./config/workflows/examples

# ----------------------------------------------------------------------------
# Observability & Telemetry
# ----------------------------------------------------------------------------
OTEL_SERVICE_NAME=shannon-llm-service
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
OTEL_ENABLED=false                      # true enables OTLP tracing export
LOG_FORMAT=plain                              # rust/agent-core (plain | json)
METRICS_PORT=2112                             # Override per service if needed

# ----------------------------------------------------------------------------
# Python WASI Sandbox (Agent Core + LLM service)
# ----------------------------------------------------------------------------
# Use the path that matches your environment. Containers mount interpreters at
# /opt/wasm-interpreters; when running locally, point to ./wasm-interpreters/…
PYTHON_WASI_WASM_PATH=./wasm-interpreters/python-3.11.4.wasm
PYTHON_WASI_SESSION_TIMEOUT=3600
WASI_MEMORY_LIMIT_MB=512
WASI_TIMEOUT_SECONDS=60

# ----------------------------------------------------------------------------
# OpenAPI & MCP Integrations
# ----------------------------------------------------------------------------
OPENAPI_ALLOWED_DOMAINS=*               # '*' or comma-separated hostnames
OPENAPI_MAX_SPEC_SIZE=5242880
OPENAPI_FETCH_TIMEOUT=30
OPENAPI_RETRIES=2
# Log OpenAPI tool requests/responses (debug)
OPENAPI_LOG_REQUESTS=false

MCP_ALLOWED_DOMAINS=*                   # '*' or comma-separated hostnames
MCP_MAX_RESPONSE_BYTES=10485760
MCP_RETRIES=3
MCP_TIMEOUT_SECONDS=10
MCP_REGISTER_TOKEN=
MCP_RATE_LIMIT_DEFAULT=60
MCP_CB_FAILURES=5
MCP_CB_RECOVERY_SECONDS=60
MCP_COST_TO_TOKENS=0

# ----------------------------------------------------------------------------
# Browser Automation (Playwright Service)
# ----------------------------------------------------------------------------
PLAYWRIGHT_SERVICE_URL=http://playwright-service:8002
BROWSER_SESSION_TTL=300                 # Browser session timeout in seconds (default: 5 min)
BROWSER_MAX_SESSIONS=50                 # Max concurrent browser sessions
BROWSER_HEADLESS=true                   # Run browser in headless mode
BROWSER_VIEWPORT_WIDTH=1280             # Default viewport width
BROWSER_VIEWPORT_HEIGHT=720             # Default viewport height

# ----------------------------------------------------------------------------
# Advanced Orchestrator Controls (optional overrides)
# ----------------------------------------------------------------------------
EVENTLOG_BATCH_SIZE=100
EVENTLOG_BATCH_INTERVAL_MS=100
RATE_LIMIT_INTERVAL_MS=60000
BACKPRESSURE_THRESHOLD=
MAX_BACKPRESSURE_DELAY_MS=
CIRCUIT_FAILURE_THRESHOLD=
CIRCUIT_HALF_OPEN_REQUESTS=
CIRCUIT_RESET_TIMEOUT_MS=
WORKER_ACT=
WORKER_WF=
WORKER_ACT_CRITICAL=
WORKER_WF_CRITICAL=
WORKER_ACT_HIGH=
WORKER_WF_HIGH=
WORKER_ACT_NORMAL=
WORKER_WF_NORMAL=
WORKER_ACT_LOW=
WORKER_WF_LOW=
LLM_TIMEOUT_SECONDS=120

# ----------------------------------------------------------------------------
# Miscellaneous
# ----------------------------------------------------------------------------
SHANNON_WORKSPACE=./workspace
SEED_DATA=false                               # Seed Qdrant with sample data
AGENT_TIMEOUT_SECONDS=600                     # Max runtime per agent execution (seconds)

# ----------------------------------------------------------------------------
# File Operations Sandbox
# ----------------------------------------------------------------------------
# When enabled, file operations route through agent-core's WASI sandbox service
# instead of Python's local filesystem (provides true capability-based isolation)
SHANNON_USE_WASI_SANDBOX=1                  # Set to 1 to enable (default: disabled)
SHANNON_SESSION_WORKSPACES_DIR=/tmp/shannon-sessions  # Base directory for session workspaces
SHANNON_MAX_WORKSPACE_SIZE_MB=100           # Per-session workspace quota