Chat System & History
Relevant source files
The following files were used as context for generating this wiki page:
The Chat System is the primary interface for users to interact with "Recoup," a specialized AI assistant designed for the music industry. The system manages complex multi-turn conversations, providing strategic analysis for marketing, fan data, and release management. It handles state through a "Rooms" and "Memories" architecture, ensuring that context is preserved across different sessions and platforms, including web and email interfaces.
Sources: lib/chat/const.ts:1-5, features/feature-email-client.md:3-10
Architecture and Data Flow
The chat architecture follows a modular pipeline: validation, session setup, AI execution (streaming or non-streaming), and post-completion processing. This ensures that every request is authenticated, associated with the correct music artist context, and persisted for future reference.
Request Lifecycle
- Validation & Authentication: Every request is checked for a valid API Key or Bearer Token. The system enforces that only one authentication mechanism is used at a time.
- Normalization: User inputs (either a raw
promptstring or amessagesarray) are converted into a standardizedUIMessageformat. - Conversation Setup: The system checks for an existing
roomId. If absent, it automatically generates a unique ID and sets up a new room. - AI Generation: The system interacts with LLM providers (e.g., OpenAI, Anthropic) using a "Sandbox-First" approach, where the AI has access to a
prompt_sandboxtool for data analysis and document generation. - Post-Processing: Once a response is generated, the system updates the chat title (if it's a new conversation), stores messages in the database, sends notifications, and calculates credit usage.
Sources: lib/chat/validateChatRequest.ts:70-130, lib/chat/handleChatGenerate.ts:20-40, lib/chat/const.ts:9-15
Chat Execution Flow
The following diagram illustrates the sequence of operations for a standard chat request:
This diagram shows the end-to-end flow from user request to message persistence.
Sources: lib/chat/validateChatRequest.ts:47-150, lib/chat/handleChatCompletion.ts:25-70
System Components
1. Request Validation (validateChatRequest)
The system uses Zod for strict schema enforcement. It handles the transition from legacy single-prompt inputs to modern message arrays while maintaining backward compatibility.
| Parameter | Type | Description |
|---|---|---|
prompt | string | Optional. Raw text input for single-turn requests. |
messages | array | Optional. Array of message objects for multi-turn history. |
roomId | uuid | Optional. The unique ID for the conversation session. |
artistId | uuid | Optional. Context for artist-specific instructions and data. |
model | string | Optional. Override for specific LLM selection. |
excludeTools | string[] | Optional. List of AI tools to disable for the session. |
Sources: lib/chat/validateChatRequest.ts:14-30
2. State Management (Rooms & Memories)
State is maintained through two primary database entities:
- Rooms: Represent a distinct conversation thread. They store metadata like the
topic(generated via AI from the first message) and theaccount_idof the owner. - Memories: Individual message entries linked to a
room_id. Both user messages and assistant responses are stored as memories to provide long-term context.
The relationship between accounts, conversation rooms, and individual message memories.
Sources: lib/chat/handleChatCompletion.ts:58-75, features/feature-email-client.md:55-65
3. Post-Completion Processing
The handleChatCompletion function orchestrates background tasks that occur after the user receives their response. This logic is wrapped in try-catch blocks to ensure that database or notification failures do not interrupt the user's chat experience.
- Title Generation: If the conversation is new, the system uses a lightweight model (e.g.,
gpt-4o-mini) to generate a concise title under 20 characters based on the first user message. - Notifications: For new conversations, a Telegram notification is sent to the team with the user's email, the conversation ID, and the first message content.
- Email Integration: If the AI invokes email-related tools, the system processes these outputs to send actual outbound emails via Resend.
Sources: lib/chat/handleChatCompletion.ts:25-85, lib/chats/tests/generateChatTitle.test.ts:35-45
Configuration and Constraints
The system operates under several hardcoded constraints to maintain performance and prevent context window overflow:
| Constant | Value | Description |
|---|---|---|
MAX_MESSAGES | 55 | The maximum number of messages sent to the AI in the context window. |
SYSTEM_PROMPT | See const.ts | The core instructions defining the AI's persona as "Recoup." |
Credit Cost | usage * 100 | Credits are deducted based on total token usage (prompt + completion). |
Min Credits | 1 | Minimum credit deduction per chat interaction. |
Sources: lib/chat/const.ts:1-3, lib/chat/tests/integration/chatEndToEnd.test.ts:354-370
Implementation Details
Non-Streaming Generation
For standard JSON responses (non-streaming), the handleChatGenerate function returns detailed metadata about the AI's response.
// Example of returned structure from handleChatGenerate.ts
{
"text": "The strategic plan for your release...",
"roomId": "room-uuid-123",
"reasoningText": "Thought process for generating this plan...",
"sources": [{ "url": "https://..." }],
"finishReason": "stop",
"usage": { "promptTokens": 1024, "completionTokens": 512 }
}
Sources: lib/chat/handleChatGenerate.ts:40-65
Credit Handling logic
Credits are calculated post-completion based on the specific model used. The system rounds the calculated cost to the nearest integer, ensuring a minimum of 1 credit is deducted.
Sources: lib/chat/tests/integration/chatEndToEnd.test.ts:340-360
Conclusion
The Chat System & History module provides a robust, stateful environment for AI interactions. By decoupling the generation logic from post-processing tasks like persistence and notifications, the system achieves a highly responsive user experience while maintaining a comprehensive record of interactions for analysis and credit management.