168 lines
3.1 KiB
Markdown
168 lines
3.1 KiB
Markdown
# 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:
|
|
|
|
```json
|
|
{
|
|
"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
|
|
```
|
|
|
|
```json
|
|
{
|
|
"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] }`:
|
|
|
|
```json
|
|
{
|
|
"kb_id": "uuid",
|
|
"kb_name": "Product Docs",
|
|
"enabled": true,
|
|
"document_count": 12
|
|
}
|
|
```
|
|
|
|
**Set** (replace all):
|
|
|
|
```
|
|
PUT /channels/:id/knowledge-bases
|
|
```
|
|
|
|
```json
|
|
{ "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
|
|
```
|
|
|
|
```json
|
|
{ "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.
|
|
|
|
---
|