RAG and Semantic Search

Codapult ships with a retrieval-augmented generation pipeline that can index product knowledge and inject relevant context into AI chat responses. It is implemented as plain TypeScript modules, so you can reuse it for search pages, copilots, helpdesk suggestions, or admin tooling.

RAG is opt-in and requires the shared AI core: set ENABLE_AI_CORE="true" and ENABLE_AI_RAG="true" only after configuring an embedding and vector provider. Indexing is organization-scoped and requires an organization administrator; search is limited to the active organization. This prevents one tenant's documents from becoming another tenant's context.

Architecture

Indexing content

Use indexDocument when your app creates or updates searchable content:

import { indexDocument } from '@/lib/ai/rag';

await indexDocument({
  sourceType: 'help',
  sourceId: 'getting-started',
  title: 'Getting Started',
  content: markdownContent,
});

For larger batches, enqueue the rag-index background job so indexing does not block the user request.

Source types

Embedding providers

Embeddings use an adapter selected by EMBEDDING_PROVIDER.

Vector stores

Vector storage is selected by VECTOR_STORE_PROVIDER.

Search endpoint

/api/ai/search can power semantic search UI. Use it when you want search results without generating an AI response. Use the RAG helpers directly when you need to inject matching chunks into a prompt.

Limits

Configure operational limits with AI_RAG_MAX_DOCUMENT_SIZE, AI_RAG_MAX_BATCH_DOCUMENTS, AI_RAG_MAX_CHUNKS_PER_QUERY, and AI_RAG_MIN_SCORE. The defaults are deliberately bounded for a first deployment.

Removal

The RAG pipeline can be removed separately from the basic chat UI. Remove src/lib/ai/rag.ts, src/lib/ai/embeddings/, src/lib/ai/vector-store/, the AI indexing routes, the ai_embedding table, and the related environment variables.