phase 1 #4

This PR introduces the foundational architecture and implementation for multi-platform support, enabling the Loyal Companion AI to operate across Discord, Web, and CLI interfaces through a new Conversation Gateway service. It establishes platform-agnostic abstractions, an intimacy-level system for behavior modulation, and documents the phased migration plan to integrate these changes.

Type: ✨ Feature

Changes

✅ Added:

ConversationGateway service for platform-agnostic conversation processing
Platform abstraction models including Platform and IntimacyLevel enums
Intimacy level system to modulate AI behavior based on context
FastAPI-based Web backend and Typer CLI client (planned in docs)
Extensive documentation for multi-platform architecture and implementation
Unit tests and verification scripts for the Conversation Gateway

📝 Modified:

docs/architecture.md to include multi-platform support overview
src/loyal_companion/services/init.py to export ConversationGateway

Files Affected

📝 docs/architecture.md - Updated architecture documentation to introduce multi-platform support and the Conversation Gateway concept
➕ docs/implementation/conversation-gateway.md - New detailed implementation guide for the Conversation Gateway service, platform models, intimacy system, and phased migration
➕ docs/multi-platform-expansion.md - New comprehensive design document outlining Web and CLI platform integration, architecture, and behavior considerations
➕ src/loyal_companion/models/platform.py - New platform-agnostic data models including Platform and IntimacyLevel enums and conversation request/response structures
➕ src/loyal_companion/services/conversation_gateway.py - New ConversationGateway service implementing core conversation logic abstracted from platform specifics
📝 src/loyal_companion/services/__init__.py - Modified to export the new ConversationGateway service
➕ tests/test_conversation_gateway.py - New unit tests covering ConversationGateway initialization, enums, intimacy modifiers, and sentiment estimation
➕ verify_gateway.py - New verification script for ConversationGateway imports, enums, and processing logic

Impact

🔴 Scope: Large
These changes establish a new architectural layer enabling multi-platform support, significantly affecting core conversation handling and future platform integrations. The Conversation Gateway centralizes AI logic, improving maintainability and extensibility, while the intimacy system enhances safety and user experience across contexts. This foundational work will require careful integration and testing in subsequent phases to ensure backward compatibility and feature parity.

## 📋 Pull Request Summary This PR introduces the foundational architecture and implementation for multi-platform support, enabling the Loyal Companion AI to operate across Discord, Web, and CLI interfaces through a new Conversation Gateway service. It establishes platform-agnostic abstractions, an intimacy-level system for behavior modulation, and documents the phased migration plan to integrate these changes. **Type:** ✨ Feature ## Changes **✅ Added:** - ConversationGateway service for platform-agnostic conversation processing - Platform abstraction models including Platform and IntimacyLevel enums - Intimacy level system to modulate AI behavior based on context - FastAPI-based Web backend and Typer CLI client (planned in docs) - Extensive documentation for multi-platform architecture and implementation - Unit tests and verification scripts for the Conversation Gateway **📝 Modified:** - docs/architecture.md to include multi-platform support overview - src/loyal_companion/services/__init__.py to export ConversationGateway ## Files Affected - 📝 `docs/architecture.md` - Updated architecture documentation to introduce multi-platform support and the Conversation Gateway concept - ➕ `docs/implementation/conversation-gateway.md` - New detailed implementation guide for the Conversation Gateway service, platform models, intimacy system, and phased migration - ➕ `docs/multi-platform-expansion.md` - New comprehensive design document outlining Web and CLI platform integration, architecture, and behavior considerations - ➕ `src/loyal_companion/models/platform.py` - New platform-agnostic data models including Platform and IntimacyLevel enums and conversation request/response structures - ➕ `src/loyal_companion/services/conversation_gateway.py` - New ConversationGateway service implementing core conversation logic abstracted from platform specifics - 📝 `src/loyal_companion/services/__init__.py` - Modified to export the new ConversationGateway service - ➕ `tests/test_conversation_gateway.py` - New unit tests covering ConversationGateway initialization, enums, intimacy modifiers, and sentiment estimation - ➕ `verify_gateway.py` - New verification script for ConversationGateway imports, enums, and processing logic ## Impact 🔴 **Scope:** Large These changes establish a new architectural layer enabling multi-platform support, significantly affecting core conversation handling and future platform integrations. The Conversation Gateway centralizes AI logic, improving maintainability and extensibility, while the intimacy system enhances safety and user experience across contexts. This foundational work will require careful integration and testing in subsequent phases to ensure backward compatibility and feature parity.

Bartender reviewed 2026-01-31 17:49:56 +00:00

Bartender left a comment

AI Code Review - Inline Comments

docs/implementation/conversation-gateway.md

Bartender commented

2026-01-31 17:49:55 +00:00

[LOW] Maintainability

The ConversationGateway service is described as async and performing multiple sequential steps including DB queries, AI invocation, and state updates. However, the document does not explicitly mention error handling or retry strategies for failures in any of these async steps, which could lead to partial failures or inconsistent state.

Recommendation: Add explicit documentation on error handling, retries, and fallback mechanisms within the ConversationGateway service to ensure robustness and easier maintenance.

**[LOW] Maintainability** The ConversationGateway service is described as async and performing multiple sequential steps including DB queries, AI invocation, and state updates. However, the document does not explicitly mention error handling or retry strategies for failures in any of these async steps, which could lead to partial failures or inconsistent state. **Recommendation:** Add explicit documentation on error handling, retries, and fallback mechanisms within the ConversationGateway service to ensure robustness and easier maintenance.

Bartender commented

2026-01-31 17:49:55 +00:00

[LOW] Readability

The IntimacyLevel enum and its behavioral modifiers are well documented, but the mapping from platform/channel type to intimacy level is only described in prose and example code in Phase 2. This could lead to inconsistent implementations across adapters.

Recommendation: Consider centralizing the platform-to-intimacy-level mapping logic in a shared utility or configuration to ensure consistent behavior across all adapters and reduce duplication.

**[LOW] Readability** The IntimacyLevel enum and its behavioral modifiers are well documented, but the mapping from platform/channel type to intimacy level is only described in prose and example code in Phase 2. This could lead to inconsistent implementations across adapters. **Recommendation:** Consider centralizing the platform-to-intimacy-level mapping logic in a shared utility or configuration to ensure consistent behavior across all adapters and reduce duplication.

Bartender commented

2026-01-31 17:49:56 +00:00

[LOW] Testing

The testing strategy for Phase 1 includes unit tests for gateway initialization, enums, intimacy modifiers, sentiment estimation, and DB requirements. However, no mention is made of security-related tests such as input validation, injection attack simulations, or abuse scenarios.

Recommendation: Add security-focused tests to validate input sanitization, prevent injection attacks, and verify enforcement of intimacy-level safety boundaries under malicious inputs.

**[LOW] Testing** The testing strategy for Phase 1 includes unit tests for gateway initialization, enums, intimacy modifiers, sentiment estimation, and DB requirements. However, no mention is made of security-related tests such as input validation, injection attack simulations, or abuse scenarios. **Recommendation:** Add security-focused tests to validate input sanitization, prevent injection attacks, and verify enforcement of intimacy-level safety boundaries under malicious inputs.

Bartender commented

2026-01-31 17:49:56 +00:00

[LOW] Architecture

The architecture diagram and description show a clean separation between platform adapters and the ConversationGateway service. However, the document notes that cross-platform identity linking is not yet implemented, which may cause user fragmentation and inconsistent state across platforms.

Recommendation: Plan and document a strategy for cross-platform user identity linking early in Phase 3 to ensure a seamless user experience and consistent Living AI state across platforms.

**[LOW] Architecture** The architecture diagram and description show a clean separation between platform adapters and the ConversationGateway service. However, the document notes that cross-platform identity linking is not yet implemented, which may cause user fragmentation and inconsistent state across platforms. **Recommendation:** Plan and document a strategy for cross-platform user identity linking early in Phase 3 to ensure a seamless user experience and consistent Living AI state across platforms.

docs/multi-platform-expansion.md

Bartender commented

2026-01-31 17:49:56 +00:00

[LOW] Security

The Web platform authentication is described as using magic links and tokens stored in HTTP-only cookies, but no mention is made of CSRF protection or rate limiting on auth endpoints.

Recommendation: Add documentation and implementation plans for CSRF protection, rate limiting, and brute force prevention on authentication endpoints to mitigate common web security risks.

**[LOW] Security** The Web platform authentication is described as using magic links and tokens stored in HTTP-only cookies, but no mention is made of CSRF protection or rate limiting on auth endpoints. **Recommendation:** Add documentation and implementation plans for CSRF protection, rate limiting, and brute force prevention on authentication endpoints to mitigate common web security risks.

Bartender commented

2026-01-31 17:49:56 +00:00

AI Code Review

This PR introduces a comprehensive multi-platform architecture expansion with a new Conversation Gateway service to unify conversation handling across Discord, Web, and CLI platforms. It includes detailed documentation, platform abstraction models, intimacy-level behavior modulation, and a clear migration path. The design emphasizes safety, maintainability, and async performance. No code diffs are present, only extensive documentation and design artifacts.

Summary

Severity	Count
HIGH	0
MEDIUM	0
LOW	5

Review Findings

[LOW] docs/implementation/conversation-gateway.md:300 - The ConversationGateway service is described as async and performing multiple sequential steps including DB queries, AI invocation, and state updates. However, the document does not explicitly mention error handling or retry strategies for failures in any of these async steps, which could lead to partial failures or inconsistent state.
[LOW] docs/implementation/conversation-gateway.md:420 - The IntimacyLevel enum and its behavioral modifiers are well documented, but the mapping from platform/channel type to intimacy level is only described in prose and example code in Phase 2. This could lead to inconsistent implementations across adapters.
[LOW] docs/multi-platform-expansion.md:250 - The Web platform authentication is described as using magic links and tokens stored in HTTP-only cookies, but no mention is made of CSRF protection or rate limiting on auth endpoints.
[LOW] docs/implementation/conversation-gateway.md:460 - The testing strategy for Phase 1 includes unit tests for gateway initialization, enums, intimacy modifiers, sentiment estimation, and DB requirements. However, no mention is made of security-related tests such as input validation, injection attack simulations, or abuse scenarios.
[LOW] docs/implementation/conversation-gateway.md:510 - The architecture diagram and description show a clean separation between platform adapters and the ConversationGateway service. However, the document notes that cross-platform identity linking is not yet implemented, which may cause user fragmentation and inconsistent state across platforms.

Overall Severity: LOW
AI Recommendation: Approve

## AI Code Review This PR introduces a comprehensive multi-platform architecture expansion with a new Conversation Gateway service to unify conversation handling across Discord, Web, and CLI platforms. It includes detailed documentation, platform abstraction models, intimacy-level behavior modulation, and a clear migration path. The design emphasizes safety, maintainability, and async performance. No code diffs are present, only extensive documentation and design artifacts. ### Summary | Severity | Count | |----------|-------| | HIGH | 0 | | MEDIUM | 0 | | LOW | 5 | ### Review Findings - **[LOW]** `docs/implementation/conversation-gateway.md:300` - The ConversationGateway service is described as async and performing multiple sequential steps including DB queries, AI invocation, and state updates. However, the document does not explicitly mention error handling or retry strategies for failures in any of these async steps, which could lead to partial failures or inconsistent state. - **[LOW]** `docs/implementation/conversation-gateway.md:420` - The IntimacyLevel enum and its behavioral modifiers are well documented, but the mapping from platform/channel type to intimacy level is only described in prose and example code in Phase 2. This could lead to inconsistent implementations across adapters. - **[LOW]** `docs/multi-platform-expansion.md:250` - The Web platform authentication is described as using magic links and tokens stored in HTTP-only cookies, but no mention is made of CSRF protection or rate limiting on auth endpoints. - **[LOW]** `docs/implementation/conversation-gateway.md:460` - The testing strategy for Phase 1 includes unit tests for gateway initialization, enums, intimacy modifiers, sentiment estimation, and DB requirements. However, no mention is made of security-related tests such as input validation, injection attack simulations, or abuse scenarios. - **[LOW]** `docs/implementation/conversation-gateway.md:510` - The architecture diagram and description show a clean separation between platform adapters and the ConversationGateway service. However, the document notes that cross-platform identity linking is not yet implemented, which may cause user fragmentation and inconsistent state across platforms. --- **Overall Severity:** `LOW` **AI Recommendation:** Approve

Sign in to join this conversation.

2 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: Hiddenden/loyal_companion#4