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-Platform Support**: Discord, Web browser, and CLI terminal access
- **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
- **Intimacy Levels**: Platform-appropriate behavior (LOW/MEDIUM/HIGH)
- **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. Choose your platform

#### Discord Bot

```bash
docker compose up -d
# Or locally:
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python -m loyal_companion
```

#### Web Platform

```bash
python3 run_web.py
# Visit http://localhost:8080
```

#### CLI Client

```bash
./lc talk
# Or: python3 lc talk
```

**See:** [Multi-Platform Documentation](docs/multi-platform-expansion.md) for detailed setup

## 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

## Multi-Platform Architecture

Loyal Companion supports three platforms, each with appropriate intimacy levels:

- **🎮 Discord** - The social bar (LOW/MEDIUM intimacy)
- **🌐 Web** - The quiet back room (HIGH intimacy)  
- **💻 CLI** - The empty table at closing (HIGH intimacy)

**Same bartender. Different stools. No one is trapped.**

See [MULTI_PLATFORM_COMPLETE.md](MULTI_PLATFORM_COMPLETE.md) for the complete architecture.

## Project Structure

```
src/loyal_companion/
├── bot.py              # Main bot class
├── config.py           # Configuration
├── cogs/
│   └── ai_chat.py      # Discord adapter (uses Conversation Gateway)
├── web/
│   ├── app.py          # FastAPI application
│   ├── routes/         # Web API endpoints
│   └── static/         # Web UI
├── models/
│   ├── platform.py     # Platform enums & ConversationRequest/Response
│   ├── platform_identity.py  # Cross-platform account linking
│   ├── user.py         # User, UserFact, UserPreference
│   ├── conversation.py # Conversation, Message
│   └── living_ai.py    # BotState, UserRelationship, Mood, etc.
└── services/
    ├── conversation_gateway.py   # Platform-agnostic processor
    ├── platform_identity_service.py  # Account linking
    ├── ai_service.py   # AI provider factory
    ├── mood_service.py # Mood system
    ├── relationship_service.py   # Relationship tracking
    └── fact_extraction_service.py # Autonomous learning

cli/
├── main.py             # Typer CLI application
├── client.py           # HTTP client for Web API
├── session.py          # Local session management
└── formatters.py       # Terminal formatting

tests/
├── test_safety_constraints.py   # A+C safety guardrails
├── test_intimacy_boundaries.py  # Intimacy level enforcement
└── test_load_performance.py     # Load and performance tests
```

## License

MIT