switchboard/core
Archived
1
0
Fork 0
Code Issues Pull Requests Actions Releases 9 Wiki Activity

Changeset 0.28.2.1 (#184)

Browse Source
This commit is contained in:
xcaliber
2026-03-13 14:36:43 +00:00
parent f94243fbf3
commit 7803ba8adf
7 changed files with 491 additions and 62 deletions
Download Patch File Download Diff File Expand all files Collapse all files

144
docs/ICD/knowledge.md
View File

@@ -7,14 +7,25 @@ The **Knowledge Base** (KB) is the RAG system: upload documents → chunk
### KB CRUD
```
GET /knowledge-bases → { "data": [KB objects] }
GET /knowledge-bases → { "data": [KB objects], "total": N }
POST /knowledge-bases ← { "name", "description", "scope", "team_id" }
GET /knowledge-bases/:id → KB object
PUT /knowledge-bases/:id ← partial update
PUT /knowledge-bases/:id ← partial update { "name", "description" }
DELETE /knowledge-bases/:id
```
KB object:
**Auth:** All endpoints require a valid JWT. `POST` additionally requires
the `kb.create` permission (checked via `RequirePermission` middleware).
**Scope rules for `POST`:**
| Scope | Requirement |
|-------|-------------|
| `personal` (default) | Any authenticated user with `kb.create` |
| `team` | `team_id` required; caller must be team admin (or system admin) |
| `global` | Caller must be system admin |
KB object (as returned by CRUD endpoints):
```json
{
@@ -24,16 +35,21 @@ KB object:
"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,
"embedding_config": {},
"document_count": 12,
"created_at": "...",
"updated_at": "..."
"chunk_count": 48,
"total_bytes": 245760,
"status": "active|processing|error",
"created_at": "2025-01-15T10:30:00Z",
"updated_at": "2025-01-15T10:30:00Z"
}
```
> **Note:** The `discoverable` field is stored in the DB and present on
> the raw model, but is **not** included in the `kbResponse` struct
> returned by CRUD endpoints. It is managed via the dedicated
> discoverable endpoints below.
### Documents
**Upload:**
@@ -43,8 +59,31 @@ 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"`.
**Auth:** Requires `kb.write` permission (checked via `RequirePermission`
middleware). Also requires a configured embedding model role — returns
`412 Precondition Failed` if missing.
Field: `file` (max 10 MB). Currently supported types: **TXT, MD, CSV,
HTML**. Binary formats (PDF, DOCX, XLSX, PPTX) are planned but require
an extraction sidecar that is not yet wired in.
Returns the document object with HTTP `202 Accepted`:
```json
{
"id": "uuid",
"kb_id": "uuid",
"filename": "guide.md",
"content_type": "text/markdown",
"size_bytes": 12345,
"chunk_count": 0,
"status": "pending",
"error": null,
"uploaded_by": "uuid",
"created_at": "2025-01-15T10:30:00Z",
"updated_at": "2025-01-15T10:30:00Z"
}
```
**List:**
@@ -52,7 +91,7 @@ Returns the document object with `status: "pending"`.
GET /knowledge-bases/:id/documents
```
Returns `{ "data": [document objects] }`.
Returns `{ "data": [document objects], "total": N }`.
**Status** (poll during processing):
@@ -60,7 +99,19 @@ Returns `{ "data": [document objects] }`.
GET /knowledge-bases/:id/documents/:docId/status
```
Status progression: `pending → chunking → embedding → ready | error`.
Returns a subset of the document object:
```json
{
"id": "uuid",
"status": "chunking",
"chunk_count": 0,
"error": null,
"filename": "guide.md"
}
```
Status progression: `pending → extracting → chunking → embedding → ready | error`.
**Delete:**
@@ -68,6 +119,9 @@ Status progression: `pending → chunking → embedding → ready | error`.
DELETE /knowledge-bases/:id/documents/:docId
```
Deletes the document, its chunks, and the stored file. Returns
`{ "deleted": true }`.
### Search
```
@@ -77,20 +131,55 @@ POST /knowledge-bases/:id/search
```json
{
"query": "How do I configure SSO?",
"limit": 5
"limit": 5,
"threshold": 0.3
}
```
Returns `{ "results": [{ "content", "score", "document_id", "metadata" }] }`.
`limit` defaults to 5, max 20. `threshold` is the minimum cosine
similarity score (defaults to 0.3).
Returns `{ "data": [...], "query": "...", "total": N }`:
```json
{
"data": [
{
"content": "To configure SSO, navigate to...",
"source": "admin-guide.md",
"kb": "Product Docs",
"similarity": 0.87,
"metadata": {}
}
],
"query": "How do I configure SSO?",
"total": 1
}
```
### Rebuild
Re-chunks and re-embeds all documents:
Re-chunks and re-embeds all documents. Skips documents whose extracted
text is missing (would need the original file from object store).
```
POST /knowledge-bases/:id/rebuild
```
Returns `202 Accepted`:
```json
{
"message": "rebuild started",
"total_docs": 12,
"rebuilding": 10,
"skipped": 2
}
```
Returns `503` if the ingestion pipeline is not configured, or `400` if
the KB has no documents.
### Channel KB Bindings
A channel can have KBs explicitly bound to it (in addition to any KBs
@@ -123,6 +212,9 @@ PUT /channels/:id/knowledge-bases
{ "kb_ids": ["kb-uuid-1", "kb-uuid-2"] }
```
Validates that the caller has access to every referenced KB before
setting the bindings.
### Discoverable KBs
The `discoverable` flag controls whether a KB appears in the user's KB
@@ -136,9 +228,10 @@ GET /knowledge-bases-discoverable
```
Returns `{ "data": [KB objects] }` — only KBs the user can see
(personal + team + discoverable global).
(personal + team + discoverable global). Uses the same `kbResponse`
format as the CRUD endpoints.
**Toggle discoverability** (admin-enforced in handler):
**Toggle discoverability:**
```
PUT /knowledge-bases/:id/discoverable
@@ -148,6 +241,10 @@ PUT /knowledge-bases/:id/discoverable
{ "discoverable": false }
```
**Auth:** Requires `loadAndAuthorize` (KB must exist, caller must have
basic access). Additionally, only the KB **owner** or a **system admin**
may change the flag — all other callers receive `403 Forbidden`.
### KB Resolution Chain
When a completion fires, KBs are resolved in priority order:
@@ -158,10 +255,17 @@ 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.
The `kb_search` tool additionally resolves project-bound KBs and
personal KBs at search time, so all user-accessible KBs are
searchable even if not explicitly listed in the hint.
### Persona KB Bindings
See §4.4. Persona-KB binding is the primary enterprise mechanism for
controlled KB access.
Managed via the Persona endpoints — see [personas.md](personas.md).
Persona-KB binding is the primary enterprise mechanism for controlled
KB access. The `auto_search` flag on persona KB bindings controls
whether top-K results are prepended to context automatically (planned,
see v0.28.4) vs available only through the `kb_search` tool (current
behavior).
---