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

+93
View File
@@ -1275,6 +1275,49 @@
}
}
},
"/api/v1/kb/defaults": {
"post": {
"operationId": "postKbDefaults",
"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.",
"tags": [
"kb"
],
"parameters": [
{
"$ref": "#/components/parameters/Actor"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/KBDefaultRequest"
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/KBDefaultView"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"default": {
"$ref": "#/components/responses/Error"
}
}
}
},
"/api/v1/kb/grants": {
"post": {
"operationId": "postKbGrants",
@@ -5016,6 +5059,49 @@
}
}
},
"KBDefaultRequest": {
"type": "object",
"description": "KBDefaultRequest sets the collections a part of the tree answers from when a request names none; none clears it.",
"properties": {
"target": {
"type": "string",
"description": "Target is org:, team:, project: (by path or ID) or key:KEY-ID."
},
"collections": {
"type": "array",
"items": {
"type": "string"
},
"description": "Collections are IDs, names when unique, or ORG/NAME."
}
}
},
"KBDefaultView": {
"type": "object",
"description": "KBDefaultView is one part of the tree's default collections.",
"properties": {
"target": {
"type": "string"
},
"name": {
"type": "string"
},
"collections": {
"type": "array",
"items": {
"type": "string"
},
"description": "Collections are ORG/NAME, in order."
},
"at": {
"type": "string",
"format": "date-time"
},
"by": {
"type": "string"
}
}
},
"KBDocumentView": {
"type": "object",
"description": "KBDocumentView is one document in a collection.",
@@ -5131,6 +5217,13 @@
"items": {
"$ref": "#/components/schemas/KBCollectionView"
}
},
"defaults": {
"type": "array",
"items": {
"$ref": "#/components/schemas/KBDefaultView"
},
"description": "Defaults are the collections parts of the tree answer from when a request names none."
}
}
},
+2 -1
View File
@@ -168,7 +168,8 @@ team or project is guaranteed and may at most hold, and what it holds now.
model that embeds it, how many documents and chunks it holds and who else it
is granted to. **A** makes one. On a row: its **Documents**, **Grant…** a
project, team, organization, person or key read or write access, **Revoke**
a grant, **Try a search…** as an administrator, or **Delete…** it. People
a grant, **Answer from it by default…** for a part of the tree, **Try a
search…** as an administrator, or **Delete…** it. People
fill collections from their own machines with `llmgw-kb`
([knowledge.md](knowledge.md)). Off on a SQLite store, and says why.
+26 -1
View File
@@ -88,6 +88,31 @@ How access works:
is answered exactly as one that does not exist, so even its name does not
leak.
### Answer from collections by default
Clients that cannot add a header still get answers from the documents when
their part of the tree has a default:
```sh
llmgw ctl kb default team:Acme/hr Acme/policies Acme/forms
llmgw ctl kb default key:KEY-ID Acme/policies
llmgw ctl kb default team:Acme/hr --clear
```
- **Which default applies.** The narrowest one: a key's over its project's,
a project's over its team's, a team's over its organization's.
- **A request can override it.** A request that names collections uses
those instead, and `X-Llmgw-Knowledge: none` turns the default off for
that request.
- **A default never refuses a request.** A collection the caller may not
read is left out for them. If the search fails (the embedding model is
down, say), the request is answered without passages and the failure is
logged.
- **Changes take effect within 30 seconds.**
In the console: **Knowledge**, Enter on a collection, then **Answer from it
by default…**.
### Look after it
```sh
@@ -274,7 +299,7 @@ How it is shaped:
| | |
|---|---|
| `X-Llmgw-Knowledge` | Collections, comma separated. |
| `X-Llmgw-Knowledge` | Collections, comma separated; `none` for no passages, whatever the default. |
| `X-Llmgw-Knowledge-K` | How many passages, 1 to 20; 5 by default. |
| `X-Llmgw-Project` | For a personal key: the project it acts in. |
| `x-llmgw-sources` (answer) | The passages given, as `document#chunk`, in their numbered order; empty when nothing matched. |