KnowledgeProvider
Knowledge-base storage behind search_knowledge.
A provider only stores and searches: the host ingests documents at run setup, and the framework checks scope, bounds and logs every call, and presents hits as untrusted reference. Build one with local_knowledge() or an adapter factory.
Methods
ingest
Admit one document version into the scope and return it with the new store revision. The same key with the same content returns the earlier version; the same key with other content is invalid.
ingest(scope: Scope, source: KnowledgeSource, key: string): Promise<Result<DocVersion>>scopeScoperequiredThe scope to admit the document into, issued by the host. See Scope.
sourceKnowledgeSourcerequiredThe document, binding included. Store the binding as given. See KnowledgeSource.
keystringrequiredThe ingest's idempotency key, unique to this scope and content. Dedup on it.
Returns an error value with one of these codes: unavailable, timeout, invalid, scope_violation.
remove
Remove a document from the scope from the next revision on; searches as of an earlier revision still see it. A retried key is a no-op. No built-in tool calls it today.
remove(scope: Scope, docId: string, key: string): Promise<Result<void>>scopeScoperequiredThe scope the document is in, issued by the host. See Scope.
docId / doc_idstringrequiredThe document to remove.
keystringrequiredThe remove's idempotency key. A retry sends the same key.
Returns an error value with one of these codes: unavailable, timeout, invalid, scope_violation.
search
Return the passages in the scope that best match a query, best first. Return only passages from this scope; the framework drops and audits any other.
search(scope: Scope, query: string, options?: {
k?: PosInt;
sources?: readonly string[];
asOf?: number;
}): Promise<Result<readonly KnowledgeHit[]>>scopeScoperequiredThe scope to search, issued by the host. See Scope.
querystringrequiredThe search text, as the model wrote it in search_knowledge.
kPosIntdefault 5The most hits to return, a positive integer. search_knowledge passes the model's k (1 to 20, 5 when it gives none), and the framework also caps the total hit text at 16 KB.
sourcesreadonly string[]Search only these documents, by doc_id (the source_id). Omitted or empty: search every document in the scope.
asOf / as_ofnumberSearch as of this store revision, a non-negative integer: a pinned fork passes the revision its snapshot recorded, so it sees the corpus its original run saw. Omitted: search the current revision.
Returns an error value with one of these codes: unavailable, timeout, invalid, scope_violation.
get
Return one admitted document version, or not_found when the scope has no such version.
get(scope: Scope, docId: string, version: string): Promise<Result<Doc>>scopeScoperequiredThe scope the document is in, issued by the host. See Scope.
docId / doc_idstringrequiredThe document to get.
versionstringrequiredThe version to get, as ingest or a hit returned it.
Returns an error value with one of these codes: not_found, unavailable, timeout, invalid, scope_violation.
revision
The store's current monotonic revision, recorded as snapshot.knowledge_revision at capture.
revision(scope: Scope): Promise<Result<number>>scopeScoperequiredThe scope asking, issued by the host. local_knowledge keeps one revision for the whole store and ignores it. See Scope.
Returns an error value with one of these codes: unavailable, timeout.