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

+528
View File
@@ -53,6 +53,9 @@
{
"name": "jobs"
},
{
"name": "kb"
},
{
"name": "metrics"
},
@@ -1069,6 +1072,338 @@
}
}
},
"/api/v1/kb": {
"get": {
"operationId": "getKb",
"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).",
"tags": [
"kb"
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/KBView"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"default": {
"$ref": "#/components/responses/Error"
}
}
}
},
"/api/v1/kb/collections": {
"post": {
"operationId": "postKbCollections",
"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.",
"tags": [
"kb"
],
"parameters": [
{
"$ref": "#/components/parameters/Actor"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/KBCreateRequest"
}
}
}
},
"responses": {
"201": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/KBCollectionView"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"default": {
"$ref": "#/components/responses/Error"
}
}
}
},
"/api/v1/kb/collections/{id}": {
"delete": {
"operationId": "deleteKbCollectionsId",
"summary": "Remove a collection with its documents and grants",
"tags": [
"kb"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "The collection's ID, its name when that is unique, or ORG/NAME.",
"schema": {
"type": "string"
}
},
{
"$ref": "#/components/parameters/Actor"
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": {}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"default": {
"$ref": "#/components/responses/Error"
}
}
}
},
"/api/v1/kb/collections/{id}/documents": {
"get": {
"operationId": "getKbCollectionsIdDocuments",
"summary": "A collection's documents",
"tags": [
"kb"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "The collection's ID, its name when that is unique, or ORG/NAME.",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/KBDocumentView"
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"default": {
"$ref": "#/components/responses/Error"
}
}
},
"delete": {
"operationId": "deleteKbCollectionsIdDocuments",
"summary": "Remove one document from a collection",
"tags": [
"kb"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "The collection's ID, its name when that is unique, or ORG/NAME.",
"schema": {
"type": "string"
}
},
{
"name": "name",
"in": "query",
"required": true,
"description": "The document's name, as listed.",
"schema": {
"type": "string"
}
},
{
"$ref": "#/components/parameters/Actor"
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": {}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"default": {
"$ref": "#/components/responses/Error"
}
}
}
},
"/api/v1/kb/grants": {
"post": {
"operationId": "postKbGrants",
"summary": "Let a scope, and everything below it, read or write a collection",
"description": "Never outside the collection's organization.",
"tags": [
"kb"
],
"parameters": [
{
"$ref": "#/components/parameters/Actor"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/KBGrantRequest"
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/KBGrantView"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"default": {
"$ref": "#/components/responses/Error"
}
}
},
"delete": {
"operationId": "deleteKbGrants",
"summary": "Take a grant away",
"tags": [
"kb"
],
"parameters": [
{
"$ref": "#/components/parameters/Actor"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/KBGrantRequest"
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/KBGrantView"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"default": {
"$ref": "#/components/responses/Error"
}
}
}
},
"/api/v1/kb/search": {
"post": {
"operationId": "postKbSearch",
"summary": "Try a search of a collection, as an administrator",
"description": "No tenancy applies: this is for checking what a collection holds and finds.",
"tags": [
"kb"
],
"parameters": [
{
"$ref": "#/components/parameters/Actor"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/KBSearchRequest"
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/KBHitView"
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"default": {
"$ref": "#/components/responses/Error"
}
}
}
},
"/api/v1/metrics/range": {
"post": {
"operationId": "postMetricsRange",
@@ -4606,6 +4941,199 @@
}
}
},
"KBCollectionView": {
"type": "object",
"description": "KBCollectionView is a collection as an administrator sees it.",
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"org": {
"type": "string"
},
"org_name": {
"type": "string"
},
"owner": {
"type": "string"
},
"owner_name": {
"type": "string"
},
"embed_model": {
"type": "string"
},
"dims": {
"type": "integer"
},
"documents": {
"type": "integer"
},
"chunks": {
"type": "integer"
},
"grants": {
"type": "array",
"items": {
"$ref": "#/components/schemas/KBGrantView"
},
"description": "Grants are who else may read or write it."
},
"created_at": {
"type": "string",
"format": "date-time"
},
"created_by": {
"type": "string"
}
}
},
"KBCreateRequest": {
"type": "object",
"description": "KBCreateRequest makes a collection.",
"properties": {
"owner": {
"type": "string",
"description": "Owner is org:NAME, team:ORG/TEAM, project:ORG/TEAM/PROJECT (or the ID after the colon), or user:USER-ID."
},
"org": {
"type": "string",
"description": "Org is the organization a person's collection belongs to; only for user: owners."
},
"name": {
"type": "string"
},
"model": {
"type": "string",
"description": "Model is the catalog model that embeds its documents."
},
"dims": {
"type": "integer",
"description": "Dims is the model's embedding dimension; asked of the model when 0."
}
}
},
"KBDocumentView": {
"type": "object",
"description": "KBDocumentView is one document in a collection.",
"properties": {
"name": {
"type": "string"
},
"digest": {
"type": "string"
},
"bytes": {
"type": "integer",
"format": "int64"
},
"chunks": {
"type": "integer"
},
"added_at": {
"type": "string",
"format": "date-time"
},
"added_by": {
"type": "string"
}
}
},
"KBGrantRequest": {
"type": "object",
"description": "KBGrantRequest lets a scope read or write a collection, or with DELETE takes that away.",
"properties": {
"collection": {
"type": "string",
"description": "Collection is its ID, its name when that is unique, or ORG/NAME."
},
"target": {
"type": "string",
"description": "Target is org:, team:, project:, key: or user: as for guard policies."
},
"perm": {
"type": "string",
"description": "Perm is read or write; ignored by DELETE."
}
}
},
"KBGrantView": {
"type": "object",
"description": "KBGrantView is one grant.",
"properties": {
"target": {
"type": "string"
},
"name": {
"type": "string"
},
"perm": {
"type": "string"
},
"at": {
"type": "string",
"format": "date-time"
},
"by": {
"type": "string"
}
}
},
"KBHitView": {
"type": "object",
"description": "KBHitView is one chunk a search found.",
"properties": {
"document": {
"type": "string"
},
"ord": {
"type": "integer"
},
"score": {
"type": "number"
},
"text": {
"type": "string"
}
}
},
"KBSearchRequest": {
"type": "object",
"description": "KBSearchRequest tries a search, as an administrator: no tenancy applies.",
"properties": {
"collection": {
"type": "string"
},
"query": {
"type": "string"
},
"k": {
"type": "integer"
}
}
},
"KBView": {
"type": "object",
"description": "KBView is every collection, or why there can be none.",
"properties": {
"available": {
"type": "boolean"
},
"reason": {
"type": "string",
"description": "Reason is why not, when not."
},
"collections": {
"type": "array",
"items": {
"$ref": "#/components/schemas/KBCollectionView"
}
}
}
},
"Live": {
"type": "object",
"description": "Live is one of the cluster's adapters as its node last reported it.",
+1
View File
@@ -180,6 +180,7 @@ func newCtlCmd() *cobra.Command {
newCapacityCmd(client, &asJSON),
newQuotaCmd(client, &asJSON),
newGuardCmd(client, &asJSON),
newKBCmd(client, &asJSON),
newConfigCmd(client, &asJSON),
newAuditCmd(client, &asJSON),
newNotifyCmd(client, &asJSON),
+199
View File
@@ -0,0 +1,199 @@
package cli
import (
"encoding/json"
"fmt"
"net/url"
"strings"
"github.com/spf13/cobra"
"gitea.mynodes.xyz/ilker/llmgw/internal/control/adminapi"
)
func newKBCmd(client func() *ctlClient, asJSON *bool) *cobra.Command {
c := &cobra.Command{
Use: "kb",
Short: "Knowledge bases: collections of documents requests are answered from",
Long: "A collection belongs to an organization, team, project or person, and is\n" +
"embedded by one model of the catalog. People put documents into it from\n" +
"their own machines with llmgw-kb (its own download, for Windows, macOS and\n" +
"Linux), which sends text and vectors, never the files.\n\n" +
"Who may read or add to a collection: its owner and everything below it,\n" +
"and whoever it is granted to (grant), never outside its organization.\n" +
"Targets are written org:Acme, team:Acme/hr, project:Acme/hr/docs (or with\n" +
"IDs), key:KEY-ID or user:USER-ID. A collection is named by its ID, its name\n" +
"when that is unique, or ORG/NAME.\n\n" +
"Needs the PostgreSQL store with pgvector; `llmgw ctl kb list` says why not.",
}
c.AddCommand(&cobra.Command{
Use: "list",
Short: "Every collection: owner, model, documents and grants",
Args: cobra.NoArgs,
RunE: func(cmd *cobra.Command, _ []string) error {
var v adminapi.KBView
if err := client().get(cmd.Context(), "/api/v1/kb", &v); err != nil {
return err
}
if *asJSON {
return json.NewEncoder(cmd.OutOrStdout()).Encode(v)
}
out := cmd.OutOrStdout()
if !v.Available {
fmt.Fprintln(out, "Knowledge bases are off: "+v.Reason)
return nil
}
if len(v.Collections) == 0 {
fmt.Fprintln(out, "No collections yet (llmgw ctl kb create).")
return nil
}
w := tab()
fmt.Fprintln(w, "COLLECTION\tOWNER\tMODEL\tDOCUMENTS\tCHUNKS\tGRANTED TO")
for _, c := range v.Collections {
var grants []string
for _, g := range c.Grants {
grants = append(grants, or(g.Name, g.Target)+" ("+g.Perm+")")
}
fmt.Fprintf(w, "%s/%s\t%s\t%s (%d)\t%d\t%d\t%s\n", or(c.OrgName, c.Org), c.Name, or(c.OwnerName, c.Owner),
c.EmbedModel, c.Dims, c.Documents, c.Chunks, strings.Join(grants, ", "))
}
return w.Flush()
},
})
var org string
var dims int
create := &cobra.Command{
Use: "create OWNER NAME MODEL",
Short: "Make a collection owned by an organization, team, project or person",
Long: "MODEL is a catalog model with capabilities.embeddings. Its dimension is asked\n" +
"of it, so it has to be able to serve now; --dims gives it instead.",
Example: " llmgw ctl kb create team:Acme/hr policies bge-m3\n" +
" llmgw ctl kb create user:USER-ID notes bge-m3 --org Acme",
Args: cobra.ExactArgs(3),
RunE: func(cmd *cobra.Command, args []string) error {
body, _ := json.Marshal(adminapi.KBCreateRequest{Owner: args[0], Name: args[1], Model: args[2], Org: org, Dims: dims})
var v adminapi.KBCollectionView
if err := client().do(cmd.Context(), "POST", "/api/v1/kb/collections", json.RawMessage(body), &v); err != nil {
return err
}
fmt.Fprintf(cmd.OutOrStdout(), "collection %s (%s), embedded by %s in %d dimensions\n", v.Name, v.ID, v.EmbedModel, v.Dims)
fmt.Fprintf(cmd.OutOrStdout(), "people with access fill it with: llmgw-kb sync %s FOLDER\n", v.Name)
return nil
},
}
create.Flags().StringVar(&org, "org", "", "the organization of a person's collection")
create.Flags().IntVar(&dims, "dims", 0, "the model's embedding dimension, instead of asking it")
c.AddCommand(create)
c.AddCommand(&cobra.Command{
Use: "delete COLLECTION",
Short: "Remove a collection, its documents and its grants",
Args: cobra.ExactArgs(1),
RunE: func(cmd *cobra.Command, args []string) error {
if err := client().do(cmd.Context(), "DELETE", "/api/v1/kb/collections/"+url.PathEscape(args[0]), nil, nil); err != nil {
return err
}
fmt.Fprintf(cmd.OutOrStdout(), "collection %s removed\n", args[0])
return nil
},
})
for _, verb := range []struct {
use, short, method string
perm bool
}{
{"grant", "Let a scope and everything below it read a collection, or with --write add to it", "POST", true},
{"revoke", "Take a grant away", "DELETE", false},
} {
var write bool
cmd := &cobra.Command{
Use: verb.use + " COLLECTION TARGET",
Short: verb.short,
Example: " llmgw ctl kb " + verb.use + " Acme/policies project:Acme/sales/crm",
Args: cobra.ExactArgs(2),
RunE: func(cmd *cobra.Command, args []string) error {
req := adminapi.KBGrantRequest{Collection: args[0], Target: args[1], Perm: "read"}
if write {
req.Perm = "write"
}
body, _ := json.Marshal(req)
if err := client().do(cmd.Context(), verb.method, "/api/v1/kb/grants", json.RawMessage(body), nil); err != nil {
return err
}
if verb.perm {
fmt.Fprintf(cmd.OutOrStdout(), "%s may %s %s\n", args[1], req.Perm, args[0])
} else {
fmt.Fprintf(cmd.OutOrStdout(), "%s no longer granted %s\n", args[1], args[0])
}
return nil
},
}
if verb.perm {
cmd.Flags().BoolVar(&write, "write", false, "add and remove documents too")
}
c.AddCommand(cmd)
}
c.AddCommand(&cobra.Command{
Use: "docs COLLECTION",
Short: "A collection's documents",
Args: cobra.ExactArgs(1),
RunE: func(cmd *cobra.Command, args []string) error {
var docs []adminapi.KBDocumentView
if err := client().get(cmd.Context(), "/api/v1/kb/collections/"+url.PathEscape(args[0])+"/documents", &docs); err != nil {
return err
}
if *asJSON {
return json.NewEncoder(cmd.OutOrStdout()).Encode(docs)
}
w := tab()
fmt.Fprintln(w, "DOCUMENT\tCHUNKS\tSIZE\tADDED\tBY")
for _, d := range docs {
fmt.Fprintf(w, "%s\t%d\t%s\t%s\t%s\n", d.Name, d.Chunks, humanBytes(d.Bytes), d.AddedAt.Local().Format("2006-01-02 15:04"), d.AddedBy)
}
return w.Flush()
},
})
c.AddCommand(&cobra.Command{
Use: "rm COLLECTION DOCUMENT",
Short: "Remove one document from a collection",
Args: cobra.ExactArgs(2),
RunE: func(cmd *cobra.Command, args []string) error {
path := "/api/v1/kb/collections/" + url.PathEscape(args[0]) + "/documents?name=" + url.QueryEscape(args[1])
if err := client().do(cmd.Context(), "DELETE", path, nil, nil); err != nil {
return err
}
fmt.Fprintf(cmd.OutOrStdout(), "%s removed from %s\n", args[1], args[0])
return nil
},
})
var k int
search := &cobra.Command{
Use: "search COLLECTION QUERY...",
Short: "Try a search of a collection, as an administrator (no tenancy applies)",
Args: cobra.MinimumNArgs(2),
RunE: func(cmd *cobra.Command, args []string) error {
body, _ := json.Marshal(adminapi.KBSearchRequest{Collection: args[0], Query: strings.Join(args[1:], " "), K: k})
var hits []adminapi.KBHitView
if err := client().do(cmd.Context(), "POST", "/api/v1/kb/search", json.RawMessage(body), &hits); err != nil {
return err
}
if *asJSON {
return json.NewEncoder(cmd.OutOrStdout()).Encode(hits)
}
out := cmd.OutOrStdout()
if len(hits) == 0 {
fmt.Fprintln(out, "Nothing found.")
}
for i, h := range hits {
fmt.Fprintf(out, "%d. %s #%d\n%s\n\n", i+1, h.Document, h.Ord, indent(strings.TrimSpace(h.Text), " "))
}
return nil
},
}
search.Flags().IntVarP(&k, "k", "k", 5, "how many chunks")
c.AddCommand(search)
return c
}
+41
View File
@@ -5,6 +5,7 @@ import (
"crypto/rand"
"crypto/tls"
"encoding/hex"
"encoding/json"
"errors"
"fmt"
"log/slog"
@@ -374,6 +375,9 @@ func newServerCmd() *cobra.Command {
api.SetAgentRestarter(agentSvc.RestartAgents)
}
api.SetAudit(st)
// Knowledge bases, with the cluster's own models to embed a
// probe (a collection's dimension) and an operator's search.
api.SetKB(&adminapi.KBAdmin{Store: st, Embed: embedder(rt.Replay)})
// The cluster's settings, each change checked against this
// machine's own keys before it is kept.
api.SetSettings(&adminapi.Settings{Store: st, LocalKeys: config.LocalKeys(),
@@ -1183,3 +1187,40 @@ func federationID(ctx context.Context, st *storepkg.DB) (string, error) {
// more of a secret than needed.
return secret[:16], nil
}
// embedder has a model embed one text through the gateway itself, the way a
// kept request is replayed: for the administrator's knowledge-base
// endpoints, not for anybody's traffic.
func embedder(replay func(ctx context.Context, path, model string, body []byte) (int, []byte, time.Duration, error)) func(context.Context, string, string) ([]float32, error) {
return func(ctx context.Context, model, text string) ([]float32, error) {
body, _ := json.Marshal(map[string]any{"model": model, "input": []string{text}})
status, out, _, err := replay(ctx, "/v1/embeddings", model, body)
if err != nil {
return nil, err
}
if status != http.StatusOK {
msg := strings.TrimSpace(string(out))
var e struct {
Error struct {
Message string `json:"message"`
} `json:"error"`
}
if json.Unmarshal(out, &e) == nil && e.Error.Message != "" {
msg = e.Error.Message
}
return nil, fmt.Errorf("%d: %s", status, msg)
}
var res struct {
Data []struct {
Embedding []float32 `json:"embedding"`
} `json:"data"`
}
if err := json.Unmarshal(out, &res); err != nil {
return nil, err
}
if len(res.Data) != 1 || len(res.Data[0].Embedding) == 0 {
return nil, fmt.Errorf("%s answered no embedding", model)
}
return res.Data[0].Embedding, nil
}
}
+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{}},