.env.example

# ══════════════════════════════════════════════════════════════════════════════
# MetaOps — Complete Configuration Reference
# ══════════════════════════════════════════════════════════════════════════════
#
# Copy this file to .env and fill in the values you need.
#
# One model drives everything: set METAOPS_PROVIDER/MODEL/API_KEY/BASE_URL
# below. PROVIDER/API_KEY/BASE_URL come from whichever section further down
# matches where you got your key (OpenRouter, KiloCode, OpenAI, Anthropic,
# Gemini, a local Ollama server, ...) — MODEL is that provider's exact model
# id/slug. All 4 values are always explicit; nothing is inferred.
# ══════════════════════════════════════════════════════════════════════════════


# ══════════════════════════════════════════════════════════════════════════════
# TELEGRAM GATEWAY
# ══════════════════════════════════════════════════════════════════════════════

# Required: Bot token from @BotFather
TELEGRAM_BOT_TOKEN=

# Comma-separated numeric Telegram user IDs allowed to use the bot.
# Leave empty = anyone who knows the bot username can message it — and in that
# case the default role is force-downgraded from admin to user (so an open bot
# is not remote code execution). Set this to keep admin sessions.
# Get your ID from @userinfobot
METAOPS_TELEGRAM_ALLOWED_USERS=

# Telegram bot behavior
# TELEGRAM_MODE=polling                          # polling or webhook (default: polling)
# TELEGRAM_REPLY_TO_MESSAGE=false                # reply to specific messages
# TELEGRAM_REACT_EMOJI=👀                        # reaction emoji when processing
# TELEGRAM_GROUP_POLICY=mention                  # mention = respond only when @mentioned
# TELEGRAM_DEFAULT_CHAT_ID=                      # home chat for cron/system deliveries (target "telegram")

# Webhook mode (only if TELEGRAM_MODE=webhook)
# TELEGRAM_WEBHOOK_URL=
# TELEGRAM_WEBHOOK_LISTEN_HOST=127.0.0.1
# TELEGRAM_WEBHOOK_LISTEN_PORT=8081
# TELEGRAM_WEBHOOK_PATH=/telegram
# TELEGRAM_WEBHOOK_SECRET_TOKEN=
# TELEGRAM_WEBHOOK_MAX_CONNECTIONS=4


# ══════════════════════════════════════════════════════════════════════════════
# LLM PRINCIPAL — un seul modèle pour tout (coordinator + tous les sous-agents)
# ══════════════════════════════════════════════════════════════════════════════
#
# 4 valeurs explicites, toujours. PROVIDER n'est qu'un label (logs/status) —
# il n'est JAMAIS utilisé pour deviner API_KEY/BASE_URL. Cela élimine les
# erreurs de routage (un modèle envoyé au mauvais endpoint parce que son nom
# "ressemblait" à celui d'un autre provider).
#
# Tous les rôles (coordinator, research, coder, thinker, etc.) utilisent ce
# modèle par défaut. Pour changer temporairement le modèle d'un agent
# spécifique sans toucher à .env, utilise l'outil set_model() en session
# (voir get_configured_models() pour la liste des agents disponibles).
#
# API_KEY/BASE_URL : valeur littérale, pas de ${VAR}. python-dotenv ne
# résout l'interpolation ${VAR} que si la variable référencée est déjà
# définie PLUS HAUT dans le fichier — fragile en cas de réordonnancement.
# Copie-colle directement la clé du provider concerné (section API PROVIDERS
# plus bas), même si ça duplique la valeur.

METAOPS_PROVIDER=
METAOPS_MODEL=
METAOPS_API_KEY=
METAOPS_BASE_URL=
METAOPS_MAX_TOKENS=16000


# ══════════════════════════════════════════════════════════════════════════════
# FALLBACKS — essayés dans l'ordre si le modèle principal échoue.
# Chacun porte ses 4 valeurs explicites (même règle que ci-dessus).
# Numérote à partir de 1 ; laisse un numéro vide pour arrêter la liste.
# ══════════════════════════════════════════════════════════════════════════════

# METAOPS_FALLBACK_1_PROVIDER=
# METAOPS_FALLBACK_1_MODEL=
# METAOPS_FALLBACK_1_API_KEY=
# METAOPS_FALLBACK_1_BASE_URL=

# METAOPS_FALLBACK_2_PROVIDER=
# METAOPS_FALLBACK_2_MODEL=
# METAOPS_FALLBACK_2_API_KEY=
# METAOPS_FALLBACK_2_BASE_URL=


# ══════════════════════════════════════════════════════════════════════════════
# RUNTIME LIMITS (prevent infinite loops, protect resources)
# ══════════════════════════════════════════════════════════════════════════════

# LLM request timeout in seconds (all LiteLLM-routed providers)
# METAOPS_LLM_TIMEOUT=60

# LLM call safety limits
# METAOPS_GATEWAY_MAX_LLM_CALLS=50        # max LLM calls per user turn (CLI/Telegram)
# METAOPS_CRON_MAX_LLM_CALLS=30           # max LLM calls per cron job run

# Thinking budget for Gemini/Anthropic BuiltInPlanner (tokens)
# METAOPS_THINKING_BUDGET=2048

# Planner: "auto" (builtin for Gemini/Anthropic, plan_react for others), "builtin", "plan_react", "none"
# METAOPS_PLANNER=auto

# Tool retry on failure (ReflectAndRetryToolPlugin)
# METAOPS_TOOL_RETRY_ENABLED=true
# METAOPS_TOOL_RETRY_MAX=3

# Context compaction (ADK EventsCompactionConfig)
# METAOPS_COMPACT_INTERVAL=20             # compact every N invocations
# METAOPS_COMPACT_OVERLAP=3               # keep N invocations of overlap

# Continuation / revision limits
# METAOPS_MAX_CONTINUATIONS=3             # max retries after response truncation
# METAOPS_MAX_REVISIONS=3                 # max coder->reviewer cycles in vibe_code
# METAOPS_MAX_REFINEMENT_ITERATIONS=3     # max evaluate/refine loops in research

# Fallback models: see METAOPS_FALLBACK_1_* / METAOPS_FALLBACK_2_* above.

# Anthropic native driver output token cap (max 8192 by default, up to 128k for capable models)
# METAOPS_ANTHROPIC_MAX_TOKENS=8192

# Telegram queue
# METAOPS_MAX_PENDING_MESSAGES=5          # max queued messages per busy session

# Checkpoint cleanup
# METAOPS_CHECKPOINT_TTL_HOURS=24         # auto-delete checkpoints older than N hours

# Shell execution
# METAOPS_SHELL_TIMEOUT=120               # command timeout in seconds
# METAOPS_SHELL_MAX_OUTPUT_BYTES=256000   # max output bytes per command
# METAOPS_SHELL_KILL_TIMEOUT=5            # grace period after kill before force-reap

# Tool output limits
# METAOPS_TOOL_OUTPUT_MAX_CHARS=2000      # max chars returned to model from shell tools

# Code executor: "local" (UnsafeLocalCodeExecutor) or "container" (ContainerCodeExecutor + Docker)
# METAOPS_CODE_EXECUTOR=local

# RAG chunking
# METAOPS_RAG_CHUNK_SIZE=1000             # characters per chunk when indexing files

# Skill display
# METAOPS_SKILL_SUMMARY_MAX_CHARS=500     # max chars in skill execution summary

# Audit limits
# METAOPS_AUDIT_MAX_FILES=150             # max source files listed per audit
# METAOPS_AUDIT_FILE_MAX_LINES=8000       # max lines read per file in audit

# Observability
# METAOPS_LOG_RETENTION_DAYS=30           # purge llm_calls/subagent_logs older than N days at startup
# METAOPS_BM25_MAX_DOCS=1000              # max documents per collection loaded for BM25 keyword search


# ══════════════════════════════════════════════════════════════════════════════
# STORAGE — Database paths
# ══════════════════════════════════════════════════════════════════════════════

# SQLite — single consolidated database (sessions, skills, logs, loop context)
METAOPS_DATABASE=.data/metaops.db

# ChromaDB — vector memory (episodic, semantic, procedural)
METAOPS_VECTOR_DB=.data/metaops_vector_db

# FileArtifactService — persistent artifacts (generated files, exports, reports)
METAOPS_ARTIFACTS_DIR=.data/artifacts


# ══════════════════════════════════════════════════════════════════════════════
# EMBEDDINGS (ChromaDB RAG — semantic memory search)
# ══════════════════════════════════════════════════════════════════════════════

# "local" = ONNX bundled in ChromaDB (no key, ~140ms per call)
# "api"   = OpenAI-compatible API (faster, needs key)
METAOPS_EMBEDDING_PROVIDER=local

# Only needed when METAOPS_EMBEDDING_PROVIDER=api:
METAOPS_EMBEDDING_MODEL=openai/text-embedding-3-small
METAOPS_EMBEDDING_API_KEY=          # leave empty to reuse provider's API key
METAOPS_EMBEDDING_BASE_URL=https://openrouter.ai/api/v1


# ══════════════════════════════════════════════════════════════════════════════
# WEB SEARCH & RESEARCH
# ══════════════════════════════════════════════════════════════════════════════

# Tavily — web search (get key at app.tavily.com)
TAVILY_API_KEY=

# Web fetch settings
# METAOPS_WEB_FETCH_USE_JINA=true               # use Jina Reader for URL extraction
# METAOPS_WEB_SEARCH_MAX_RESULTS=5
# METAOPS_WEB_SEARCH_TIMEOUT=30


# ══════════════════════════════════════════════════════════════════════════════
# MCP SERVERS (Model Context Protocol — external tool providers)
# ══════════════════════════════════════════════════════════════════════════════

# Fallback URL when mcp_servers.json is absent
MCP_SERVER_URL=http://localhost:8000/sse

# MCP server startup timeout in seconds
# METAOPS_MCP_TIMEOUT=30


# ══════════════════════════════════════════════════════════════════════════════
# APPLICATION — Roles & Behavior
# ══════════════════════════════════════════════════════════════════════════════

# Target platform for cron deliveries: "cli" or "telegram:<chat_id>"
METAOPS_CRON_DELIVERY_TARGET=cli

# Role permissions:
#   "admin"  = full shell access, all tools
#   "user"   = restricted shell, no dangerous commands
#   "guest"  = no shell access, read-only
METAOPS_DEFAULT_CLI_ROLE=admin
METAOPS_DEFAULT_CRON_ROLE=user
METAOPS_DEFAULT_TELEGRAM_ROLE=admin


# ══════════════════════════════════════════════════════════════════════════════
# API PROVIDERS — Fill in only the ones you use
# ══════════════════════════════════════════════════════════════════════════════

# ── Aggregators (hundreds of models via one key) ──────────────────────────

# OpenRouter — 300+ models (recommended starting point)
OPENROUTER_API_KEY=
OPENROUTER_BASE_URL=https://openrouter.ai/api/v1

# NousResearch — Hermes models + community
NOUSRESEARCH_API_KEY=
NOUSRESEARCH_BASE_URL=https://inference-api.nousresearch.com/v1

# Novita AI — hosted open-source
NOVITA_API_KEY=
NOVITA_BASE_URL=https://api.novita.ai/v1

# Kilo Code — dev-focused aggregator
KILOCODE_API_KEY=
KILOCODE_BASE_URL=https://api.kilo.ai/api/gateway

# OpenCode Zen — open-source aggregator
OPENCODE_ZEN_API_KEY=
OPENCODE_ZEN_BASE_URL=https://opencode.ai/zen/v1


# ── Cloud Providers ────────────────────────────────────────────────────────

# OpenAI — GPT-4o, o3, etc.
OPENAI_API_KEY=
OPENAI_BASE_URL=https://api.openai.com/v1

# Anthropic — Claude 4 / 3.5 / 3
ANTHROPIC_API_KEY=
ANTHROPIC_BASE_URL=https://api.anthropic.com

# Google Gemini — Gemini 2.5 Pro/Flash
GOOGLE_API_KEY=
GEMINI_API_KEY=
GEMINI_BASE_URL=https://generativelanguage.googleapis.com/v1beta
# GOOGLE_APPLICATION_CREDENTIALS=         # path to Vertex AI service account JSON

# xAI — Grok-3, Grok-2
XAI_API_KEY=
XAI_BASE_URL=https://api.x.ai/v1

# DeepSeek — deepseek-chat, deepseek-r1
DEEPSEEK_API_KEY=
DEEPSEEK_BASE_URL=https://api.deepseek.com/v1

# Mistral AI — mistral-large, codestral
MISTRAL_API_KEY=
MISTRAL_BASE_URL=https://api.mistral.ai/v1

# Groq — ultra-fast inference
GROQ_API_KEY=
GROQ_BASE_URL=https://api.groq.com/openai/v1

# Perplexity — models with built-in web search
PERPLEXITY_API_KEY=
PERPLEXITY_BASE_URL=https://api.perplexity.ai

# Cohere — Command R+
COHERE_API_KEY=
COHERE_BASE_URL=https://api.cohere.ai/v1

# Together AI — open-source models
TOGETHER_API_KEY=
TOGETHER_BASE_URL=https://api.together.ai/v1

# Fireworks AI — fast open-source inference
FIREWORKS_API_KEY=
FIREWORKS_BASE_URL=https://api.fireworks.ai/inference/v1

# NVIDIA NIM — NVIDIA-accelerated models
NVIDIA_API_KEY=
NVIDIA_BASE_URL=https://integrate.api.nvidia.com/v1

# Hugging Face Inference Router
HF_TOKEN=
HF_BASE_URL=https://router.huggingface.co/v1

# GitHub Copilot
COPILOT_GITHUB_TOKEN=
# GH_TOKEN=                              # alternative name for GitHub token
# GITHUB_TOKEN=                          # another alternative name
COPILOT_API_BASE_URL=https://api.githubcopilot.com

# Arcee AI — enterprise SLMs
ARCEEAI_API_KEY=
ARCEE_BASE_URL=https://api.arcee.ai/api/v1

# GMI Cloud
GMI_API_KEY=
GMI_BASE_URL=https://api.gmi-serving.com/v1

# Azure AI Foundry
AZURE_FOUNDRY_API_KEY=
AZURE_FOUNDRY_BASE_URL=


# ── Asian Providers ────────────────────────────────────────────────────────

# Alibaba / Qwen (DashScope)
DASHSCOPE_API_KEY=
DASHSCOPE_BASE_URL=https://dashscope-intl.aliyuncs.com/compatible-mode/v1

# Kimi / Moonshot
KIMI_API_KEY=
KIMI_CODING_API_KEY=
KIMI_BASE_URL=https://api.moonshot.ai/v1

# MiniMax
MINIMAX_API_KEY=
MINIMAX_BASE_URL=https://api.minimax.io/anthropic

# StepFun
STEPFUN_API_KEY=
STEPFUN_BASE_URL=https://api.stepfun.ai/step_plan/v1

# Z.AI / GLM
GLM_API_KEY=
ZAI_API_KEY=
# Z_AI_API_KEY=                          # alternative name for Z.AI API key
GLM_BASE_URL=https://api.z.ai/api/paas/v4

# Xiaomi MiMo
XIAOMI_API_KEY=
XIAOMI_BASE_URL=https://api.xiaomimimo.com/v1

# Tencent TokenHub
TOKENHUB_API_KEY=
TOKENHUB_BASE_URL=https://tokenhub.tencentmaas.com/v1


# ── Local / Self-Hosted ────────────────────────────────────────────────────

# Ollama
OLLAMA_BASE_URL=http://localhost:11434/v1

# LM Studio
LM_API_KEY=
LM_BASE_URL=http://127.0.0.1:1234/v1


# ══════════════════════════════════════════════════════════════════════════════
# TOOL SETTINGS
# ══════════════════════════════════════════════════════════════════════════════

# File operations
# METAOPS_FILE_RESTRICT_TO_WORKSPACE=true        # prevent writes outside project

# Browser (headless Chrome)
# METAOPS_BROWSER_ENABLED=true
# METAOPS_BROWSER_HEADLESS=true
# METAOPS_BROWSER_TIMEOUT_MS=30000
# METAOPS_BROWSER_VIEWPORT_WIDTH=1280
# METAOPS_BROWSER_VIEWPORT_HEIGHT=720


# ══════════════════════════════════════════════════════════════════════════════
# ADVANCED — Things you probably don't need to change
# ══════════════════════════════════════════════════════════════════════════════

# Timezone for cron jobs
# METAOPS_TIMEZONE=UTC

# Bot identity
# METAOPS_BOT_NAME=metaops
# METAOPS_BOT_ICON=🐈

# Debug mode (verbose logging)
# metaops --debug

# Skip cron scheduler on startup
# metaops --no-cron