Archived

This repository has been archived on 2026-04-03. You can view files and clone it. You cannot open issues or pull requests or push a commit.

Files

xcaliber 58313f7e31 Changeset 0.28.0.1 (#173 )

2026-03-11 14:45:37 +00:00

3.1 KiB

Raw Blame History

Knowledge Bases

The Knowledge Base (KB) is the RAG system: upload documents → chunk → embed (pgvector / app-level cosine for SQLite) → search via kb_search tool during completions.

KB CRUD

GET    /knowledge-bases             → { "data": [KB objects] }
POST   /knowledge-bases             ← { "name", "description", "scope", "team_id" }
GET    /knowledge-bases/:id         → KB object
PUT    /knowledge-bases/:id         ← partial update
DELETE /knowledge-bases/:id

KB object:

{
  "id": "uuid",
  "name": "Product Docs",
  "description": "Internal product documentation",
  "scope": "personal|team|global",
  "owner_id": "uuid|null",
  "team_id": "uuid|null",
  "discoverable": true,
  "embedding_model": "text-embedding-3-small",
  "chunk_size": 512,
  "chunk_overlap": 50,
  "document_count": 12,
  "created_at": "...",
  "updated_at": "..."
}

Documents

Upload:

POST /knowledge-bases/:id/documents
Content-Type: multipart/form-data

Field: file. Supported: PDF, DOCX, TXT, MD, HTML, CSV, XLSX, PPTX. Returns the document object with status: "pending".

List:

GET /knowledge-bases/:id/documents

Returns { "data": [document objects] }.

Status (poll during processing):

GET /knowledge-bases/:id/documents/:docId/status

Status progression: pending → chunking → embedding → ready | error.

Delete:

DELETE /knowledge-bases/:id/documents/:docId

Search

POST /knowledge-bases/:id/search

{
  "query": "How do I configure SSO?",
  "limit": 5
}

Returns { "results": [{ "content", "score", "document_id", "metadata" }] }.

Rebuild

Re-chunks and re-embeds all documents:

POST /knowledge-bases/:id/rebuild

Channel KB Bindings

A channel can have KBs explicitly bound to it (in addition to any KBs coming from the active Persona or parent Project).

Get:

GET /channels/:id/knowledge-bases

Returns { "data": [ChannelKB objects] }:

{
  "kb_id": "uuid",
  "kb_name": "Product Docs",
  "enabled": true,
  "document_count": 12
}

Set (replace all):

PUT /channels/:id/knowledge-bases

{ "kb_ids": ["kb-uuid-1", "kb-uuid-2"] }

Discoverable KBs

The discoverable flag controls whether a KB appears in the user's KB picker. Non-discoverable KBs are hidden from direct access but still searchable through Persona bindings (enterprise KB mode).

List discoverable (for KB picker UI):

GET /knowledge-bases-discoverable

Returns { "data": [KB objects] } — only KBs the user can see (personal + team + discoverable global).

Toggle discoverability (admin-enforced in handler):

PUT /knowledge-bases/:id/discoverable

{ "discoverable": false }

KB Resolution Chain

When a completion fires, KBs are resolved in priority order:

Persona KBs → Project KBs → Channel KBs → Personal KBs

The BuildKBHint function assembles all applicable KBs into the system prompt, and the kb_search tool searches across all of them.

Persona KB Bindings

See §4.4. Persona-KB binding is the primary enterprise mechanism for controlled KB access.

3.1 KiB Raw Blame History