196 lines
7.8 KiB
Markdown
196 lines
7.8 KiB
Markdown
# 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 daemon_boyfriend
|
|
```
|
|
|
|
### 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 |
|