# Conversation Gateway Implementation Guide

## Phase 1: Complete ✅

This document describes the Conversation Gateway implementation completed in Phase 1 of the multi-platform expansion.

---

## What Was Implemented

### 1. Platform Abstraction Models

**File:** `src/loyal_companion/models/platform.py`

Created core types for platform-agnostic conversation handling:

- **`Platform` enum:** DISCORD, WEB, CLI
- **`IntimacyLevel` enum:** LOW, MEDIUM, HIGH
- **`ConversationContext`:** Metadata about the conversation context
- **`ConversationRequest`:** Normalized input format from any platform
- **`ConversationResponse`:** Normalized output format to any platform
- **`MoodInfo`:** Mood metadata in responses
- **`RelationshipInfo`:** Relationship metadata in responses

**Key features:**
- Platform-agnostic data structures
- Explicit intimacy level modeling
- Rich context passing
- Response metadata for platform-specific formatting

---

### 2. Conversation Gateway Service

**File:** `src/loyal_companion/services/conversation_gateway.py`

Extracted core conversation logic into a reusable service:

```python
class ConversationGateway:
    async def process_message(
        request: ConversationRequest
    ) -> ConversationResponse
```

**Responsibilities:**
- Accept normalized `ConversationRequest` from any platform
- Load conversation history from database
- Gather Living AI context (mood, relationship, style, opinions)
- Apply intimacy-level-based prompt modifiers
- Invoke AI service
- Save conversation to database
- Update Living AI state asynchronously
- Return normalized `ConversationResponse`

**Key features:**
- Platform-agnostic processing
- Intimacy-aware behavior modulation
- Safety boundaries at all intimacy levels
- Async Living AI updates
- Sentiment estimation
- Fact extraction (respects intimacy level)
- Proactive event detection (respects intimacy level)

---

### 3. Intimacy Level System

**Behavior modulation by intimacy level:**

#### LOW (Discord Guilds)
- Brief, light responses
- No deep emotional topics
- No personal memory surfacing
- Minimal proactive behavior
- Grounding language only
- Public-safe topics

#### MEDIUM (Discord DMs)
- Balanced warmth and depth
- Personal memory references allowed
- Moderate emotional engagement
- Casual but caring tone
- Moderate proactive behavior

#### HIGH (Web, CLI)
- Deeper reflection permitted
- Emotional naming encouraged
- Silence tolerance
- Proactive follow-ups allowed
- Deep memory surfacing
- Thoughtful, considered responses

**Safety boundaries (enforced at ALL levels):**
- Never claim exclusivity
- Never reinforce dependency
- Never discourage external connections
- Always defer crisis situations
- No romantic/sexual framing

---

### 4. Service Integration

**File:** `src/loyal_companion/services/__init__.py`

- Exported `ConversationGateway` for use by adapters
- Maintained backward compatibility with existing services

---

## Architecture

```
┌─────────────────────────────────────────────────────────┐
│                  Platform Adapters                       │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐     │
│  │   Discord   │  │     Web     │  │     CLI     │     │
│  │   Adapter   │  │   Adapter   │  │   Adapter   │     │
│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘     │
└─────────┼─────────────────┼─────────────────┼───────────┘
          │                 │                 │
          └────────┬────────┴────────┬────────┘
                   ▼                 ▼
         ┌─────────────────────────────────────┐
         │     ConversationRequest             │
         │  - user_id                          │
         │  - platform                         │
         │  - message                          │
         │  - context (intimacy, metadata)     │
         └─────────────────────────────────────┘
                          │
                          ▼
         ┌─────────────────────────────────────┐
         │     ConversationGateway             │
         │                                      │
         │  1. Load conversation history        │
         │  2. Gather Living AI context         │
         │  3. Apply intimacy modifiers         │
         │  4. Build enhanced system prompt     │
         │  5. Invoke AI service                │
         │  6. Save conversation                │
         │  7. Update Living AI state           │
         └─────────────────────────────────────┘
                          │
                          ▼
         ┌─────────────────────────────────────┐
         │     ConversationResponse            │
         │  - response (text)                  │
         │  - mood (optional)                  │
         │  - relationship (optional)          │
         │  - extracted_facts (list)           │
         │  - platform_hints (dict)            │
         └─────────────────────────────────────┘
                          │
          ┌───────────────┼───────────────┐
          ▼               ▼               ▼
    ┌─────────┐    ┌─────────┐    ┌─────────┐
    │ Discord │    │   Web   │    │   CLI   │
    │ Format  │    │ Format  │    │ Format  │
    └─────────┘    └─────────┘    └─────────┘
```

---

## Usage Example

```python
from loyal_companion.models.platform import (
    ConversationContext,
    ConversationRequest,
    IntimacyLevel,
    Platform,
)
from loyal_companion.services import ConversationGateway

# Create gateway
gateway = ConversationGateway()

# Build request (from any platform)
request = ConversationRequest(
    user_id="discord:123456789",
    platform=Platform.DISCORD,
    session_id="channel-987654321",
    message="I'm feeling overwhelmed today",
    context=ConversationContext(
        is_public=False,
        intimacy_level=IntimacyLevel.MEDIUM,
        guild_id="12345",
        channel_id="987654321",
        user_display_name="Alice",
    ),
)

# Process message
response = await gateway.process_message(request)

# Use response
print(response.response)  # AI's reply
print(response.mood.label if response.mood else "No mood")
print(response.relationship.level if response.relationship else "No relationship")
```

---

## File Structure

```
loyal_companion/
├── src/loyal_companion/
│   ├── models/
│   │   └── platform.py                   # ✨ NEW: Platform abstractions
│   ├── services/
│   │   ├── conversation_gateway.py       # ✨ NEW: Gateway service
│   │   └── __init__.py                   # Updated: Export gateway
│   └── cogs/
│       └── ai_chat.py                    # Unchanged (Phase 2 will refactor)
├── docs/
│   ├── multi-platform-expansion.md       # ✨ NEW: Architecture doc
│   ├── architecture.md                   # Updated: Reference gateway
│   └── implementation/
│       └── conversation-gateway.md       # ✨ NEW: This file
├── tests/
│   └── test_conversation_gateway.py      # ✨ NEW: Gateway tests
└── verify_gateway.py                     # ✨ NEW: Verification script
```

---

## What's Next: Phase 2

**Goal:** Refactor Discord adapter to use the Conversation Gateway

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

**Changes:**
1. Import `ConversationGateway` and platform models
2. Replace `_generate_response_with_db()` with gateway call
3. Build `ConversationRequest` from Discord message
4. Map Discord context to `IntimacyLevel`:
   - Guild channels → LOW
   - DMs → MEDIUM
5. Format `ConversationResponse` for Discord output
6. Test that Discord functionality is unchanged

**Expected outcome:**
- Discord uses gateway internally
- No user-visible changes
- Gateway is proven to work
- Ready for Web and CLI platforms

---

## Testing Strategy

### Unit Tests (tests/test_conversation_gateway.py)

- Gateway initialization
- Request/response creation
- Enum values
- Intimacy modifiers
- Sentiment estimation
- Database requirement

### Integration Tests (Phase 2)

- Discord adapter using gateway
- History persistence
- Living AI updates
- Multi-turn conversations

### Verification Script (verify_gateway.py)

- Import verification
- Enum verification
- Request creation
- Gateway initialization
- Intimacy modifiers
- Sentiment estimation

---

## Configuration

No new configuration required for Phase 1.

Existing settings still apply:
- `LIVING_AI_ENABLED` - Master switch for Living AI features
- `MOOD_ENABLED` - Mood tracking
- `RELATIONSHIP_ENABLED` - Relationship tracking
- `FACT_EXTRACTION_ENABLED` - Autonomous fact learning
- `PROACTIVE_ENABLED` - Proactive events
- `STYLE_LEARNING_ENABLED` - Communication style adaptation
- `OPINION_FORMATION_ENABLED` - Topic opinion tracking

Phase 3 (Web) will add:
- `WEB_ENABLED`
- `WEB_HOST`
- `WEB_PORT`
- `WEB_AUTH_SECRET`

Phase 4 (CLI) will add:
- `CLI_ENABLED`
- `CLI_DEFAULT_INTIMACY`
- `CLI_ALLOW_EMOJI`

---

## Safety Considerations

### Intimacy-Based Constraints

The gateway enforces safety boundaries based on intimacy level:

**LOW intimacy:**
- No fact extraction (privacy)
- No proactive events (respect boundaries)
- No deep memory surfacing
- Surface-level engagement only

**MEDIUM intimacy:**
- Moderate fact extraction
- Limited proactive events
- Personal memory allowed
- Emotional validation permitted

**HIGH intimacy:**
- Full fact extraction
- Proactive follow-ups allowed
- Deep memory surfacing
- Emotional naming encouraged

**ALL levels enforce:**
- No exclusivity claims
- No dependency reinforcement
- No discouragement of external connections
- Professional boundaries maintained
- Crisis deferral to professionals

---

## Performance Considerations

### Database Requirements

The gateway **requires** a database connection. It will raise `ValueError` if `DATABASE_URL` is not configured.

This is intentional:
- Living AI state requires persistence
- Cross-platform identity requires linking
- Conversation history needs durability

### Async Operations

All gateway operations are async:
- Database queries
- AI invocations
- Living AI updates

Living AI updates happen after the response is returned, so they don't block the user experience.

---

## Known Limitations

### Phase 1 Limitations

1. **Discord-only:** Gateway exists but isn't used yet
2. **No cross-platform identity:** Each platform creates separate users
3. **No platform-specific features:** Discord images/embeds not supported in gateway yet

### To Be Addressed

**Phase 2:**
- Integrate with Discord adapter
- Add Discord-specific features to gateway (images, mentioned users)

**Phase 3:**
- Add Web platform
- Implement cross-platform user identity linking

**Phase 4:**
- Add CLI client
- Add CLI-specific formatting (no emojis, minimal output)

---

## Migration Path

### Current State (Phase 1 Complete)

```python
# Discord Cog (current)
async def _generate_response_with_db(message, user_message):
    # All logic inline
    # Discord-specific
    # Not reusable
```

### Phase 2 (Discord Refactor)

```python
# Discord Cog (refactored)
async def _generate_response_with_db(message, user_message):
    request = ConversationRequest(...)  # Build from Discord
    response = await gateway.process_message(request)
    return response.response  # Format for Discord
```

### Phase 3 (Web Platform Added)

```python
# Web API
@app.post("/chat")
async def chat(session_id: str, message: str):
    request = ConversationRequest(...)  # Build from Web
    response = await gateway.process_message(request)
    return response  # Return as JSON
```

### Phase 4 (CLI Platform Added)

```python
# CLI Client
async def talk(message: str):
    request = ConversationRequest(...)  # Build from CLI
    response = await http_client.post("/chat", request)
    print(response.response)  # Format for terminal
```

---

## Success Criteria

Phase 1 is considered complete when:

- ✅ Platform models created and documented
- ✅ ConversationGateway service implemented
- ✅ Intimacy level system implemented
- ✅ Safety boundaries enforced at all levels
- ✅ Services exported and importable
- ✅ Documentation updated
- ✅ Syntax validation passes

Phase 2 success criteria:
- Discord cog refactored to use gateway
- No regression in Discord functionality
- All existing tests pass
- Living AI updates still work

---

## Conclusion

Phase 1 successfully established the foundation for multi-platform support:

1. **Platform abstraction** - Clean separation of concerns
2. **Intimacy system** - Behavior modulation for different contexts
3. **Safety boundaries** - Consistent across all platforms
4. **Reusable gateway** - Ready for Discord, Web, and CLI

The architecture is now ready for Phase 2 (Discord refactor) and Phase 3 (Web platform).

Same bartender. Different stools. No one is trapped.

---

**Last updated:** 2026-01-31  
**Status:** Phase 1 Complete ✅  
**Next:** Phase 2 - Discord Refactor