diff --git a/docs/admin-api.openapi.json b/docs/admin-api.openapi.json index be73360..81b1160 100644 --- a/docs/admin-api.openapi.json +++ b/docs/admin-api.openapi.json @@ -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.", diff --git a/internal/cli/ctl.go b/internal/cli/ctl.go index 3ee886a..8474b00 100644 --- a/internal/cli/ctl.go +++ b/internal/cli/ctl.go @@ -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), diff --git a/internal/cli/kb.go b/internal/cli/kb.go new file mode 100644 index 0000000..7480fd4 --- /dev/null +++ b/internal/cli/kb.go @@ -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 +} diff --git a/internal/cli/server.go b/internal/cli/server.go index 2c5fa45..5741f30 100644 --- a/internal/cli/server.go +++ b/internal/cli/server.go @@ -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 + } +} diff --git a/internal/control/adminapi/api.go b/internal/control/adminapi/api.go index e8570d5..ddd921a 100644 --- a/internal/control/adminapi/api.go +++ b/internal/control/adminapi/api.go @@ -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) diff --git a/internal/control/adminapi/kb.go b/internal/control/adminapi/kb.go new file mode 100644 index 0000000..4701e40 --- /dev/null +++ b/internal/control/adminapi/kb.go @@ -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) +} diff --git a/internal/control/adminapi/kb_test.go b/internal/control/adminapi/kb_test.go new file mode 100644 index 0000000..5f975e0 --- /dev/null +++ b/internal/control/adminapi/kb_test.go @@ -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 } diff --git a/internal/control/adminapi/routes.go b/internal/control/adminapi/routes.go index e2aca76..c5ed415 100644 --- a/internal/control/adminapi/routes.go +++ b/internal/control/adminapi/routes.go @@ -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{}},