Changeset 0.28.0.1 (#173)

2026-03-11 14:45:37 +00:00
parent 93c72daadf
commit 58313f7e31
57 changed files with 5139 additions and 3206 deletions
--- a/docs/ICD/knowledge.md
+++ b/docs/ICD/knowledge.md
@@ -0,0 +1,167 @@
+# 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.
+
+---