@squidcloud/twilio-client 1.0.493

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,2144 @@
1
+ import { AgentContextRequest, AiChatModelSelection, AiReasoningEffort, ContextImageFailure, UpsertContextStatusError } from './ai-agent.public-types';
2
+ import { AiEmbeddingsModelSelection, AiRerankProvider } from './ai-common.public-types';
3
+ import { AiContextId, AiKnowledgeBaseId, AppId } from './communication.public-types';
4
+ import { DocumentExtractionMethod } from './extraction.public-types';
5
+ import { MetadataAndFilter, MetadataFieldFilter, MetadataOrFilter, MetadataSimpleFilter, MetadataValue, MetadataValueArray } from './metadata-filter.public-types';
6
+ /**
7
+ * The set of supported vector store backends for a knowledge base. The authoritative backend for a
8
+ * given KB is persisted on its record; reads/writes route through the matching vector provider.
9
+ * @category AI
10
+ */
11
+ export declare const VECTOR_DB_TYPES: readonly ["postgres", "mongoAtlas"];
12
+ /**
13
+ * A vector store backend identifier. See {@link VECTOR_DB_TYPES}.
14
+ * @category AI
15
+ */
16
+ export type VectorDbType = (typeof VECTOR_DB_TYPES)[number];
17
+ /**
18
+ * Represents an AI knowledge base that can be attached to an AI agent.
19
+ * @category AI
20
+ */
21
+ export interface AiKnowledgeBase {
22
+ /** The unique identifier of the knowledge base.*/
23
+ id: AiKnowledgeBaseId;
24
+ /** The app id that the knowledge base belongs to. */
25
+ appId: AppId;
26
+ /** The user's description of the knowledge base */
27
+ description: string;
28
+ /** A set of predefined metadata fields for the knowledge base that can be used for filtering.*/
29
+ metadataFields: Array<AiKnowledgeBaseMetadataField>;
30
+ /** The embedding model that should be used for this knowledge base.*/
31
+ embeddingModel: AiEmbeddingsModelSelection;
32
+ /** The model name that should be used when asking questions of this knowledge base. */
33
+ chatModel: AiChatModelSelection;
34
+ /**
35
+ * The vector store backend this knowledge base reads/writes from. Set at creation (defaulting to
36
+ * the server's `SQUID_DEFAULT_VECTOR_DB_TYPE`, otherwise `'postgres'`) and immutable thereafter.
37
+ * Optional on the read type for backwards compatibility with older records.
38
+ */
39
+ vectorDbType?: VectorDbType;
40
+ /**
41
+ * Opt-in GraphRAG configuration. Only honored for `vectorDbType:'mongoAtlas'` KBs; enables
42
+ * per-chunk entity/relationship extraction at ingest and `searchMode:'graph'` at query time.
43
+ */
44
+ graphRag?: AiKnowledgeBaseGraphConfig;
45
+ /**
46
+ * Default RAG strategy for newly ingested contexts; a per-request `options.ragType` overrides it.
47
+ * Omitted ⇒ the server default (`'contextual'`). Changing it affects future ingests only — existing
48
+ * chunks are not re-processed.
49
+ */
50
+ ragType?: AiRagType;
51
+ /**
52
+ * Lifetime LLM usage of the contextual-RAG situating-blurb calls on this KB (server-managed; ignored
53
+ * on upsert). Persisted on the KB itself so the record survives Core restarts and covers any vector
54
+ * store. Under the combined-ingest strategy this stays ≈0 — growth is a visible fallback-rate signal.
55
+ */
56
+ contextualIngestUsage?: KnowledgeBaseGraphUsage;
57
+ /**
58
+ * Per-caller access control over retrieval. Omitted ⇒ `'none'`: stored scopes are ignored and every
59
+ * caller sees every chunk.
60
+ */
61
+ accessControl?: AiKnowledgeBaseAccessControl;
62
+ /** The timestamp the knowledge base was last updated */
63
+ updatedAt: Date;
64
+ }
65
+ /**
66
+ * The access-control modes a knowledge base can be in. See {@link AiKnowledgeBaseAccessControl}.
67
+ * @category AI
68
+ */
69
+ export declare const AI_KB_ACCESS_CONTROL_MODES: readonly ["none", "enforced"];
70
+ /**
71
+ * A knowledge base access-control mode. See {@link AI_KB_ACCESS_CONTROL_MODES}.
72
+ * @category AI
73
+ */
74
+ export type AiKnowledgeBaseAccessControlMode = (typeof AI_KB_ACCESS_CONTROL_MODES)[number];
75
+ /**
76
+ * Restricts what a search returns to the content its caller is entitled to.
77
+ *
78
+ * Under `'enforced'`, every chunk carries the access scopes of the context it came from, the caller is
79
+ * resolved to the scopes they hold, and the two are intersected inside the vector query — so a caller
80
+ * never retrieves a chunk they hold no scope for. A chunk stamped as public is visible to everyone; a
81
+ * chunk with no scopes at all (ingested before access control was enabled) is visible to no one.
82
+ *
83
+ * Enforcement covers retrieval channels that can apply the scope predicate. The raw-text scan (`grep`)
84
+ * and knowledge-graph (`queryGraph`, `searchMode: 'graph'`) channels read stores that carry no scopes,
85
+ * so an enforced knowledge base refuses them rather than answering unfiltered.
86
+ *
87
+ * Mutable, but enabling it on a populated knowledge base hides everything already ingested until those
88
+ * contexts are re-ingested with scopes.
89
+ *
90
+ * @category AI
91
+ */
92
+ export interface AiKnowledgeBaseAccessControl {
93
+ /** `'none'` (the default) ignores stored scopes entirely; `'enforced'` intersects them per caller. */
94
+ mode: AiKnowledgeBaseAccessControlMode;
95
+ /**
96
+ * The backend function that resolves a caller into the access scopes they hold, as
97
+ * `'ServiceName:functionName'`. It runs once per search, receives a `ResolveKbScopesContext` and
98
+ * returns the scopes as an array of strings. Required under `'enforced'`.
99
+ *
100
+ * An `'enforced'` knowledge base whose function is not deployed fails every search rather than
101
+ * falling back to an unfiltered one.
102
+ *
103
+ * @pattern ^[^:]+:[^:]+$
104
+ */
105
+ scopeResolver?: string;
106
+ }
107
+ /**
108
+ * Represents a field in an AI knowledge base metadata.
109
+ */
110
+ export interface AiKnowledgeBaseMetadataField {
111
+ /** The name of field.*/
112
+ name: string;
113
+ /**
114
+ * The field data type - used for validation and filtering. `date` values are normalized to integer
115
+ * epoch milliseconds at write time so range filters (`$gt`/`$lt`) work across vector store backends.
116
+ * `array` is not yet supported and is rejected at knowledge-base upsert time.
117
+ */
118
+ dataType: 'string' | 'number' | 'boolean' | 'date' | 'array';
119
+ /** Indicates if the field is required for knowledge base entries.*/
120
+ required: boolean;
121
+ /**
122
+ * In case that the field is required and not provided when uploaded to the knowledge base,
123
+ * this description will be used for extracting the value from the document.
124
+ * Also, it will be used for auto filtering when a prompt is sent to an AI agent.
125
+ */
126
+ description?: string;
127
+ /**
128
+ * True when {@link description} was AI-generated (via `generateMetadataFieldDescriptions`). Undefined or
129
+ * false means the description was authored by a human or has not been generated yet; it clears back to
130
+ * false once a human edits the description.
131
+ */
132
+ descriptionGeneratedByAi?: boolean;
133
+ /**
134
+ * Whether the LLM extraction pass may fill this field when it is missing. Defaults to `true` when
135
+ * undefined, so knowledge bases created before this flag existed keep their behavior. Set to `false`
136
+ * for fields whose value the caller supplies deterministically (e.g. folder-derived path metadata): a
137
+ * missing value then stays absent rather than being guessed from the document.
138
+ */
139
+ llmExtraction?: boolean;
140
+ }
141
+ /**
142
+ * A record of metadata key-value pairs for AI context, where values are primitive types or undefined.
143
+ * @category AI
144
+ */
145
+ export type AiContextMetadata = Record<string, AiContextMetadataValue>;
146
+ /**
147
+ * @category AI
148
+ * @deprecated Use {@link MetadataValue} from `metadata-filter.public-types` instead.
149
+ */
150
+ export type AiContextMetadataValue = MetadataValue;
151
+ /**
152
+ * @category AI
153
+ * @deprecated Use {@link MetadataValueArray} from `metadata-filter.public-types` instead.
154
+ */
155
+ export type AiContextMetadataValueArray = MetadataValueArray;
156
+ /**
157
+ * @category AI
158
+ * @deprecated Use {@link MetadataSimpleFilter} from `metadata-filter.public-types` instead.
159
+ */
160
+ export type AiContextMetadataSimpleFilter = MetadataSimpleFilter;
161
+ /**
162
+ * A filter for AI context metadata based on field-specific conditions or values.
163
+ * @category AI
164
+ * @deprecated Use {@link MetadataFieldFilter} from `metadata-filter.public-types` instead.
165
+ */
166
+ export type AiContextMetadataFieldFilter = MetadataFieldFilter;
167
+ /**
168
+ * A filter combining multiple AI context metadata filters with a logical AND operation.
169
+ * @category AI
170
+ * @deprecated Use {@link MetadataAndFilter} from `metadata-filter.public-types` instead.
171
+ */
172
+ export type AiContextMetadataAndFilter = MetadataAndFilter;
173
+ /**
174
+ * A filter combining multiple AI context metadata filters with a logical OR operation.
175
+ * @category AI
176
+ * @deprecated Use {@link MetadataOrFilter} from `metadata-filter.public-types` instead.
177
+ */
178
+ export type AiContextMetadataOrFilter = MetadataOrFilter;
179
+ /**
180
+ * Retrieval mode for a knowledge-base search.
181
+ * - `'vector'`: dense-only similarity.
182
+ * - `'hybrid'`: native fusion of dense + lexical (only distinct on backends with native fusion, e.g.
183
+ * Mongo Atlas; on pgvector it degrades to dense + a legacy app-side keyword fallback).
184
+ * - `'keyword'`: embedding-free lexical retrieval; the mechanism is backend-specific — native Lucene BM25
185
+ * on Mongo Atlas (ranked, term-optional: a partial-term query still matches), and a boolean substring
186
+ * filter on pgvector (every term must appear literally; unranked).
187
+ * - `'graph'`: GraphRAG retrieval — seeds entities via vector search, expands relationships via graph
188
+ * traversal, then maps entities back to their source chunks, RRF-fused with a standard hybrid search.
189
+ * Only available on `vectorDbType:'mongoAtlas'` KBs with `graphRag.enabled`; tuned via
190
+ * {@link AiKnowledgeBaseGraphSearchOptions}. This is the DEFAULT mode when a search omits `searchMode`
191
+ * on a `graphRag.enabled` KB (non-graph KBs default to `'hybrid'`).
192
+ * @category AI
193
+ */
194
+ export type AiKnowledgeBaseSearchMode = 'vector' | 'hybrid' | 'keyword' | 'graph';
195
+ /**
196
+ * Fine-grained options for `searchMode: 'graph'` retrieval (GraphRAG). The graph channel is always
197
+ * RRF-fused with a standard hybrid search; themes-level "global" answering has moved to the
198
+ * `globalSummary` op of the `queryKnowledgeGraph` surface.
199
+ * @category AI
200
+ */
201
+ export interface AiKnowledgeBaseGraphSearchOptions {
202
+ /** Entities seeded via vector search before graph expansion. Default 8, max 25. */
203
+ seedLimit?: number;
204
+ /** Number of hops to expand from each seed (traversal depth + 1). Default 2, max 3. */
205
+ maxHops?: number;
206
+ /** When true, attach the traversed {@link AiKnowledgeBaseGraphContext} to the response. Default false. */
207
+ includeGraphContext?: boolean;
208
+ }
209
+ /**
210
+ * Per-knowledge-base GraphRAG configuration. Opt-in and mutable (unlike `embeddingModel`/`vectorDbType`);
211
+ * only honored for `vectorDbType:'mongoAtlas'` KBs. Enabling it on a KB that already has content backfills
212
+ * the graph automatically (a debounced structural build runs once the KB goes quiet); the `rebuildGraph`
213
+ * endpoint remains available for an immediate or full rebuild.
214
+ * @category AI
215
+ */
216
+ export interface AiKnowledgeBaseGraphConfig {
217
+ /** When true, ingestion extracts an entity/relationship graph and `searchMode:'graph'` becomes available. */
218
+ enabled: boolean;
219
+ /** Chat model used for per-chunk entity/relationship extraction. Defaults to the server's graph model. */
220
+ extractionModel?: AiChatModelSelection;
221
+ /** Optional domain taxonomy hint (entity types) injected into the extraction prompt. */
222
+ entityTypes?: string[];
223
+ /**
224
+ * Quiet window (milliseconds) after the last graph activity before the sweep auto-builds the
225
+ * structure. Must be a positive integer, and is floored at 3 seconds — a shorter window is not
226
+ * servable. Defaults to the server's window (5 minutes); the sweep cadence (1 minute) bounds how
227
+ * promptly an elapsed window is picked up.
228
+ */
229
+ autoBuildDebounceMs?: number;
230
+ /**
231
+ * When true, the sweep does not start automatic structural builds for this KB: activity keeps arming
232
+ * the build, and the first quiet window after the flag is cleared runs it. Meant for an ingestion
233
+ * campaign whose builds an operator wants to schedule by hand; `rebuildGraph` stays available.
234
+ * Defaults to false.
235
+ */
236
+ autoBuildPaused?: boolean;
237
+ /** Concept-layer (facet taxonomy) configuration. Omitted ⇒ `facets: 'auto'`. */
238
+ concepts?: AiKnowledgeBaseGraphConceptsConfig;
239
+ }
240
+ /**
241
+ * Configuration of the graph's concept layer (Layered KB Graph L3 facets — deterministic trees built
242
+ * from metadata values at rebuild).
243
+ * @category AI
244
+ */
245
+ export interface AiKnowledgeBaseGraphConceptsConfig {
246
+ /**
247
+ * Which metadata fields become value facets (flat sets of categorical values). `'auto'` (the default)
248
+ * profiles the KB's context metadata and selects the categorical fields; an explicit list overrides
249
+ * auto-selection (fields still subject to the hard cardinality cap); `[]` disables value facets.
250
+ */
251
+ facets?: string[] | 'auto';
252
+ /**
253
+ * Explicit path facets — deterministic trees split from a hierarchical path field (e.g. a folder path)
254
+ * rather than LLM-grouped. Independent of {@link facets}: a path facet always builds when its field has
255
+ * values, coexists with auto value-facet selection (reserved outside the facet cap), and is exempt from
256
+ * the categorical eligibility gates (a path field is near-unique by leaf). Omitted/`[]` ⇒ no path facets.
257
+ */
258
+ pathFacets?: AiKnowledgeBaseGraphPathFacetConfig[];
259
+ }
260
+ /**
261
+ * The canonical folder-path metadata field: a POSIX-separated path relative to the upload root, no
262
+ * leading/trailing slash, case-preserved. Stamped by folder-aware ingestion (console folder upload,
263
+ * SDK clients). Register it under `graphRag.concepts.pathFacets` (`[{ field: 'folderPath', type: 'path' }]`)
264
+ * to build a navigable folder tree in the graph — the field name is never treated specially on its own.
265
+ * @category AI
266
+ */
267
+ export declare const FOLDER_PATH_METADATA_FIELD_NAME = "folderPath";
268
+ /**
269
+ * A path facet: a deterministic tree built by splitting a hierarchical path field on {@link separator}.
270
+ * Interior nodes are the path prefixes; scoping a search to one node matches that folder and everything
271
+ * beneath it. Exempt from the near-unique/cardinality eligibility gates (those judge flat value sets).
272
+ * Declared under {@link AiKnowledgeBaseGraphConceptsConfig.pathFacets}.
273
+ * @category AI
274
+ */
275
+ export interface AiKnowledgeBaseGraphPathFacetConfig {
276
+ /** The metadata field holding the path values (e.g. `'folderPath'`). */
277
+ field: string;
278
+ /** Marks this as a path facet. */
279
+ type: 'path';
280
+ /** Path segment separator. Defaults to `'/'`. */
281
+ separator?: string;
282
+ }
283
+ /**
284
+ * The canonical declaration of {@link FOLDER_PATH_METADATA_FIELD_NAME}, shared by every writer that
285
+ * declares it on a knowledge base. `llmExtraction` is off, so a missing folder path stays absent
286
+ * instead of being guessed from document content.
287
+ * @category AI
288
+ */
289
+ export declare const FOLDER_PATH_METADATA_FIELD: AiKnowledgeBaseMetadataField;
290
+ /** A single entity surfaced in a graph search's {@link AiKnowledgeBaseGraphContext}. @category AI */
291
+ export interface AiKnowledgeBaseGraphContextEntity {
292
+ /** Canonical display name of the entity. */
293
+ name: string;
294
+ /** Entity type (e.g. PERSON, ORGANIZATION). */
295
+ type: string;
296
+ /** Compacted description of the entity. */
297
+ description: string;
298
+ /** Traversal relevance score in [0,1]. */
299
+ score: number;
300
+ }
301
+ /** A single relationship surfaced in a graph search's {@link AiKnowledgeBaseGraphContext}. @category AI */
302
+ export interface AiKnowledgeBaseGraphContextRelationship {
303
+ /** Source entity display name. */
304
+ source: string;
305
+ /** Target entity display name. */
306
+ target: string;
307
+ /** Relationship label (short verb phrase). */
308
+ type: string;
309
+ /** Optional description of the relationship. */
310
+ description?: string;
311
+ }
312
+ /**
313
+ * The subgraph traversed to answer a `searchMode:'graph'` query. Additive/optional — returned only when
314
+ * `graphOptions.includeGraphContext` is set; clients that ignore it are unaffected.
315
+ * @category AI
316
+ */
317
+ export interface AiKnowledgeBaseGraphContext {
318
+ /** Entities reached by the traversal, sorted by score descending. */
319
+ entities: Array<AiKnowledgeBaseGraphContextEntity>;
320
+ /** Outgoing relationships between reached entities. */
321
+ relationships: Array<AiKnowledgeBaseGraphContextRelationship>;
322
+ }
323
+ /**
324
+ * The options for the AI knowledgebase search method.
325
+ * @category AI
326
+ */
327
+ export interface AiKnowledgeBaseChatOptions {
328
+ /** A set of filters that will limit the context the AI can access. */
329
+ contextMetadataFilter?: AiContextMetadataFilter;
330
+ /** Whether to include references from the source context in the response. Default to false. */
331
+ includeReference?: boolean;
332
+ /** Include metadata in the context */
333
+ includeMetadata?: boolean;
334
+ /** Which provider's reranker to use for reranking the context. Defaults to 'cohere'. */
335
+ rerankProvider?: AiRerankProvider;
336
+ /**
337
+ * Minimum reranker relevance score a chunk must reach to stay once at least 10 chunks are already kept.
338
+ * Defaults to 0.2. Lets an eval tune the drop threshold per reranker, whose score ranges differ.
339
+ */
340
+ rerankScoreThreshold?: number;
341
+ /** The maximum number of results to return. Defaults to 30 */
342
+ limit?: number;
343
+ /** How many chunks to look over. Defaults to 100 */
344
+ chunkLimit?: number;
345
+ /** Which chat model to use when asking the question */
346
+ chatModel?: AiChatModelSelection;
347
+ /**
348
+ * Selects how the underlying vector store generates candidates:
349
+ * - `'hybrid'` (default): fuses dense vector and keyword candidates when the backend supports it
350
+ * (Mongo Atlas uses `$rankFusion`; backends without native fusion fall back to dense-only with
351
+ * the legacy app-side keyword fallback).
352
+ * - `'vector'`: dense-only — skips native fusion even on backends that support it.
353
+ * - `'keyword'`: embedding-free lexical retrieval; the mechanism is backend-specific. On Mongo Atlas it
354
+ * is native Lucene BM25 (`$search`): results are ranked by relevance and term-optional — a partial-term
355
+ * query still returns its best matches. On Postgres it is a boolean substring filter (`ILIKE ALL`):
356
+ * every whitespace-separated term must appear in a chunk as a literal, case-insensitive substring,
357
+ * matched independently (order, adjacency and relevance are NOT considered), so results are unranked and
358
+ * for broad terms the returned top-k is arbitrary. Both skip embedding, dense, reranking and the
359
+ * app-side keyword fallback. Lets an agent (or an eval) target exact tokens — identifiers, names, codes
360
+ * — that dense retrieval tends to miss.
361
+ *
362
+ * Intended to let A/B evaluations compare dense-only, hybrid and boolean-keyword candidate generation
363
+ * on the same backend.
364
+ *
365
+ * When omitted, the default is `'graph'` (RRF-fused GraphRAG) on a `graphRag.enabled` KB and
366
+ * `'hybrid'` otherwise. See {@link AiKnowledgeBaseSearchMode}.
367
+ */
368
+ searchMode?: AiKnowledgeBaseSearchMode;
369
+ /**
370
+ * Per-pipeline weights for native hybrid fusion (Mongo `$rankFusion.combination.weights`). Only
371
+ * applies when `searchMode` is `'hybrid'` on a backend with native fusion; ignored otherwise.
372
+ * Each value must be a finite non-negative number; an omitted key defaults to `1` (the MongoDB
373
+ * default). Useful for A/B evaluating dense-vs-keyword weighting on the same backend.
374
+ */
375
+ hybridWeights?: AiHybridSearchWeights;
376
+ /** Tuning for `searchMode:'graph'` (GraphRAG). Ignored for other search modes. */
377
+ graphOptions?: AiKnowledgeBaseGraphSearchOptions;
378
+ /**
379
+ * Scopes the search to the documents under one concept of the KB's graph (Layered KB Graph).
380
+ * Composes with every `searchMode` and with `contextMetadataFilter`. Requires `graphRag.enabled`.
381
+ */
382
+ graphFilter?: AiKnowledgeBaseGraphFilter;
383
+ }
384
+ /**
385
+ * Graph scope for a knowledge-base search: restricts results to the documents under one concept.
386
+ * @category AI
387
+ */
388
+ export interface AiKnowledgeBaseGraphFilter {
389
+ /**
390
+ * The concept to scope to: a facet nodeId (`facet_…` — exact, the only persistable concept handles)
391
+ * or a concept name, resolved server-side (exact → alias → similarity). Facet scopes filter by exact
392
+ * metadata membership; topic scopes are thematic (recall-safe but fuzzy — docs outside the theme's
393
+ * current membership are excluded). An unresolvable ref fails with `CONCEPT_NOT_FOUND` and the
394
+ * nearest matching concept names.
395
+ */
396
+ underConcept: string;
397
+ }
398
+ /**
399
+ * Per-pipeline weights for native hybrid fusion. Sub-keys mirror the `$rankFusion` pipeline names.
400
+ * @category AI
401
+ */
402
+ export interface AiHybridSearchWeights {
403
+ /** Weight for the dense vector sub-pipeline. Defaults to `1`. */
404
+ vector?: number;
405
+ /** Weight for the BM25 keyword sub-pipeline. Defaults to `1`. */
406
+ keyword?: number;
407
+ }
408
+ /**
409
+ * Segment-safe subtree match on a hierarchical string field such as a folder path: matches when the
410
+ * field's value is exactly the operand, or begins with the operand followed by a `/` separator. Unlike
411
+ * a raw character prefix, `{ folderPath: { $underPath: 'reports/2023' } }` matches `reports/2023` and
412
+ * `reports/2023/q1/deck` but never the lexical sibling `reports/2023 drafts` — the separator supplies
413
+ * the segment boundary, so subtree scoping never leaks into a sibling that merely shares a prefix.
414
+ *
415
+ * The operand is normalized by stripping any leading and trailing `/` before matching, so a caller that
416
+ * writes `reports/2023/` addresses the same subtree as `reports/2023`. The empty operand matches every
417
+ * document that HAS the field. Matching is case-sensitive.
418
+ *
419
+ * ### Canonical `folderPath` contract
420
+ * The value this operator is designed for — a document's `folderPath` metadata — is written and matched
421
+ * under one canonical form so filters, subtree scoping and the knowledge-graph path facet never
422
+ * fragment by how a value was authored:
423
+ * - POSIX `/` separators; no leading or trailing slash.
424
+ * - The empty string denotes the upload root (a file directly under it), never `undefined`.
425
+ * - Case-preserved on write and matched case-sensitively (`Reports` and `reports` are distinct folders).
426
+ * - NFC-normalized on write, so canonically-equivalent Unicode spellings compare equal.
427
+ *
428
+ * `folderPath` is an ordinary metadata key (not reserved); this operator is the tool for scoping to it.
429
+ * `$underPath` is knowledge-base-only: it is deliberately absent from the shared {@link MetadataSimpleFilter}
430
+ * that metrics and matchmaking consume (they reject unknown operators at runtime).
431
+ * @category AI
432
+ */
433
+ export interface MetadataUnderPathFilter {
434
+ /** The subtree root the field's value must equal or sit under (leading/trailing `/` are ignored). */
435
+ $underPath: string;
436
+ }
437
+ /** A knowledge-base single-field operator: the shared {@link MetadataSimpleFilter} operators plus `$underPath`. */
438
+ export type AiKbMetadataSimpleFilter = MetadataSimpleFilter | MetadataUnderPathFilter;
439
+ /** A knowledge-base field filter: field names mapped to a {@link AiKbMetadataSimpleFilter} or a direct scalar. */
440
+ export interface AiKbMetadataFieldFilter {
441
+ /** A record where keys are field names and values are either operator objects or direct scalar values. */
442
+ [field: string]: AiKbMetadataSimpleFilter | MetadataValue;
443
+ }
444
+ /** Knowledge-base filters combined with logical AND; each branch may itself use `$underPath`. */
445
+ export interface AiKbMetadataAndFilter {
446
+ /** An array of filters that must all be true for the condition to pass. */
447
+ $and: AiContextMetadataFilter[];
448
+ }
449
+ /** Knowledge-base filters combined with logical OR; each branch may itself use `$underPath`. */
450
+ export interface AiKbMetadataOrFilter {
451
+ /** An array of filters where at least one must be true for the condition to pass. */
452
+ $or: AiContextMetadataFilter[];
453
+ }
454
+ /**
455
+ * The knowledge-base context metadata filter: the shared MongoDB-style filter syntax extended with the
456
+ * KB-only `$underPath` operator (see {@link MetadataUnderPathFilter}). Other subsystems (metrics,
457
+ * matchmaking) use the plain `MetadataFilter`, which omits `$underPath`.
458
+ * @category AI
459
+ */
460
+ export type AiContextMetadataFilter = AiKbMetadataFieldFilter | AiKbMetadataAndFilter | AiKbMetadataOrFilter;
461
+ /**
462
+ * Represents an AI knowledge base's context entry with metadata and content.
463
+ * @category AI
464
+ */
465
+ export interface AiKnowledgeBaseContext {
466
+ /** The unique identifier of the context entry. */
467
+ id: string;
468
+ /** The application id of the context entry */
469
+ appId: AppId;
470
+ /** The knowledge base id of the context entry */
471
+ knowledgeBaseId: AiKnowledgeBaseId;
472
+ /** The date and time the context was created. */
473
+ createdAt: Date;
474
+ /** The date and time the context was last updated. */
475
+ updatedAt: Date;
476
+ /** The type of context (e.g., 'text' or 'file'). */
477
+ type: AiKnowledgeBaseContextType;
478
+ /** A title describing the context content. */
479
+ title: string;
480
+ /** The text content of the context. */
481
+ text: string;
482
+ /** Indicates whether the context is a preview; defaults to false. */
483
+ preview: boolean;
484
+ /** The size of the context content in bytes. */
485
+ sizeBytes: number;
486
+ /** Metadata associated with the context. */
487
+ metadata: AiContextMetadata;
488
+ /**
489
+ * Names of metadata fields whose stored values were machine-extracted from the content
490
+ * (driven by the knowledge base's `metadataFields` schema, plus the reserved `lastModified` key
491
+ * every knowledge base derives from the document container) rather than user-supplied.
492
+ * On re-upsert/replay, extracted values count as not-supplied (re-extracted fresh) while
493
+ * user-supplied values are preserved; consumers can also use this to caveat extracted values.
494
+ */
495
+ autoExtractedMetadataFields?: string[];
496
+ /**
497
+ * SHA-256 (hex) of the source bytes (file) or UTF-8 text this context was ingested from. Powers
498
+ * content-level dedup on upsert. Absent on legacy contexts ingested before hashing was introduced.
499
+ */
500
+ contentHash?: string;
501
+ /** Original request configuration for how the context content was processed. */
502
+ requestConfig?: AgentContextRequest;
503
+ }
504
+ /**
505
+ * @category AI
506
+ */
507
+ export type AiKnowledgeBaseContextType = 'text' | 'file';
508
+ /**
509
+ * @category AI
510
+ */
511
+ export type AiKnowledgeBaseContextRequest = AiKnowledgeBaseTextContextRequest | AiKnowledgeBaseFileContextRequest;
512
+ /**
513
+ * Base fields shared by all knowledge base context requests.
514
+ * @category AI
515
+ */
516
+ export interface BaseAiKnowledgeBaseContextRequest {
517
+ /** The unique identifier of the context item. */
518
+ contextId?: string;
519
+ /** The type of the context content. */
520
+ type: AiKnowledgeBaseContextType;
521
+ /** Optional metadata associated with the context item. */
522
+ metadata?: AiContextMetadata;
523
+ /**
524
+ * Access scopes granting read access to this context, stamped onto every chunk it produces. Only
525
+ * meaningful on a knowledge base with `accessControl.mode: 'enforced'`, where a caller retrieves the
526
+ * context only if they hold at least one of these scopes.
527
+ *
528
+ * Supplied here rather than through a follow-up call so a restricted context is never briefly
529
+ * readable by everyone between being indexed and being scoped. Omitted on a re-ingest keeps whatever
530
+ * scopes the context already had; an empty array makes it visible to every caller.
531
+ *
532
+ * Scopes are opaque strings the resolver and the ingest side agree on. The `__` prefix is reserved.
533
+ */
534
+ scopes?: Array<string>;
535
+ }
536
+ /**
537
+ * Base options for upserting text content into the AI agent's context.
538
+ * @category AI
539
+ */
540
+ export interface AiKnowledgeBaseContextTextOptions extends BaseAiKnowledgeBaseContextOptions {
541
+ }
542
+ /**
543
+ * Base options for upserting file content into the AI agent's context.
544
+ * @category AI
545
+ */
546
+ export interface AiKnowledgeBaseContextFileOptions extends BaseAiKnowledgeBaseContextOptions {
547
+ }
548
+ /**
549
+ * Hint about the format of a text context payload.
550
+ *
551
+ * - `auto`: detect the format from the content (default).
552
+ * - `markdown`: treat the text as Markdown — image references will be extracted if `extractImages` is true.
553
+ * - `html`: treat the text as HTML — `<img>` tags will be extracted if `extractImages` is true.
554
+ * - `plain`: treat the text as plain text — no image extraction is performed even if `extractImages` is true.
555
+ *
556
+ * @category AI
557
+ */
558
+ export type AiKnowledgeBaseTextFormat = 'auto' | 'markdown' | 'html' | 'plain';
559
+ /**
560
+ * Request structure for adding text-based context to an AI agent.
561
+ * @category AI
562
+ */
563
+ export interface AiKnowledgeBaseTextContextRequest extends BaseAiKnowledgeBaseContextRequest {
564
+ /**
565
+ * The id of the context. Optional: when omitted, the server generates one and rejects the upload if
566
+ * another context in the knowledge base already holds identical content (content-level dedup). Provide
567
+ * an explicit id to address a specific context — that overwrites it unconditionally and allows duplicate
568
+ * content across different ids.
569
+ */
570
+ contextId?: AiContextId;
571
+ /** Specifies the context type as 'text'. */
572
+ type: 'text';
573
+ /** A title for the text context. */
574
+ title: string;
575
+ /** The text content to add to the context. */
576
+ text: string;
577
+ /**
578
+ * Hint about the format of the text. If omitted (or `'auto'`), the format is sniffed from the content.
579
+ * Only `'markdown'` and `'html'` (or `'auto'` with content that looks like markdown/HTML) participate in
580
+ * image extraction when `extractImages` is true.
581
+ */
582
+ format?: AiKnowledgeBaseTextFormat;
583
+ /**
584
+ * Whether to extract images embedded in markdown/HTML text. Defaults to FALSE — deliberately the
585
+ * opposite of {@link AiKnowledgeBaseFileContextRequest.extractImages}. A pasted blob's inline images
586
+ * are usually layout chrome, whereas an uploaded document's images are part of its content. Uploading
587
+ * the same markdown as a `.md` file is therefore the file case, and defaults to images ON.
588
+ *
589
+ * When true and the text is detected as (or declared to be) markdown/HTML, image references inside the
590
+ * text (`![alt](url)` or `<img src="...">`) are fetched, stored, and have descriptions generated
591
+ * just like images extracted from a PDF.
592
+ *
593
+ * Has no effect for plain text.
594
+ */
595
+ extractImages?: boolean;
596
+ /** Minimum width/height (in pixels) for an image to be kept. Smaller images are skipped. */
597
+ imageMinSizePixels?: number;
598
+ /** The AI model to use for generating image descriptions, if specified. */
599
+ imageExtractionModel?: AiChatModelSelection;
600
+ /** General options for how to process the text. */
601
+ options?: AiKnowledgeBaseContextTextOptions;
602
+ }
603
+ /**
604
+ * Request structure for adding file-based context to an AI agent.
605
+ * @category AI
606
+ */
607
+ export interface AiKnowledgeBaseFileContextRequest extends BaseAiKnowledgeBaseContextRequest {
608
+ /**
609
+ * The id of the context. Optional: when omitted, the server generates one and rejects the upload if
610
+ * another context in the knowledge base already holds identical content (content-level dedup). Provide
611
+ * an explicit id to address a specific context — that overwrites it unconditionally and allows duplicate
612
+ * content across different ids.
613
+ */
614
+ contextId?: AiContextId;
615
+ /** Specifies the context type as 'file'. */
616
+ type: 'file';
617
+ /**
618
+ * Whether to extract images from the file, describe them with a vision model, and index those
619
+ * descriptions alongside the text. Defaults to TRUE — a document's charts, diagrams and scanned pages
620
+ * carry content the text layer does not, so a file context captures them unless asked not to.
621
+ *
622
+ * Note this is the opposite of {@link AiKnowledgeBaseTextContextRequest.extractImages}, which defaults
623
+ * to false: images referenced from a pasted markdown/HTML blob are usually layout chrome, and fetching
624
+ * them means following URLs the caller supplied.
625
+ */
626
+ extractImages?: boolean;
627
+ /** The minimum size for extracted images, if applicable. */
628
+ imageMinSizePixels?: number;
629
+ /** The AI model to use for extraction, if specified. */
630
+ imageExtractionModel?: AiChatModelSelection;
631
+ /** General options for how to process the file. */
632
+ options?: AiKnowledgeBaseContextFileOptions;
633
+ /** The preferred method for extracting data from the document. */
634
+ preferredExtractionMethod?: DocumentExtractionMethod;
635
+ /**
636
+ * Whether Squid keeps or discards the original file.
637
+ *
638
+ * Keeping the original file allows reprocessing and the ability for the user to download it later.
639
+ *
640
+ * Defaults to false.
641
+ */
642
+ discardOriginalFile?: boolean;
643
+ }
644
+ /**
645
+ * Largest single file the bulk multipart staging endpoint accepts (`bulkUpsertContexts` with `files`).
646
+ *
647
+ * Public and shared deliberately: the upload parser rejects an oversized part with a 413 that carries no
648
+ * fallback token, so a client that does not know this bound has no way to route around it — every retry
649
+ * fails identically. Callers with larger files should use `createBulkUploadUrls` + `stagedObjectKey`, which
650
+ * uploads straight to storage and is not subject to it.
651
+ * @category AI
652
+ */
653
+ export declare const BULK_INGESTION_MAX_MULTIPART_FILE_BYTES: number;
654
+ /**
655
+ * Largest single file the platform's upload endpoints accept, per file: the multer limit core applies
656
+ * to every file-upload route (`COMMON_FILE_UPLOAD_OPTIONS`). By definition it also caps a bulk-ingestion
657
+ * source object, whichever way its bytes arrive: core re-enforces it on every staged object — rejecting
658
+ * the whole staging batch with the oversized object — so a staging caller pre-parks larger files.
659
+ * @category AI
660
+ */
661
+ export declare const MAX_UPLOAD_FILE_BYTES: number;
662
+ /**
663
+ * @category AI
664
+ */
665
+ export declare const RAG_TYPES: readonly ["contextual", "basic"];
666
+ /**
667
+ * @category AI
668
+ */
669
+ export type AiRagType = (typeof RAG_TYPES)[number];
670
+ /**
671
+ * Base options for how to deal with the content being upserted.
672
+ * @category AI
673
+ */
674
+ export type BaseAiKnowledgeBaseContextOptions = {
675
+ /** The type of RAG to use for the content. */
676
+ ragType?: AiRagType;
677
+ /** Amount of chunk overlap, in characters. */
678
+ chunkOverlap?: number;
679
+ };
680
+ /**
681
+ * Specific options for the AI knowledgebase search method.
682
+ * @category AI
683
+ */
684
+ export interface AiKnowledgeBaseSearchOptions {
685
+ /** The prompt to search for */
686
+ prompt: string;
687
+ /** The maximum number of results to return */
688
+ limit?: number;
689
+ /** Which provider's reranker to use for reranking the context. Defaults to 'cohere'. */
690
+ rerankProvider?: AiRerankProvider;
691
+ /**
692
+ * Minimum reranker relevance score a chunk must reach to stay once at least 10 chunks are already kept.
693
+ * Defaults to 0.2. Lets an eval tune the drop threshold per reranker, whose score ranges differ.
694
+ */
695
+ rerankScoreThreshold?: number;
696
+ /** How many chunks to look over. Defaults to 100 */
697
+ chunkLimit?: number;
698
+ /** Which chat model to use when asking the question */
699
+ chatModel?: AiChatModelSelection;
700
+ /**
701
+ * Selects how the underlying vector store generates candidates:
702
+ * - `'hybrid'` (default): fuses dense vector and keyword candidates when the backend supports it
703
+ * (Mongo Atlas uses `$rankFusion`; backends without native fusion fall back to dense-only with
704
+ * the legacy app-side keyword fallback).
705
+ * - `'vector'`: dense-only — skips native fusion even on backends that support it.
706
+ * - `'keyword'`: embedding-free lexical retrieval; the mechanism is backend-specific. On Mongo Atlas it
707
+ * is native Lucene BM25 (`$search`): results are ranked by relevance and term-optional — a partial-term
708
+ * query still returns its best matches. On Postgres it is a boolean substring filter (`ILIKE ALL`):
709
+ * every whitespace-separated term must appear in a chunk as a literal, case-insensitive substring,
710
+ * matched independently (order, adjacency and relevance are NOT considered), so results are unranked and
711
+ * for broad terms the returned top-k is arbitrary. Both skip embedding, dense, reranking and the
712
+ * app-side keyword fallback. Lets an agent (or an eval) target exact tokens — identifiers, names, codes
713
+ * — that dense retrieval tends to miss.
714
+ *
715
+ * Intended to let A/B evaluations compare dense-only, hybrid and boolean-keyword candidate generation
716
+ * on the same backend.
717
+ *
718
+ * When omitted, the default is `'graph'` (RRF-fused GraphRAG) on a `graphRag.enabled` KB and
719
+ * `'hybrid'` otherwise. See {@link AiKnowledgeBaseSearchMode}.
720
+ */
721
+ searchMode?: AiKnowledgeBaseSearchMode;
722
+ /**
723
+ * Per-pipeline weights for native hybrid fusion (Mongo `$rankFusion.combination.weights`). Only
724
+ * applies when `searchMode` is `'hybrid'` on a backend with native fusion; ignored otherwise.
725
+ * Each value must be a finite non-negative number; an omitted key defaults to `1` (the MongoDB
726
+ * default). Useful for A/B evaluating dense-vs-keyword weighting on the same backend.
727
+ */
728
+ hybridWeights?: AiHybridSearchWeights;
729
+ /** Tuning for `searchMode:'graph'` (GraphRAG). Ignored for other search modes. */
730
+ graphOptions?: AiKnowledgeBaseGraphSearchOptions;
731
+ /**
732
+ * Scopes the search to the documents under one concept of the KB's graph (Layered KB Graph).
733
+ * Composes with every `searchMode` and with `contextMetadataFilter`. Requires `graphRag.enabled`.
734
+ */
735
+ graphFilter?: AiKnowledgeBaseGraphFilter;
736
+ }
737
+ /**
738
+ * A single chunk of data returned from an AI search operation.
739
+ * @category AI
740
+ */
741
+ export interface AiKnowledgeBaseSearchResultChunk {
742
+ /** The unique identifier of the context. */
743
+ contextId: string;
744
+ /** The data content of the search result chunk. */
745
+ data: string;
746
+ /** Optional metadata associated with the chunk. */
747
+ metadata?: AiContextMetadata;
748
+ /** The relevance score of the chunk, indicating match quality. */
749
+ score: number;
750
+ }
751
+ /**
752
+ * Response structure for upserting context for an AiKnowledgeBase
753
+ * @category AI
754
+ */
755
+ export interface UpsertKnowledgeBaseContextResponse {
756
+ /** List of the upsert status of each item sent in the request. */
757
+ failure?: UpsertContextStatusError;
758
+ /**
759
+ * Set when the context was stored (and is fully searchable via vector/keyword) but NOT graph-indexed
760
+ * because the knowledge base is over its per-KB graph chunk cap. Only GraphRAG coverage is absent; the
761
+ * singular counterpart of {@link UpsertKnowledgeBaseContextsResponse.graphIndexingSkippedContextIds}.
762
+ */
763
+ graphIndexingSkipped?: boolean;
764
+ /**
765
+ * First images (capped) the context lacks a description for because describing them failed; the context
766
+ * is otherwise fully ingested. Absent when every image succeeded. `imageFailureCount` is the total.
767
+ */
768
+ imageFailures?: Array<ContextImageFailure>;
769
+ /** Total number of failed images, which exceeds `imageFailures.length` when the list was capped. */
770
+ imageFailureCount?: number;
771
+ }
772
+ /**
773
+ * The failed images of one context in a multi-context upsert.
774
+ * @category AI
775
+ */
776
+ export interface UpsertContextImageFailures {
777
+ /** The context the images belong to. */
778
+ contextId: AiContextId;
779
+ /** First failed images (capped); `imageFailureCount` is the total. */
780
+ imageFailures: Array<ContextImageFailure>;
781
+ /** Total number of failed images, which exceeds `imageFailures.length` when the list was capped. */
782
+ imageFailureCount: number;
783
+ }
784
+ /**
785
+ * Response structure for upserting contexts for an AiKnowledgeBase
786
+ * @category AI
787
+ */
788
+ export interface UpsertKnowledgeBaseContextsResponse {
789
+ /** List of the upsert status of each item sent in the request. */
790
+ failures: Array<UpsertContextStatusError>;
791
+ /**
792
+ * The context id of every request in the batch, positionally aligned with the `contextRequests` array
793
+ * that was sent — `contextIds[i]` is the id of the i-th request. Each entry is the caller-supplied id,
794
+ * or the id the server generated when the request omitted one, and is present regardless of whether that
795
+ * request succeeded or failed. Lets a caller that upserts without a contextId learn the assigned id.
796
+ *
797
+ * Optional because a newer client talking to an older core (which predates this field) receives it as
798
+ * `undefined` at runtime — callers must handle its absence rather than trust it is always populated.
799
+ */
800
+ contextIds?: Array<AiContextId>;
801
+ /**
802
+ * Contexts that were stored (and are fully searchable via vector/keyword) but NOT graph-indexed because
803
+ * the knowledge base is over its per-KB graph chunk cap. Only GraphRAG coverage is absent; surfaced so a
804
+ * caller can report the graph-coverage gap. Absent/empty when nothing was skipped or graph is disabled.
805
+ */
806
+ graphIndexingSkippedContextIds?: Array<AiContextId>;
807
+ /**
808
+ * Per stored context, the images that lack a description because describing them failed; each such
809
+ * context is otherwise fully ingested. A context that failed outright lists its images on its entry in
810
+ * `failures` instead. Absent when every image succeeded.
811
+ */
812
+ imageFailures?: Array<UpsertContextImageFailures>;
813
+ }
814
+ /**
815
+ * Request structure for searching an AiKnowledgeBase
816
+ * @category AI
817
+ */
818
+ export interface AiKnowledgeBaseSearchRequest {
819
+ /** The id of the AiKnowledgeBase */
820
+ knowledgeBaseId: string;
821
+ /** The user prompt to search on */
822
+ prompt: string;
823
+ /** The search options for this search */
824
+ options: AiKnowledgeBaseSearchOptions;
825
+ }
826
+ /** Default number of grep matches returned when the caller does not ask for a specific number. */
827
+ export declare const GREP_KNOWLEDGE_BASE_DEFAULT_MAX_MATCHES = 50;
828
+ /** Hard ceiling on grep matches: a larger `maxMatches` is clamped down to this value. */
829
+ export declare const GREP_KNOWLEDGE_BASE_MAX_MATCHES = 200;
830
+ /**
831
+ * Longest accepted grep pattern. A literal needle is short by nature; the cap exists so an
832
+ * adversarially long pattern cannot be used to inflate matching cost on a shared server.
833
+ */
834
+ export declare const GREP_KNOWLEDGE_BASE_MAX_PATTERN_CHARS = 500;
835
+ /** Longest `line` / `context` a single match returns; anything longer is clipped with an ellipsis. */
836
+ export declare const GREP_KNOWLEDGE_BASE_MAX_MATCH_LINE_CHARS = 500;
837
+ /**
838
+ * Options for a literal scan over a knowledge base's raw extracted text.
839
+ * @category AI
840
+ */
841
+ export interface GrepKnowledgeBaseOptions {
842
+ /**
843
+ * Scopes the scan to the contexts whose metadata matches this filter — the same grammar knowledge-base
844
+ * chunk search accepts, including `$and`/`$or` composition and the `$underPath` folder operator. The
845
+ * filter selects the contexts BEFORE any text is matched.
846
+ */
847
+ metadataFilter?: AiContextMetadataFilter;
848
+ /**
849
+ * The maximum number of matches to return. Defaults to {@link GREP_KNOWLEDGE_BASE_DEFAULT_MAX_MATCHES}
850
+ * and is clamped to {@link GREP_KNOWLEDGE_BASE_MAX_MATCHES}.
851
+ */
852
+ maxMatches?: number;
853
+ }
854
+ /**
855
+ * Request structure for a literal scan over a knowledge base's raw extracted text.
856
+ * @category AI
857
+ */
858
+ export interface GrepKnowledgeBaseRequest {
859
+ /** The id of the AiKnowledgeBase */
860
+ knowledgeBaseId: AiKnowledgeBaseId;
861
+ /**
862
+ * The literal substring to look for. Every regex metacharacter in it is escaped, so punctuation and
863
+ * symbols mean themselves, and it may span lines. Capped at
864
+ * {@link GREP_KNOWLEDGE_BASE_MAX_PATTERN_CHARS} characters.
865
+ *
866
+ * Matching is case-insensitive for ASCII letters only: `acme` finds `ACME`, but `café` does not find
867
+ * `CAFÉ`. The store and the server run two different regex engines, and their `i` flags disagree on
868
+ * non-ASCII folding — matching ASCII-only is what keeps them in step, so a hit is never reported as an
869
+ * absence. Search the exact casing for non-ASCII text.
870
+ */
871
+ pattern: string;
872
+ /** Scan options. */
873
+ options?: GrepKnowledgeBaseOptions;
874
+ }
875
+ /**
876
+ * One matching line found by {@link GrepKnowledgeBaseRequest}.
877
+ * @category AI
878
+ */
879
+ export interface AiKnowledgeBaseGrepMatch {
880
+ /** The id of the context the match was found in. */
881
+ contextId: AiContextId;
882
+ /** The source file name (or context title for text contexts). */
883
+ fileName: string;
884
+ /** The locator within the file: a sheet/section title when the extractor supplied one, else `page N`. */
885
+ part: string;
886
+ /** The 1-based line number the match starts on within its part. */
887
+ lineNumber: number;
888
+ /** The matching line, clipped to {@link GREP_KNOWLEDGE_BASE_MAX_MATCH_LINE_CHARS} with an ellipsis. */
889
+ line: string;
890
+ /**
891
+ * The matching line plus a small window of the lines around it, joined by newlines and clipped to
892
+ * {@link GREP_KNOWLEDGE_BASE_MAX_MATCH_LINE_CHARS}. Wide spreadsheet rows are the normal case here, so
893
+ * the clip is what keeps a full result set from overflowing an agent's context window.
894
+ */
895
+ context: string;
896
+ }
897
+ /**
898
+ * Why a grep result does not cover everything the caller asked for. Absent means the scan was complete
899
+ * over the requested scope, and only then may an empty `matches` be read as the pattern being absent.
900
+ * At most one applies; the server picks the most significant.
901
+ *
902
+ * - `timedOut` — the scan hit its server-side deadline. Routine on large knowledge bases, since the
903
+ * match is unindexed. Says nothing at all about whether the pattern occurs.
904
+ * - `noIndexedText` — nothing in scope has stored text, so nothing was searched. Contexts ingested
905
+ * before literal search existed sit here until they are re-ingested.
906
+ * - `filterMatchedNoContexts` — `metadataFilter`, composed with any visibility filter the application
907
+ * applies, admitted no contexts, so the scan had nothing to read.
908
+ * - `scopeTruncated` — `metadataFilter` admitted more contexts than one scan can cover, so only a prefix
909
+ * of them was searched. Narrow the filter.
910
+ * - `partsCapReached` — the scan filled its per-call budget of matching pages/sheets, so more matching
911
+ * places exist than it read.
912
+ * - `partialCoverage` — some contexts in scope have stored text and some do not; see
913
+ * {@link GrepKnowledgeBaseResponse.unscannedContextCount}.
914
+ * - `truncatedContent` — some in-scope text was cut at ingest, either because one page or sheet exceeded
915
+ * the per-part storage cap or because a document had more pages than the per-document cap, so that
916
+ * content was never searchable.
917
+ * - `coverageUnknown` — the scan itself succeeded, but how much of the scope holds stored text could not
918
+ * be determined, so completeness cannot be asserted either way.
919
+ * @category AI
920
+ */
921
+ export type GrepScanLimitation = 'timedOut' | 'noIndexedText' | 'filterMatchedNoContexts' | 'scopeTruncated' | 'partsCapReached' | 'partialCoverage' | 'truncatedContent' | 'coverageUnknown';
922
+ /**
923
+ * Response structure for a literal scan over a knowledge base's raw extracted text.
924
+ * @category AI
925
+ */
926
+ export interface GrepKnowledgeBaseResponse {
927
+ /** The matches found, in context/part/line order. */
928
+ matches: Array<AiKnowledgeBaseGrepMatch>;
929
+ /**
930
+ * True when the returned list stopped at `maxMatches` — more matches exist than were returned. This
931
+ * means ONLY that: every other way a scan can fall short of the request lives in {@link limitation},
932
+ * so a caller branching on this one field never mistakes an incomplete scan for "there are more hits".
933
+ */
934
+ truncated: boolean;
935
+ /**
936
+ * Why the scan did not cover the full requested scope, if it did not. Absent means it did — which is
937
+ * the only case where an empty `matches` is evidence that the pattern does not occur. The whole point
938
+ * of this API is to make absence claims trustworthy, so callers must branch on this before concluding
939
+ * anything from an empty result.
940
+ */
941
+ limitation?: GrepScanLimitation;
942
+ /**
943
+ * With `limitation: 'partialCoverage'`, how many contexts in scope have no stored text and were
944
+ * therefore never scanned. The result is silent about those contexts.
945
+ */
946
+ unscannedContextCount?: number;
947
+ /**
948
+ * With `limitation: 'truncatedContent'`, the file names of documents known to have lost content at
949
+ * ingest. A bounded sample, not a complete list — present it as an example, and do not infer that
950
+ * documents missing from it are intact.
951
+ */
952
+ truncatedContentFileNames?: Array<string>;
953
+ }
954
+ /**
955
+ * Request structure for searching AI contexts in the AiKnowledgeBase.
956
+ * @category AI
957
+ */
958
+ export interface BaseAiKnowledgeBaseSearchContextsRequest {
959
+ /** The id of the AiKnowledgeBase */
960
+ knowledgeBaseId: AiKnowledgeBaseId;
961
+ /** The maximum number of results to return */
962
+ limit?: number;
963
+ /** A set of filters that will limit the context the AI can access. */
964
+ contextMetadataFilter?: AiContextMetadataFilter;
965
+ /** Whether to rerank the results with AI and provide reasoning - defaults to true */
966
+ rerank?: boolean;
967
+ /** Which chat model to use when doing reranking */
968
+ chatModel?: AiChatModelSelection;
969
+ /**
970
+ * Reasoning effort of the reranking model. A score needs little thought, so `'low'` is the usual
971
+ * choice; when unset the model applies its own default.
972
+ */
973
+ rerankReasoningEffort?: AiReasoningEffort;
974
+ }
975
+ /**
976
+ * Request structure for searching AI contexts in the AiKnowledgeBase with prompt.
977
+ * @category AI
978
+ */
979
+ export interface AiKnowledgeBaseSearchContextsWithPromptRequest extends BaseAiKnowledgeBaseSearchContextsRequest {
980
+ /** The user prompt to search on */
981
+ prompt: string;
982
+ }
983
+ /**
984
+ * Request structure for searching AI contexts in the AiKnowledgeBase with an existing context.
985
+ * @category AI
986
+ */
987
+ export interface AiKnowledgeBaseSearchContextsWithContextIdRequest extends BaseAiKnowledgeBaseSearchContextsRequest {
988
+ /** The contextId to search with */
989
+ contextId: string;
990
+ }
991
+ /**
992
+ * A context with reasoning and matching score.
993
+ * @category AI
994
+ */
995
+ export interface AiKnowledgeBaseContextWithReasoning {
996
+ /** The actual context */
997
+ context: AiKnowledgeBaseContext;
998
+ /** The reasoning behind why this context was matched - can be undefined if no reasoning was requested */
999
+ reasoning?: string;
1000
+ /** The score of the match, ranging from 0 to 100, where 100 is the best match. */
1001
+ score: number;
1002
+ }
1003
+ /**
1004
+ * Response structure for searching contexts in an AiKnowledgeBase.
1005
+ * @category AI
1006
+ */
1007
+ export interface AiKnowledgeBaseSearchContextsResponse {
1008
+ /** The resulting contexts, with reasoning if it was requested */
1009
+ results: Array<AiKnowledgeBaseContextWithReasoning>;
1010
+ }
1011
+ /**
1012
+ * Request structure for requesting a download link to the context file that you previously provided.
1013
+ * @category AI
1014
+ */
1015
+ export interface AiKnowledgeBaseDownloadContextRequest {
1016
+ /** The id of the AiKnowledgeBase */
1017
+ knowledgeBaseId: string;
1018
+ /** The id of the particular AiKnowledgeBaseContext */
1019
+ contextId: string;
1020
+ }
1021
+ /**
1022
+ * Response structure with the URL to download the specified context.
1023
+ *
1024
+ * Can be undefined if the file is not available in Squid.
1025
+ * @category AI
1026
+ */
1027
+ export interface AiKnowledgeBaseDownloadContextResponse {
1028
+ /** The URL to download the file, if available. */
1029
+ url?: string;
1030
+ }
1031
+ /**
1032
+ * KnowledgeBase with optional fields, used during upsert
1033
+ * @category AI
1034
+ */
1035
+ export type AiEmbeddingsModelWithOptionalFields = Omit<AiKnowledgeBase, 'chatModel' | 'embeddingModel'> & {
1036
+ chatModel?: AiKnowledgeBase['chatModel'];
1037
+ name?: string;
1038
+ embeddingModel?: AiEmbeddingsModelSelection;
1039
+ };
1040
+ /**
1041
+ * API request for deleting an AiKnowledgeBase
1042
+ * @category AI
1043
+ */
1044
+ export interface DeleteAiKnowledgeBaseRequest {
1045
+ /** The id of the AiKnowledgeBase */
1046
+ id: string;
1047
+ }
1048
+ /**
1049
+ * API request for upserting an AiKnowledgeBase
1050
+ * @category AI
1051
+ */
1052
+ export interface UpsertAiKnowledgeBaseRequest {
1053
+ /** The AiKnowledgeBase to upsert */
1054
+ knowledgeBase: Omit<AiEmbeddingsModelWithOptionalFields, 'appId' | 'updatedAt'>;
1055
+ }
1056
+ /**
1057
+ * API request for deleting AiKnowledgeBaseContexts
1058
+ * @category AI
1059
+ */
1060
+ export interface DeleteAiKnowledgeBaseContextsRequest {
1061
+ /** The id of the AiKnowledgeBase */
1062
+ knowledgeBaseId: string;
1063
+ /** An array of AiKnowledgeBaseContext ids */
1064
+ contextIds: Array<string>;
1065
+ }
1066
+ /**
1067
+ * API response to list AiKnowledgeBaseContexts
1068
+ * @category AI
1069
+ */
1070
+ export interface ListAiKnowledgeBaseContextsResponse {
1071
+ /** The list of AiKnowledgeBaseContexts */
1072
+ contexts: Array<AiKnowledgeBaseContext>;
1073
+ }
1074
+ /**
1075
+ * Options for {@link AiKnowledgeBaseReference.listContextsPage}
1076
+ * @category AI
1077
+ */
1078
+ export interface ListKnowledgeBaseContextsOptions {
1079
+ /** The number of characters after which text is truncated. Optional */
1080
+ truncateTextAfter?: number;
1081
+ /** The number of contexts to skip, for pagination. Optional */
1082
+ offset?: number;
1083
+ /** The maximum number of contexts to return, for pagination. Optional */
1084
+ limit?: number;
1085
+ /** Case-insensitive substring search across id/title only. Optional */
1086
+ search?: string;
1087
+ }
1088
+ /**
1089
+ * API request for listing a page of AiKnowledgeBaseContexts
1090
+ * @category AI
1091
+ */
1092
+ export interface ListAiKnowledgeBaseContextsPageRequest {
1093
+ /** The id of the AiKnowledgeBase */
1094
+ id: string;
1095
+ /** The number of characters after which text is truncated. Optional */
1096
+ truncateTextAfter?: number;
1097
+ /** The number of contexts to skip, for pagination. Optional */
1098
+ offset?: number;
1099
+ /** The maximum number of contexts to return, for pagination. Optional */
1100
+ limit?: number;
1101
+ /** Case-insensitive substring search across id/title only. Optional */
1102
+ search?: string;
1103
+ }
1104
+ /**
1105
+ * API response to list a page of AiKnowledgeBaseContexts
1106
+ * @category AI
1107
+ */
1108
+ export interface ListAiKnowledgeBaseContextsPageResponse {
1109
+ /** The list of AiKnowledgeBaseContexts */
1110
+ contexts: Array<AiKnowledgeBaseContext>;
1111
+ /** The total number of contexts in the AiKnowledgeBase, ignoring offset/limit */
1112
+ totalCount: number;
1113
+ }
1114
+ /**
1115
+ * API response for searching an AiKnowledgeBase
1116
+ * @category AI
1117
+ */
1118
+ export interface AiKnowledgeBaseSearchResponse {
1119
+ /** Array of result chunks from the search */
1120
+ chunks: Array<AiKnowledgeBaseSearchResultChunk>;
1121
+ /**
1122
+ * The subgraph traversed for a `searchMode:'graph'` query. Present only when
1123
+ * `graphOptions.includeGraphContext` was set; absent for all other searches.
1124
+ */
1125
+ graphContext?: AiKnowledgeBaseGraphContext;
1126
+ }
1127
+ /**
1128
+ * Response containing the list of AI knowledge bases in an application.
1129
+ * @category AI
1130
+ */
1131
+ export interface ListAiKnowledgeBasesResponse {
1132
+ /** All AI knowledge bases defined for the application. */
1133
+ knowledgeBases: Array<AiKnowledgeBase>;
1134
+ }
1135
+ /** Request to AI-generate descriptions for a KB's metadata fields and return them (the caller persists). */
1136
+ export interface GenerateMetadataFieldDescriptionsRequest {
1137
+ /** The id of the AiKnowledgeBase. */
1138
+ knowledgeBaseId: AiKnowledgeBaseId;
1139
+ /** Limit generation to these fields; omitted ⇒ all declared fields. */
1140
+ fieldNames?: string[];
1141
+ /** When true, regenerate fields that already have a description; default false (fill empties only). */
1142
+ overwriteExisting?: boolean;
1143
+ }
1144
+ /** Response for the AI-generated metadata field descriptions. */
1145
+ export interface GenerateMetadataFieldDescriptionsResponse {
1146
+ /** The (re)generated fields with their new descriptions; not persisted — the caller saves them. */
1147
+ fields: Array<GeneratedMetadataFieldDescription>;
1148
+ }
1149
+ /** A generated description for a single metadata field. */
1150
+ export interface GeneratedMetadataFieldDescription {
1151
+ /** The name of the metadata field. */
1152
+ name: string;
1153
+ /** The AI-generated description for the field. */
1154
+ description: string;
1155
+ }
1156
+ /**
1157
+ * Request structure for reading a knowledge base's GraphRAG build/readiness status.
1158
+ * @category AI
1159
+ */
1160
+ export interface GetKnowledgeBaseGraphStatusRequest {
1161
+ /** The id of the AiKnowledgeBase. */
1162
+ knowledgeBaseId: AiKnowledgeBaseId;
1163
+ }
1164
+ /**
1165
+ * Response structure for a knowledge base's GraphRAG build/readiness status. Drives the ai-eval
1166
+ * readiness poll (index until `contextsIndexed === contextsTotal` and `buildJob` is not in-progress).
1167
+ * @category AI
1168
+ */
1169
+ export interface GetKnowledgeBaseGraphStatusResponse {
1170
+ /** Whether GraphRAG is enabled on the KB. */
1171
+ enabled: boolean;
1172
+ /** Number of live entities in the KB's graph partition (quarantined ones excluded). */
1173
+ entityCount: number;
1174
+ /** Entities hidden by a dead-weight quarantine run; absent when the KB's graph store cannot quarantine. */
1175
+ quarantinedEntityCount?: number;
1176
+ /** Number of outgoing relationships (mirrors excluded). */
1177
+ relationshipCount: number;
1178
+ /** Number of communities detected (Phase 3), 0 when none. */
1179
+ communityCount: number;
1180
+ /** Contexts stamped as graph-indexed. */
1181
+ contextsIndexed: number;
1182
+ /** Total contexts in the KB. */
1183
+ contextsTotal: number;
1184
+ /** Document nodes in the KB's graph (Layered KB Graph L1) — one per graph-indexed context. */
1185
+ docNodesTotal?: number;
1186
+ /** Document nodes carrying a non-empty LLM description (failed descriptions retry on rebuild). */
1187
+ docsDescribed?: number;
1188
+ /** The KB's facet trees (Layered KB Graph L3, deterministic) — empty until a rebuild builds them. */
1189
+ facets?: Array<KnowledgeBaseGraphFacetStatus>;
1190
+ /**
1191
+ * The KB's topic (theme) hierarchy — present once a graph build has clustered topics. Ids churn on
1192
+ * rebuild ({@link KnowledgeBaseGraphTopic.id}); resolve them per session, never persist them.
1193
+ */
1194
+ topics?: Array<KnowledgeBaseGraphTopic>;
1195
+ /**
1196
+ * Leaf-level inter-topic edges (relationship counts crossing topic boundaries), present once a graph
1197
+ * build has computed them. Roll up to coarser tiers by mapping each endpoint to its ancestor.
1198
+ */
1199
+ topicEdges?: Array<KnowledgeBaseGraphTopicEdge>;
1200
+ /**
1201
+ * True when documents were graph-indexed after the last topic build — themes may lag content until
1202
+ * the next `rebuildGraph`. Only meaningful once topics exist (absent before the first rebuild).
1203
+ */
1204
+ structureStale?: boolean;
1205
+ /** Documents added since the last topic build (the `structureStale` numerator). */
1206
+ staleDocCount?: number;
1207
+ /** Status of the most recent backfill/rebuild job, when one exists. */
1208
+ buildJob?: KnowledgeBaseGraphBuildJob;
1209
+ /** Lifetime LLM usage of incremental graph ingestion (per-upsert extraction), when any was recorded. */
1210
+ ingestUsage?: KnowledgeBaseGraphUsage;
1211
+ /**
1212
+ * LLM usage of the most recent COMPLETED `rebuildGraph` run (including its re-extraction), when one
1213
+ * ran. A build in flight leaves it on the previous build until it completes — read
1214
+ * {@link buildUsageHistory} for the in-flight run.
1215
+ */
1216
+ lastRebuildUsage?: KnowledgeBaseGraphUsage;
1217
+ /**
1218
+ * Per-build LLM usage of the KB's most recent `rebuildGraph` runs, newest first, bounded to the last
1219
+ * 50 builds. Unlike {@link lastRebuildUsage} no build erases another's record, so back-to-back builds
1220
+ * are all accounted for.
1221
+ */
1222
+ buildUsageHistory?: Array<KnowledgeBaseGraphBuildUsage>;
1223
+ /**
1224
+ * Lifetime LLM usage of the combined contextual-blurb + graph-extraction call (run automatically for
1225
+ * `ragType:'contextual'` graph-enabled KBs), when any was recorded. Covers BOTH the contextual blurb
1226
+ * and graph extraction in one call, so it is not directly comparable to the graph-only
1227
+ * {@link ingestUsage}.
1228
+ */
1229
+ combinedIngestUsage?: KnowledgeBaseGraphUsage;
1230
+ /** When a structural/full rebuild last completed successfully (epoch millis), when one ever has. */
1231
+ lastStructureBuildAt?: number;
1232
+ /**
1233
+ * When the debounced auto-build sweep will pick the KB up (epoch millis), present while an auto-build
1234
+ * is pending. Recomputed per poll — it moves forward while ingest activity continues.
1235
+ */
1236
+ nextAutoBuildAt?: number;
1237
+ /**
1238
+ * True when graph-scoped search (`graphFilter.underConcept`) runs on the index-native denormalized
1239
+ * `conceptIds` pre-filter: the backend's search indexes serve the field AND the chunk copies are in
1240
+ * sync with the doc nodes. False while either half is not ready (index still building, or a rebuild
1241
+ * is in flight — a rebuild drops the sync gate for its duration); scoped search then uses the
1242
+ * capped contextId-closure fallback. Absent when GraphRAG is disabled.
1243
+ */
1244
+ conceptScopeReady?: boolean;
1245
+ /** The incremental entity-resolution sweep's latest readings, present once a sweep has sampled the KB. */
1246
+ resolution?: KnowledgeBaseGraphResolutionStatus;
1247
+ }
1248
+ /**
1249
+ * Readings the incremental entity-resolution sweep persists on a knowledge base: the dirty backlog it
1250
+ * drains across sweeps and the duplicate-name fragmentation it exists to merge.
1251
+ * @category AI
1252
+ */
1253
+ export interface KnowledgeBaseGraphResolutionStatus {
1254
+ /** Entities rewritten since the sweep last examined them. */
1255
+ backlog: number;
1256
+ /** When `backlog` was sampled (epoch millis) — the start or end of a sweep. */
1257
+ backlogSampledAt: number;
1258
+ /** Entities sharing another entity's significant-name-token signature; absent until a sweep sampled it. */
1259
+ duplicateNames?: number;
1260
+ /** When `duplicateNames` was sampled (epoch millis). */
1261
+ duplicateNamesSampledAt?: number;
1262
+ /** The most recent sweep: the bounds it ran under and what it got through; absent until one has run. */
1263
+ lastSweep?: KnowledgeBaseGraphResolutionSweep;
1264
+ }
1265
+ /**
1266
+ * One incremental entity-resolution sweep's bounds and counters, as persisted at its start (counters
1267
+ * zero) and again at its end.
1268
+ * @category AI
1269
+ */
1270
+ export interface KnowledgeBaseGraphResolutionSweep {
1271
+ /** Dirty entities one pass of the sweep examined at most. */
1272
+ dirtyBatch: number;
1273
+ /** Drain rounds the sweep ran at most. */
1274
+ maxRounds: number;
1275
+ /** Candidate pairs one drain round of the sweep adjudicated at most. */
1276
+ maxPairsPerRound: number;
1277
+ /** Resolution passes one drain round of the sweep ran at most. */
1278
+ maxPasses: number;
1279
+ /** Adjudication calls the sweep kept in flight. */
1280
+ adjudicationConcurrency: number;
1281
+ /** Dirty entities one pass of the sweep searched candidates for at once. */
1282
+ proposalConcurrency: number;
1283
+ /** Drain rounds the sweep ran. */
1284
+ rounds: number;
1285
+ /** Dirty entities the sweep examined. */
1286
+ examined: number;
1287
+ /** Candidate pairs the sweep sent to adjudication. */
1288
+ pairsAdjudicated: number;
1289
+ /** Candidate pairs adjudication confirmed as the same entity. */
1290
+ pairsConfirmed: number;
1291
+ /** Adjudication calls the sweep made; absent on a reading from a sweep that did not record calls. */
1292
+ adjudicationCalls?: number;
1293
+ /** Of those, calls the provider served the instruction prefix from its prompt cache; absent with them. */
1294
+ adjudicationCachedCalls?: number;
1295
+ /**
1296
+ * Index-visibility wait tokens the sweep spent: a count of waits, not a duration. Absent on a reading
1297
+ * from a sweep that did not record waits.
1298
+ */
1299
+ visibilityWaits?: number;
1300
+ /** When this reading was written (epoch millis). */
1301
+ sampledAt: number;
1302
+ }
1303
+ /** The most recent graph backfill/rebuild job of a knowledge base. @category AI */
1304
+ export interface KnowledgeBaseGraphBuildJob {
1305
+ /** The job's lifecycle state. */
1306
+ status: 'in_progress' | 'completed' | 'failed';
1307
+ /** Failure message, present when `status` is `'failed'`. */
1308
+ error?: string;
1309
+ /** When the job was enqueued (epoch millis). */
1310
+ startedAt?: number;
1311
+ }
1312
+ /**
1313
+ * LLM usage of one graph build (`rebuildGraph` run), kept per build so a later build cannot erase it.
1314
+ * Accumulated across the run's execution attempts — a resumed rebuild adds to the same record.
1315
+ * @category AI
1316
+ */
1317
+ export interface KnowledgeBaseGraphBuildUsage {
1318
+ /** Identity of the build, stable across its execution attempts. */
1319
+ buildId: string;
1320
+ /** The plan the build executed; `'resolution'` is the internal resolution-only continuation. */
1321
+ mode: KnowledgeBaseGraphRebuildMode | 'resolution';
1322
+ /** The build's lifecycle state. */
1323
+ status: 'in_progress' | 'completed' | 'failed';
1324
+ /** When the build started (epoch millis). */
1325
+ startedAt: number;
1326
+ /** When the build reached a terminal state (epoch millis); absent while it runs. */
1327
+ completedAt?: number;
1328
+ /** Contexts whose chunks the build re-extracted; `0` when it re-extracted nothing. */
1329
+ contextsReextracted: number;
1330
+ /** The build's total LLM usage, with its per-model split. */
1331
+ usage: KnowledgeBaseGraphUsage;
1332
+ /** The split of {@link usage} across the stages the build ran. */
1333
+ stages: KnowledgeBaseGraphBuildStageUsage;
1334
+ }
1335
+ /**
1336
+ * A graph build's LLM usage split by pipeline stage. A stage the build entered but spent nothing on
1337
+ * reads zero; a stage it never ran (skipped by its plan, or by a resume) is absent.
1338
+ * @category AI
1339
+ */
1340
+ export interface KnowledgeBaseGraphBuildStageUsage {
1341
+ /** Entity/relationship re-extraction from the KB's chunks. */
1342
+ reextraction?: KnowledgeBaseGraphUsage;
1343
+ /** Entity resolution (duplicate-name adjudication and merges). */
1344
+ resolution?: KnowledgeBaseGraphUsage;
1345
+ /** The lexical mention backstop, which is deterministic and normally spends nothing. */
1346
+ backstop?: KnowledgeBaseGraphUsage;
1347
+ /** Topic clustering and topic summaries. */
1348
+ topics?: KnowledgeBaseGraphUsage;
1349
+ /** Facet tree construction. */
1350
+ facets?: KnowledgeBaseGraphUsage;
1351
+ }
1352
+ /**
1353
+ * Aggregated LLM token usage (and best-effort cost) of graph work on a KB. Token counts are the
1354
+ * provider-reported ground truth; `estCostUsd` is estimated from model list prices at call time —
1355
+ * recompute from the tokens for exact accounting.
1356
+ * @category AI
1357
+ */
1358
+ export interface KnowledgeBaseGraphUsage {
1359
+ /** Number of LLM calls. */
1360
+ llmCalls: number;
1361
+ /** Prompt (input) tokens. */
1362
+ inputTokens: number;
1363
+ /** Completion (output) tokens. */
1364
+ outputTokens: number;
1365
+ /** Reasoning tokens, where the provider reports them separately. */
1366
+ reasoningTokens: number;
1367
+ /** Input tokens served from the provider's prompt cache. */
1368
+ cacheReadTokens: number;
1369
+ /** Input tokens written into the provider's prompt cache. */
1370
+ cacheWriteTokens: number;
1371
+ /** Best-effort USD estimated from list prices at call time. */
1372
+ estCostUsd: number;
1373
+ /**
1374
+ * Per-model split of the totals above (LLM calls only), present when any usage was recorded. The
1375
+ * per-model figures sum to the aggregate; embedding usage is excluded from both.
1376
+ */
1377
+ byModel?: Array<KnowledgeBaseGraphModelUsage>;
1378
+ }
1379
+ /**
1380
+ * One model's slice of a KB's graph LLM usage, keyed by the resolved model name. Token counts are the
1381
+ * provider-reported ground truth; `estCostUsd` is estimated from model list prices at call time.
1382
+ * @category AI
1383
+ */
1384
+ export interface KnowledgeBaseGraphModelUsage {
1385
+ /** The resolved model these totals are attributed to. */
1386
+ model: string;
1387
+ /** Number of LLM calls billed to this model. */
1388
+ llmCalls: number;
1389
+ /** Prompt (input) tokens. */
1390
+ inputTokens: number;
1391
+ /** Completion (output) tokens. */
1392
+ outputTokens: number;
1393
+ /** Reasoning tokens, where the provider reports them separately. */
1394
+ reasoningTokens: number;
1395
+ /** Input tokens served from the provider's prompt cache. */
1396
+ cacheReadTokens: number;
1397
+ /** Input tokens written into the provider's prompt cache. */
1398
+ cacheWriteTokens: number;
1399
+ /** Best-effort USD estimated from list prices at call time. */
1400
+ estCostUsd: number;
1401
+ }
1402
+ /**
1403
+ * One facet tree in a graph status response: the metadata field it is built from and its value leaves
1404
+ * (most-populated first, capped — compare `values.length` against `valueCount` for truncation).
1405
+ * @category AI
1406
+ */
1407
+ export interface KnowledgeBaseGraphFacetStatus {
1408
+ /** The metadata field the facet is built from. */
1409
+ facetKey: string;
1410
+ /** Display name of the facet root. */
1411
+ name: string;
1412
+ /** Total facet-value leaves (may exceed `values.length` — the list is capped). */
1413
+ valueCount: number;
1414
+ /** Documents carrying any value of this facet. */
1415
+ docCount: number;
1416
+ /** The facet's value leaves. */
1417
+ values: Array<KnowledgeBaseGraphFacetValueStatus>;
1418
+ }
1419
+ /** One value leaf of a facet in a graph status response. @category AI */
1420
+ export interface KnowledgeBaseGraphFacetValueStatus {
1421
+ /** Display name of the value (the most frequent raw variant). */
1422
+ name: string;
1423
+ /** Documents assigned to this value. */
1424
+ docCount: number;
1425
+ /** Raw variants consolidated into this value ("USA" under "United States"), when any. */
1426
+ aliases?: string[];
1427
+ }
1428
+ /**
1429
+ * How much of the knowledge base's graph a rebuild recomputes.
1430
+ *
1431
+ * - `'structural'` (default) — keeps the already-extracted entity graph (LLM extraction runs only for
1432
+ * contexts that were never graph-indexed, e.g. after an interrupted ingest) and recomputes the
1433
+ * derived structure on top of it: entity resolution, lexical mentions, topics and facets. Typically
1434
+ * a small fraction of a full rebuild's cost — the right choice for folding freshly ingested
1435
+ * documents into topics/facets.
1436
+ * - `'full'` — wipes the graph and re-extracts entities/relationships from every chunk with an LLM,
1437
+ * then rebuilds the concept layer. The expensive deep-clean: re-extraction dominates its cost.
1438
+ * Only needed when the extraction itself must be redone, e.g. after changing `entityTypes` or
1439
+ * `extractionModel`.
1440
+ * @category AI
1441
+ */
1442
+ export type KnowledgeBaseGraphRebuildMode = 'full' | 'structural';
1443
+ /**
1444
+ * Request structure for enqueuing a GraphRAG rebuild/backfill of a knowledge base.
1445
+ * @category AI
1446
+ */
1447
+ export interface RebuildKnowledgeBaseGraphRequest {
1448
+ /** The id of the AiKnowledgeBase. */
1449
+ knowledgeBaseId: AiKnowledgeBaseId;
1450
+ /** What to recompute (see {@link KnowledgeBaseGraphRebuildMode}). Default `'structural'`. */
1451
+ mode?: KnowledgeBaseGraphRebuildMode;
1452
+ /**
1453
+ * When true, starts the rebuild even while a bulk-ingestion job on the KB is still active. Off by
1454
+ * default: such a rebuild is refused (`GRAPH_REBUILD_BLOCKED_BY_BULK_JOB`) because it re-extracts the
1455
+ * contexts the job is still merging. Set it for a job that is wedged (its pod died and its deadline
1456
+ * has not passed) when cancelling the job is not an option.
1457
+ */
1458
+ ignoreActiveBulkJobs?: boolean;
1459
+ }
1460
+ /**
1461
+ * Request structure for exploring a bounded subgraph of a knowledge base's graph (Phase 3 visualization).
1462
+ * Returns the highest-degree entities and the relationships among them. Seed-based exploration
1463
+ * (prompt/entity-name seeding + traversal depth) is a planned extension; its fields will be added
1464
+ * here once implemented.
1465
+ * @category AI
1466
+ */
1467
+ export interface ExploreKnowledgeBaseGraphRequest {
1468
+ /** The id of the AiKnowledgeBase. */
1469
+ knowledgeBaseId: AiKnowledgeBaseId;
1470
+ /** Hard cap on returned nodes. Default 200, max 1000. */
1471
+ nodeLimit?: number;
1472
+ /**
1473
+ * Restricts the subgraph to entities under the given topic node id — any hierarchy level; an entity
1474
+ * matches when the topic appears anywhere in its `topicPath`. Unknown ids fail with
1475
+ * `TOPIC_NOT_FOUND`. Ids come from {@link KnowledgeBaseGraphTopic.id} and churn on rebuild.
1476
+ */
1477
+ topicId?: string;
1478
+ }
1479
+ /** A node in an {@link ExploreKnowledgeBaseGraphResponse}. @category AI */
1480
+ export interface KnowledgeBaseGraphNode {
1481
+ /** Stable node id (the entity's document id). */
1482
+ id: string;
1483
+ /** Canonical display name. */
1484
+ name: string;
1485
+ /** Entity type. */
1486
+ type: string;
1487
+ /** Compacted description. */
1488
+ description: string;
1489
+ /** Relationship degree (denormalized). */
1490
+ degree: number;
1491
+ /** Community id (Phase 3), when community detection has run. */
1492
+ communityId?: string;
1493
+ /** Level-0..k topic nodeIds (bottom-up, Layered KB Graph), when a topic rebuild has run. */
1494
+ topicPath?: string[];
1495
+ /** Norm-names this entity absorbed via resolution merges (present only when non-empty). */
1496
+ aliases?: string[];
1497
+ }
1498
+ /** An edge in an {@link ExploreKnowledgeBaseGraphResponse}. @category AI */
1499
+ export interface KnowledgeBaseGraphEdge {
1500
+ /** Source node id. */
1501
+ source: string;
1502
+ /** Target node id. */
1503
+ target: string;
1504
+ /** Relationship label. */
1505
+ type: string;
1506
+ /** Co-mention weight. */
1507
+ weight: number;
1508
+ }
1509
+ /**
1510
+ * Response structure for the bounded subgraph exploration (Phase 3 visualization).
1511
+ * @category AI
1512
+ */
1513
+ export interface ExploreKnowledgeBaseGraphResponse {
1514
+ /** The subgraph nodes. */
1515
+ nodes: Array<KnowledgeBaseGraphNode>;
1516
+ /** The subgraph edges (outgoing only, both endpoints present in `nodes`). */
1517
+ edges: Array<KnowledgeBaseGraphEdge>;
1518
+ /**
1519
+ * The KB's topic (theme) nodes — the id→name/hierarchy table for the nodes' `topicPath` ids, so a
1520
+ * visualization can label and group by theme without extra round trips. Present when the concept
1521
+ * layer has been built (a rebuild ran).
1522
+ */
1523
+ topics?: Array<KnowledgeBaseGraphTopic>;
1524
+ }
1525
+ /**
1526
+ * A topic (theme) node of the graph's concept layer, as referenced by
1527
+ * {@link KnowledgeBaseGraphNode.topicPath}.
1528
+ * @category AI
1529
+ */
1530
+ export interface KnowledgeBaseGraphTopic {
1531
+ /** Topic nodeId (matches `topicPath` entries). Churns on rebuild — not a persistable handle. */
1532
+ id: string;
1533
+ /** Topic display name. Re-resolves by name across rebuilds. */
1534
+ name: string;
1535
+ /** Hierarchy level: 0 = leaf tier, higher = coarser tiers. */
1536
+ level: number;
1537
+ /** Parent topic nodeId, when the topic sits under a coarser tier. */
1538
+ parentId?: string;
1539
+ /** Documents under the topic, when tracked. */
1540
+ docCount?: number;
1541
+ /** Members of the topic: entities at level 0, child topics at higher levels. */
1542
+ memberCount?: number;
1543
+ }
1544
+ /**
1545
+ * An aggregated relationship edge between two leaf topics: how many entity relationships cross
1546
+ * between their member entities. Undirected (one entry per pair) and pruned to each topic's
1547
+ * strongest neighbors, so weak long-tail links may be absent. Ids churn on rebuild, like
1548
+ * {@link KnowledgeBaseGraphTopic.id}.
1549
+ * @category AI
1550
+ */
1551
+ export interface KnowledgeBaseGraphTopicEdge {
1552
+ /** One endpoint's topic nodeId. */
1553
+ source: string;
1554
+ /** The other endpoint's topic nodeId. */
1555
+ target: string;
1556
+ /** Number of entity relationships crossing between the two topics. */
1557
+ weight: number;
1558
+ }
1559
+ /**
1560
+ * The closed operation set of the `queryKnowledgeGraph` surface (Layered KB Graph P4). Every op is one
1561
+ * round trip with a complete answer — no per-level walking.
1562
+ * @category AI
1563
+ */
1564
+ export type KnowledgeBaseGraphQueryOp = 'overview' | 'resolve' | 'describe' | 'subtree' | 'docsUnder' | 'conceptsOf' | 'neighborhood' | 'pathBetween' | 'globalSummary';
1565
+ /**
1566
+ * Request structure for querying a knowledge base's graph (documents, entities, topics, facets) through
1567
+ * the closed op set. `ref` accepts a facet nodeId (`facet_…` — exact; the only persistable concept
1568
+ * handles) or a name, resolved server-side (exact → alias → similarity). An unresolvable ref fails with
1569
+ * `CONCEPT_NOT_FOUND` plus the nearest matching names.
1570
+ * @category AI
1571
+ */
1572
+ export interface QueryKnowledgeBaseGraphRequest {
1573
+ /** The id of the AiKnowledgeBase. */
1574
+ knowledgeBaseId: AiKnowledgeBaseId;
1575
+ /** The operation to run. */
1576
+ op: KnowledgeBaseGraphQueryOp;
1577
+ /** Node ref (name or facet nodeId). Required by resolve/describe/subtree/docsUnder/neighborhood/pathBetween. */
1578
+ ref?: string;
1579
+ /** Second node ref for `pathBetween`. */
1580
+ refB?: string;
1581
+ /** The document's contextId for `conceptsOf`. */
1582
+ contextId?: string;
1583
+ /** The free-text question for `globalSummary` (ranks the KB's topic summaries against it). */
1584
+ query?: string;
1585
+ /** `subtree`: maximum depth below the resolved node. Default (and cap) 3. */
1586
+ depth?: number;
1587
+ /** `neighborhood`: expansion hops from the resolved entity. Default 1, max 2. */
1588
+ hops?: number;
1589
+ /** `docsUnder`: when true (default), include documents under the whole subtree, not just the node itself. */
1590
+ recursive?: boolean;
1591
+ /** `docsUnder`: maximum documents returned. Default 25, max 100 (`totalDocs` always reports the full count). */
1592
+ limit?: number;
1593
+ }
1594
+ /** One node matched by a graph query (`resolve`, and the anchors of other ops). @category AI */
1595
+ export interface KnowledgeBaseGraphQueryMatch {
1596
+ /** What kind of node matched. */
1597
+ kind: 'document' | 'entity' | 'topic' | 'facetRoot' | 'facetValue';
1598
+ /** Display name (document title, entity/topic/facet name). */
1599
+ name: string;
1600
+ /**
1601
+ * Persistable handle, present only where one exists: facet nodeIds (stable across rebuilds) and
1602
+ * document contextIds. Topic and entity refs re-resolve by name — their internal ids are omitted.
1603
+ */
1604
+ id?: string;
1605
+ /** The metadata field a facet node belongs to. */
1606
+ facetKey?: string;
1607
+ /** Node description (may be empty for facet leaves). */
1608
+ description?: string;
1609
+ /** Documents under the node, where tracked (topics and facet nodes). */
1610
+ docCount?: number;
1611
+ /** Topics: members of the node (entities at level 0, child topics at higher levels). */
1612
+ memberCount?: number;
1613
+ }
1614
+ /** A node in a `subtree` response: the resolved node with its children, recursively. @category AI */
1615
+ export interface KnowledgeBaseGraphQuerySubtreeNode {
1616
+ /** Display name. */
1617
+ name: string;
1618
+ /** Persistable facet nodeId (present on facet nodes; see {@link KnowledgeBaseGraphQueryMatch.id}). */
1619
+ id?: string;
1620
+ /** Documents under this node. */
1621
+ docCount?: number;
1622
+ /** Raw variants consolidated into a facet value ("United States of America" under "United States"). */
1623
+ aliases?: string[];
1624
+ /** Child nodes, depth-limited by the request. */
1625
+ children?: Array<KnowledgeBaseGraphQuerySubtreeNode>;
1626
+ }
1627
+ /** A document summary returned by `docsUnder`. @category AI */
1628
+ export interface KnowledgeBaseGraphQueryDoc {
1629
+ /** The document's contextId (usable with `conceptsOf` and the KB context APIs). */
1630
+ contextId: string;
1631
+ /** Document title, when one exists. */
1632
+ title?: string;
1633
+ /** The document node's LLM description ('' when generation failed). */
1634
+ description?: string;
1635
+ }
1636
+ /** A document's concept memberships (`conceptsOf`): facet paths + topics. @category AI */
1637
+ export interface KnowledgeBaseGraphQueryConcepts {
1638
+ /** The facet values the document carries, with their persistable leaf ids. */
1639
+ facets: Array<{
1640
+ facetKey: string;
1641
+ value: string;
1642
+ id: string;
1643
+ }>;
1644
+ /** Names of the topics (flat themes) the document belongs to. Thematic — refs re-resolve by name. */
1645
+ topics: Array<string>;
1646
+ }
1647
+ /**
1648
+ * One topic (community) summary returned by the `globalSummary` op — the themes-level "global" answer
1649
+ * content, ranked against the query. @category AI
1650
+ */
1651
+ export interface KnowledgeBaseGraphQueryGlobalSummary {
1652
+ /** Topic display name. Thematic — re-resolves by name across rebuilds. */
1653
+ topic: string;
1654
+ /** The topic's LLM-generated summary. */
1655
+ summary: string;
1656
+ }
1657
+ /**
1658
+ * A `pathBetween` answer. Two-tier: an entity path when one exists (explanatory — the chain of typed
1659
+ * relationships), else concept/topic co-membership labeled `thematic` (the refs share concepts but no
1660
+ * entity chain connects them).
1661
+ * @category AI
1662
+ */
1663
+ export interface KnowledgeBaseGraphQueryPath {
1664
+ /** Which tier answered: `'entity'` (relationship chain) or `'thematic'` (shared concepts only). */
1665
+ tier: 'entity' | 'thematic';
1666
+ /** Entity tier: the relationship chain, in order. */
1667
+ steps?: Array<{
1668
+ from: string;
1669
+ type: string;
1670
+ to: string;
1671
+ }>;
1672
+ /** Thematic tier: names of concepts both refs sit under. */
1673
+ sharedConcepts?: Array<string>;
1674
+ }
1675
+ /**
1676
+ * Response structure for a graph query. `op` echoes the request; exactly the fields that op produces
1677
+ * are set (e.g. `matches` for `resolve`, `tree` for `subtree`).
1678
+ * @category AI
1679
+ */
1680
+ export interface QueryKnowledgeBaseGraphResponse {
1681
+ /** The operation that ran. */
1682
+ op: KnowledgeBaseGraphQueryOp;
1683
+ /** `overview`: the rendered knowledge-graph map (names + counts). */
1684
+ overview?: string;
1685
+ /** `resolve`: matching nodes across all kinds, best first. */
1686
+ matches?: Array<KnowledgeBaseGraphQueryMatch>;
1687
+ /** `describe`: the resolved node. */
1688
+ node?: KnowledgeBaseGraphQueryMatch;
1689
+ /** `describe`: ancestor names root-first (facet path / topic hierarchy), when the node has one. */
1690
+ path?: Array<string>;
1691
+ /** `describe`: immediate related nodes — children with counts, a document's concepts, an entity's edges. */
1692
+ related?: Array<{
1693
+ relation: string;
1694
+ name: string;
1695
+ docCount?: number;
1696
+ }>;
1697
+ /** `subtree`: the resolved node's subtree with doc counts. */
1698
+ tree?: KnowledgeBaseGraphQuerySubtreeNode;
1699
+ /** `docsUnder`: documents in the resolved node's closure (capped by `limit`). */
1700
+ documents?: Array<KnowledgeBaseGraphQueryDoc>;
1701
+ /** `docsUnder`: the full closure size (compare with `documents.length` for truncation). */
1702
+ totalDocs?: number;
1703
+ /** `conceptsOf`: the document's concept memberships. */
1704
+ concepts?: KnowledgeBaseGraphQueryConcepts;
1705
+ /** `neighborhood`: the entity subgraph around the resolved entity. */
1706
+ graph?: ExploreKnowledgeBaseGraphResponse;
1707
+ /** `pathBetween`: the two-tier path answer; absent when the refs are entirely unconnected. */
1708
+ pathBetween?: KnowledgeBaseGraphQueryPath;
1709
+ /** `globalSummary`: the KB's topic summaries ranked against the query, most relevant first. */
1710
+ summaries?: Array<KnowledgeBaseGraphQueryGlobalSummary>;
1711
+ }
1712
+ /**
1713
+ * One context to stage through bulk ingestion.
1714
+ * @category AI
1715
+ */
1716
+ export interface BulkIngestionContext {
1717
+ /**
1718
+ * The id of the context. Optional: when omitted, the server generates one and rejects the upload if
1719
+ * another context in the knowledge base already holds identical content (content-level dedup). Provide
1720
+ * an explicit id to address a specific context — that overwrites it unconditionally and allows duplicate
1721
+ * content across different ids, exactly as the synchronous `upsertContexts` treats a supplied id. Must
1722
+ * be unique within one request (each staged context becomes one per-file row keyed by this id), at most
1723
+ * 512 UTF-8 bytes of letters, digits, `_`, `.`, `:`, `@` or `-` only, and the overwrite lands
1724
+ * asynchronously when the job finalizes the file.
1725
+ */
1726
+ contextId?: AiContextId;
1727
+ /** `'text'` (the default) stages a text context; `'file'` consumes the next uploaded file positionally. */
1728
+ type?: 'text' | 'file';
1729
+ /** Title for a text context (required); optional display title for a file context. */
1730
+ title?: string;
1731
+ /** The text content to stage; required for `type: 'text'`. */
1732
+ text?: string;
1733
+ /** Whether to extract images: inline markdown/HTML images for text contexts, embedded images for files. */
1734
+ extractImages?: boolean;
1735
+ /** Hint about a text context's format; only meaningful for `type: 'text'`. */
1736
+ format?: 'markdown' | 'html' | 'plain';
1737
+ /**
1738
+ * Key returned by bulk/createUploadUrls; the server ingests the staged object as this context's file.
1739
+ * Mutually exclusive with a positional multipart file.
1740
+ */
1741
+ stagedObjectKey?: string;
1742
+ /**
1743
+ * The preferred method for extracting data from a file context; mirrors the sync lane's field of the
1744
+ * same name, so a caller's choice survives whichever lane a deployment routes the upload through.
1745
+ */
1746
+ preferredExtractionMethod?: DocumentExtractionMethod;
1747
+ /**
1748
+ * Optional metadata associated with the context item; mirrors {@link BaseAiKnowledgeBaseContextRequest.metadata}.
1749
+ * Squid-reserved keys are stripped server-side, and values are validated/normalized against the target
1750
+ * knowledge base's `metadataFields` schema when one is declared.
1751
+ */
1752
+ metadata?: Record<string, unknown>;
1753
+ /**
1754
+ * Access scopes granting read access to this context, stamped onto every chunk it produces when the
1755
+ * job finalizes; mirrors {@link BaseAiKnowledgeBaseContextRequest.scopes}, with the same semantics:
1756
+ * omitted keeps whatever scopes the context already had, an empty array makes it visible to every
1757
+ * caller. On a knowledge base with `accessControl.mode: 'enforced'`, a context whose scopes resolve
1758
+ * to nothing at finalize is stamped unreadable rather than public.
1759
+ */
1760
+ scopes?: Array<string>;
1761
+ }
1762
+ /**
1763
+ * Request structure for staging contexts through bulk ingestion: a durable, asynchronous lane that
1764
+ * processes contexts through provider batch APIs rather than inline, for high-volume ingestion. Poll
1765
+ * {@link BulkIngestionJobStatusResponse} with the returned job id for progress.
1766
+ * @category AI
1767
+ */
1768
+ export interface BulkIngestionUpsertContextsRequest {
1769
+ /** The id of the AiKnowledgeBase to ingest into. */
1770
+ knowledgeBaseId: string;
1771
+ /** The contexts to stage; each becomes one bulk-ingestion file. */
1772
+ contexts: Array<BulkIngestionContext>;
1773
+ /**
1774
+ * How quickly this job must finish. A hint, not a command: Squid honours it where the job's models and
1775
+ * its share of the ingestion pool allow, and otherwise runs the job the way it can. Read
1776
+ * {@link BulkIngestionJobStatusResponse.transport} to see what it actually ran as.
1777
+ */
1778
+ speed?: BulkIngestionSpeed;
1779
+ }
1780
+ /**
1781
+ * The optional half of a bulk-ingestion staging call.
1782
+ * @category AI
1783
+ */
1784
+ export interface BulkIngestionUpsertContextsOptions {
1785
+ /** See {@link BulkIngestionUpsertContextsRequest.speed}. */
1786
+ speed?: BulkIngestionSpeed;
1787
+ }
1788
+ /**
1789
+ * How quickly a bulk-ingestion job must finish, and so which provider tier Squid buys for it. The model,
1790
+ * the prompts and the resulting chunks are identical at every speed — only the queue in front of them
1791
+ * differs.
1792
+ *
1793
+ * - `economy` — provider batch, cheapest, tails up to 24 hours.
1794
+ * - `auto` — Squid decides from the job's size. The default.
1795
+ * - `fast` — runs inline, minutes rather than hours, at full list price.
1796
+ * @category AI
1797
+ */
1798
+ export declare const BULK_INGESTION_SPEEDS: readonly ["economy", "auto", "fast"];
1799
+ /** See {@link BULK_INGESTION_SPEEDS}. */
1800
+ export type BulkIngestionSpeed = (typeof BULK_INGESTION_SPEEDS)[number];
1801
+ /**
1802
+ * Response for a staged bulk-ingestion request.
1803
+ * @category AI
1804
+ */
1805
+ export interface BulkIngestionUpsertContextsResponse {
1806
+ /** The id of the staged bulk-ingestion job. */
1807
+ jobId: string;
1808
+ /**
1809
+ * Context ids assigned to the staged contexts, in the same order as the request's `contexts` array. A
1810
+ * context rejected as a duplicate still occupies its slot here, so this stays index-aligned with the
1811
+ * request; cross-reference `duplicates` by `contextId` to tell which ids were actually staged.
1812
+ */
1813
+ contextIds: Array<string>;
1814
+ /**
1815
+ * Contexts rejected because the knowledge base already holds identical content — either stored under
1816
+ * an existing context or accepted earlier in this same call. Absent when nothing was rejected.
1817
+ *
1818
+ * Same shape and `errorCode: 'DUPLICATE_CONTENT'` the synchronous `upsertContexts` returns, so a caller
1819
+ * handles a duplicate identically on both lanes. These contexts are NOT part of the job: they are not
1820
+ * extracted, not staged, and never appear in its per-file statuses.
1821
+ *
1822
+ * Covers TEXT contexts and MULTIPART file contexts (their bytes are in hand at staging). A file staged
1823
+ * by `stagedObjectKey` is the one exception: its bytes are first read by the deferred extraction pass,
1824
+ * so its duplicate surfaces asynchronously as a failed file with `errorCode: 'DUPLICATE_CONTENT'` in
1825
+ * the job's per-file statuses instead.
1826
+ */
1827
+ duplicates?: Array<UpsertContextStatusError>;
1828
+ }
1829
+ /**
1830
+ * Request structure for reading a bulk-ingestion job's progress.
1831
+ * @category AI
1832
+ */
1833
+ export interface BulkIngestionJobStatusRequest {
1834
+ /** The id of the bulk-ingestion job to inspect. */
1835
+ jobId: string;
1836
+ }
1837
+ /**
1838
+ * Progress counters for a bulk-ingestion job, aggregated from its files and logical requests.
1839
+ * @category AI
1840
+ */
1841
+ export interface BulkIngestionJobStatusCounts {
1842
+ /** Total files staged for the job. */
1843
+ files: number;
1844
+ /** Files whose contexts have been finalized into the knowledge base. */
1845
+ finalized: number;
1846
+ /** Files that terminally failed. */
1847
+ failed: number;
1848
+ /** Logical requests still pending submission. */
1849
+ requestsPending: number;
1850
+ /** Logical requests submitted to the provider and awaiting results. */
1851
+ requestsSubmitted: number;
1852
+ }
1853
+ /**
1854
+ * Per-file/per-context status within a bulk-ingestion job, so a caller can see which file finished,
1855
+ * which is still processing, and why a file failed.
1856
+ * @category AI
1857
+ */
1858
+ export interface BulkIngestionFileStatus {
1859
+ /** The context id assigned to this file at staging. */
1860
+ contextId: string;
1861
+ /** The file's title — the uploaded file name, or the caller-supplied title for text contexts. */
1862
+ title: string;
1863
+ /** User-facing per-file status. */
1864
+ status: 'processing' | 'completed' | 'failed';
1865
+ /** Present only when status is 'failed': the terminal failure reason. */
1866
+ errorMessage?: string;
1867
+ /**
1868
+ * Machine-readable class of a failed file, for outcomes to treat differently from real failures.
1869
+ * Terminal — reported with `retryable: false` — are `'CONTENT_TOO_LARGE'` (past the per-context
1870
+ * ceiling), `'ENCRYPTED_DOCUMENT'`, `'NO_EMBEDDABLE_CONTENT'`, `'SOURCE_OVER_PROVIDER_LIMIT'` (the
1871
+ * bytes exceed what the extraction provider accepts) and `'UNSUPPORTED_FILE_TYPE'`.
1872
+ * `'DUPLICATE_CONTENT'` is a skip rather than a failure: the KB already holds this content.
1873
+ * `'EXTRACTION_TIMED_OUT'` stays retryable — the deadline is contended, so a borderline document can
1874
+ * cross it under load. `'JOB_FULL'`: the job's request ceiling had no room left for this file, so re-submit it
1875
+ * in a fresh job; a file that alone exceeds the ceiling fails this way in every job. Additive; absent for
1876
+ * ordinary failures.
1877
+ */
1878
+ errorCode?: 'CONTENT_TOO_LARGE' | 'DUPLICATE_CONTENT' | 'ENCRYPTED_DOCUMENT' | 'EXTRACTION_TIMED_OUT' | 'JOB_FULL' | 'NO_EMBEDDABLE_CONTENT' | 'SOURCE_OVER_PROVIDER_LIMIT' | 'UNSUPPORTED_FILE_TYPE';
1879
+ /**
1880
+ * Present only on a failed file: the same bytes fail the same way, so a caller must park the file
1881
+ * instead of re-submitting it. Absence means retryable.
1882
+ */
1883
+ retryable?: false;
1884
+ /**
1885
+ * First images (capped) the context lacks a description for because describing them failed; a
1886
+ * `completed` file is otherwise fully ingested. Absent when every image succeeded.
1887
+ */
1888
+ imageFailures?: Array<ContextImageFailure>;
1889
+ /** Total number of failed images, which exceeds `imageFailures.length` when the list was capped. */
1890
+ imageFailureCount?: number;
1891
+ }
1892
+ /**
1893
+ * Why a whole bulk-ingestion staging call was refused, on the `details` of its 400 response. The
1894
+ * refusal names the one context that caused it, so a caller recording per-file outcomes charges only
1895
+ * that file.
1896
+ * @category AI
1897
+ */
1898
+ export interface BulkIngestionStagingRefusal {
1899
+ /** The staged object exceeds the per-file source ceiling. */
1900
+ errorCode: 'STAGED_OBJECT_TOO_LARGE';
1901
+ /** The same bytes are refused the same way, so the named file must be parked rather than re-staged. */
1902
+ retryable: false;
1903
+ /** The context whose file caused the refusal. */
1904
+ contextId: string;
1905
+ }
1906
+ /**
1907
+ * One provider batch created for a bulk-ingestion job, so a caller can tell a job waiting on a
1908
+ * submitted provider batch (healthy — the designed cost/latency tradeoff of the batch lane, with
1909
+ * turnaround up to 24 hours) from a job that is actually stuck, and see since when.
1910
+ * @category AI
1911
+ */
1912
+ export interface BulkIngestionProviderBatchStatus {
1913
+ /** The provider running the batch. Mirrors the core batch row's union, like {@link state}. */
1914
+ provider: 'openai' | 'anthropic' | 'mistral' | 'voyage';
1915
+ /** The provider API the batch rides. Mirrors the core batch row's union, like {@link state}. */
1916
+ endpoint: '/v1/embeddings' | '/v1/messages/batches' | '/v1/chat/completions' | '/v1/ocr';
1917
+ /**
1918
+ * The batch's lifecycle state: `intent` (created, not yet submitted), `submitted` (waiting on the
1919
+ * provider), `ended` (provider finished, results not yet absorbed), or terminal
1920
+ * (`reconciled`/`cancelled`/`failed`).
1921
+ */
1922
+ state: 'intent' | 'submitted' | 'ended' | 'reconciled' | 'cancelled' | 'failed';
1923
+ /** The provider's own batch id; absent until the batch is submitted. */
1924
+ providerBatchId?: string;
1925
+ /** When the batch was created — the "since when has this been waiting" clock for an in-flight batch. */
1926
+ createdAt: Date;
1927
+ /**
1928
+ * When the batch row was last written. NOT a state-transition time: the poller refreshes it on every
1929
+ * poll of an in-flight batch, so on a healthy job it is always recent — it freezing means polling
1930
+ * stopped, not that the batch is waiting. Read wait duration off {@link createdAt}.
1931
+ */
1932
+ updatedAt: Date;
1933
+ /** The lanes of the requests the batch carries; empty when a batch of an older core cannot tell. */
1934
+ lanes?: Array<BulkIngestionRequestLane>;
1935
+ /**
1936
+ * The provider's status at the newest poll, as the adapter reports it: provider-raw for OpenAI, normalized
1937
+ * (`in_progress`, `completed`, …) for Anthropic and Mistral.
1938
+ */
1939
+ providerStatus?: string;
1940
+ /** When a poll first saw {@link providerStatus}. */
1941
+ providerStatusChangedAt?: Date;
1942
+ /** When the provider started running the batch; absent while it has not. */
1943
+ providerInProgressAt?: Date;
1944
+ /** Per-request progress at the newest poll; absent for a provider that does not report it. */
1945
+ requestCounts?: BulkIngestionProviderBatchRequestCounts;
1946
+ /** When the poll that read {@link requestCounts} ran. */
1947
+ requestCountsAt?: Date;
1948
+ }
1949
+ /**
1950
+ * The lane a bulk-ingestion request belongs to; core's `BulkIngestionLane` is this type.
1951
+ * @category AI
1952
+ */
1953
+ export type BulkIngestionRequestLane = 'embeddings' | 'imageDescription' | 'spreadsheetSummary' | 'metadataExtraction' | 'chunkContext' | 'documentOcr';
1954
+ /**
1955
+ * A provider batch's per-request progress as the provider reports it.
1956
+ * @category AI
1957
+ */
1958
+ export interface BulkIngestionProviderBatchRequestCounts {
1959
+ /** Requests in the batch. */
1960
+ total: number;
1961
+ /**
1962
+ * Requests the provider ran to a result, succeeded or failed. Requests it reports as cancelled or expired unrun are
1963
+ * left out, so `total − completed` is not the count still in flight.
1964
+ */
1965
+ completed: number;
1966
+ /** Of {@link completed}, the ones that failed, when the provider reports that breakdown. */
1967
+ failed?: number;
1968
+ }
1969
+ /**
1970
+ * Provider-side progress of one job's batches on one provider route (provider, endpoint and model). A route
1971
+ * is the unit the provider queues, and one batch can carry several lanes, so progress is reported per route.
1972
+ * @category AI
1973
+ */
1974
+ export interface BulkIngestionProviderRouteThroughput {
1975
+ /** The provider running the route's batches. */
1976
+ provider: BulkIngestionProviderBatchStatus['provider'];
1977
+ /** The provider API the route's batches ride. */
1978
+ endpoint: BulkIngestionProviderBatchStatus['endpoint'];
1979
+ /** The model the route's batches run on. */
1980
+ model: string;
1981
+ /** The lanes the route's batches carry. */
1982
+ lanes: Array<BulkIngestionRequestLane>;
1983
+ /** The route's batches created or submitted and not yet ended at the provider. */
1984
+ batchesInFlight: number;
1985
+ /** Requests in those batches the provider has not settled yet. */
1986
+ requestsInFlight: number;
1987
+ /** Requests the provider ran to a result, succeeded or failed, across the route's batches. */
1988
+ requestsCompleted: number;
1989
+ /** Of {@link requestsCompleted}, the ones that failed; absent when no batch reports that breakdown. */
1990
+ requestsFailed?: number;
1991
+ /**
1992
+ * Requests the provider completed per minute over the last {@link BulkIngestionProviderThroughput.windowMinutes};
1993
+ * absent when no batch of the route reports counts.
1994
+ */
1995
+ completedPerMinute?: number;
1996
+ /**
1997
+ * The oldest view of an in-flight batch: when its counts were read, else when its status last was, else when it
1998
+ * was created. Older than a few minutes means polls lag or return no counts, not that the provider stalled:
1999
+ * {@link completedPerMinute} then misses what the provider did since.
2000
+ */
2001
+ countsObservedAt?: Date;
2002
+ }
2003
+ /**
2004
+ * One in-flight provider-batch budget of the app on the shared system credential.
2005
+ * @category AI
2006
+ */
2007
+ export interface BulkIngestionInFlightBatchBudget {
2008
+ /** The lanes whose batches the budget gates. */
2009
+ lanes: Array<BulkIngestionRequestLane>;
2010
+ /** Batches of the WHOLE app holding the budget: another job of the app holds slots too. */
2011
+ inFlight: number;
2012
+ /** How many batches the budget admits right now; a lane whose budget is full waits for a slot. */
2013
+ limit: number;
2014
+ }
2015
+ /**
2016
+ * Whether a running job's provider batches are draining: per-route progress and the app's in-flight budgets.
2017
+ * @category AI
2018
+ */
2019
+ export interface BulkIngestionProviderThroughput {
2020
+ /** The span, in minutes, the per-route completion rates cover. */
2021
+ windowMinutes: number;
2022
+ /** Progress per provider route the job has batches on. */
2023
+ routes: Array<BulkIngestionProviderRouteThroughput>;
2024
+ /** The app's in-flight budgets; absent when the job's batches run on the app's own provider key, which is not capped. */
2025
+ inFlightBatchBudgets?: Array<BulkIngestionInFlightBatchBudget>;
2026
+ }
2027
+ /**
2028
+ * Response describing a bulk-ingestion job's current state and progress counts.
2029
+ * @category AI
2030
+ */
2031
+ export interface BulkIngestionJobStatusResponse {
2032
+ /** The job's lifecycle state (e.g. running, completed, failed, cancelled). */
2033
+ state: string;
2034
+ /**
2035
+ * The job's execution transport: `'batch'` rides provider batches (half price, tails up to 24
2036
+ * hours), `'sync'` executes inline within minutes. Decided at staging from the job's size, with one
2037
+ * transition — a defer-eligible job whose OCR routing lands on the provider batch is promoted
2038
+ * `'sync'` to `'batch'` — and held from then on. Descriptive metadata ONLY: it says how the job
2039
+ * runs, never whether a batch is draining right now, so it must not gate any wait/timeout policy;
2040
+ * that is {@link activeProviderBatchCount}. Optional on the wire: consumers must tolerate its
2041
+ * absence.
2042
+ */
2043
+ transport?: 'batch' | 'sync';
2044
+ /**
2045
+ * The lanes a `'batch'` job ROUTES inline — at the synchronous price, within minutes — rather than onto a
2046
+ * provider batch: `embeddings`, whose batches are too small for the discount to beat the queue tail.
2047
+ * Absent when every lane batches, and on a `'sync'` job (every lane of which runs inline). The job's
2048
+ * routing policy, not a record of what ran: a lane handed to the inline transport by a cancelled
2049
+ * provider-batch tail executes inline without being named here. Descriptive metadata, like {@link transport}.
2050
+ */
2051
+ inlineLanes?: Array<'embeddings' | 'imageDescription' | 'spreadsheetSummary' | 'metadataExtraction'>;
2052
+ /** Progress counters aggregated from the job's files and logical requests. */
2053
+ counts: BulkIngestionJobStatusCounts;
2054
+ /** Provider batch ids created for this job, across every batch state — including already-drained ones. */
2055
+ providerBatchIds: Array<string>;
2056
+ /**
2057
+ * Number of provider batches still in flight (created, submitted, or awaiting result reconciliation).
2058
+ * THE deferral signal: work is draining through a provider batch right now exactly when this is
2059
+ * positive — unlike {@link providerBatchIds}, which keeps terminal batches, and unlike
2060
+ * {@link transport}, which is descriptive metadata. Optional on the wire: consumers must tolerate
2061
+ * its absence.
2062
+ */
2063
+ activeProviderBatchCount?: number;
2064
+ /**
2065
+ * Per-batch detail for every provider batch of the job, so a caller can tell a healthy wait on a
2066
+ * submitted provider batch from a stall — and see since when. A SUPERSET of
2067
+ * {@link providerBatchIds}, not index-aligned with it: an `intent` batch appears here with no
2068
+ * `providerBatchId` while that list omits it. Optional on the wire: consumers must tolerate its
2069
+ * absence.
2070
+ */
2071
+ providerBatches?: Array<BulkIngestionProviderBatchStatus>;
2072
+ /**
2073
+ * Coarse answer to "what is this job doing right now": `awaiting-provider-batch` while the
2074
+ * PROVIDER is working — an `intent` or `submitted` batch (deferred OCR included; it wins whatever stage the
2075
+ * files carry) or batch-route work still queued for submission — `extracting` while files still
2076
+ * await or undergo extraction with no submitted batch, and `indexing` otherwise (inline/flex
2077
+ * requests executing, `ended` batches' results being absorbed, contexts being written — our own
2078
+ * work, however long it takes). Present only while the job {@link state} is `running`; the other
2079
+ * non-terminal states (`finalizing`, `cancelling`) already name what the job is doing. Optional on
2080
+ * the wire: consumers must tolerate its absence.
2081
+ */
2082
+ phase?: 'extracting' | 'awaiting-provider-batch' | 'indexing';
2083
+ /**
2084
+ * Provider-side progress of the job's batches, so a saturated in-flight budget the provider is draining
2085
+ * reads differently from one it completes nothing in. Present only while a `'batch'` job is `running`.
2086
+ * Optional on the wire: consumers must tolerate its absence.
2087
+ */
2088
+ providerThroughput?: BulkIngestionProviderThroughput;
2089
+ /** Per-file status, one entry per staged context (bounded by the job's file cap). */
2090
+ files: Array<BulkIngestionFileStatus>;
2091
+ }
2092
+ /**
2093
+ * Request structure for cancelling a running bulk-ingestion job.
2094
+ * @category AI
2095
+ */
2096
+ export interface BulkIngestionCancelRequest {
2097
+ /** The id of the bulk-ingestion job to cancel. */
2098
+ jobId: string;
2099
+ }
2100
+ /**
2101
+ * Request structure for subscribing to push updates on a bulk-ingestion job. Once subscribed, the caller's
2102
+ * client id receives a `bulkIngestionStatus` socket event on each orchestrator tick that touches the job,
2103
+ * plus one final event on completion/failure/cancellation — in addition to (not instead of) polling
2104
+ * {@link BulkIngestionJobStatusResponse} through `bulk/getJob`.
2105
+ * @category AI
2106
+ */
2107
+ export interface BulkIngestionSubscribeRequest {
2108
+ /** The id of the bulk-ingestion job to subscribe to. */
2109
+ jobId: string;
2110
+ }
2111
+ /**
2112
+ * Request structure for minting presigned upload URLs for direct-to-storage bulk ingestion: the caller
2113
+ * PUTs each file's bytes straight to storage, then references it in {@link BulkIngestionContext} via
2114
+ * `stagedObjectKey`, bypassing multipart upload through core.
2115
+ * @category AI
2116
+ */
2117
+ export interface BulkIngestionCreateUploadUrlsRequest {
2118
+ /** The files to mint upload URLs for (at most 500 per call). */
2119
+ files: Array<{
2120
+ fileName: string;
2121
+ }>;
2122
+ }
2123
+ /**
2124
+ * Response listing a presigned upload URL and staged-object key for each requested file, positionally
2125
+ * aligned with the request's `files` array.
2126
+ * @category AI
2127
+ */
2128
+ export interface BulkIngestionCreateUploadUrlsResponse {
2129
+ /** One entry per requested file. */
2130
+ uploads: Array<{
2131
+ /** The original file name, echoed back from the request. */
2132
+ fileName: string;
2133
+ /** Presigned URL the caller PUTs the file's bytes to; expires shortly after minting. */
2134
+ uploadUrl: string;
2135
+ /**
2136
+ * Headers the PUT MUST carry in addition to the caller's own `Content-Type`. Empty on storage
2137
+ * backends that mandate none (S3); on Azure Blob Storage the PUT is rejected with 400
2138
+ * `MissingRequiredHeader` unless these are sent.
2139
+ */
2140
+ requiredHeaders: Record<string, string>;
2141
+ /** Key to pass as {@link BulkIngestionContext.stagedObjectKey} once the PUT completes. */
2142
+ stagedObjectKey: string;
2143
+ }>;
2144
+ }