Knowledge bases administered: llmgw ctl kb and /api/v1/kb

Collections made for an organization, team, project or person, their
dimension asked of the embedding model; granted and revoked by path, never
outside their organization; their documents listed and removed; and a search
an operator can try. In the OpenAPI document.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
This commit is contained in:
Ilker ManapandClaude Opus 5.5 committed 2026-10-08 13:49:44 +02:00
1 parent ffab3c99e3
commit 6466f37d50
8 files changed
+1405 -1

No files matched your search

+4 -1
View File
@@ -68,7 +68,9 @@ type API struct {
// nil without a store.
federation *federation.Service
// guard is the guardrail policies' library and attachments.
guard *GuardAdmin
guard *GuardAdmin
// kb is knowledge bases; nil without a store.
kb *KBAdmin
settings *Settings
// restartAgents tells every connected agent to start again.
restartAgents func(reason string) []string
@@ -114,6 +116,7 @@ func (a *API) Register(mux Mux) {
mux.HandleFunc("POST /api/v1/models/{name}/scale", a.scaleModel)
mux.HandleFunc("POST /api/v1/models/{name}/resources", a.setResources)
a.registerQuotas(mux)
a.registerKB(mux)
a.registerGuard(mux)
a.registerSettings(mux)
mux.HandleFunc("POST /api/v1/agents/restart", a.restartAgentsHandler)
+469
View File
@@ -0,0 +1,469 @@
package adminapi
import (
"context"
"encoding/json"
"errors"
"fmt"
"net/http"
"strings"
"time"
"gitea.mynodes.xyz/ilker/llmgw/internal/store"
)
// Knowledge bases, administered (BACKLOG F): collections made, granted,
// emptied and removed here; documents put into them by people with
// llmgw-kb, through the gateway.
// KBStore is the part of the store knowledge bases need.
type KBStore interface {
KnowledgeAvailable() error
Collections(ctx context.Context) ([]store.KBCollection, error)
Collection(ctx context.Context, id string) (store.KBCollection, error)
CreateCollection(ctx context.Context, c store.KBCollection) (store.KBCollection, error)
DeleteCollection(ctx context.Context, id string) error
Grant(ctx context.Context, g store.KBGrant) error
Revoke(ctx context.Context, scope store.Scope, scopeID, collection string) (bool, error)
Grants(ctx context.Context, collection string) ([]store.KBGrant, error)
Documents(ctx context.Context, collection string) ([]store.KBDocument, error)
DeleteDocument(ctx context.Context, collection, name string) (bool, error)
SearchChunks(ctx context.Context, q store.KBSearch) ([]store.KBHit, error)
}
// KBAdmin is what the knowledge-base endpoints need: the store, and a way to
// have a model embed a text (to learn its dimension, and to try a search).
type KBAdmin struct {
Store KBStore
Embed func(ctx context.Context, model, text string) ([]float32, error)
}
// SetKB enables the knowledge-base endpoints.
func (a *API) SetKB(k *KBAdmin) { a.kb = k }
// KBView is every collection, or why there can be none.
type KBView struct {
Available bool `json:"available"`
// Reason is why not, when not.
Reason string `json:"reason,omitempty"`
Collections []KBCollectionView `json:"collections"`
}
// KBCollectionView is a collection as an administrator sees it.
type KBCollectionView struct {
ID string `json:"id"`
Name string `json:"name"`
Org string `json:"org"`
OrgName string `json:"org_name,omitempty"`
Owner string `json:"owner"`
OwnerName string `json:"owner_name,omitempty"`
EmbedModel string `json:"embed_model"`
Dims int `json:"dims"`
Documents int `json:"documents"`
Chunks int `json:"chunks"`
// Grants are who else may read or write it.
Grants []KBGrantView `json:"grants"`
CreatedAt time.Time `json:"created_at"`
CreatedBy string `json:"created_by,omitempty"`
}
// KBGrantView is one grant.
type KBGrantView struct {
Target string `json:"target"`
Name string `json:"name,omitempty"`
Perm string `json:"perm"`
At time.Time `json:"at"`
By string `json:"by,omitempty"`
}
// KBCreateRequest makes a collection.
type KBCreateRequest struct {
// Owner is org:NAME, team:ORG/TEAM, project:ORG/TEAM/PROJECT (or the ID
// after the colon), or user:USER-ID.
Owner string `json:"owner"`
// Org is the organization a person's collection belongs to; only for
// user: owners.
Org string `json:"org,omitempty"`
Name string `json:"name"`
// Model is the catalog model that embeds its documents.
Model string `json:"model"`
// Dims is the model's embedding dimension; asked of the model when 0.
Dims int `json:"dims,omitempty"`
}
// KBGrantRequest lets a scope read or write a collection, or with DELETE
// takes that away.
type KBGrantRequest struct {
// Collection is its ID, its name when that is unique, or ORG/NAME.
Collection string `json:"collection"`
// Target is org:, team:, project:, key: or user: as for guard policies.
Target string `json:"target"`
// Perm is read or write; ignored by DELETE.
Perm string `json:"perm,omitempty"`
}
// KBDocumentView is one document in a collection.
type KBDocumentView struct {
Name string `json:"name"`
Digest string `json:"digest"`
Bytes int64 `json:"bytes"`
Chunks int `json:"chunks"`
AddedAt time.Time `json:"added_at"`
AddedBy string `json:"added_by,omitempty"`
}
// KBSearchRequest tries a search, as an administrator: no tenancy applies.
type KBSearchRequest struct {
Collection string `json:"collection"`
Query string `json:"query"`
K int `json:"k,omitempty"`
}
// KBHitView is one chunk a search found.
type KBHitView struct {
Document string `json:"document"`
Ord int `json:"ord"`
Score float64 `json:"score"`
Text string `json:"text"`
}
func (a *API) registerKB(mux Mux) {
mux.HandleFunc("GET /api/v1/kb", a.kbList)
mux.HandleFunc("POST /api/v1/kb/collections", a.kbCreate)
mux.HandleFunc("DELETE /api/v1/kb/collections/{id}", a.kbDelete)
mux.HandleFunc("GET /api/v1/kb/collections/{id}/documents", a.kbDocuments)
mux.HandleFunc("DELETE /api/v1/kb/collections/{id}/documents", a.kbDeleteDocument)
mux.HandleFunc("POST /api/v1/kb/grants", a.kbGrant(true))
mux.HandleFunc("DELETE /api/v1/kb/grants", a.kbGrant(false))
mux.HandleFunc("POST /api/v1/kb/search", a.kbSearch)
}
// kbReady answers for a gateway without knowledge bases, and says whether
// it did.
func (a *API) kbReady(w http.ResponseWriter) bool {
if a.kb == nil {
writeError(w, http.StatusNotImplemented, "knowledge bases need the store, which this control plane runs without")
return false
}
if err := a.kb.Store.KnowledgeAvailable(); err != nil {
writeError(w, http.StatusNotImplemented, err.Error())
return false
}
return true
}
func (a *API) names(ctx context.Context) map[string]string {
if a.quotas == nil {
return map[string]string{}
}
n, err := a.scopeNames(ctx)
if err != nil {
return map[string]string{}
}
return n
}
func (a *API) kbList(w http.ResponseWriter, r *http.Request) {
if a.kb == nil {
writeJSON(w, http.StatusOK, KBView{Reason: "knowledge bases need the store", Collections: []KBCollectionView{}})
return
}
if err := a.kb.Store.KnowledgeAvailable(); err != nil {
writeJSON(w, http.StatusOK, KBView{Reason: err.Error(), Collections: []KBCollectionView{}})
return
}
cs, err := a.kb.Store.Collections(r.Context())
if err != nil {
writeError(w, http.StatusInternalServerError, err.Error())
return
}
grants, err := a.kb.Store.Grants(r.Context(), "")
if err != nil {
writeError(w, http.StatusInternalServerError, err.Error())
return
}
names := a.names(r.Context())
v := KBView{Available: true, Collections: []KBCollectionView{}}
for _, c := range cs {
cv := KBCollectionView{ID: c.ID, Name: c.Name, Org: c.OrgID, OrgName: names["org:"+c.OrgID],
Owner: string(c.OwnerScope) + ":" + c.OwnerID, OwnerName: names[string(c.OwnerScope)+":"+c.OwnerID],
EmbedModel: c.EmbedModel, Dims: c.Dims, Grants: []KBGrantView{}, CreatedAt: c.CreatedAt, CreatedBy: c.CreatedBy}
if docs, err := a.kb.Store.Documents(r.Context(), c.ID); err == nil {
cv.Documents = len(docs)
for _, d := range docs {
cv.Chunks += d.Chunks
}
}
for _, g := range grants {
if g.Collection == c.ID {
key := string(g.Scope) + ":" + g.ScopeID
cv.Grants = append(cv.Grants, KBGrantView{Target: key, Name: names[key], Perm: string(g.Perm), At: g.AddedAt, By: g.AddedBy})
}
}
v.Collections = append(v.Collections, cv)
}
writeJSON(w, http.StatusOK, v)
}
// kbTarget reads a grant's or an owner's target: org:, team: and project:
// by path or ID, key: and user: by ID.
func (a *API) kbTarget(ctx context.Context, target string) (store.Scope, string, error) {
kind, what, ok := strings.Cut(strings.TrimSpace(target), ":")
what = strings.TrimSpace(what)
if !ok || what == "" {
return "", "", fmt.Errorf("%q is not org:, team:, project:, key: or user: and what", target)
}
switch store.Scope(kind) {
case store.ScopeKey, store.ScopeUser:
return store.Scope(kind), what, nil
case store.ScopeOrg, store.ScopeTeam, store.ScopeProject:
if a.quotas == nil {
return store.Scope(kind), what, nil
}
scope, id, _, err := a.resolveScope(ctx, target)
return scope, id, err
}
return "", "", fmt.Errorf("%q: org, team, project, key or user", kind)
}
// kbFind reads a collection by ID, by its name when that is unique, or by
// ORG/NAME.
func (a *API) kbFind(ctx context.Context, ref string) (store.KBCollection, error) {
ref = strings.TrimSpace(ref)
if c, err := a.kb.Store.Collection(ctx, ref); err == nil {
return c, nil
}
cs, err := a.kb.Store.Collections(ctx)
if err != nil {
return store.KBCollection{}, err
}
names := a.names(ctx)
org, name, scoped := strings.Cut(ref, "/")
var found []store.KBCollection
for _, c := range cs {
switch {
case scoped && strings.EqualFold(c.Name, name) &&
(c.OrgID == org || strings.EqualFold(names["org:"+c.OrgID], org)):
found = append(found, c)
case !scoped && strings.EqualFold(c.Name, ref):
found = append(found, c)
}
}
switch len(found) {
case 0:
return store.KBCollection{}, fmt.Errorf("no collection %q", ref)
case 1:
return found[0], nil
}
return store.KBCollection{}, fmt.Errorf("%q names a collection in more than one organization; write ORG/%s", ref, ref)
}
func (a *API) kbCreate(w http.ResponseWriter, r *http.Request) {
if !a.kbReady(w) {
return
}
var in KBCreateRequest
if err := json.NewDecoder(r.Body).Decode(&in); err != nil {
writeError(w, http.StatusBadRequest, err.Error())
return
}
scope, id, err := a.kbTarget(r.Context(), in.Owner)
if err != nil {
writeError(w, http.StatusBadRequest, err.Error())
return
}
org := ""
if scope == store.ScopeUser {
if in.Org == "" {
writeError(w, http.StatusBadRequest, "a person's collection names its organization (org)")
return
}
if _, org, err = a.kbTarget(r.Context(), "org:"+in.Org); err != nil {
writeError(w, http.StatusBadRequest, err.Error())
return
}
}
m, ok := a.ctl.Catalog().Resolve(in.Model)
if !ok {
writeError(w, http.StatusBadRequest, "no model "+in.Model+" in the catalog")
return
}
if !m.Capabilities.Embeddings {
writeError(w, http.StatusBadRequest, m.Name+" does not embed (capabilities.embeddings); a collection needs an embedding model")
return
}
dims := in.Dims
if dims == 0 {
if a.kb.Embed == nil {
writeError(w, http.StatusBadRequest, "give the model's dimension (dims): nothing here can ask it")
return
}
// Asked of the model: a dimension typed by hand and wrong would be
// found only when the first document is refused.
ctx, cancel := context.WithTimeout(r.Context(), 10*time.Minute)
defer cancel()
v, err := a.kb.Embed(ctx, m.Name, "llmgw")
if err != nil {
writeError(w, http.StatusBadGateway, "asking "+m.Name+" for its dimension: "+err.Error()+
" (is it running? or give dims)")
return
}
dims = len(v)
}
c, err := a.kb.Store.CreateCollection(r.Context(), store.KBCollection{OwnerScope: scope, OwnerID: id, OrgID: org,
Name: in.Name, EmbedModel: m.Name, Dims: dims, CreatedBy: actorOf(r)})
if err != nil {
code := http.StatusBadRequest
if errors.Is(err, store.ErrNotFound) {
code = http.StatusNotFound
}
writeError(w, code, err.Error())
return
}
writeJSON(w, http.StatusCreated, KBCollectionView{ID: c.ID, Name: c.Name, Org: c.OrgID,
Owner: string(c.OwnerScope) + ":" + c.OwnerID, EmbedModel: c.EmbedModel, Dims: c.Dims,
Grants: []KBGrantView{}, CreatedAt: c.CreatedAt, CreatedBy: c.CreatedBy})
}
func (a *API) kbCollection(w http.ResponseWriter, r *http.Request) (store.KBCollection, bool) {
if !a.kbReady(w) {
return store.KBCollection{}, false
}
c, err := a.kbFind(r.Context(), r.PathValue("id"))
if err != nil {
writeError(w, http.StatusNotFound, err.Error())
return store.KBCollection{}, false
}
return c, true
}
func (a *API) kbDelete(w http.ResponseWriter, r *http.Request) {
c, ok := a.kbCollection(w, r)
if !ok {
return
}
if err := a.kb.Store.DeleteCollection(r.Context(), c.ID); err != nil {
writeError(w, http.StatusInternalServerError, err.Error())
return
}
writeJSON(w, http.StatusOK, map[string]any{"id": c.ID, "name": c.Name, "deleted": true})
}
func (a *API) kbDocuments(w http.ResponseWriter, r *http.Request) {
c, ok := a.kbCollection(w, r)
if !ok {
return
}
docs, err := a.kb.Store.Documents(r.Context(), c.ID)
if err != nil {
writeError(w, http.StatusInternalServerError, err.Error())
return
}
out := []KBDocumentView{}
for _, d := range docs {
out = append(out, KBDocumentView{Name: d.Name, Digest: d.Digest, Bytes: d.Bytes, Chunks: d.Chunks,
AddedAt: d.AddedAt, AddedBy: d.AddedBy})
}
writeJSON(w, http.StatusOK, out)
}
func (a *API) kbDeleteDocument(w http.ResponseWriter, r *http.Request) {
c, ok := a.kbCollection(w, r)
if !ok {
return
}
name := r.URL.Query().Get("name")
gone, err := a.kb.Store.DeleteDocument(r.Context(), c.ID, name)
if err != nil {
writeError(w, http.StatusInternalServerError, err.Error())
return
}
if !gone {
writeError(w, http.StatusNotFound, "no document "+name+" in "+c.Name)
return
}
writeJSON(w, http.StatusOK, map[string]any{"name": name, "deleted": true})
}
func (a *API) kbGrant(grant bool) http.HandlerFunc {
return func(w http.ResponseWriter, r *http.Request) {
if !a.kbReady(w) {
return
}
var in KBGrantRequest
if err := json.NewDecoder(r.Body).Decode(&in); err != nil {
writeError(w, http.StatusBadRequest, err.Error())
return
}
c, err := a.kbFind(r.Context(), in.Collection)
if err != nil {
writeError(w, http.StatusNotFound, err.Error())
return
}
scope, id, err := a.kbTarget(r.Context(), in.Target)
if err != nil {
writeError(w, http.StatusBadRequest, err.Error())
return
}
if !grant {
gone, err := a.kb.Store.Revoke(r.Context(), scope, id, c.ID)
if err != nil {
writeError(w, http.StatusInternalServerError, err.Error())
return
}
if !gone {
writeError(w, http.StatusNotFound, "no such grant")
return
}
writeJSON(w, http.StatusOK, KBGrantView{Target: string(scope) + ":" + id})
return
}
perm := store.KBPerm(strings.ToLower(strings.TrimSpace(in.Perm)))
if perm == "" {
perm = store.KBRead
}
if err := a.kb.Store.Grant(r.Context(), store.KBGrant{Scope: scope, ScopeID: id, Collection: c.ID,
Perm: perm, AddedBy: actorOf(r)}); err != nil {
writeError(w, http.StatusBadRequest, err.Error())
return
}
writeJSON(w, http.StatusOK, KBGrantView{Target: string(scope) + ":" + id, Perm: string(perm), At: time.Now(), By: actorOf(r)})
}
}
func (a *API) kbSearch(w http.ResponseWriter, r *http.Request) {
if !a.kbReady(w) {
return
}
var in KBSearchRequest
if err := json.NewDecoder(r.Body).Decode(&in); err != nil {
writeError(w, http.StatusBadRequest, err.Error())
return
}
c, err := a.kbFind(r.Context(), in.Collection)
if err != nil {
writeError(w, http.StatusNotFound, err.Error())
return
}
k := in.K
if k <= 0 || k > 50 {
k = 5
}
q := store.KBSearch{OrgID: c.OrgID, Collections: []store.KBCollection{c}, Text: in.Query, K: k}
// Without the model, the full-text half still answers.
if a.kb.Embed != nil {
if v, err := a.kb.Embed(r.Context(), c.EmbedModel, in.Query); err == nil {
q.Embeddings = map[string][]float32{c.EmbedModel: v}
}
}
hits, err := a.kb.Store.SearchChunks(r.Context(), q)
if err != nil {
writeError(w, http.StatusInternalServerError, err.Error())
return
}
out := []KBHitView{}
for _, h := range hits {
out = append(out, KBHitView{Document: h.Document, Ord: h.Ord, Score: h.Score, Text: h.Body})
}
writeJSON(w, http.StatusOK, out)
}
+138
View File
@@ -0,0 +1,138 @@
package adminapi
import (
"context"
"encoding/json"
"net/http"
"net/url"
"os"
"path/filepath"
"strings"
"testing"
"gitea.mynodes.xyz/ilker/llmgw/internal/control/catalog"
"gitea.mynodes.xyz/ilker/llmgw/internal/store"
)
func kbModels() []catalog.Model {
return append(testModels(), catalog.Model{Name: "bge-m3", Source: "/e",
Capabilities: catalog.Capabilities{Embeddings: true},
Profiles: []catalog.Profile{{Name: "cpu", GPUClass: "h100-80g", TP: 1}}})
}
func TestKnowledgeBasesListSaysWhyThereAreNone(t *testing.T) {
a, _ := setup(t, kbModels())
s, err := store.OpenSQLite(context.Background(), filepath.Join(t.TempDir(), "s.db"))
if err != nil {
t.Fatal(err)
}
defer s.Close()
a.SetKB(&KBAdmin{Store: s})
var v KBView
if code := call(t, a, "GET", "/api/v1/kb", "", &v); code != http.StatusOK || v.Available || !strings.Contains(v.Reason, "SQLite") {
t.Errorf("got %d %+v", code, v)
}
if code := call(t, a, "POST", "/api/v1/kb/collections", `{"owner":"org:x","name":"n","model":"bge-m3"}`, nil); code != http.StatusNotImplemented {
t.Errorf("creating on SQLite: %d", code)
}
}
func TestKnowledgeBasesAdministered(t *testing.T) {
dsn := os.Getenv("LLMGW_TEST_POSTGRES")
if dsn == "" {
t.Skip("set LLMGW_TEST_POSTGRES to a pgvector database to run this")
}
if u, err := url.Parse(dsn); err != nil || !strings.Contains(u.Path, "test") {
t.Fatalf("refusing a database whose name does not say test")
}
ctx := context.Background()
s, err := store.OpenPostgres(ctx, dsn)
if err != nil {
t.Fatal(err)
}
defer s.Close()
if err := s.KnowledgeAvailable(); err != nil {
t.Skip(err)
}
a, _ := setup(t, kbModels())
a.SetQuotas(s)
probes := 0
a.SetKB(&KBAdmin{Store: s, Embed: func(_ context.Context, model, _ string) ([]float32, error) {
probes++
return make([]float32, 4), nil
}})
sfx := strings.ToLower(store.NewID(""))
org, _ := s.CreateOrg(ctx, "Acme"+sfx)
team, _ := s.CreateTeam(ctx, org, "hr")
_, _ = s.CreateProject(ctx, team, "docs")
other, _ := s.CreateOrg(ctx, "Other"+sfx)
// Owner by path; the dimension asked of the model.
var c KBCollectionView
rec := func(method, path, body string, out any) int { return call(t, a, method, path, body, out) }
body := `{"owner":"team:Acme` + sfx + `/hr","name":"politikalar","model":"bge-m3"}`
if code := callCreated(t, a, body, &c); code != http.StatusCreated || c.Dims != 4 || probes != 1 || c.Org != org {
t.Fatalf("create: %d %+v (probes %d)", code, c, probes)
}
// A model that does not embed is refused before anything is written.
if code := rec("POST", "/api/v1/kb/collections", `{"owner":"org:`+org+`","name":"x","model":"llama"}`, nil); code != http.StatusBadRequest {
t.Errorf("a chat model as the embedder: %d", code)
}
// Grants by path, never across organizations.
if code := rec("POST", "/api/v1/kb/grants", `{"collection":"Acme`+sfx+`/politikalar","target":"project:Acme`+sfx+`/hr/docs","perm":"write"}`, nil); code != http.StatusOK {
t.Errorf("grant: %d", code)
}
if code := rec("POST", "/api/v1/kb/grants", `{"collection":"`+c.ID+`","target":"org:`+other+`"}`, nil); code != http.StatusBadRequest {
t.Errorf("a grant to another organization: %d", code)
}
var v KBView
rec("GET", "/api/v1/kb", "", &v)
var got *KBCollectionView
for i := range v.Collections {
if v.Collections[i].ID == c.ID {
got = &v.Collections[i]
}
}
if got == nil || len(got.Grants) != 1 || got.Grants[0].Perm != "write" || !strings.Contains(got.OwnerName, "hr") {
t.Fatalf("list: %+v", got)
}
// By ORG/NAME too.
if code := rec("DELETE", "/api/v1/kb/grants", `{"collection":"Acme`+sfx+`/politikalar","target":"project:Acme`+sfx+`/hr/docs"}`, nil); code != http.StatusOK {
t.Errorf("revoke: %d", code)
}
if code := rec("DELETE", "/api/v1/kb/collections/"+c.ID, "", nil); code != http.StatusOK {
t.Errorf("delete: %d", code)
}
}
func callCreated(t *testing.T, a *API, body string, out any) int {
t.Helper()
mux := http.NewServeMux()
a.Register(mux)
r, _ := http.NewRequest("POST", "/api/v1/kb/collections", strings.NewReader(body))
r.Header.Set("Content-Type", "application/json")
w := &recorder{h: http.Header{}}
mux.ServeHTTP(w, r)
if w.code == http.StatusCreated {
_ = json.Unmarshal(w.body, out)
} else {
t.Logf("create answered %d %s", w.code, w.body)
}
return w.code
}
type recorder struct {
h http.Header
code int
body []byte
}
func (r *recorder) Header() http.Header { return r.h }
func (r *recorder) Write(b []byte) (int, error) {
if r.code == 0 {
r.code = http.StatusOK
}
r.body = append(r.body, b...)
return len(b), nil
}
func (r *recorder) WriteHeader(c int) { r.code = c }
+25
View File
@@ -66,6 +66,7 @@ var PathParams = map[string]string{
"quotas/{scope}": "The scope: org:NAME, team:ORG/TEAM, project:ORG/TEAM/PROJECT, or their IDs after the colon.",
"federation/{peer}": "The federation peer's name, as `llmgw ctl federation list` lists it.",
"holds/{domain}": "The domain as level:name, rack:r12-07, as `llmgw ctl facility` lists it.",
"collections/{id}": "The collection's ID, its name when that is unique, or ORG/NAME.",
}
// Routes is every endpoint Register mounts.
@@ -263,6 +264,30 @@ var Routes = []Route{
{Method: "DELETE", Path: "/api/v1/guard/attachments", Summary: "Detach a guardrail policy",
Request: GuardAttachmentRequest{}, Response: guard.Attachment{}},
// Knowledge bases: collections of documents, which people fill with
// llmgw-kb from their own machines through the gateway.
{Method: "GET", Path: "/api/v1/kb", Summary: "Every knowledge-base collection, with its documents' count and grants",
Description: "Says why there are none when the store cannot hold them (SQLite, or PostgreSQL without pgvector).",
Response: KBView{}},
{Method: "POST", Path: "/api/v1/kb/collections", Summary: "Make a collection, owned by an organization, team, project or person",
Description: "The embedding model's dimension is asked of the model when dims is not given, so the model must be able to serve.",
Request: KBCreateRequest{}, Response: KBCollectionView{}, Status: http.StatusCreated},
{Method: "DELETE", Path: "/api/v1/kb/collections/{id}", Summary: "Remove a collection with its documents and grants",
Response: map[string]any{}},
{Method: "GET", Path: "/api/v1/kb/collections/{id}/documents", Summary: "A collection's documents",
Response: []KBDocumentView{}},
{Method: "DELETE", Path: "/api/v1/kb/collections/{id}/documents", Summary: "Remove one document from a collection",
Query: []Param{{Name: "name", Description: "The document's name, as listed.", Required: true}},
Response: map[string]any{}},
{Method: "POST", Path: "/api/v1/kb/grants", Summary: "Let a scope, and everything below it, read or write a collection",
Description: "Never outside the collection's organization.",
Request: KBGrantRequest{}, Response: KBGrantView{}},
{Method: "DELETE", Path: "/api/v1/kb/grants", Summary: "Take a grant away",
Request: KBGrantRequest{}, Response: KBGrantView{}},
{Method: "POST", Path: "/api/v1/kb/search", Summary: "Try a search of a collection, as an administrator",
Description: "No tenancy applies: this is for checking what a collection holds and finds.",
Request: KBSearchRequest{}, Response: []KBHitView{}},
{Method: "POST", Path: "/api/v1/agents/restart", Summary: "Have every node's agent start again; their engines keep serving",
Response: AgentRestartView{}},