loyal_companion/docs/multi-platform-expansion.md

# Multi-Platform Expansion
## Adding Web & CLI Interfaces

This document extends the Loyal Companion architecture beyond Discord.
The goal is to support **Web** and **CLI** interaction channels while preserving:

- one shared Living AI core
- consistent personality & memory
- attachment-safe A+C hybrid behavior
- clear separation between platform and cognition

---

## 1. Core Principle

**Platforms are adapters, not identities.**

Discord, Web, and CLI are merely different rooms
through which the same companion is accessed.

The companion:
- remains one continuous entity
- may adjust tone by platform
- never fragments into separate personalities

---

## 2. New Architectural Layer: Conversation Gateway

### Purpose

Introduce a single entry point for **all conversations**, regardless of platform.

```text
[ Discord Adapter ] ─┐
[ Web Adapter ] ─────┼──▶ ConversationGateway ─▶ Living AI Core
[ CLI Adapter ] ─────┘
```

### Responsibilities

The Conversation Gateway:

* normalizes incoming messages
* assigns platform metadata
* invokes the existing AI + Living AI pipeline
* returns responses in a platform-agnostic format

### Required Data Structure

```python
@dataclass
class ConversationRequest:
    user_id: str                    # Platform-specific user ID
    platform: Platform              # Enum: DISCORD | WEB | CLI
    session_id: str                 # Conversation/channel identifier
    message: str                    # User's message content
    context: ConversationContext    # Additional metadata

@dataclass
class ConversationContext:
    is_public: bool                 # Public channel vs private
    intimacy_level: IntimacyLevel   # LOW | MEDIUM | HIGH
    platform_metadata: dict         # Platform-specific extras
    guild_id: str | None = None     # Discord guild (if applicable)
    channel_id: str | None = None   # Discord/Web channel
```

### Current Implementation Location

**Existing message handling:** `src/loyal_companion/cogs/ai_chat.py`

The current `_generate_response_with_db()` method contains all the logic
that will be extracted into the Conversation Gateway:

- History loading
- Living AI context gathering (mood, relationship, style, opinions)
- System prompt enhancement
- AI invocation
- Post-response Living AI updates

**Goal:** Extract this into a platform-agnostic service layer.

---

## 3. Platform Metadata & Intimacy Levels

### Intimacy Levels (Important for A+C Safety)

Intimacy level influences:

* language warmth
* depth of reflection
* frequency of proactive behavior
* memory surfacing

| Platform        | Default Intimacy | Notes                    |
| --------------- | ---------------- | ------------------------ |
| Discord (guild) | LOW              | Social, public, shared   |
| Discord (DM)    | MEDIUM           | Private but casual       |
| Web             | HIGH             | Intentional, reflective  |
| CLI             | HIGH             | Quiet, personal, focused |

### Intimacy Level Behavior Modifiers

**LOW (Discord Guild):**
- Less emotional intensity
- More grounding language
- Minimal proactive behavior
- Surface-level memory recall only
- Shorter responses
- Public-safe topics only

**MEDIUM (Discord DM):**
- Balanced warmth
- Casual tone
- Moderate proactive behavior
- Personal memory recall allowed
- Normal response length

**HIGH (Web/CLI):**
- Deeper reflection permitted
- Silence tolerance (not rushing to respond)
- Proactive check-ins allowed
- Deep memory surfacing
- Longer, more thoughtful responses
- Emotional naming encouraged

---

## 4. Web Platform

### Goal

Provide a **private, 1-on-1 chat interface**
for deeper, quieter conversations than Discord allows.

### Architecture

* Backend: FastAPI (async Python web framework)
* Transport: HTTP REST + optional WebSocket
* Auth: Magic link / JWT token / local account
* No guilds, no other users visible
* Session persistence via database

### Backend Components

#### New API Module Structure

```
src/loyal_companion/web/
├── __init__.py
├── app.py                  # FastAPI application factory
├── dependencies.py         # Dependency injection (DB sessions, auth)
├── middleware.py           # CORS, rate limiting, error handling
├── routes/
│   ├── __init__.py
│   ├── chat.py             # POST /chat, WebSocket /ws
│   ├── session.py          # GET/POST /sessions
│   ├── history.py          # GET /sessions/{id}/history
│   └── auth.py             # POST /auth/login, /auth/verify
├── models.py               # Pydantic request/response models
└── adapter.py              # Web → ConversationGateway adapter
```

#### Chat Flow

1. User sends message via web UI
2. Web adapter creates `ConversationRequest`
3. `ConversationGateway.process_message()` invoked
4. Living AI generates response
5. Response returned as JSON

#### Example API Request

**POST /chat**

```json
{
  "session_id": "abc123",
  "message": "I'm having a hard evening."
}
```

**Response:**

```json
{
  "response": "That sounds heavy. Want to sit with it for a bit?",
  "mood": {
    "label": "calm",
    "valence": 0.2,
    "arousal": -0.3
  },
  "relationship_level": "close_friend"
}
```

#### Authentication

**Phase 1:** Simple token-based auth
- User registers with email
- Server sends magic link
- Token stored in HTTP-only cookie

**Phase 2:** Optional OAuth integration

### UI Considerations (Out of Scope for Core)

The web UI should:
- Use minimal chat bubbles (user left, bot right)
- Avoid typing indicators from others (no other users)
- Optional timestamps
- No engagement metrics (likes, seen, read receipts)
- No "X is typing..." unless real-time WebSocket
- Dark mode default

**Recommended stack:**
- Frontend: SvelteKit / React / Vue
- Styling: TailwindCSS
- Real-time: WebSocket for live chat

---

## 5. CLI Platform

### Goal

A **local, quiet, terminal-based interface**
for people who want presence without noise.

### Invocation

```bash
loyal-companion talk
```

or (short alias):

```bash
lc talk
```

### CLI Behavior

* Single ongoing session by default
* Optional named sessions (`lc talk --session work`)
* No emojis unless explicitly enabled
* Text-first, reflective tone
* Minimal output (no spinners, no progress bars)
* Supports piping and scripting

### Architecture

CLI is a **thin client**, not the AI itself.
It communicates with the web backend via HTTP.

```
cli/
├── __init__.py
├── main.py             # Typer CLI app entry point
├── client.py           # HTTP client for web backend
├── session.py          # Local session persistence (.lc/sessions.json)
├── config.py           # CLI-specific config (~/.lc/config.toml)
└── formatters.py       # Response formatting for terminal
```

### Session Management

Sessions are stored locally:

```
~/.lc/
├── config.toml         # API endpoint, auth token, preferences
└── sessions.json       # Session ID → metadata mapping
```

**Session lifecycle:**

1. First `lc talk` → creates default session, stores ID locally
2. Subsequent calls → reuses session ID
3. `lc talk --new` → starts fresh session
4. `lc talk --session work` → named session

### Example Interaction

```text
$ lc talk
Bartender is here.

You: I miss someone tonight.

Bartender: That kind of missing doesn't ask to be solved.
           Do you want to talk about what it feels like in your body,
           or just let it be here for a moment?

You: Just let it be.

Bartender: Alright. I'm here.

You: ^D

Session saved.
```

### CLI Commands

| Command | Purpose |
|---------|---------|
| `lc talk` | Start/resume conversation |
| `lc talk --session <name>` | Named session |
| `lc talk --new` | Start fresh session |
| `lc history` | Show recent exchanges |
| `lc sessions` | List all sessions |
| `lc config` | Show/edit configuration |
| `lc auth` | Authenticate with server |

---

## 6. Shared Identity & Memory

### Relationship Model

All platforms share:

* the same `User` record (keyed by platform-specific ID)
* the same `UserRelationship`
* the same long-term memory (`UserFact`)
* the same mood history

But:

* **contextual behavior varies** by intimacy level
* **expression adapts** to platform norms
* **intensity is capped** per platform

### Cross-Platform User Identity

**Challenge:** A user on Discord and CLI are the same person.

**Solution:**

1. Each platform creates a `User` record with platform-specific ID
2. Introduce `PlatformIdentity` linking model

```python
class PlatformIdentity(Base):
    __tablename__ = "platform_identities"
    
    id: Mapped[int] = mapped_column(primary_key=True)
    user_id: Mapped[int] = mapped_column(ForeignKey("users.id"))
    platform: Mapped[Platform] = mapped_column(Enum(Platform))
    platform_user_id: Mapped[str] = mapped_column(String, unique=True)
    
    user: Mapped["User"] = relationship(back_populates="identities")
```

**Later enhancement:** Account linking UI for users to connect platforms.

### Example Cross-Platform Memory Surfacing

A memory learned via CLI:

> "User tends to feel lonelier at night."

May surface on Web (HIGH intimacy):

> "You've mentioned nights can feel heavier for you."

But **not** in Discord guild chat (LOW intimacy).

---

## 7. Safety Rules per Platform

### Web & CLI (HIGH Intimacy)

**Allowed:**
- Deeper reflection
- Naming emotions ("That sounds like grief")
- Silence tolerance (not rushing responses)
- Proactive follow-ups ("You mentioned feeling stuck yesterday—how's that today?")

**Still forbidden:**
- Exclusivity claims ("I'm the only one who truly gets you")
- Dependency reinforcement ("You need me")
- Discouraging external connection ("They don't understand like I do")
- Romantic/sexual framing
- Crisis intervention (always defer to professionals)

### Discord DM (MEDIUM Intimacy)

**Allowed:**
- Personal memory references
- Emotional validation
- Moderate warmth

**Constraints:**
- Less proactive behavior than Web/CLI
- Lighter tone
- Shorter responses

### Discord Guild (LOW Intimacy)

**Allowed:**
- Light banter
- Topic-based conversation
- Public-safe responses

**Additional constraints:**
- No personal memory surfacing
- No emotional intensity
- No proactive check-ins
- Grounding language only
- Short responses

---

## 8. Configuration Additions

### New Settings (config.py)

```python
# Platform Toggles
web_enabled: bool = True
cli_enabled: bool = True

# Web Server
web_host: str = "127.0.0.1"
web_port: int = 8080
web_cors_origins: list[str] = ["http://localhost:3000"]
web_auth_secret: str = Field(..., env="WEB_AUTH_SECRET")

# CLI
cli_default_intimacy: IntimacyLevel = IntimacyLevel.HIGH
cli_allow_emoji: bool = False

# Intimacy Scaling
intimacy_enabled: bool = True
intimacy_discord_guild: IntimacyLevel = IntimacyLevel.LOW
intimacy_discord_dm: IntimacyLevel = IntimacyLevel.MEDIUM
intimacy_web: IntimacyLevel = IntimacyLevel.HIGH
intimacy_cli: IntimacyLevel = IntimacyLevel.HIGH
```

### Environment Variables

```env
# Platform Toggles
WEB_ENABLED=true
CLI_ENABLED=true

# Web
WEB_HOST=127.0.0.1
WEB_PORT=8080
WEB_AUTH_SECRET=<random-secret>

# CLI
CLI_DEFAULT_INTIMACY=high
CLI_ALLOW_EMOJI=false
```

---

## 9. Implementation Order

### Phase 1: Extract Conversation Gateway ✅

**Goal:** Create platform-agnostic conversation processor

**Files to create:**
- `src/loyal_companion/services/conversation_gateway.py`
- `src/loyal_companion/models/platform.py` (enums, request/response types)

**Tasks:**
1. Define `Platform` enum (DISCORD, WEB, CLI)
2. Define `IntimacyLevel` enum (LOW, MEDIUM, HIGH)
3. Define `ConversationRequest` and `ConversationResponse` dataclasses
4. Extract logic from `cogs/ai_chat.py` into gateway
5. Add intimacy-level-based prompt modifiers

### Phase 2: Refactor Discord to Use Gateway ✅

**Files to modify:**
- `src/loyal_companion/cogs/ai_chat.py`

**Tasks:**
1. Import `ConversationGateway`
2. Replace `_generate_response_with_db()` with gateway call
3. Build `ConversationRequest` from Discord message
4. Format `ConversationResponse` for Discord output
5. Test that Discord functionality unchanged

### Phase 3: Add Web Platform 🌐

**Files to create:**
- `src/loyal_companion/web/` (entire module)
- `src/loyal_companion/web/app.py`
- `src/loyal_companion/web/routes/chat.py`

**Tasks:**
1. Set up FastAPI application
2. Add authentication middleware
3. Create `/chat` endpoint
4. Create WebSocket endpoint (optional)
5. Add session management
6. Test with Postman/curl

### Phase 4: Add CLI Client 💻

**Files to create:**
- `cli/` (new top-level directory)
- `cli/main.py`
- `cli/client.py`

**Tasks:**
1. Create Typer CLI app
2. Add `talk` command
3. Add local session persistence
4. Add authentication flow
5. Test end-to-end with web backend

### Phase 5: Intimacy Scaling 🔒

**Files to create:**
- `src/loyal_companion/services/intimacy_service.py`

**Tasks:**
1. Define intimacy level behavior modifiers
2. Modify system prompt based on intimacy
3. Filter proactive behavior by intimacy
4. Add memory surfacing rules
5. Add safety constraint enforcement

### Phase 6: Safety Regression Tests 🛡️

**Files to create:**
- `tests/test_safety_constraints.py`
- `tests/test_intimacy_boundaries.py`

**Tasks:**
1. Test no exclusivity claims at any intimacy level
2. Test no dependency reinforcement
3. Test intimacy boundaries respected
4. Test proactive behavior filtered by platform
5. Test memory surfacing respects intimacy

---

## 10. Non-Goals

This expansion does NOT aim to:

* Duplicate Discord features (guilds, threads, reactions)
* Introduce social feeds or timelines
* Add notifications or engagement streaks
* Increase engagement artificially
* Create a "social network"
* Add gamification mechanics

The goal is **availability**, not addiction.

---

## 11. Outcome

When complete:

* **Discord is the social bar** — casual, public, low-commitment
* **Web is the quiet back room** — intentional, private, reflective
* **CLI is the empty table at closing time** — minimal, focused, silent presence

Same bartender.
Different stools.
No one is trapped.

---

## 12. Current Implementation Status

### Completed
- ❌ None yet

### In Progress
- 🔄 Documentation update
- 🔄 Phase 1: Conversation Gateway extraction

### Planned
- ⏳ Phase 2: Discord refactor
- ⏳ Phase 3: Web platform
- ⏳ Phase 4: CLI client
- ⏳ Phase 5: Intimacy scaling
- ⏳ Phase 6: Safety tests

---

## Next Steps

See [Implementation Guide](implementation/conversation-gateway.md) for detailed Phase 1 instructions.