added technical documentation
This commit is contained in:
301
docs/living-ai/README.md
Normal file
301
docs/living-ai/README.md
Normal file
@@ -0,0 +1,301 @@
|
||||
# Living AI System
|
||||
|
||||
The Living AI system gives the bot personality, emotional depth, and relationship awareness. It transforms a simple chatbot into a character that learns, remembers, and evolves through interactions.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [Overview](#overview)
|
||||
- [System Components](#system-components)
|
||||
- [How It Works Together](#how-it-works-together)
|
||||
- [Feature Toggle Reference](#feature-toggle-reference)
|
||||
|
||||
## Overview
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────────────────┐
|
||||
│ Living AI System │
|
||||
├─────────────────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
|
||||
│ │ Mood │ │ Relationship │ │ Fact │ │ Opinion │ │
|
||||
│ │ System │ │ System │ │ Extraction │ │ System │ │
|
||||
│ │ │ │ │ │ │ │ │ │
|
||||
│ │ Valence + │ │ 5 levels │ │ AI-based │ │ Topic │ │
|
||||
│ │ Arousal │ │ 0-100 score │ │ learning │ │ sentiments │ │
|
||||
│ └──────────────┘ └──────────────┘ └──────────────┘ └──────────────┘ │
|
||||
│ │
|
||||
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
|
||||
│ │Communication │ │ Proactive │ │ Association │ │ Self │ │
|
||||
│ │ Style │ │ Events │ │ System │ │ Awareness │ │
|
||||
│ │ │ │ │ │ │ │ │ │
|
||||
│ │ Learned │ │ Birthdays, │ │ Cross-user │ │ Stats, │ │
|
||||
│ │ preferences │ │ follow-ups │ │ memory │ │ reflection │ │
|
||||
│ └──────────────┘ └──────────────┘ └──────────────┘ └──────────────┘ │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## System Components
|
||||
|
||||
### 1. Mood System
|
||||
**File:** `services/mood_service.py`
|
||||
**Documentation:** [mood-system.md](mood-system.md)
|
||||
|
||||
The bot has emotions that affect how it responds. Uses a valence-arousal psychological model:
|
||||
|
||||
- **Valence** (-1 to +1): Negative to positive emotional state
|
||||
- **Arousal** (-1 to +1): Calm to excited energy level
|
||||
|
||||
**Mood Labels:**
|
||||
| Valence | Arousal | Label |
|
||||
|---------|---------|-------|
|
||||
| High | High | Excited |
|
||||
| High | Low | Happy |
|
||||
| Neutral | Low | Calm |
|
||||
| Neutral | Neutral | Neutral |
|
||||
| Low | Low | Bored |
|
||||
| Low | High | Annoyed |
|
||||
| Neutral | High | Curious |
|
||||
|
||||
**Key Features:**
|
||||
- Time decay: Mood gradually returns to neutral
|
||||
- Inertia: Changes are dampened (30% absorption rate)
|
||||
- Mood affects response style via prompt modifiers
|
||||
|
||||
---
|
||||
|
||||
### 2. Relationship System
|
||||
**File:** `services/relationship_service.py`
|
||||
**Documentation:** [relationship-system.md](relationship-system.md)
|
||||
|
||||
Tracks relationship depth with each user:
|
||||
|
||||
| Score | Level | Behavior |
|
||||
|-------|-------|----------|
|
||||
| 0-20 | Stranger | Polite, formal |
|
||||
| 21-40 | Acquaintance | Friendly, reserved |
|
||||
| 41-60 | Friend | Casual, warm |
|
||||
| 61-80 | Good Friend | Personal, references past |
|
||||
| 81-100 | Close Friend | Very casual, inside jokes |
|
||||
|
||||
**Relationship Score Factors:**
|
||||
- Interaction sentiment (+/- 0.5 base)
|
||||
- Message length (up to +0.3 bonus)
|
||||
- Conversation depth (up to +0.2 bonus)
|
||||
- Minimum interaction bonus (+0.1)
|
||||
|
||||
---
|
||||
|
||||
### 3. Fact Extraction System
|
||||
**File:** `services/fact_extraction_service.py`
|
||||
**Documentation:** [fact-extraction.md](fact-extraction.md)
|
||||
|
||||
Autonomously learns facts about users from conversations:
|
||||
|
||||
**Fact Types:**
|
||||
- `hobby` - Activities and interests
|
||||
- `work` - Job, career, professional life
|
||||
- `family` - Family members and relationships
|
||||
- `preference` - Likes, dislikes, preferences
|
||||
- `location` - Where they live, travel to
|
||||
- `event` - Important life events
|
||||
- `relationship` - Personal relationships
|
||||
- `general` - Other facts
|
||||
|
||||
**Extraction Process:**
|
||||
1. Rate-limited (default 30% of messages)
|
||||
2. AI analyzes message for extractable facts
|
||||
3. Deduplication against existing facts
|
||||
4. Facts stored with confidence and importance scores
|
||||
|
||||
---
|
||||
|
||||
### 4. Opinion System
|
||||
**File:** `services/opinion_service.py`
|
||||
**Documentation:** [opinion-system.md](opinion-system.md)
|
||||
|
||||
Bot develops opinions on topics over time:
|
||||
|
||||
**Opinion Attributes:**
|
||||
- **Sentiment** (-1 to +1): How positive/negative about the topic
|
||||
- **Interest Level** (0 to 1): How engaged when discussing
|
||||
- **Discussion Count**: How often topic has come up
|
||||
- **Reasoning**: AI-generated explanation (optional)
|
||||
|
||||
**Topic Detection:**
|
||||
Simple keyword-based extraction for categories like:
|
||||
- Hobbies (gaming, music, movies, etc.)
|
||||
- Technology (programming, AI, etc.)
|
||||
- Life (work, family, health, etc.)
|
||||
- Interests (philosophy, science, nature, etc.)
|
||||
|
||||
---
|
||||
|
||||
### 5. Communication Style System
|
||||
**File:** `services/communication_style_service.py`
|
||||
|
||||
Learns each user's preferred communication style:
|
||||
|
||||
**Tracked Preferences:**
|
||||
- **Response Length**: short / medium / long
|
||||
- **Formality**: 0 (casual) to 1 (formal)
|
||||
- **Emoji Usage**: 0 (none) to 1 (frequent)
|
||||
- **Humor Level**: 0 (serious) to 1 (playful)
|
||||
- **Detail Level**: 0 (brief) to 1 (thorough)
|
||||
|
||||
**Learning Process:**
|
||||
- Analyzes last 50 messages (rolling window)
|
||||
- Requires 10+ samples for confidence > 0.3
|
||||
- Generates prompt modifiers to adapt response style
|
||||
|
||||
---
|
||||
|
||||
### 6. Proactive Events System
|
||||
**File:** `services/proactive_service.py`
|
||||
|
||||
Schedules and triggers proactive messages:
|
||||
|
||||
**Event Types:**
|
||||
- **Birthday**: Remembers and celebrates birthdays
|
||||
- **Follow-up**: Returns to check on mentioned events
|
||||
- **Reminder**: General scheduled reminders
|
||||
|
||||
**Detection Methods:**
|
||||
- Birthday: Regex patterns for dates
|
||||
- Follow-up: AI-based event detection or keyword matching
|
||||
|
||||
**Event Lifecycle:**
|
||||
1. Detection from conversation
|
||||
2. Scheduled in database
|
||||
3. Triggered when due
|
||||
4. Personalized message generated
|
||||
|
||||
---
|
||||
|
||||
### 7. Association System
|
||||
**File:** `services/association_service.py`
|
||||
|
||||
Links facts across different users (optional, disabled by default):
|
||||
|
||||
**Use Cases:**
|
||||
- "User A and User B both work at the same company"
|
||||
- "Multiple users share an interest in hiking"
|
||||
- Enables group context and shared topic suggestions
|
||||
|
||||
---
|
||||
|
||||
### 8. Self-Awareness System
|
||||
**File:** `services/self_awareness_service.py`
|
||||
|
||||
Provides the bot with statistics about itself:
|
||||
|
||||
**Available Stats:**
|
||||
- Age (time since first activation)
|
||||
- Total messages sent
|
||||
- Total facts learned
|
||||
- Total users known
|
||||
- Favorite topics (from opinions)
|
||||
|
||||
Used for the `!botstats` command and self-reflection in responses.
|
||||
|
||||
---
|
||||
|
||||
## How It Works Together
|
||||
|
||||
When a user sends a message, the Living AI components work together:
|
||||
|
||||
```
|
||||
┌──────────────────────────────────────────────────────────────────────────────┐
|
||||
│ Message Processing │
|
||||
└──────────────────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
┌───────────────┼───────────────┐
|
||||
▼ ▼ ▼
|
||||
┌──────────────┐┌──────────────┐┌──────────────┐
|
||||
│ Get Mood ││Get Relationship│ Get Style │
|
||||
│ ││ ││ │
|
||||
│ Current state││ Level + refs ││ Preferences │
|
||||
└──────────────┘└──────────────┘└──────────────┘
|
||||
│ │ │
|
||||
└───────────────┼───────────────┘
|
||||
▼
|
||||
┌──────────────────────────────────────┐
|
||||
│ Build Enhanced System Prompt │
|
||||
│ │
|
||||
│ Base personality + mood modifier + │
|
||||
│ relationship context + style prefs + │
|
||||
│ relevant opinions │
|
||||
└──────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌──────────────────────────────────────┐
|
||||
│ Generate Response │
|
||||
└──────────────────────────────────────┘
|
||||
│
|
||||
┌───────────────┼───────────────┐
|
||||
▼ ▼ ▼
|
||||
┌──────────────┐┌──────────────┐┌──────────────┐
|
||||
│ Update Mood ││ Record ││ Maybe │
|
||||
│ ││ Interaction ││Extract Facts │
|
||||
│Sentiment + ││ ││ │
|
||||
│arousal delta ││Score update ││ Rate-limited │
|
||||
└──────────────┘└──────────────┘└──────────────┘
|
||||
│
|
||||
▼
|
||||
┌──────────────────────────────────────┐
|
||||
│ Check for Proactive Events │
|
||||
│ │
|
||||
│ Detect birthdays, follow-ups │
|
||||
└──────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### Example System Prompt Enhancement
|
||||
|
||||
```
|
||||
[Base Personality]
|
||||
You are Daemon, a friendly AI companion...
|
||||
|
||||
[Mood Modifier]
|
||||
You're feeling enthusiastic and energetic right now! Be expressive,
|
||||
use exclamation marks, show genuine excitement.
|
||||
|
||||
[Relationship Context]
|
||||
This is a good friend you know well. Be relaxed and personal.
|
||||
Reference things you've talked about before. Feel free to be playful.
|
||||
You have inside jokes together: "the coffee incident".
|
||||
|
||||
[Communication Style]
|
||||
This user prefers longer, detailed responses with some humor.
|
||||
They use casual language, so match their tone.
|
||||
|
||||
[Relevant Opinions]
|
||||
You really enjoy discussing programming; You find gaming interesting.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Feature Toggle Reference
|
||||
|
||||
All Living AI features can be individually enabled/disabled:
|
||||
|
||||
| Environment Variable | Default | Description |
|
||||
|---------------------|---------|-------------|
|
||||
| `LIVING_AI_ENABLED` | `true` | Master switch for all Living AI features |
|
||||
| `MOOD_ENABLED` | `true` | Enable mood system |
|
||||
| `RELATIONSHIP_ENABLED` | `true` | Enable relationship tracking |
|
||||
| `FACT_EXTRACTION_ENABLED` | `true` | Enable autonomous fact extraction |
|
||||
| `FACT_EXTRACTION_RATE` | `0.3` | Probability of extracting facts (0-1) |
|
||||
| `PROACTIVE_ENABLED` | `true` | Enable proactive messages |
|
||||
| `CROSS_USER_ENABLED` | `false` | Enable cross-user associations |
|
||||
| `OPINION_FORMATION_ENABLED` | `true` | Enable opinion formation |
|
||||
| `STYLE_LEARNING_ENABLED` | `true` | Enable communication style learning |
|
||||
| `MOOD_DECAY_RATE` | `0.1` | How fast mood returns to neutral (per hour) |
|
||||
|
||||
---
|
||||
|
||||
## Detailed Documentation
|
||||
|
||||
- [Mood System Deep Dive](mood-system.md)
|
||||
- [Relationship System Deep Dive](relationship-system.md)
|
||||
- [Fact Extraction Deep Dive](fact-extraction.md)
|
||||
- [Opinion System Deep Dive](opinion-system.md)
|
||||
Reference in New Issue
Block a user