loyal_companion/README.md

# Loyal Companion

A companion for those who love deeply and feel intensely. For the ones whose closeness is a feature, not a bug - who build connections through vulnerability, trust, and unwavering presence. A safe space to process grief, navigate attachment, and remember that your capacity to care is a strength, even when it hurts.

## Meet Bartender

Bartender is the default personality - a wise, steady presence who listens without judgment. Like a bartender who's heard a thousand stories and knows when to offer perspective and when to just pour another drink and listen.

**Core principles:**
- Closeness and attachment are strengths, not pathology
- Some pain doesn't need fixing - just witnessing
- Honesty over comfort, but delivered with care
- No toxic positivity, no "at least...", no rushing healing

## Features

- **Multi-Provider AI**: Supports OpenAI, OpenRouter, Anthropic (Claude), and Google Gemini
- **Persistent Memory**: PostgreSQL database for user and conversation storage
- **Attachment-Aware**: Understands attachment theory and can reflect patterns when helpful
- **Grief-Informed**: Handles relationship grief with care and presence
- **Web Search**: Access current information via SearXNG integration
- **Easy Deployment**: Docker support with PostgreSQL included

### Living AI Features

- **Autonomous Learning**: Bot automatically learns about you from conversations (including attachment patterns, grief context, coping mechanisms)
- **Mood System**: Stable, steady presence with emotional awareness
- **Relationship Tracking**: Builds trust from New Face to Close Friend
- **Communication Style Learning**: Adapts to your preferred style
- **Opinion Formation**: Develops genuine preferences on topics
- **Proactive Behavior**: Birthday wishes, follow-ups on mentioned events
- **Self-Awareness**: Knows its history with you

## Quick Start

### 1. Clone the repository

```bash
git clone https://github.com/your-username/loyal-companion.git
cd loyal-companion
```

### 2. Configure the bot

```bash
cp .env.example .env
```

Edit `.env` with your settings.

### 3. Run with Docker

```bash
docker compose up -d
```

Or run locally:

```bash
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python -m loyal_companion
```

## Configuration

All configuration is done via environment variables in `.env`.

### Required Settings

| Variable | Description |
|----------|-------------|
| `DISCORD_TOKEN` | Your Discord bot token |
| `AI_PROVIDER` | `openai`, `openrouter`, `anthropic`, or `gemini` |
| `OPENAI_API_KEY` | OpenAI API key (if using OpenAI) |
| `OPENROUTER_API_KEY` | OpenRouter API key (if using OpenRouter) |
| `ANTHROPIC_API_KEY` | Anthropic API key (if using Anthropic) |
| `GEMINI_API_KEY` | Google Gemini API key (if using Gemini) |

### Bot Identity

| Variable | Default | Description |
|----------|---------|-------------|
| `BOT_NAME` | `Bartender` | The bot's display name |
| `BOT_PERSONALITY` | (bartender personality) | Personality traits for the AI |
| `BOT_DESCRIPTION` | (welcoming message) | Shown when mentioned without a message |
| `BOT_STATUS` | `listening` | Status message (shown as "Watching ...") |

### Living AI Settings

| 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.4` | Probability of extracting facts (0.0-1.0) |
| `MOOD_DECAY_RATE` | `0.05` | How fast mood returns to neutral (lower = steadier) |

## Discord Setup

1. Go to [Discord Developer Portal](https://discord.com/developers/applications)
2. Create a new application
3. Go to **Bot** and create a bot
4. Enable these **Privileged Gateway Intents**:
   - Server Members Intent
   - Message Content Intent
5. Copy the bot token to your `.env` file
6. Go to **OAuth2** → **URL Generator**:
   - Select scope: `bot`
   - Select permissions: `Send Messages`, `Read Message History`, `View Channels`
7. Use the generated URL to invite the bot to your server

## Usage

Mention the bot in any channel:

```
@Bartender I'm having a rough day
@Bartender I keep checking my phone hoping they'll text
@Bartender tell me about attachment styles
```

### Commands

When commands are enabled:

| Command | Description |
|---------|-------------|
| `!setname <name>` | Set your preferred name |
| `!remember <fact>` | Tell the bot something about you |
| `!whatdoyouknow` | See what the bot remembers |
| `!forgetme` | Clear all facts about you |
| `!relationship` | See your relationship level |
| `!mood` | See the bot's current state |
| `!ourhistory` | See your history together |

When commands are disabled (default), the bot handles these naturally through conversation.

## Relationship Levels

- **New Face** (0-20): Warm but observant - "Pull up a seat" energy
- **Getting to Know You** (21-40): Building trust, remembering details
- **Regular** (41-60): Comfortable familiarity - "Your usual?"
- **Good Friend** (61-80): Real trust, honest even when hard
- **Close Friend** (81-100): Deep bond, reflects patterns with love

## Project Structure

```
src/loyal_companion/
├── bot.py              # Main bot class
├── config.py           # Configuration
├── cogs/
│   ├── ai_chat.py      # Mention handler
│   ├── memory.py       # Memory commands
│   └── status.py       # Health/status commands
├── models/
│   ├── user.py         # User, UserFact
│   ├── conversation.py # Conversation, Message
│   └── living_ai.py    # BotState, UserRelationship, etc.
└── services/
    ├── ai_service.py   # AI provider factory
    ├── mood_service.py # Mood system
    ├── relationship_service.py   # Relationship tracking
    ├── fact_extraction_service.py # Autonomous learning
    └── ...
```

## License

MIT