config_example.yaml

# ============================================================================
# Construct AI Bot Configuration Example
# ============================================================================
# Copy this file to data/config.yaml and customize it for your setup.
#
# Setup Instructions:
#   1. Create data directory: mkdir -p data
#   2. Copy this file: cp config_example.yaml data/config.yaml
#   3. Edit data/config.yaml with your credentials
#   4. Set your API keys as environment variables (see below)
#   5. Run: cargo run
# ============================================================================

# ----------------------------------------------------------------------------
# System Configuration
# ----------------------------------------------------------------------------
system:
  # Base directory for projects. Used by `.list` command.
  # Optional but recommended for easier project navigation.
  projects_dir: "/home/user/Projects"

  # Admin users who can execute raw shell commands with `, <command>`
  # Must be full Matrix usernames (e.g., "@user:matrix.org")
  admin:
    - "@admin:matrix.org"

  # Auto-start delay for next milestone in minutes (default: 30)
  auto_start_delay_minutes: 30

# ----------------------------------------------------------------------------
# AI Agent Configuration
# ----------------------------------------------------------------------------
# Each agent needs:
#   - provider: The provider to use
#   - model: Specific model (optional, has defaults)
#   - api_key_env: Environment variable name containing the API key (optional)
#   - endpoint: Custom API endpoint (only for OpenAI-compatible APIs)
#   - requests_per_minute: Rate limiting (optional, handled at application level)
#
# Available protocols: openai, anthropic, gemini, groq, xai, deepai, zai
#
# Native Caching:
#   - Anthropic (Claude): Automatic prompt caching for system messages
#   - Gemini: Automatic context caching (up to 1M tokens, 4 hours)
#   - Others: No native caching support
#
# To enable caching in your code, use context.with_cache(CacheConfig { max_age_seconds: Some(3600) })
# ----------------------------------------------------------------------------

agents:
  # ==========================================================================
  # ZAI Provider (GLM Models)
  # ==========================================================================
  # Zai provides access to General Language Models through an OpenAI-compatible API.
  # Uses OpenAI-compatible protocol with custom endpoint.
  #
  # Requires: export ZAI_API_KEY="your-api-key" (or set api_key below)
  #
  # Available Zai Models:
  #   - glm-4.7      (Flagship)
  #   - glm-4.5      (General Purpose)
  #   - glm-4.5-flash (Fast)

  zai:
    #   provider: "openai"
    model: "glm-4.7"
    endpoint: "https://api.z.ai/api/coding/paas/v4/responses"
    api_key_env: "ZAI_API_KEY"
    requests_per_minute: 60

  # ==========================================================================
  # Gemini Provider (Google)
  # ==========================================================================
  # Google's Gemini models with native context caching support.
  # Caching: System messages can be cached for up to 4 hours (1M tokens).
  #
  # Requires: export GEMINI_API_KEY="your-api-key" (or set api_key below)
  #
  # Available Gemini Models:
  #   - gemini-1.5-pro    (Most capable)
  #   - gemini-1.5-flash  (Faster, cheaper)

  gemini:
    #   provider: "gemini"
    model: "gemini-1.5-pro"
    api_key_env: "GEMINI_API_KEY"
    requests_per_minute: 15

  # ==========================================================================
  # Groq Provider (Fast Inference)
  # ==========================================================================
  # Ultra-fast inference with Llama models.
  # Uses OpenAI-compatible protocol.
  #
  # Requires: export GROQ_API_KEY="your-api-key" (or set api_key below)
  #
  # Available Groq Models:
  #   - llama-3.3-70b-versatile  (Most popular)
  #   - llama-3.1-70b-versatile
  #   - mixtral-8x7b-32768

  groq:
    #   provider: "openai"
    model: "llama-3.3-70b-versatile"
    endpoint: "https://api.groq.com/openai/v1"
    api_key_env: "GROQ_API_KEY"
    requests_per_minute: 30

  # ==========================================================================
  # Anthropic Provider (Claude)
  # ==========================================================================
  # Anthropic's Claude models with native prompt caching support.
  # Caching: System messages automatically cached (up to 90% savings on long context).
  #
  # Requires: export ANTHROPIC_API_KEY="your-api-key" (or set api_key below)
  #
  # Available Claude Models:
  #   - claude-3-5-sonnet-20241022  (Most capable, latest)
  #   - claude-3-5-haiku-20241022   (Faster, cheaper)
  #   - claude-3-opus-20240229         (Older, more expensive)

  anthropic:
    protocol: "anthropic"
    model: "claude-3-5-sonnet-20241022"
    api_key_env: "ANTHROPIC_API_KEY"
    requests_per_minute: 50

  # ==========================================================================
  # OpenAI Provider
  # ==========================================================================
  # OpenAI's GPT models.
  # No native caching support.
  #
  # Requires: export OPENAI_API_KEY="your-api-key" (or set api_key below)
  #
  # Available OpenAI Models:
  #   - gpt-4o                 (Flagship, multimodal)
  #   - gpt-4o-mini             (Faster, cheaper)
  #   - gpt-4-turbo             (Good balance)
  #   - gpt-3.5-turbo           (Legacy)

  openai:
    #   provider: "openai"
    model: "gpt-4o"
    api_key_env: "OPENAI_API_KEY"
    requests_per_minute: 50

  # ==========================================================================
  # xAI Provider (Grok)
  # ==========================================================================
  # xAI's Grok models.
  # Uses OpenAI-compatible protocol.
  #
  # Requires: export XAI_API_KEY="your-api-key" (or set api_key below)
  #
  # Available Grok Models:
  #   - grok-beta               (Latest)
  #   - grok-1                   (Newer)
  #   - grok-0                   (Legacy)

  xai:
    #   provider: "openai"
    model: "grok-beta"
    endpoint: "https://api.x.ai/v1"
    api_key_env: "XAI_API_KEY"
    requests_per_minute: 50

  # ==========================================================================
  # DeepAI Provider (Legacy/Fallback)
  # ==========================================================================
  # Basic AI models for simple tasks.
  # Uses OpenAI-compatible protocol.
  # No native caching support.
  #
  # Requires: export DEEPAI_API_KEY="your-api-key" (or set api_key below)
  #
  # Available DeepAI Models:
  #   - standard                 (Default)
  #   - text-davinci-003        (Legacy)

  deepai:
    #   provider: "openai"
    model: "standard"
    endpoint: "https://api.deepai.com/v1"
    api_key_env: "DEEPAI_API_KEY"
    requests_per_minute: 10

# ----------------------------------------------------------------------------
# Service Configuration
# ----------------------------------------------------------------------------
services:
  # Matrix (chat) service configuration
  matrix:
    username: "@your_bot:matrix.org"
    password: "your_matrix_password"
    homeserver: "https://matrix.org"
    display_name: "Construct AI Bot" # Optional: Bot's display name
    protocol: "matrix" # Optional, defaults to empty string

# ----------------------------------------------------------------------------
# Bridge Configuration
# ----------------------------------------------------------------------------
# Bridges connect Matrix rooms to AI agents and workflows.
# Each bridge has a name and can route to specific agents or use defaults.
# ----------------------------------------------------------------------------
bridges:
  # Example: Development room with Zai as default agent
  "Development":
    - service: "matrix"
      channel: "!room_id_1:matrix.org" # Replace with actual room ID
    - service: "zai" # Default agent for this room

  # Example: Staging room restricted to specific agents
  "Staging":
    - service: "matrix"
      channel: "!room_id_2:matrix.org" # Replace with actual room ID
    - agents: # Only these agents can be used in this room
        - "gemini"
        - "groq"

  # Example: Testing room with Groq
  "Testing":
    - service: "matrix"
      channel: "!room_id_3:matrix.org" # Replace with actual room ID
    - service: "groq"

# ----------------------------------------------------------------------------
# Command Permissions
# ----------------------------------------------------------------------------
# Control which shell commands can be executed through the bot.
# Modes:
#   - ask: Prompt user for confirmation (default, safe)
#   - allow: Execute without confirmation
#   - block: Never execute
# ----------------------------------------------------------------------------
commands:
  default: "ask" # Default mode for commands not listed

  # Commands that require user confirmation
  ask:
    - "sudo"
    - "rm"
    - "mv"

  # Always allowed commands (safe to execute)
  allowed:
    - "ls"
    - "cat"
    - "grep"
    - "cd"
    - "pwd"
    - "git"
    - "echo"
    - "head"
    - "tail"
    - "wc"
    - "read"
    - "find"
    - "sed"
    - "awk"

  # Blocked commands (never allowed, even for admins)
  blocked:
    - "su"
    - "passwd"
    - "chmod 777"

  # Command timeouts (in seconds)
  # Prevents commands from hanging indefinitely.
  # If a command exceeds this limit, the process is KILLED immediately.
  timeouts:
    default: 30 # Default for all unlisted commands (ls, cat, grep, etc.)
    long: 600   # For specific long-running commands (see below)
    
    # Commands that are allowed to run for the 'long' duration
    long_commands:
      - "cargo"
      - "npm"
      - "docker"
      - "git"
      - "make"
      - "./scripts/deploy.sh"

# ----------------------------------------------------------------------------
# MCP (Model Context Protocol) Configuration
# ----------------------------------------------------------------------------
# MCP provides secure tool execution through a sidecar server.
# The server enforces sandboxing and access controls for all agent operations.
# ----------------------------------------------------------------------------
mcp:
  # Path to MCP server binary
  # Download from: https://github.com/modelcontextprotocol/rust-sdk
  server_path: "./mcp-filesystem-server"

  # Directories MCP server is allowed to access
  # Agent commands (.build, .read, etc.) are restricted to these directories
  allowed_directories:
    - "./projects"
    - "./data"e

  # Enable read-only mode for additional safety
  # When true, agent cannot write files or execute commands
  # Set to false when using .build, .deploy, .modify, etc.
  readonly: false

  # Default timeout in seconds for command execution
  # Can be overridden per command based on command type
  default_timeout: 120

# ============================================================================
# API Key Environment Variables
# ============================================================================
# Set these environment variables or add api_key directly in config:
#
# For Zai:
#   export ZAI_API_KEY="your-zai-key"
# For Gemini:
#   export GEMINI_API_KEY="your-gemini-key"
# For Groq:
#   export GROQ_API_KEY="your-groq-key"
# For Anthropic:
#   export ANTHROPIC_API_KEY="your-anthropic-key"
# For OpenAI:
#   export OPENAI_API_KEY="your-openai-key"
# For xAI:
#   export XAI_API_KEY="your-xai-key"
# For DeepAI:
#   export DEEPAI_API_KEY="your-deepai-key"
#
# Alternatively, set api_key directly in the agent config:
#   agents:
#     openai:
#       protocol: "openai"
#       model: "gpt-4o"
#       api_key: "sk-your-actual-key-here"
#
# ============================================================================

# ============================================================================
# Quick Start Guide
# ============================================================================
# 1. Set your API keys:
#    export ZAI_API_KEY="your-zai-key"
#    export GEMINI_API_KEY="your-gemini-key"  # if using Gemini
#
# 2. Create config:
#    mkdir -p data
#    cp config_example.yaml data/config.yaml
#    # Edit data/config.yaml with your settings
#
# 3. Update credentials:
#    # Edit data/config.yaml:
#    # - Update Matrix credentials under "services:"
#    # - Add your room IDs under "bridges:"
#    # - Set admin users under "system:"
#    # - Uncomment your preferred agent(s) under "agents:"
#
# 4. Run bot:
#    cargo run
#
# 5. Invite bot to your Matrix rooms:
#    # Invite the bot (using the Matrix username you configured)
#    # Bot will automatically join configured rooms
#
# 6. Start interacting:
#    # Use .status to see active agent
#    # Use .ask <question> for simple queries
#    # Use .build <task> for code generation
#    # Use .agent <name> to switch AI providers
#
# ============================================================================
# Using Native Caching
# ============================================================================
# The simplified LLM API supports provider-native caching:
#
# Anthropic (Claude):
#   System messages are automatically cached when you set context.cache
#   Saves up to 90% on long contexts (5-minute cache lifetime)
#
# Gemini:
#   Supports context caching (up to 1M tokens, 4-hour cache lifetime)
#   Cache is applied when you set context.cache
#
# Example: Enable caching in your code
#   let context = Context::new()
#       .add_system_message("You are a Rust expert...")
#       .add_user_message("Explain ownership.")
#       .with_cache(CacheConfig {
#           max_age_seconds: Some(3600),  // 1 hour
#       });
#
#   let response = client.chat("anthropic", context).await?;
#   println!("Cached: {}, Tokens: {}", response.cached, response.usage.total_tokens);
#
# ============================================================================
# API Differences
# ============================================================================
# OpenAI-compatible (OpenAI, Groq, xAI, DeepAI, Zai):
#   - No native caching
#   - Standard chat completions API
#   - Full streaming support (not implemented in simplified API)
#
# Anthropic (Claude):
#   - Native prompt caching for system messages
#   - Messages API (different from OpenAI format)
#   - 200K token context
#
# Gemini:
#   - Native context caching
#   - generateContent API
#   - 1M token context
#   - No system message role (becomes user message)
#
# ============================================================================