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:
1 parent
ffab3c99e3
commit
6466f37d50
8 files changed
+1405
-1
No files matched your search
@@ -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.",
|
||||
|
||||
@@ -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),
|
||||
|
||||
@@ -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
|
||||
}
|
||||
@@ -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
|
||||
}
|
||||
}
|
||||
@@ -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)
|
||||
|
||||
@@ -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)
|
||||
}
|
||||
@@ -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 }
|
||||
@@ -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{}},
|
||||
|
||||
|
||||
Reference in new issue
Block a user