# Daemon Boyfriend - Technical Documentation

Welcome to the technical documentation for Daemon Boyfriend, a Discord bot with AI-powered personality, emotional depth, and relationship awareness.

## Quick Navigation

| Document | Description |
|----------|-------------|
| [Architecture Overview](architecture.md) | High-level system design, components, data flow |
| [Living AI System](living-ai/README.md) | Mood, relationships, fact extraction, opinions |
| [Services Reference](services/README.md) | API documentation for all services |
| [Database Schema](database.md) | Complete database schema reference |
| [Configuration](configuration.md) | All environment variables and settings |
| [Developer Guides](guides/README.md) | How to extend and develop the bot |

---

## What is Daemon Boyfriend?

Daemon Boyfriend is a Discord bot that goes beyond simple chatbot functionality. It features a sophisticated "Living AI" system that gives the bot:

- **Emotional States** - A mood system based on psychological valence-arousal model
- **Relationship Tracking** - Evolving relationships from stranger to close friend
- **Memory** - Learns and remembers facts about users
- **Opinions** - Develops opinions on topics through discussion
- **Personality Adaptation** - Learns each user's communication style

---

## Architecture at a Glance

```
┌─────────────────────────────────────────────────────────────────┐
│                         Discord API                              │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                        Discord Bot                               │
│  ┌────────────┐  ┌────────────┐  ┌────────────┐                 │
│  │ AIChatCog  │  │ MemoryCog  │  │ StatusCog  │                 │
│  └────────────┘  └────────────┘  └────────────┘                 │
└─────────────────────────────────────────────────────────────────┘
                              │
          ┌───────────────────┼───────────────────┐
          ▼                   ▼                   ▼
┌────────────────┐  ┌────────────────┐  ┌────────────────────────┐
│ Core Services  │  │ Living AI      │  │    AI Providers        │
│                │  │                │  │                        │
│ UserService    │  │ MoodService    │  │ OpenAI / Anthropic /   │
│ DatabaseService│  │ RelationshipSvc│  │ Gemini / OpenRouter    │
│ ConversationMgr│  │ FactExtraction │  │                        │
│ SearXNGService │  │ OpinionService │  │                        │
└────────────────┘  └────────────────┘  └────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                      PostgreSQL Database                         │
└─────────────────────────────────────────────────────────────────┘
```

---

## Documentation Structure

### Core Documentation

| File | Contents |
|------|----------|
| [architecture.md](architecture.md) | System architecture, design patterns, component interactions |
| [database.md](database.md) | Database schema, tables, indexes, relationships |
| [configuration.md](configuration.md) | All configuration options with examples |

### Living AI Deep Dives

| File | Contents |
|------|----------|
| [living-ai/README.md](living-ai/README.md) | Overview of all Living AI systems |
| [living-ai/mood-system.md](living-ai/mood-system.md) | Valence-arousal model, mood labels, decay |
| [living-ai/relationship-system.md](living-ai/relationship-system.md) | Relationship levels, scoring algorithm |
| [living-ai/fact-extraction.md](living-ai/fact-extraction.md) | AI-powered fact learning, deduplication |
| [living-ai/opinion-system.md](living-ai/opinion-system.md) | Topic sentiment, interest tracking |

### Developer Resources

| File | Contents |
|------|----------|
| [services/README.md](services/README.md) | Complete API reference for all services |
| [guides/README.md](guides/README.md) | How to add providers, commands, features |

---

## Key Concepts

### Message Flow

1. User @mentions the bot in Discord
2. `AIChatCog` receives the message
3. User context is built (name, facts, preferences)
4. Living AI context is gathered (mood, relationship, style, opinions)
5. Enhanced system prompt is constructed
6. AI provider generates response
7. Living AI systems are updated (mood, relationship, facts)
8. Response is sent to Discord

### Living AI Components

| Component | Purpose | Update Frequency |
|-----------|---------|------------------|
| **Mood** | Emotional state | Every interaction |
| **Relationship** | User familiarity | Every interaction |
| **Facts** | User knowledge | ~30% of messages |
| **Opinions** | Topic preferences | When topics discussed |
| **Style** | Communication preferences | Rolling 50 messages |

### Database Modes

| Mode | Configuration | Use Case |
|------|---------------|----------|
| **PostgreSQL** | `DATABASE_URL` set | Production, persistence |
| **In-Memory** | `DATABASE_URL` not set | Development, testing |

---

## Quick Start

### 1. Install

```bash
pip install -r requirements.txt
pip install -e .
```

### 2. Configure

```bash
# Minimum .env
DISCORD_TOKEN=your_token
OPENAI_API_KEY=your_key
```

### 3. Run

```bash
python -m loyal_companion
```

### 4. Interact

Mention the bot in Discord:
```
@Daemon Hello! How are you today?
```

---

## Commands Reference

### User Commands

| Command | Description |
|---------|-------------|
| `!setname <name>` | Set your preferred name |
| `!clearname` | Reset to Discord name |
| `!remember <fact>` | Tell the bot something about you |
| `!whatdoyouknow` | See what the bot remembers |
| `!forgetme` | Clear all your facts |
| `!relationship` | See your relationship status |
| `!mood` | See the bot's current mood |
| `!botstats` | View bot statistics |
| `!ourhistory` | See your history with the bot |
| `!birthday <date>` | Set your birthday |

### Admin Commands

| Command | Description |
|---------|-------------|
| `!setusername @user <name>` | Set name for another user |
| `!teachbot @user <fact>` | Add a fact about a user |
| `!status` | View bot health metrics |

---

## Support

- **Project Issues:** GitHub Issues
- **Documentation Updates:** Submit a PR

---

## Document Changelog

| Version | Date | Changes |
|---------|------|---------|
| 1.0 | 2024-01 | Initial documentation |