AI Domain

The AI module centers on a configurable Agent aggregate and the execution data produced around it.

Agent Aggregate

An Agent owns the high-level product behavior exposed to end users:

• Identity: name, role, avatar, description, internalNameId, visibility, and isEnabled.
• Brain config: primary model, optional fallbackModel, and supported languages.
• Instruction config: systemPrompt, optional greetingMessage, fixed rules, variable rules, prohibitions, personality, and writingStyle.
• Knowledge config: isEnabled, chunkSize, chunkOverlap, embeddingModel, similarityThreshold, searchResults, and an internal qdrantCollectionName.
• Limits config: request media limits, messagesPerMinute, token budgets, and the executionLimitAction for capped or blocked executions.
• Stats: chat count, user count, and processed message count.

Important Defaults

• New agents always get a knowledge config, but it starts disabled.
• The knowledge collection name defaults to agent-<agentId>.
• Knowledge defaults are chunkSize=700, chunkOverlap=150, embeddingModel=openai/text-embedding-3-small, similarityThreshold=0.35, and searchResults=5.
• Limits default to messagesPerMinute=60, one document per request, and zero-valued token budgets, which the module treats as unlimited.
• The default execution over-budget policy is block_next.

Conversation Model

• Chat stores the conversational container for one agentId and one userId.
• Message stores raw Vercel AI SDK parts, optional metadata, the role (user or assistant), and optional message stats.
• The read-side message query only exposes user and assistant messages in paginated history reads.

Knowledge Model

• AgentKnowledgeDocument represents one uploaded knowledge asset for an agent.
• Documents move through pending -> processing -> completed | failed.
• Successful processing records chunkCount and processedAt; failures keep a truncated errorMessage.
• Qdrant payloads store the fragment text plus documentId, fileName, description, language, and agentId so retrieval and cleanup can stay document-aware.

Model Catalog

• Model mirrors metadata discovered from the Vercel AI Gateway catalog.
• The entity stores descriptive metadata, base pricing, provider-specific endpoint data, architecture capabilities, sync status, and last sync timestamps/errors.
• Sync status moves through PENDING, IN_PROGRESS, SYNCED, FAILED, and REMOVED.

Token Accounting

• TokenUsageLog stores every tracked AI cost event with the action type, model id, token counters, cost, and optional execution context (agentId, chatId, userId).
• OrgTokenUsageSummary aggregates monthly totals by organization and agency, and keeps breakdowns by model and action.
• The summary update path uses a database transaction plus pessimistic locking to avoid lost updates under concurrent writes.

Persistence Ownership

The module owns a dedicated PostgreSQL schema named ai and a dedicated TypeORM connection named ai. Persistence entities exist for:

• agents and their nested configs
• chats and messages
• knowledge documents
• models
• token usage logs and monthly org summaries

AI-specific migration files are not present yet, so the schema contract is represented in code but not fully operationalized for deployment.