Collections a part of the tree answers from when a request names none

On an organization, team, project or key, the narrowest winning: llmgw ctl
kb default, POST /api/v1/kb/defaults, and the console's Knowledge screen. A
request's own X-Llmgw-Knowledge overrides it and none turns it off. A default
never refuses a request: a collection the caller cannot read is left out, and
a failed search answers without passages. Removing a collection takes it out
of every default.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
This commit is contained in:
Ilker ManapandClaude Opus 5.5 committed 2026-10-08 15:52:43 +02:00
1 parent 54ba04c52a
commit 0093cc3d45
16 files changed
+552 -12

No files matched your search

+75 -3
View File
@@ -29,6 +29,8 @@ type KBStore interface {
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)
SetKBDefault(ctx context.Context, d store.KBDefault) error
KBDefaults(ctx context.Context) ([]store.KBDefault, error)
}
// KBAdmin is what the knowledge-base endpoints need: the store, and a way to
@@ -47,6 +49,28 @@ type KBView struct {
// Reason is why not, when not.
Reason string `json:"reason,omitempty"`
Collections []KBCollectionView `json:"collections"`
// Defaults are the collections parts of the tree answer from when a
// request names none.
Defaults []KBDefaultView `json:"defaults"`
}
// KBDefaultView is one part of the tree's default collections.
type KBDefaultView struct {
Target string `json:"target"`
Name string `json:"name,omitempty"`
// Collections are ORG/NAME, in order.
Collections []string `json:"collections"`
At time.Time `json:"at"`
By string `json:"by,omitempty"`
}
// KBDefaultRequest sets the collections a part of the tree answers from
// when a request names none; none clears it.
type KBDefaultRequest struct {
// Target is org:, team:, project: (by path or ID) or key:KEY-ID.
Target string `json:"target"`
// Collections are IDs, names when unique, or ORG/NAME.
Collections []string `json:"collections"`
}
// KBCollectionView is a collection as an administrator sees it.
@@ -136,6 +160,7 @@ func (a *API) registerKB(mux Mux) {
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)
mux.HandleFunc("POST /api/v1/kb/defaults", a.kbSetDefault)
}
// kbReady answers for a gateway without knowledge bases, and says whether
@@ -165,11 +190,11 @@ func (a *API) names(ctx context.Context) map[string]string {
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{}})
writeJSON(w, http.StatusOK, KBView{Reason: "knowledge bases need the store", Collections: []KBCollectionView{}, Defaults: []KBDefaultView{}})
return
}
if err := a.kb.Store.KnowledgeAvailable(); err != nil {
writeJSON(w, http.StatusOK, KBView{Reason: err.Error(), Collections: []KBCollectionView{}})
writeJSON(w, http.StatusOK, KBView{Reason: err.Error(), Collections: []KBCollectionView{}, Defaults: []KBDefaultView{}})
return
}
cs, err := a.kb.Store.Collections(r.Context())
@@ -183,7 +208,7 @@ func (a *API) kbList(w http.ResponseWriter, r *http.Request) {
return
}
names := a.names(r.Context())
v := KBView{Available: true, Collections: []KBCollectionView{}}
v := KBView{Available: true, Collections: []KBCollectionView{}, Defaults: []KBDefaultView{}}
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],
@@ -202,6 +227,23 @@ func (a *API) kbList(w http.ResponseWriter, r *http.Request) {
}
v.Collections = append(v.Collections, cv)
}
label := map[string]string{}
for _, c := range cs {
label[c.ID] = or(names["org:"+c.OrgID], c.OrgID) + "/" + c.Name
}
defaults, err := a.kb.Store.KBDefaults(r.Context())
if err != nil {
writeError(w, http.StatusInternalServerError, err.Error())
return
}
for _, d := range defaults {
key := string(d.Scope) + ":" + d.ScopeID
dv := KBDefaultView{Target: key, Name: names[key], Collections: []string{}, At: d.AddedAt, By: d.AddedBy}
for _, id := range d.Collections {
dv.Collections = append(dv.Collections, or(label[id], id))
}
v.Defaults = append(v.Defaults, dv)
}
writeJSON(w, http.StatusOK, v)
}
@@ -471,3 +513,33 @@ func (a *API) kbSearch(w http.ResponseWriter, r *http.Request) {
}
writeJSON(w, http.StatusOK, out)
}
func (a *API) kbSetDefault(w http.ResponseWriter, r *http.Request) {
if !a.kbReady(w) {
return
}
var in KBDefaultRequest
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.Target)
if err != nil {
writeError(w, http.StatusBadRequest, err.Error())
return
}
d := store.KBDefault{Scope: scope, ScopeID: id, AddedBy: actorOf(r)}
for _, ref := range in.Collections {
c, err := a.kbFind(r.Context(), ref)
if err != nil {
writeError(w, http.StatusNotFound, err.Error())
return
}
d.Collections = append(d.Collections, c.ID)
}
if err := a.kb.Store.SetKBDefault(r.Context(), d); err != nil {
writeError(w, http.StatusBadRequest, err.Error())
return
}
writeJSON(w, http.StatusOK, KBDefaultView{Target: string(scope) + ":" + id, Collections: in.Collections, At: time.Now(), By: actorOf(r)})
}
+4
View File
@@ -284,6 +284,10 @@ var Routes = []Route{
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/defaults", Summary: "Set the collections a part of the tree answers from when a request names none",
Description: "On an organization, team, project or key; the narrowest one with a default wins. No collections clears it. " +
"A request's own X-Llmgw-Knowledge overrides it, and X-Llmgw-Knowledge: none turns it off.",
Request: KBDefaultRequest{}, Response: KBDefaultView{}},
{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{}},