.env.example

# ScallopBot Configuration

# =============================================================================
# LLM Provider API Keys (at least one required)
# =============================================================================
ANTHROPIC_API_KEY=your_anthropic_api_key_here
# OPENAI_API_KEY=your_openai_api_key_here
# GROQ_API_KEY=your_groq_api_key_here
# MOONSHOT_API_KEY=your_moonshot_api_key_here
# KIMI_THINKING_ENABLED=false  # Enable extended thinking mode for Kimi K2.5 (uses more tokens, better reasoning)
# XAI_API_KEY=your_xai_api_key_here
# OPENROUTER_API_KEY=your_openrouter_api_key_here

# =============================================================================
# Model Selection
# =============================================================================
# SINGLE SWITCH — point the WHOLE bot (chat + every background job: reranker,
# fact-extraction, cognition/proactivity, critic, evolution, eval) at one
# provider in one line. Value is a provider name (built-in or a
# CUSTOM_PROVIDER_* name), optionally "provider:model". Unknown names fail fast.
#
# MODEL=openrouter
#
# Precedence (most specific wins, so MODEL is just a convenient default):
#   chat:    PROVIDER_ORDER   > MODEL > built-in chain
#   purpose: MODEL_<PURPOSE>  > MODEL > built-in per-purpose default
#
# Runtime equivalent: the /model command is the same switch, live (no restart).
# It moves chat + every background purpose; purposes pinned with MODEL_<PURPOSE>
# stay put (the carve-out for keeping memory/tools on a separate model).
# /model auto clears the runtime switch and reverts to the values below.
#
# Fine-grained controls (optional — only needed to override MODEL for a slice):
#   PROVIDER_ORDER=openrouter,moonshot   # chat fallback chain (first available wins)
#   MODEL_RERANKER, MODEL_FACT_EXTRACTION, MODEL_COGNITION,
#   MODEL_CRITIC, MODEL_EVOLUTION, MODEL_EVAL
#     — each accepts a provider name, "provider:model",
#       "tier:fast|standard|capable", "main", or "background".
# Per-provider model id (which model that provider serves):
#   ANTHROPIC_MODEL, OPENAI_MODEL, GROQ_MODEL, OLLAMA_MODEL,
#   OPENROUTER_MODEL, MOONSHOT_MODEL, XAI_MODEL

# =============================================================================
# Telegram Bot Configuration
# =============================================================================
TELEGRAM_BOT_TOKEN=your_telegram_bot_token_here

# Comma-separated list of allowed Telegram user IDs (leave empty to allow all)
# Get your user ID by messaging @userinfobot on Telegram
# Example: TELEGRAM_ALLOWED_USERS=123456789,987654321
TELEGRAM_ALLOWED_USERS=

# Enable voice reply (bot responds with voice when receiving voice messages)
TELEGRAM_VOICE_REPLY=false

# =============================================================================
# Agent Configuration
# =============================================================================
AGENT_WORKSPACE=/path/to/your/workspace
AGENT_MAX_ITERATIONS=100
# No cumulative turn or per-model wall-clock deadline by default. Provider
# cancellation, user stop, tool-specific timeouts, iteration/loop protection,
# and token/cost budgets still apply. Set a positive value only if an operator
# explicitly wants one of these hard caps.
AGENT_FOREGROUND_CALL_TIMEOUT_MS=0
AGENT_TURN_TIMEOUT_MS=0

# Progress-aware tool-loop protection. There is no cumulative per-turn call
# ceiling: useful workflows can continue while results change. This only
# rejects an anomalously huge single model response; repeated identical
# no-progress calls warn, then stop at the thresholds below.
TOOL_MAX_CALLS_PER_RESPONSE=64
TOOL_LOOP_HISTORY_SIZE=30
TOOL_LOOP_WARNING_THRESHOLD=10
TOOL_LOOP_CRITICAL_THRESHOLD=20
TOOL_LOOP_CIRCUIT_BREAKER_THRESHOLD=30

# Smart tier routing is on by default. Optional MMR trades a little pure
# relevance for less-duplicative memory results (1.0=relevance, 0.0=diversity).
ENABLE_COMPLEXITY_ANALYSIS=true
# Per-attempt timeout for CUSTOM_PROVIDER_* OpenAI-compatible endpoints. After
# this, routing can fall back instead of hanging indefinitely (5s-10m).
MULTI_MODEL_TIMEOUT_MS=60000
MMR_ENABLED=false
MMR_LAMBDA=0.7

# =============================================================================
# Evidence-Gated Skill Learning
# =============================================================================
# Captures reusable 5+ tool workflows and failures, proposes procedural skills,
# evaluates candidates against held-out cases, runs a fail-closed safety review,
# then promotes only measured improvements. Agent-created skills are backed up
# and move active -> stale -> archived when unused; archives are recoverable.
# Production stays disabled unless EVOLUTION_ENABLED is explicitly the exact
# string "true". Opt in only after reviewing the security model. Automatic
# documentation/procedure skills are supported; machine-authored executable
# scripts remain blocked.
EVOLUTION_ENABLED=false
EVOLUTION_MIN_TOOL_CALLS=5
EVOLUTION_REUSABLE_SCORE_BAR=0.8
EVOLUTION_LOW_QUALITY_THRESHOLD=0.5
EVOLUTION_MAX_PROPOSALS=5
EVOLUTION_FITNESS_EPSILON=0.05
# The holdout fitness gate is mandatory and cannot be disabled.
# Explicit privacy consent. When false, neither task previews nor raw session
# messages are included in reflection/fitness prompts. This is more private but
# keeps new-skill/prompt proposals pending. Separate eval routing is opt-in.
EVOLUTION_INCLUDE_SESSION_CONTENT=false
EVOLUTION_ALLOW_SEPARATE_EVAL_PROVIDER=false
EVOLUTION_USE_LLM_JUDGE=true
EVOLUTION_ROLLBACK_WINDOW=5
EVOLUTION_CURATOR_ENABLED=true
EVOLUTION_CURATOR_STALE_DAYS=30
EVOLUTION_CURATOR_ARCHIVE_DAYS=90
EVOLUTION_CURATOR_BACKUP_KEEP=5

# Tool allow/deny policy (JSON). Deny rules win. Channel policy is applied after
# the global policy. Example locks Telegram to read/search/messaging tools:
# TOOL_POLICY_JSON={"deny":["bash","docker"]}
# TOOL_CHANNEL_POLICIES_JSON={"telegram":{"allow":["read_file","memory_search","web_search","send_message"]}}

# =============================================================================
# Lifecycle Event Relay (optional)
# =============================================================================
# When set, ScallopBot POSTs lifecycle events for consolidation completion,
# reflection output, and affect-state changes to this webhook.
# SCALLOPBOT_EVENT_WEBHOOK_URL=https://orchestrator.example.com/scallopbot/events
# SCALLOPBOT_EVENT_WEBHOOK_SECRET=replace-with-shared-secret
# SCALLOPBOT_EVENT_WEBHOOK_TIMEOUT_MS=5000
# SCALLOPBOT_AGENT_ID=scallopbot

# =============================================================================
# Multi-Model Mode (optional)
# =============================================================================
# By default one model serves every purpose. Toggle this on to register extra
# OpenAI-compatible endpoints under your own names — e.g. specialized or
# fine-tuned models for memory vs. the main agent loop.
#
# MULTI_MODEL_ENABLED=true
#
# Declare endpoints as CUSTOM_PROVIDER_<NAME>="<baseUrl>|<model>[|<apiKey>]"
# (<NAME> becomes the lowercase provider name; apiKey defaults to "sk-local",
# which any llama-server-style endpoint accepts):
#
# CUSTOM_PROVIDER_MY_TOOLS=http://localhost:11434/v1|my-tools-model
# CUSTOM_PROVIDER_MY_MEMORY=http://localhost:11434/v1|my-memory-model
#
# Optional exact limits for custom/local models. Keys may be provider names,
# model ids, or "provider/model". Unknown models use conservative defaults.
# MODEL_TOKEN_LIMITS={"my_memory":{"contextWindowTokens":262144,"maxOutputTokens":32768}}
#
# Optional pricing for paid custom endpoints. Omit this for local/free models.
# COST_MODEL_PRICING={"my_tools/my-tools-model":{"inputPerMillion":0.3,"outputPerMillion":1.8}}
#
# Then route with them — pin background purposes and/or put one in the chat chain:
#
# MODEL_FACT_EXTRACTION=my_memory
# MODEL_RERANKER=my_memory
# PROVIDER_ORDER=my_tools,openrouter
#
# Purposes: MODEL_RERANKER, MODEL_FACT_EXTRACTION, MODEL_COGNITION,
# MODEL_CRITIC, MODEL_EVOLUTION, MODEL_EVAL — each accepts a provider name,
# "provider:model", "tier:fast|standard|capable", "main", or "background".

# =============================================================================
# Web Search (Brave Search API)
# =============================================================================
# Get your API key from https://brave.com/search/api/
# BRAVE_SEARCH_API_KEY=your_brave_search_api_key_here

# =============================================================================
# Browser / Proxy Configuration
# =============================================================================
# Proxy server for browser automation (e.g., residential proxy)
# BROWSER_PROXY=http://127.0.0.1:8888
# Set to false to disable proxy
# BROWSER_USE_PROXY=true

# =============================================================================
# Sub-agent orchestration (optional)
# =============================================================================
# SUBAGENT_MAX_CONCURRENT_PER_SESSION=3
# SUBAGENT_MAX_CONCURRENT_GLOBAL=5
# Allow orchestrator children to delegate one additional level (0 disables nesting).
# SUBAGENT_MAX_SPAWN_DEPTH=1
# Productive work has no short wall-clock limit by default. Set a positive hard
# limit only when your deployment requires one.
# SUBAGENT_DEFAULT_TIMEOUT=0
# SUBAGENT_MAX_TIMEOUT=3600
# Stop a child after this much time with no model/tool progress.
# SUBAGENT_IDLE_TIMEOUT=300
# SUBAGENT_MAX_IDLE_TIMEOUT=1800
# SUBAGENT_MAX_INPUT_TOKENS=80000
# SUBAGENT_MAX_COST_USD=2
# SUBAGENT_MAX_SUMMARY_CHARS=12000
# SUBAGENT_CONTEXT_MODE=brief

# =============================================================================
# Logging
# =============================================================================
LOG_LEVEL=info