Changeset 0.28.2.1 (#184)
This commit is contained in:
@@ -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).
|
||||
|
||||
---
|
||||
|
||||
@@ -84,6 +84,25 @@ Known ICD report failures to investigate (likely envelope shape mismatches):
|
||||
- [x] Remove dead `NotifTypeProjectInvite` constant
|
||||
- [ ] Notification handler + store tests (PG + SQLite)
|
||||
|
||||
**Knowledge ICD audit (cs1–cs4):**
|
||||
- [x] `knowledge.md` corrected: KB object shape (6 field mismatches), search envelope
|
||||
(`data` not `results`), search result fields, status progression (`extracting`
|
||||
step), file type support (text-only, not binary), auth annotations
|
||||
- [x] Test harness: add `RequirePermission` on `POST /knowledge-bases` and
|
||||
`POST /:id/documents`, add missing `GET /:id/documents/:docId/status` and
|
||||
`DELETE /:id/documents/:docId` routes
|
||||
- [x] New tests: document status polling, document delete, update-empty-body 400,
|
||||
permission denial for non-privileged user
|
||||
- [x] P0 fix: `SetDiscoverable` authorization — `loadAndAuthorize` + owner/admin
|
||||
check, audit log, cross-user security tests (cs2)
|
||||
- [x] `ListDiscoverableKBs` response normalization — use `toKBResponse()`,
|
||||
shape assertion test (cs3)
|
||||
- [x] Dead code removal: `ListGlobal`/`ListForTeam` on KnowledgeBaseStore —
|
||||
interface + PG + SQLite (cs4)
|
||||
- [x] Move `CreateKB` team role check from raw `database.DB.QueryRow` to
|
||||
`stores.Teams.IsTeamAdmin`; remove `database` import (cs4)
|
||||
- [x] Team-scoped KB creation test: member denied, team admin succeeds (cs4)
|
||||
|
||||
### v0.28.3 — Security Tier (ICD Runner Red Team)
|
||||
New `security` tier in ICD test runner. Multi-user fixtures already exist.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user