loyal_companion/docs/configuration.md

Configuration Reference

Complete reference for all environment variables and configuration options.

Table of Contents

• Overview
• Required Configuration
• AI Provider Configuration
• Bot Identity
• Database Configuration
• Web Search (SearXNG)
• Living AI Configuration
• Command Toggles
• Logging Configuration
• Example .env File

---

Overview

Configuration is managed via environment variables using pydantic-settings.

Loading Order:

1. Environment variables
2. .env file in project root

Case Sensitivity: Variable names are case-insensitive.

---

Required Configuration

DISCORD_TOKEN

DISCORD_TOKEN=your_discord_bot_token

Required. Your Discord bot token from the Discord Developer Portal.

API Key (one required)

At least one API key is required based on your chosen AI_PROVIDER:

# 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

AI_PROVIDER=openai

Default: openai
Options: openai, openrouter, anthropic, gemini

Which AI provider to use for generating responses.

AI_MODEL

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

AI_MAX_TOKENS=1024

Default: 1024
Range: 100-4096

Maximum tokens in AI response.

AI_TEMPERATURE

AI_TEMPERATURE=0.7

Default: 0.7
Range: 0.0-2.0

Sampling temperature. Higher = more creative, lower = more focused.

---

Bot Identity

BOT_NAME

BOT_NAME=Daemon

Default: AI Bot

The bot's display name used in system prompts.

BOT_PERSONALITY

BOT_PERSONALITY=friendly, witty, and helpful

Default: helpful and friendly

Personality description used in the default system prompt.

BOT_DESCRIPTION

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

BOT_STATUS=for @mentions

Default: for mentions

Discord status message (shown as "Watching ...").

SYSTEM_PROMPT

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

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

DATABASE_ECHO=false

Default: false

Log all SQL statements. Useful for debugging.

DATABASE_POOL_SIZE

DATABASE_POOL_SIZE=5

Default: 5
Range: 1-20

Number of connections in the pool.

DATABASE_MAX_OVERFLOW

DATABASE_MAX_OVERFLOW=10

Default: 10
Range: 0-30

Maximum connections beyond the pool size.

---

Web Search (SearXNG)

SEARXNG_URL

SEARXNG_URL=http://localhost:8888

Default: None (disabled)

URL of your SearXNG instance for web search capability.

SEARXNG_ENABLED

SEARXNG_ENABLED=true

Default: true

Enable/disable web search even if URL is configured.

SEARXNG_MAX_RESULTS

SEARXNG_MAX_RESULTS=5

Default: 5
Range: 1-20

Maximum search results to fetch per query.

---

Living AI Configuration

Master Switch

LIVING_AI_ENABLED

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

MOOD_ENABLED=true

Default: true

Enable the mood system (valence-arousal emotional model).

RELATIONSHIP_ENABLED

RELATIONSHIP_ENABLED=true

Default: true

Enable relationship tracking (0-100 score, 5 levels).

FACT_EXTRACTION_ENABLED

FACT_EXTRACTION_ENABLED=true

Default: true

Enable autonomous fact extraction from conversations.

FACT_EXTRACTION_RATE

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

PROACTIVE_ENABLED=true

Default: true

Enable proactive messages (birthdays, follow-ups, reminders).

CROSS_USER_ENABLED

CROSS_USER_ENABLED=false

Default: false

Enable cross-user memory associations. Privacy-sensitive - allows linking facts between users.

OPINION_FORMATION_ENABLED

OPINION_FORMATION_ENABLED=true

Default: true

Enable bot opinion formation on topics.

STYLE_LEARNING_ENABLED

STYLE_LEARNING_ENABLED=true

Default: true

Enable learning user communication style preferences.

---

Mood System Settings

MOOD_DECAY_RATE

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

MAX_CONVERSATION_HISTORY=20

Default: 20

Maximum messages to keep in conversation history per user.

CONVERSATION_TIMEOUT_MINUTES

CONVERSATION_TIMEOUT_MINUTES=60

Default: 60
Range: 5-1440

Minutes of inactivity before starting a new conversation.

---

Command Toggles

Master Switch

COMMANDS_ENABLED

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:

# Disable only the forgetme command
CMD_FORGETME_ENABLED=false

---

Logging Configuration

LOG_LEVEL

LOG_LEVEL=INFO

Default: INFO
Options: DEBUG, INFO, WARNING, ERROR, CRITICAL

Logging verbosity level.

LOG_FILE

LOG_FILE=/var/log/loyal_companion.log

Default: None (console only)

Path to log file. If not set, logs only to console.

LOG_FORMAT

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

# =============================================================================
# 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

DISCORD_TOKEN=your_token
OPENAI_API_KEY=your_key

Production Setup

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

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

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.