Knowledge bases (RAG)

A knowledge base answers "what do our documents say about this?". Help articles, PDFs, policies, product sheets or web pages go in; passages that answer a question come out, best first, each with a numbered citation of the document and section it came from. It lives in your project's own Postgres as an ordinary table, so your access rules apply to it like to any other data.

#Create one

Open Knowledge and choose New knowledge base, or use the SDK. A name like support_docs becomes the table kb_support_docs. Pick who can search it:

This is enforced by the table's own row-level security (enabled and forced), not by the client: one user never retrieves another user's private passages, through the API, the SDK or an agent. Each document has one owner, so nobody can add sections to someone else's document.

await sov.knowledge.create('support_docs', { access: 'app_users', description: 'Help center' })

#Add documents

Upload files (PDF with a text layer, DOCX, HTML, Markdown, TXT, CSV, JSON — up to 7 MB each), paste text, or give a public web page. Markdown headings become sections, and each answer cites its section. Re-adding a document with the same document_id replaces it: unchanged sections keep their embeddings, so only what changed is embedded (and paid for) again.

await sov.knowledge.addFile('support_docs', file)                       // a File from <input type="file">
await sov.knowledge.addUrl('support_docs', 'https://example.com/help/refunds')
await sov.knowledge.addText('support_docs', '# Refunds\nWithin 30 days…', { documentId: 'refunds', metadata: { area: 'billing' } })

Each add returns its sections, tokens, how many were new or unchanged, how many are still embedding, and estimated_cost_usd. Sections are searchable by exact words at once and by meaning as soon as they are embedded (seconds for most documents).

#Search

const { results, citations } = await sov.knowledge.search('support_docs', 'can I return a gift card?', { k: 5 })
// results[i]: { title, heading, content, citation, score, metadata, source_uri }

mode is hybrid (meaning and exact words, the default), vector or keyword; metadata_filter keeps sections whose metadata contains the given keys and values.

#Agents that answer from it

In Agents, pick knowledge bases in the Knowledge section. The agent searches them, answers with numbered citations like [1], and says it doesn't know when the passages don't cover a question. An agent that serves your app's users needs knowledge bases open to app users. See Sovariq AI and agents in your app.

#Cost

You pay for embedding (once per section, and again only when it changes) and for storage (your database size). Sovaria's managed model counts against ai.embeddings_month; your own key is billed by your provider (Vector search and embeddings). The Knowledge page shows tokens and estimated cost per knowledge base and this month's total. To keep large collections cheap: a small model with 512 dimensions, sections of 300–600 tokens, and re-adding with the same document_id so unchanged parts aren't embedded again.