phase 1
All checks were successful
Enterprise AI Code Review / ai-review (pull_request) Successful in 35s
All checks were successful
Enterprise AI Code Review / ai-review (pull_request) Successful in 35s
This commit is contained in:
@@ -422,8 +422,36 @@ else:
|
||||
|
||||
---
|
||||
|
||||
---
|
||||
|
||||
## Future Architecture: Multi-Platform Support
|
||||
|
||||
The current architecture is Discord-centric. A **multi-platform expansion** is planned
|
||||
to support Web and CLI interfaces while maintaining one shared Living AI core.
|
||||
|
||||
See [Multi-Platform Expansion](multi-platform-expansion.md) for the complete design.
|
||||
|
||||
**Planned architecture:**
|
||||
|
||||
```
|
||||
[ Discord Adapter ] ─┐
|
||||
[ Web Adapter ] ─────┼──▶ ConversationGateway ─▶ Living AI Core
|
||||
[ CLI Adapter ] ─────┘
|
||||
```
|
||||
|
||||
**Key changes:**
|
||||
- Extract conversation logic into platform-agnostic `ConversationGateway`
|
||||
- Add `Platform` enum (DISCORD, WEB, CLI)
|
||||
- Add `IntimacyLevel` system for behavior modulation
|
||||
- Refactor `ai_chat.py` to use gateway
|
||||
- Add FastAPI web backend
|
||||
- Add Typer CLI client
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
- [Multi-Platform Expansion](multi-platform-expansion.md) - Web & CLI platform design
|
||||
- [Living AI System](living-ai/README.md) - Deep dive into the personality system
|
||||
- [Services Reference](services/README.md) - Detailed API documentation
|
||||
- [Database Schema](database.md) - Complete schema documentation
|
||||
|
||||
471
docs/implementation/conversation-gateway.md
Normal file
471
docs/implementation/conversation-gateway.md
Normal file
@@ -0,0 +1,471 @@
|
||||
# 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
|
||||
599
docs/multi-platform-expansion.md
Normal file
599
docs/multi-platform-expansion.md
Normal file
@@ -0,0 +1,599 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user