config.example.yaml

# Teleton Agent Configuration
# Copy this file to ~/.teleton/config.yaml and fill in your values.
# Or run: teleton setup

agent:
  provider: "anthropic"              # anthropic | openai | google | xai | groq | openrouter | nvidia
  api_key: "YOUR_API_KEY"
  model: "claude-opus-4-8" # Model ID (varies by provider)
  # utility_model: "claude-haiku-4-5-20251001"  # Optional: cheap model for summarization
  max_tokens: 4096
  temperature: 0.7
  # system_prompt: null              # Custom system prompt override (null = use SOUL.md)
  max_agentic_iterations: 5
  session_reset_policy:
    daily_reset_enabled: true
    daily_reset_hour: 4              # 0-23, hour of day to reset sessions
    idle_expiry_enabled: true
    idle_expiry_minutes: 1440        # 24 hours

# Optional self-correction loop.
# LLM evaluation/regeneration is off by default because it adds extra model calls.
self_correction:
  enabled: false                      # Generate -> evaluate -> reflect -> regenerate
  threshold: 0.7                      # Minimum quality score to accept a response
  max_iterations: 3                   # Prevent infinite correction loops
  min_input_chars: 40                 # Skip short/simple messages
  skip_simple_messages: true
  # model: "claude-3-5-haiku-20241022" # Optional override; defaults to agent.utility_model
  tool_recovery_enabled: true         # Add retry guidance after failed tool calls

# Optional: managed-agent registry defaults.
# The WebUI Agents page can create agents from ResearchAgent, CodeAgent,
# ContentAgent, OrchestratorAgent, MonitorAgent, or custom definitions.
# agent_registry:
#   enabled: true
#   default_type: "CustomAgent"
#   default_memory_policy: "isolated"

telegram:
  mode: "user"                       # "user" (default) or "bot" — user requires phone auth, bot requires bot_token
  api_id: 0                          # From https://my.telegram.org/apps
  api_hash: "YOUR_API_HASH"
  phone: "+1234567890"               # Phone number linked to Telegram account
  session_name: "teleton_session"    # GramJS session file name
  session_path: "~/.teleton"         # Directory for session files
  dm_policy: "open"                  # open | allowlist | admin-only | disabled
  allow_from: []                     # Telegram user IDs (for allowlist policy)
  group_policy: "open"               # open | allowlist | disabled
  group_allow_from: []               # Group chat IDs (for allowlist group policy)
  require_mention: true              # In groups, only respond when mentioned
  # max_message_length: 4096         # MTProto limit, rarely needs changing
  typing_simulation: true            # Show "typing..." while processing
  rate_limit_messages_per_second: 1.0
  rate_limit_groups_per_minute: 20
  admin_ids: [123456789]             # Your Telegram user ID (from @userinfobot). Required (non-empty) to enable the autonomous task manager and heartbeat.
  # agent_channel: null              # Channel username or ID for announcements
  owner_name: "Your Name"
  owner_username: "your_username"
  # owner_id: 123456789              # Owner's Telegram user ID
  debounce_ms: 1500                  # Group message batching delay (0 = disabled)

  # Optional: inline bot for deals system
  # bot_token: "123456:ABC-DEF..."   # From @BotFather
  # bot_username: "your_deals_bot"

# Optional: TonAPI key for higher rate limits
# tonapi_key: "YOUR_TONAPI_KEY"      # From @tonapi_bot

# Optional: AES-256-GCM encryption key for wallet.json
# When set, the 24-word mnemonic is stored encrypted at rest.
# Generate a key: node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
# Can also be set via the TELETON_WALLET_KEY environment variable (takes precedence).
# wallet_encryption_key: "your-64-char-hex-key-here"

# Optional: Tavily API key for web search/fetch tools
# tavily_api_key: "YOUR_TAVILY_KEY"  # From https://tavily.com

# Groq multi-modal configuration (can be used alongside any primary LLM provider)
# Enables native STT (Whisper) and TTS (Orpheus) via Groq's API.
# If direct API access is geo-restricted, use the groq-mcp-server instead (see mcp section below).
# groq:
#   stt_model: "whisper-large-v3-turbo"         # STT model: whisper-large-v3 | whisper-large-v3-turbo | distil-whisper-large-v3-en
#   tts_model: "canopylabs/orpheus-v1-english"  # TTS model: canopylabs/orpheus-v1-english | canopylabs/orpheus-arabic-saudi
#   tts_voice: "autumn"                         # Voice name (English: autumn, diana, hannah, austin, daniel, troy; Arabic: ahmad, nadia)
#   tts_format: "wav"                           # Groq Orpheus output format. Telegram voice replies are converted to OGG/Opus.
#   stt_language: ""                            # Language hint for STT (e.g. "en"). Empty = auto-detect.
#   rate_limit_mode: "auto"                     # Rate limit handling: auto | strict | off

# Embedding provider for RAG vector search
embedding:
  provider: "local"                  # local | anthropic | none
  # model: "Xenova/all-MiniLM-L6-v2" # Model override (auto-detected per provider)
  #
  # local    = ONNX runtime, runs entirely on CPU, no API calls needed
  # anthropic = uses Voyage API via your agent.api_key
  # none     = FTS5 full-text search only (no vector embeddings)
  #
  # If Upstash is unavailable, Teleton falls back to local SQLite/FTS5.

# Optional Upstash Vector primary semantic store.
# These settings can also be edited from WebUI -> Configuration -> Vector Memory.
# Environment variables UPSTASH_VECTOR_REST_URL, UPSTASH_VECTOR_REST_TOKEN,
# and UPSTASH_VECTOR_NAMESPACE override these config values.
# vector_memory:
#   upstash_rest_url: "https://..."
#   upstash_rest_token: "..."
#   namespace: "teleton-memory"

# Memory prioritization and retention.
# Scores are recalculated periodically. Cleanup archives active memories first,
# then deletes archived rows after archive_days.
memory:
  prioritization:
    enabled: true
    interval_minutes: 60
    recency_half_life_days: 30
    weights:
      recency: 0.35
      frequency: 0.20
      impact: 0.20
      explicit: 0.15
      centrality: 0.10
  retention:
    min_score: 0.1
    max_age_days: 90
    max_entries: 10000
    archive_days: 30
    auto_cleanup: false # Set true to let the scheduler archive candidates automatically

# Telegram feed retention. The scheduler prunes tg_messages, tg_messages_vec,
# and the feed FTS index by age and total message count.
feed:
  retention_days: 90
  max_messages: 100000

# Temporal context engine.
# Timezone can also be overridden with TELETON_TIMEZONE.
temporal_context:
  enabled: true
  timezone: "UTC"                    # IANA timezone, e.g. "America/New_York"
  pattern_min_frequency: 2
  pattern_confidence_threshold: 0.5
  context_patterns_limit: 5
  weighting:
    enabled: true
    decay_curve: "exponential"       # exponential | linear | step
    recency_half_life_days: 30
    temporal_relevance_weight: 0.2

# Optional: WebUI dashboard (disabled by default for security)
webui:
  enabled: false                      # Enable web dashboard
  port: 7777                          # HTTP server port
  host: "127.0.0.1"                   # Localhost only (secure)
  # auth_token: "..."                 # Auto-generated if omitted
  cors_origins:
    - "http://localhost:5173"         # Vite dev server
    - "http://localhost:7777"         # Production server
  log_requests: false                 # Log HTTP requests

# Optional: HTTPS Management API (disabled by default)
# api:
#   enabled: true
#   port: 7778                        # HTTPS server port
#   host: "127.0.0.1"                 # SECURITY: keep as 127.0.0.1 (localhost only)
#                                     # Change to "0.0.0.0" ONLY if you need LAN access
#                                     # and understand the security implications.
#   # key_hash: "..."                 # scrypt hash of API key (auto-generated if omitted)
#   allowed_ips: []                   # IP whitelist (empty = all authenticated requests)

# Internal event bus and webhook delivery.
event_bus:
  enabled: true                       # Store recent internal events for stream/replay/debugging
  max_log_entries: 1000               # Recent events retained in SQLite

webhooks:
  enabled: true                       # Subscribe outgoing webhooks to internal events
  default_max_retries: 5              # Delivery attempts before marking failed
  delivery_timeout_ms: 5000           # Timeout for each outgoing webhook POST
  # Secrets are stored encrypted with TELETON_WEBHOOK_KEY or generated ~/.teleton/.webhook-secret-key.

# Optional: multi-agent network protocol for cross-deployment collaboration.
network:
  enabled: false
  agent_id: "primary"
  agent_name: "Primary Agent"
  endpoint: null                      # Public HTTPS URL ending in /api/agent-network
  discovery_mode: "central"           # central | peer-to-peer | dns
  registry_url: null
  known_peers: []
  public_key: null                    # PEM Ed25519 public key advertised to peers
  private_key: null                   # PEM Ed25519 private key for outbound signatures
  allowlist: []                       # Optional trusted agent ids
  blocklist: []                       # Blocked agent ids
  default_trust_level: "untrusted"    # trusted | verified | untrusted
  message_timeout_ms: 15000
  max_clock_skew_seconds: 300

# Autonomous task engine settings.
autonomous:
  pause_timeout_hours: 24              # Hours a paused task may wait before being auto-cancelled (AUDIT-M5)

# Prediction engine: learns repeated message/tool patterns and exposes suggestions.
predictions:
  enabled: true                       # Record behavior events and serve prediction APIs
  confidence_threshold: 0.6           # Minimum confidence before suggestions appear
  proactive_suggestions: false        # Append suggestions to agent replies (off by default)
  max_suggestions: 5                  # Max predictions per API response
  history_limit: 5000                 # Max behavior events retained locally

# Feedback learning: explicit ratings plus conservative cross-session preferences.
feedback:
  enabled: true                       # Store feedback and expose feedback analytics APIs
  implicit_signals: true              # Infer corrections/rephrasing/accepted output signals
  prompt_adjustments: true            # Apply repeated learned preferences to future prompts
  min_feedback_for_prompt: 2          # Repeated theme count needed before prompt injection
  correction_window_seconds: 600      # Follow-up correction window
  acceptance_delay_seconds: 300       # Delay before treating no correction as accepted output

# Adaptive prompting: section variants, A/B tests, and conservative optimizer suggestions.
adaptive_prompting:
  enabled: true
  default_traffic_percentage: 20      # Candidate traffic share for new A/B tests
  min_samples: 30                     # Samples per variant before auto-promotion
  auto_promote: true                  # Activate winning variants automatically

# Anomaly detection: rolling baselines for volume, errors, latency, tool usage, and cost.
anomaly_detection:
  enabled: true                       # Enable automated anomaly detection
  sensitivity: 2.5                    # Z-score threshold in standard deviations
  baseline_days: 7                    # Rolling baseline window
  min_samples: 24                     # Hourly samples required before alerting
  cooldown_minutes: 15                # Suppress duplicate alerts for same type/metric
  alerting:
    in_app: true                      # Create WebUI notifications
    telegram: false                   # Send alerts to admin IDs or telegram_chat_ids
    telegram_chat_ids: []             # Optional explicit chat IDs; empty = admin_ids
    webhook_url: null                 # Optional Slack/PagerDuty-compatible webhook URL

# Unified integration layer: registry, encrypted credentials, and outbound limits.
integrations:
  enabled: true
  # credential_key: "..."             # Optional key material; generated locally if omitted
  health_check_interval_minutes: 5
  global_rate_limit:
    # requests_per_minute: 120
    # requests_per_hour: 5000

# Tool RAG: semantic tool selection per message (ENABLED by default)
# Reduces tool definitions sent to the LLM from 120+ to ~25 most relevant.
# Uses local ONNX embeddings (zero-config) + FTS5 hybrid search.
# Set enabled: false to disable and send all tools to the LLM.
# tool_rag:
#   enabled: true                      # Enabled by default — disable with false
#   top_k: 35                          # Max tools to retrieve per LLM call
#   skip_unlimited_providers: false    # RAG applies to ALL providers (including Anthropic)
#   always_include:                    # Tools always included regardless of query
#     - telegram_send_message
#     - telegram_reply_message
#     - telegram_send_photo
#     - telegram_send_document
#     - "journal_*"                    # Prefix glob: all journal_ tools
#     - "workspace_*"
#     - "web_*"

# Predictive cache: bounded in-memory cache for tools, prompts, embeddings, and opt-in API responses.
cache:
  enabled: true
  max_entries: 512
  ttl:
    tools_ms: 300000
    prompts_ms: 60000
    embeddings_ms: 1800000
    api_responses_ms: 300000

# Comprehensive audit trail: tamper-evident agent decisions, tool calls, LLM calls,
# WebUI mutations, and security validations. Payloads above payload_max_bytes are
# truncated before storage to keep the database bounded.
audit_trail:
  enabled: true
  retention_days: 90
  compliance_retention_days: 2555   # 7 years
  payload_max_bytes: 16384

# Deals / OTC trading module
# deals:
#   enabled: true
#   expiry_seconds: 120              # Seconds before a pending deal expires
#   buy_max_floor_percent: 100       # Max price as % of floor for buy offers
#   sell_min_floor_percent: 105      # Min price as % of floor for sell offers
#   poll_interval_ms: 5000           # Payment verification polling interval
#   max_verification_retries: 12     # Max payment verification attempts
#   expiry_check_interval_ms: 60000  # Stale deal check interval

# Exec capability — run shell commands from the agent (DISABLED by default)
# WARNING: enabling exec gives the agent shell access on your host system.
# Use "allowlist" mode to restrict which commands can be executed.
# capabilities:
#   exec:
#     mode: "off"          # off (default, safe) | allowlist (recommended) | yolo (dangerous — full shell access)
#     scope: "admin-only"  # admin-only | allowlist | all
#     allowlist: []        # Telegram user IDs (when scope = allowlist)
#     command_allowlist:   # Allowed program names when mode = allowlist (first token of command must match exactly)
#       - "git"            # allows: git status, git diff, git log, etc.
#       - "npm"            # allows: npm run, npm install, etc.
#       - "ls"
#       - "cat"
#     sandbox_mode: "unrestricted" # unrestricted | sandboxed (temp cwd/minimal env) | dry-run
#     # NOTE: pipes, &&, ||, redirects, and command substitution are always rejected in allowlist mode.

# Storage paths (defaults are fine for most users)
# storage:
#   sessions_file: "~/.teleton/sessions.json"
#   pairing_file: "~/.teleton/pairing.json"
#   memory_file: "~/.teleton/memory.json"
#   history_limit: 100

# Developer options
# dev:
#   hot_reload: false                # Watch ~/.teleton/plugins/ for changes

# MCP (Model Context Protocol) — external tool servers
# mcp:
#   servers:
#     filesystem:
#       command: npx -y @modelcontextprotocol/server-filesystem /tmp
#     brave:
#       command: npx -y @modelcontextprotocol/server-brave-search
#       env:
#         BRAVE_API_KEY: "sk-xxx"
#     remote:
#       url: http://localhost:3001/mcp
#
#     # Groq MCP Server — alternative Groq integration via MCP protocol
#     # Use this when direct Groq API access is geo-restricted (403 errors).
#     # Provides STT (Whisper), TTS (PlayAI), vision, and chat tools via MCP.
#     #
#     # Prerequisites:
#     #   pip install groq-mcp        (or: uv tool install groq-mcp)
#     #
#     # Tools exposed (prefixed as mcp_groq_*):
#     #   mcp_groq_transcribe_audio   — speech-to-text via Whisper
#     #   mcp_groq_translate_audio    — translate audio to English
#     #   mcp_groq_text_to_speech     — text-to-speech via PlayAI
#     #   mcp_groq_list_voices        — list available TTS voices
#     #   mcp_groq_analyze_image      — image analysis via Llama 4 Vision
#     #   mcp_groq_list_stt_models    — list available STT models
#     #
#     groq:
#       command: groq-mcp
#       env:
#         GROQ_API_KEY: "gsk_your_groq_api_key"
#         BASE_OUTPUT_PATH: "/tmp/groq-mcp-output"  # Directory for saved TTS files

# MTProto proxy configuration (MRTPOTO)
# Route Telegram connections through MTProto proxies.
# Useful when Telegram is blocked or unreliable on your network.
# Multiple servers are tried in order — automatic failover to the next if one fails.
# Requires restart to take effect.
# mtproto:
#   enabled: false                     # Set to true to activate proxy routing
#   proxies:
#     - server: "proxy1.example.com"   # 🖥 Server: hostname or IP
#       port: 443                      # 🔌 Port: proxy server port
#       secret: "dd1234abcdef..."      # 🔑 Secret: hex/base64url; dd for padded, ee+domain for fake TLS
#     - server: "proxy2.example.com"
#       port: 8888
#       secret: "abcdef1234..."
#   # Optional: HTTP/HTTPS or SOCKS5 proxy URL for the Telegram Bot API HTTPS path
#   # (api.telegram.org). MTProto proxies cannot tunnel HTTPS, so set this when
#   # api.telegram.org is also blocked. The Bot API path is only used for the
#   # inline deals bot today, but it is required for the agent to work end-to-end
#   # in regions that block Telegram at the IP level.
#   # bot_api_proxy: "socks5://user:pass@proxy.example.com:1080"

# Autonomous task policy — governs spending limits and human-approval rules.
# These defaults are conservative to protect wallets on first run.
# Raise limits only if you understand the risk.
#
# Safe preset (default):
# autonomous:
#   policy:
#     ton_spending:
#       per_task: 0.1            # Max TON per autonomous task (≈ $0.50)
#       daily: 0.5               # Max TON per calendar day (≈ $2.50)
#       require_confirmation_above: 0.05  # Ask before spending more than this amount
#
# Aggressive preset (for trusted environments with explicit oversight):
# autonomous:
#   policy:
#     ton_spending:
#       per_task: 1.0            # 10× higher — verify your approval flows first
#       daily: 5.0
#       require_confirmation_above: 0.5

# Per-plugin configuration (key = plugin name)
# plugins:
#   casino:
#     min_bet: 0.1
#     cooldown_seconds: 30