Knowledge Base and RAG

The AI module lets each agent maintain its own document-backed knowledge base, then exposes that knowledge through a retrieval tool during chat execution.

Controller Surface

• GET /agent/:agentId/knowledge/documents
• POST /agent/:agentId/knowledge/documents
• DELETE /agent/:agentId/knowledge/documents/:docId

These routes are implemented in source but are not live yet because the module is not mounted.

Knowledge Document Contract

Adding a document requires:

• fileName
• description
• language
• s3Key
• contentType

The module persists the row immediately with status pending, then continues processing asynchronously through an event handler.

Indexing Pipeline

KnowledgeDocumentAddedEvent performs the full indexing flow:

1. Load the document and agent.
2. Mark the document as processing.
3. Resolve a download URL for the stored file.
4. Download the file content.
5. Parse application/pdf, Word documents, or text/* payloads.
6. Split the extracted text using the agent's chunk settings.
7. Generate embeddings in batches of 50.
8. Ensure the Qdrant collection exists.
9. Upsert one vector point per chunk.
10. Mark the document as completed or failed.

Each embedding batch also emits token accounting events under the DocumentIndexing action.

Retrieval Tool

• Agents with knowledge.isEnabled=true automatically receive the search-knowledge-base tool.
• The tool embeds the query, searches the agent's Qdrant collection, and returns the best fragments that survive adaptive thresholding.
• Query embeddings are tracked as token usage under the RagQueryEmbedding action.
• Retrieved fragments include the source text and a relevance score.

Defaults and Tuning

• knowledge is disabled by default for new agents
• default chunk size is 700
• default chunk overlap is 150
• default similarity threshold is 0.35
• default result limit is 5
• default embedding model is openai/text-embedding-3-small

Delete Behavior

• Removing a knowledge document first attempts to delete matching Qdrant points by documentId.
• The command then deletes the metadata row from PostgreSQL.
• After database deletion, the module publishes KnowledgeDocumentRemovedEvent so the original file can be deleted from storage.

Current Gaps

The knowledge flow is not fully production-ready yet:

• FileDownloadAdapter currently always throws File not found for key: ..., so document ingestion cannot succeed end-to-end.
• FileDeletionAdapter is a no-op, so file cleanup is not actually requested after document removal.
• The update command intentionally blocks embedding-model changes, because re-embedding and collection migration are not implemented.

Structured Error Contract

Code	HTTP	Meaning
AI.AGENT_NOT_FOUND	404	The target agent does not exist.
AI.AGENT_HAS_NO_KNOWLEDGE_CONFIG	400	Knowledge operations were attempted for an agent without a usable knowledge config.
AI.DOCUMENT_NOT_FOUND	404	The target knowledge document does not exist for that agent.
AI.UNEXPECTED_ERROR	500	Persistence or integration failure while saving or deleting the document row.