Class AiKnowledgeBaseReference

Stages contexts through bulk ingestion — a durable, asynchronous lane that processes contexts through provider batch APIs rather than inline, built for high-volume ingestion. Unlike upsertContexts, this method returns as soon as the request is staged and never awaits ingestion completion; track progress with observeBulkIngestionJob or by polling getBulkIngestionJob with the returned job id.

Cancels a running bulk-ingestion job. Already-finalized contexts are kept; the job transitions to cancelled once in-flight provider work drains.

Mints presigned upload URLs for direct-to-storage bulk files, bypassing multipart upload through core. PUT each file's bytes to its uploadUrl — sending every header in that entry's requiredHeaders, which some storage backends reject the PUT without — then reference the matching stagedObjectKey in a BulkIngestionContext passed to bulkUpsertContexts.

Deletes the AI knowledge base.

Deletes a specific context by its ID.

Deletes multiple contexts.

Gets the download URL for the requested context.

Returns a bounded slice of the knowledge base's entity graph (highest-degree entities and the relationships among them) for exploration/visualization. Requires graphRag.enabled.

AI-generates descriptions for this knowledge base's metadata fields and returns them WITHOUT persisting — the caller saves them onto the KB (e.g. via upsertKnowledgeBase). By default only fields with an empty description are generated; pass overwriteExisting to regenerate all.

Returns a bulk-ingestion job's current lifecycle state and progress counts.

Retrieves a specific context by its ID.

Returns the knowledge base's graph build/readiness status: counts, facets, staleness, the most recent rebuild job, and the graph's LLM token/cost usage (ingestUsage, lastRebuildUsage).

Returns the AI knowledge base.

Scans the knowledge base's raw extracted text for a literal string and returns every matching line with its file and locator. Unlike search this reads the pre-chunking text, which includes spreadsheet rows verbatim, and matches characters rather than meaning. The pattern is always a literal — regex metacharacters in it are escaped — and matching is case-insensitive. options.metadataFilter scopes the scan to the contexts it admits before any text is matched.

Lists the ids for all contexts associated with the knowledge base.

Lists all contexts associated with the knowledge base.

Lists contexts associated with the knowledge base, paginated via offset/limit and optionally filtered via search (case-insensitive substring match on id/title only).

Returns all AI knowledge bases.

Emits every bulkIngestionStatus push the server sends for the job and completes once a terminal state (completed, failed or cancelled) is emitted. Unlike JobClient.awaitJob, a terminal failed/cancelled state is delivered as a normal emitted value — the observable itself never errors because the job reached a terminal state; it only errors on a transport/subscription failure.

Re-subscribes to the server-side push automatically if the client's connection id changes mid-subscription (e.g. after a long disconnect). Unsubscribing tears down the underlying socket listener. The observable is cold: each subscription independently registers a server-side push subscription, so share it (e.g. rxjs share()) when multiple consumers observe one job.

If the job's app or knowledge base is deleted mid-flight, the job row is purged without a terminal push, so the observable never completes on its own; bound it (e.g. rxjs timeout()) when deletion is possible.

Queries the knowledge base's graph (documents, entities, themes, facets) through the closed op set — overview / resolve / describe / subtree / docsUnder / conceptsOf / neighborhood / pathBetween / globalSummary. Requires graphRag.enabled on the knowledge base.

Enqueues a graph rebuild/backfill. The default 'structural' mode keeps the already-extracted entity graph (extracting only contexts never graph-indexed) and rebuilds just the concept layer (topics + facets); mode: 'full' wipes the graph and re-extracts every context with an LLM — expensive, and only needed when the extraction itself must be redone (e.g. after changing entityTypes or extractionModel). Requires graphRag.enabled. Track progress via getGraphStatus's buildJob; only one rebuild can run per knowledge base at a time.

Performs a semantic search in the knowledge base and returns chunks from the different contexts.

Performs a semantic search in the knowledge base and returns contexts with reasoning. Can be used for matchmaking or similarity search.

Performs a semantic search in the knowledge base and returns contexts with reasoning. Can be used for matchmaking or similarity search.

Like search, but returns the full response — including graphContext (the traversed subgraph) when the search ran with searchMode: 'graph' and graphOptions.includeGraphContext. search predates graphContext and keeps returning only the chunks.

Adds or updates a single context.

Adds or updates multiple contexts. A context request may omit its contextId; when it does, the server generates one and rejects the request if identical content already exists in the knowledge base (content-level dedup). Requests that carry an explicit contextId overwrite that context unconditionally.

Upserts the AI knowledge base.