added technical documentation
This commit is contained in:
195
docs/README.md
Normal file
195
docs/README.md
Normal file
@@ -0,0 +1,195 @@
|
||||
# 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 |
|
||||
Reference in New Issue
Block a user