added technical documentation

2026-01-13 17:20:52 +00:00
parent ff394c9250
commit b29822efc7
12 changed files with 4953 additions and 1 deletions
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -0,0 +1,637 @@
+# 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/daemon_boyfriend
+```
+
+**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/daemon_boyfriend.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/daemon_boyfriend
+# 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/daemon_boyfriend.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.