# Configuration Reference Complete reference for all environment variables and configuration options. ## Table of Contents - [Overview](#overview) - [Required Configuration](#required-configuration) - [AI Provider Configuration](#ai-provider-configuration) - [Bot Identity](#bot-identity) - [Database Configuration](#database-configuration) - [Web Search (SearXNG)](#web-search-searxng) - [Living AI Configuration](#living-ai-configuration) - [Command Toggles](#command-toggles) - [Logging Configuration](#logging-configuration) - [Example .env File](#example-env-file) --- ## Overview Configuration is managed via environment variables using [pydantic-settings](https://docs.pydantic.dev/latest/concepts/pydantic_settings/). **Loading Order:** 1. Environment variables 2. `.env` file in project root **Case Sensitivity:** Variable names are case-insensitive. --- ## Required Configuration ### DISCORD_TOKEN ```bash DISCORD_TOKEN=your_discord_bot_token ``` **Required.** Your Discord bot token from the [Discord Developer Portal](https://discord.com/developers/applications). ### API Key (one required) At least one API key is required based on your chosen `AI_PROVIDER`: ```bash # For OpenAI OPENAI_API_KEY=sk-... # For OpenRouter OPENROUTER_API_KEY=sk-or-... # For Anthropic ANTHROPIC_API_KEY=sk-ant-... # For Gemini GEMINI_API_KEY=AIza... ``` --- ## AI Provider Configuration ### AI_PROVIDER ```bash AI_PROVIDER=openai ``` **Default:** `openai` **Options:** `openai`, `openrouter`, `anthropic`, `gemini` Which AI provider to use for generating responses. ### AI_MODEL ```bash AI_MODEL=gpt-4o ``` **Default:** `gpt-4o` The model to use. Depends on your provider: | Provider | Example Models | |----------|----------------| | openai | `gpt-4o`, `gpt-4o-mini`, `gpt-4-turbo` | | openrouter | `anthropic/claude-3.5-sonnet`, `google/gemini-pro` | | anthropic | `claude-3-5-sonnet-20241022`, `claude-3-opus-20240229` | | gemini | `gemini-pro`, `gemini-1.5-pro` | ### AI_MAX_TOKENS ```bash AI_MAX_TOKENS=1024 ``` **Default:** `1024` **Range:** 100-4096 Maximum tokens in AI response. ### AI_TEMPERATURE ```bash AI_TEMPERATURE=0.7 ``` **Default:** `0.7` **Range:** 0.0-2.0 Sampling temperature. Higher = more creative, lower = more focused. --- ## Bot Identity ### BOT_NAME ```bash BOT_NAME=Daemon ``` **Default:** `AI Bot` The bot's display name used in system prompts. ### BOT_PERSONALITY ```bash BOT_PERSONALITY=friendly, witty, and helpful ``` **Default:** `helpful and friendly` Personality description used in the default system prompt. ### BOT_DESCRIPTION ```bash BOT_DESCRIPTION=I'm Daemon, your friendly AI companion! ``` **Default:** `I'm an AI assistant here to help you.` Description shown when bot is mentioned without a message. ### BOT_STATUS ```bash BOT_STATUS=for @mentions ``` **Default:** `for mentions` Discord status message (shown as "Watching ..."). ### SYSTEM_PROMPT ```bash SYSTEM_PROMPT=You are a helpful AI assistant named Daemon. Be friendly and concise. ``` **Default:** `None` (auto-generated) Custom system prompt. If not set, one is generated from `BOT_NAME` and `BOT_PERSONALITY`. --- ## Database Configuration ### DATABASE_URL ```bash DATABASE_URL=postgresql+asyncpg://user:password@localhost:5432/loyal_companion ``` **Default:** `None` (in-memory mode) PostgreSQL connection URL. Format: `postgresql+asyncpg://user:pass@host:port/database` If not set, the bot runs in in-memory mode without persistence. ### DATABASE_ECHO ```bash DATABASE_ECHO=false ``` **Default:** `false` Log all SQL statements. Useful for debugging. ### DATABASE_POOL_SIZE ```bash DATABASE_POOL_SIZE=5 ``` **Default:** `5` **Range:** 1-20 Number of connections in the pool. ### DATABASE_MAX_OVERFLOW ```bash DATABASE_MAX_OVERFLOW=10 ``` **Default:** `10` **Range:** 0-30 Maximum connections beyond the pool size. --- ## Web Search (SearXNG) ### SEARXNG_URL ```bash SEARXNG_URL=http://localhost:8888 ``` **Default:** `None` (disabled) URL of your SearXNG instance for web search capability. ### SEARXNG_ENABLED ```bash SEARXNG_ENABLED=true ``` **Default:** `true` Enable/disable web search even if URL is configured. ### SEARXNG_MAX_RESULTS ```bash SEARXNG_MAX_RESULTS=5 ``` **Default:** `5` **Range:** 1-20 Maximum search results to fetch per query. --- ## Living AI Configuration ### Master Switch #### LIVING_AI_ENABLED ```bash LIVING_AI_ENABLED=true ``` **Default:** `true` Master switch for all Living AI features. When disabled, the bot acts as a basic chatbot. --- ### Feature Toggles #### MOOD_ENABLED ```bash MOOD_ENABLED=true ``` **Default:** `true` Enable the mood system (valence-arousal emotional model). #### RELATIONSHIP_ENABLED ```bash RELATIONSHIP_ENABLED=true ``` **Default:** `true` Enable relationship tracking (0-100 score, 5 levels). #### FACT_EXTRACTION_ENABLED ```bash FACT_EXTRACTION_ENABLED=true ``` **Default:** `true` Enable autonomous fact extraction from conversations. #### FACT_EXTRACTION_RATE ```bash FACT_EXTRACTION_RATE=0.3 ``` **Default:** `0.3` **Range:** 0.0-1.0 Probability of attempting fact extraction for each message. Lower = fewer API calls. #### PROACTIVE_ENABLED ```bash PROACTIVE_ENABLED=true ``` **Default:** `true` Enable proactive messages (birthdays, follow-ups, reminders). #### CROSS_USER_ENABLED ```bash CROSS_USER_ENABLED=false ``` **Default:** `false` Enable cross-user memory associations. **Privacy-sensitive** - allows linking facts between users. #### OPINION_FORMATION_ENABLED ```bash OPINION_FORMATION_ENABLED=true ``` **Default:** `true` Enable bot opinion formation on topics. #### STYLE_LEARNING_ENABLED ```bash STYLE_LEARNING_ENABLED=true ``` **Default:** `true` Enable learning user communication style preferences. --- ### Mood System Settings #### MOOD_DECAY_RATE ```bash MOOD_DECAY_RATE=0.1 ``` **Default:** `0.1` **Range:** 0.0-1.0 How fast mood returns to neutral per hour. | Value | Effect | |-------|--------| | 0.0 | Mood never decays | | 0.1 | Full decay in ~10 hours | | 0.5 | Full decay in ~2 hours | | 1.0 | Full decay in ~1 hour | --- ### Conversation Settings #### MAX_CONVERSATION_HISTORY ```bash MAX_CONVERSATION_HISTORY=20 ``` **Default:** `20` Maximum messages to keep in conversation history per user. #### CONVERSATION_TIMEOUT_MINUTES ```bash CONVERSATION_TIMEOUT_MINUTES=60 ``` **Default:** `60` **Range:** 5-1440 Minutes of inactivity before starting a new conversation. --- ## Command Toggles ### Master Switch #### COMMANDS_ENABLED ```bash COMMANDS_ENABLED=true ``` **Default:** `true` Master switch for all commands. When disabled, no commands work. --- ### Individual Commands | Variable | Command | Default | Description | |----------|---------|---------|-------------| | `CMD_RELATIONSHIP_ENABLED` | `!relationship` | `true` | View relationship status | | `CMD_MOOD_ENABLED` | `!mood` | `true` | View bot's current mood | | `CMD_BOTSTATS_ENABLED` | `!botstats` | `true` | View bot statistics | | `CMD_OURHISTORY_ENABLED` | `!ourhistory` | `true` | View history with the bot | | `CMD_BIRTHDAY_ENABLED` | `!birthday` | `true` | Set birthday | | `CMD_REMEMBER_ENABLED` | `!remember` | `true` | Tell bot a fact | | `CMD_SETNAME_ENABLED` | `!setname` | `true` | Set custom name | | `CMD_WHATDOYOUKNOW_ENABLED` | `!whatdoyouknow` | `true` | View known facts | | `CMD_FORGETME_ENABLED` | `!forgetme` | `true` | Delete all facts | **Example:** ```bash # Disable only the forgetme command CMD_FORGETME_ENABLED=false ``` --- ## Logging Configuration ### LOG_LEVEL ```bash LOG_LEVEL=INFO ``` **Default:** `INFO` **Options:** `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL` Logging verbosity level. ### LOG_FILE ```bash LOG_FILE=/var/log/loyal_companion.log ``` **Default:** `None` (console only) Path to log file. If not set, logs only to console. ### LOG_FORMAT ```bash LOG_FORMAT=%(asctime)s - %(name)s - %(levelname)s - %(message)s ``` **Default:** `%(asctime)s - %(name)s - %(levelname)s - %(message)s` Python logging format string. --- ## Example .env File ```bash # ============================================================================= # DAEMON BOYFRIEND CONFIGURATION # ============================================================================= # ----------------------------------------------------------------------------- # REQUIRED # ----------------------------------------------------------------------------- # Discord bot token (from Discord Developer Portal) DISCORD_TOKEN=your_discord_bot_token_here # AI Provider API Key (choose one based on AI_PROVIDER) OPENAI_API_KEY=sk-your-openai-key-here # OPENROUTER_API_KEY=sk-or-your-openrouter-key # ANTHROPIC_API_KEY=sk-ant-your-anthropic-key # GEMINI_API_KEY=AIza-your-gemini-key # ----------------------------------------------------------------------------- # AI PROVIDER # ----------------------------------------------------------------------------- # Provider: openai, openrouter, anthropic, gemini AI_PROVIDER=openai # Model to use (depends on provider) AI_MODEL=gpt-4o # Response settings AI_MAX_TOKENS=1024 AI_TEMPERATURE=0.7 # ----------------------------------------------------------------------------- # BOT IDENTITY # ----------------------------------------------------------------------------- BOT_NAME=Daemon BOT_PERSONALITY=friendly, witty, and helpful BOT_DESCRIPTION=I'm Daemon, your AI companion! BOT_STATUS=for @mentions # Optional: Override the entire system prompt # SYSTEM_PROMPT=You are a helpful AI assistant named Daemon. # ----------------------------------------------------------------------------- # DATABASE (Optional - runs in-memory if not set) # ----------------------------------------------------------------------------- DATABASE_URL=postgresql+asyncpg://daemon:password@localhost:5432/loyal_companion # DATABASE_ECHO=false # DATABASE_POOL_SIZE=5 # DATABASE_MAX_OVERFLOW=10 # ----------------------------------------------------------------------------- # WEB SEARCH (Optional) # ----------------------------------------------------------------------------- # SEARXNG_URL=http://localhost:8888 # SEARXNG_ENABLED=true # SEARXNG_MAX_RESULTS=5 # ----------------------------------------------------------------------------- # LIVING AI FEATURES # ----------------------------------------------------------------------------- # Master switch LIVING_AI_ENABLED=true # Individual features MOOD_ENABLED=true RELATIONSHIP_ENABLED=true FACT_EXTRACTION_ENABLED=true FACT_EXTRACTION_RATE=0.3 PROACTIVE_ENABLED=true CROSS_USER_ENABLED=false OPINION_FORMATION_ENABLED=true STYLE_LEARNING_ENABLED=true # Mood settings MOOD_DECAY_RATE=0.1 # Conversation settings MAX_CONVERSATION_HISTORY=20 CONVERSATION_TIMEOUT_MINUTES=60 # ----------------------------------------------------------------------------- # COMMAND TOGGLES # ----------------------------------------------------------------------------- COMMANDS_ENABLED=true # CMD_RELATIONSHIP_ENABLED=true # CMD_MOOD_ENABLED=true # CMD_BOTSTATS_ENABLED=true # CMD_OURHISTORY_ENABLED=true # CMD_BIRTHDAY_ENABLED=true # CMD_REMEMBER_ENABLED=true # CMD_SETNAME_ENABLED=true # CMD_WHATDOYOUKNOW_ENABLED=true # CMD_FORGETME_ENABLED=true # ----------------------------------------------------------------------------- # LOGGING # ----------------------------------------------------------------------------- LOG_LEVEL=INFO # LOG_FILE=/var/log/loyal_companion.log ``` --- ## Configuration Profiles ### Minimal Setup ```bash DISCORD_TOKEN=your_token OPENAI_API_KEY=your_key ``` ### Production Setup ```bash DISCORD_TOKEN=your_token OPENAI_API_KEY=your_key AI_MODEL=gpt-4o DATABASE_URL=postgresql+asyncpg://user:pass@db:5432/daemon LOG_LEVEL=WARNING ``` ### Development Setup ```bash DISCORD_TOKEN=your_token OPENAI_API_KEY=your_key AI_MODEL=gpt-4o-mini # Cheaper model DATABASE_ECHO=true LOG_LEVEL=DEBUG ``` ### Privacy-Focused Setup ```bash DISCORD_TOKEN=your_token OPENAI_API_KEY=your_key FACT_EXTRACTION_ENABLED=false CROSS_USER_ENABLED=false CMD_WHATDOYOUKNOW_ENABLED=true CMD_FORGETME_ENABLED=true ``` --- ## Validation Settings are validated at startup using Pydantic: - **Type checking:** Ensures correct types - **Range validation:** Enforces min/max values - **Required fields:** Ensures essential config is present If validation fails, the bot will not start and will show an error message indicating what's wrong.