@squidcloud/twilio-client 1.0.510 → 1.0.512

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.
@@ -1,6 +1,7 @@
1
1
  import { JSONSchema } from 'json-schema-typed';
2
2
  import { AiAudioCreateSpeechModelName, AiAudioTranscriptionModelName, AiChatModelName, AiImageModelName, AiProviderType, AiRerankProvider, AnthropicChatModelName, CanonicalReasoningEffort, EmbeddingModelIdSpec, GeminiChatModelName, GrokChatModelName, ModelIdSpec, OpenAiAudioCreateSpeechModelName, OpenAiAudioTranscriptionModelName, OpenAiChatModelName, OpenAiCreateSpeechFormat, OpenAiImageModelName, VendorAiChatModelName } from './ai-common.public-types';
3
3
  import { AiContextMetadata, AiContextMetadataFilter, AiKnowledgeBaseContextType, AiRagType } from './ai-knowledge-base.public-types';
4
+ import { AiOntologyId } from './ai-ontology.public-types';
4
5
  import { AiFunctionId, AiFunctionIdWithContext, UserAiChatModelName } from './backend.public-types';
5
6
  import { AiAgentId, AiContextId, AiKnowledgeBaseId, AppId, IntegrationId } from './communication.public-types';
6
7
  import { DocumentExtractionMethod } from './extraction.public-types';
@@ -461,7 +462,8 @@ export interface AiModelRoutingStep {
461
462
  }
462
463
  /**
463
464
  * Gives the answering model a tool that consults a stronger model mid-turn. The turn stays on its own model, so its
464
- * prompt cache survives, and the advisor gets only what the answering model passes it.
465
+ * prompt cache survives, and the advisor gets only what the answering model passes it. Models rarely consult it
466
+ * unprompted: name in the agent's instructions when they should.
465
467
  * @category AI
466
468
  */
467
469
  export interface AiAdvisorOptions {
@@ -548,6 +550,8 @@ export interface BackupModelOptions {
548
550
  export interface AiAnswerValidationOptions {
549
551
  /** Judge model; defaults to the model that produced the initial answer. */
550
552
  model?: AiChatModelSelection;
553
+ /** The effort the judge runs at; defaults to the model's own. A vendor model runs at the nearest level it accepts. */
554
+ reasoningEffort?: AiReasoningEffort;
551
555
  /** Additional acceptance criteria for the judge. */
552
556
  instructions?: string;
553
557
  /** Maximum answer attempts, including the initial answer. Defaults to 2; accepts 1–5. */
@@ -564,7 +568,10 @@ export interface AiAnswerValidationResult {
564
568
  }
565
569
  /** Shared options for agent chat requests. @category AI */
566
570
  export interface BaseAiChatOptions {
567
- /** Enables validation for non-CLI models; an empty object uses defaults. Judge read-only behavior is instruction-based. */
571
+ /**
572
+ * Enables validation for non-CLI models; an empty object uses defaults. Judge read-only behavior is instruction-based.
573
+ * Conversation memory keeps the answer only when it passes validation.
574
+ */
568
575
  validation?: AiAnswerValidationOptions;
569
576
  /**
570
577
  * The maximum number of input tokens that Squid can use when making the request to the AI model.
@@ -618,6 +625,11 @@ export interface BaseAiChatOptions {
618
625
  * enable downloads. Default to false (citations render source names only).
619
626
  */
620
627
  allowSourceDownloads?: boolean;
628
+ /**
629
+ * The ontology whose accepted relationships this agent's answers and database queries follow. Honored ONLY from the
630
+ * agent's stored options; the per-request value is ignored.
631
+ */
632
+ ontologyId?: AiOntologyId;
621
633
  /**
622
634
  * The format of the response from the AI model. Defaults to 'text'. A `json_schema` format is
623
635
  * refused for a model whose provider has no way to carry a schema — see
@@ -627,35 +639,48 @@ export interface BaseAiChatOptions {
627
639
  /** Whether to response in a "smooth typing" way, beneficial when the chat result is displayed in a UI. Default to true. */
628
640
  smoothTyping?: boolean;
629
641
  /**
630
- * Global context passed to the agent and all AI functions of the agent. A request's value also reaches the AI
631
- * functions of its connected agents, merged over each one's stored `agentContext`. Its keys are caller input and
632
- * win over stored ones: only the root agent's `@secureAiAgent` rules can vet them, and none run for a public agent.
642
+ * Global context passed to the agent and all AI functions of the agent. A request's value replaces the stored one
643
+ * and also reaches the AI functions of its connected agents, merged over each one's stored `agentContext`. On a
644
+ * public agent, whose `@secureAiAgent` rules do not run, only a request made with the app API key sets it.
633
645
  */
634
646
  agentContext?: Record<string, unknown>;
635
647
  /**
636
648
  * Functions to expose to the AI.
637
649
  * Either a function name or a name with an extra function context passed only to this function.
638
650
  * The parameter values must be valid serializable JSON values.
639
- * Overrides the stored value.
651
+ * Overrides the stored value; on a public agent, only on a request made with the app API key.
640
652
  */
641
653
  functions?: Array<AiFunctionId | AiFunctionIdWithContext>;
642
654
  /** Instructions to include with the prompt. */
643
655
  instructions?: string;
644
656
  /** A set of filters that will limit the context the AI can access.
657
+ * On a public agent, a caller without the app API key can narrow the stored filter with it, not widen it.
645
658
  * @deprecated use `contextMetadataFilterForKnowledgeBase` instead.
646
659
  */
647
660
  contextMetadataFilter?: AiContextMetadataFilter;
648
- /** A set of filters that will limit the context the AI can access. */
661
+ /**
662
+ * A set of filters that will limit the context the AI can access.
663
+ * On a public agent, a caller without the app API key can narrow the stored filters with it, not widen them.
664
+ */
649
665
  contextMetadataFilterForKnowledgeBase?: Record<AiKnowledgeBaseId, AiContextMetadataFilter>;
650
666
  /** The options to use for the response in voice. */
651
667
  voiceOptions?: AiAudioCreateSpeechOptions;
652
668
  /** A stronger model the answering model can consult mid-turn. Overrides the stored value. */
653
669
  advisor?: AiAdvisorOptions;
654
- /** List of connected AI agents can be called by the current agent. Overrides the stored value. */
670
+ /**
671
+ * Connected AI agents the current agent can call. Overrides the stored value; on a public agent, only on a request
672
+ * made with the app API key.
673
+ */
655
674
  connectedAgents?: Array<AiConnectedAgentMetadata>;
656
- /** List of connected AI agents can be called by the current agent. Overrides the stored value. */
675
+ /**
676
+ * Connected integrations the current agent can call. Overrides the stored value; on a public agent, only on a
677
+ * request made with the app API key.
678
+ */
657
679
  connectedIntegrations?: Array<AiConnectedIntegrationMetadata>;
658
- /** List of connected AiKnowlegeBases that can be called by the current agent */
680
+ /**
681
+ * List of connected AiKnowlegeBases that can be called by the current agent.
682
+ * On a public agent, a caller without the app API key can narrow the stored list with it, not widen it.
683
+ */
659
684
  connectedKnowledgeBases?: Array<AiConnectedKnowledgeBaseMetadata>;
660
685
  /** Current budget for nested or recursive AI chat calls per single prompt. */
661
686
  quotas?: AiChatPromptQuotas;
@@ -673,6 +698,8 @@ export interface BaseAiChatOptions {
673
698
  * a value passed with a chat request is ignored, so a caller cannot switch off its own screening.
674
699
  */
675
700
  pii?: AiPiiOptions;
701
+ /** Runtime security policies. Only the stored agent's configuration is honored. */
702
+ security?: AiAgentSecurityOptions;
676
703
  /** The LLM model to use. Can be a vendor model name (string) or an integration-based model (object). */
677
704
  model?: AiChatModelSelection;
678
705
  /**
@@ -761,6 +788,7 @@ export interface BaseAiChatOptions {
761
788
  * Enables a code interpreter for executing Python code.
762
789
  * - 'none': Code interpreter is disabled (default).
763
790
  * - 'llm': The model runs Python in Squid's sandbox through a tool call. Requires a model that supports tool calling.
791
+ * On a public agent this is honored only on a request made with the app API key; otherwise the stored value applies.
764
792
  */
765
793
  useCodeInterpreter?: 'none' | 'llm';
766
794
  /**
@@ -999,7 +1027,10 @@ export interface AiAgent<T extends AiChatModelSelection | undefined = undefined>
999
1027
  updatedAt: Date;
1000
1028
  /** An optional description of the agent's purpose or capabilities. */
1001
1029
  description?: string;
1002
- /** Indicates whether the agent is publicly accessible; defaults to false. */
1030
+ /**
1031
+ * Indicates whether the agent is publicly accessible; defaults to false. A caller of a public agent without the
1032
+ * app API key can narrow its stored knowledge bases and metadata filters per request, not widen them.
1033
+ */
1003
1034
  isPublic?: boolean;
1004
1035
  /** Enables audit logging for the agent's activities if true; defaults to false. */
1005
1036
  auditLog?: boolean;
@@ -1025,6 +1056,12 @@ export type UpsertAgentRequest = Omit<AiAgent, 'createdAt' | 'updatedAt' | 'opti
1025
1056
  * @category AI
1026
1057
  */
1027
1058
  export declare const AGENT_STATUS_TITLE_AGENT_RESPONSE = "Agent Response";
1059
+ /**
1060
+ * Status update title broadcast when the agent's model fails and the `ask` is retried on its backup model. Its audit
1061
+ * log entry carries the failed model and its usage in its tags; the backup's attempt records the job's response.
1062
+ * @category AI
1063
+ */
1064
+ export declare const AGENT_STATUS_TITLE_MODEL_FAILOVER = "Primary Model Failed";
1028
1065
  /**
1029
1066
  * Status update title broadcast when the agent invokes a knowledge-base
1030
1067
  * callable. A matching invocation produces a single event with this title.
@@ -1399,38 +1436,56 @@ export type GuardrailsOptions = {
1399
1436
  * @category AI
1400
1437
  */
1401
1438
  export type AiPiiEntityType = 'email' | 'phoneNumber' | 'creditCard' | 'ssn' | 'iban' | 'passport';
1439
+ /** Text boundaries inspected by an agent's runtime security policy. @category AI */
1440
+ export type AiSecurityScope = 'input' | 'context' | 'output' | 'toolArguments';
1441
+ /** Settings shared by independently configurable security classifiers. @category AI */
1442
+ export interface AiSecurityClassifierOptions {
1443
+ /** Model override. Omitted, the detector uses its deployment-wide platform role. */
1444
+ model?: AiChatModelSelection;
1445
+ /** Reasoning effort of the classifier; omitted, uses the model's default. */
1446
+ reasoningEffort?: AiReasoningEffort;
1447
+ /** Screening timeout in milliseconds, from 1000 to 300000. Defaults to 60000. */
1448
+ timeoutMs?: number;
1449
+ /** Additional detection rules, expressed in plain language. */
1450
+ customRules?: Array<string>;
1451
+ }
1452
+ /** Detects instruction overrides in user input and retrieved text. @category AI */
1453
+ export interface AiPromptInjectionOptions extends AiSecurityClassifierOptions {
1454
+ /** Defaults to off. Monitor warns without blocking; block refuses detected attacks. */
1455
+ onDetect: 'off' | 'monitor' | 'block';
1456
+ /** Defaults to both input and context, including tool results and conversation history. */
1457
+ scopes?: Array<'input' | 'context'>;
1458
+ }
1459
+ /** Prompt injection protection inherited by delegated agents. @category AI */
1460
+ export interface AiAgentSecurityOptions {
1461
+ /** Uses the platform's chat.promptInjection role unless a model override is supplied. */
1462
+ promptInjection?: AiPromptInjectionOptions;
1463
+ }
1402
1464
  /** Entity kinds screened when {@link AiPiiOptions.entities} is omitted. */
1403
1465
  export declare const DEFAULT_PII_ENTITY_TYPES: ReadonlyArray<AiPiiEntityType>;
1404
1466
  /** Model that screens prompts unless overridden. Small and fast: it runs on every prompt. */
1405
1467
  export declare const DEFAULT_PII_CLASSIFIER_MODEL = "gpt-6-luna";
1406
- /**
1407
- * Rejects a prompt before it reaches the agent's model when it carries PII, so the prompt is never
1408
- * sent to the model provider, never answered, and never written to chat memory.
1409
- *
1410
- * Screening is one {@link classifierModel} call per prompt, covering {@link entities} and
1411
- * {@link customRules} together. Because a model does the reading rather than a pattern, a value is
1412
- * judged by what the prompt says it is, and app-specific identifiers can be described in plain
1413
- * language instead of expressed as a format.
1414
- *
1415
- * This is the inverse of {@link GuardrailsOptions.disablePii}, which asks the agent's own model not
1416
- * to *emit* PII in its answer.
1417
- * @category AI
1418
- */
1468
+ /** Inspects selected boundaries for sensitive data. Legacy reject settings screen input only. @category AI */
1419
1469
  export type AiPiiOptions = {
1420
- /** `reject` refuses a prompt carrying PII; `off` (default) disables screening entirely. */
1421
- onDetect: 'off' | 'reject';
1470
+ /** Reject blocks detected data; monitor warns; redact replaces values. Defaults to off. */
1471
+ onDetect: 'off' | 'reject' | 'monitor' | 'redact';
1422
1472
  /** Entity kinds to screen for. Defaults to {@link DEFAULT_PII_ENTITY_TYPES}. */
1423
- entities?: Array<AiPiiEntityType>;
1473
+ entities?: Array<AiPiiEntityType | 'secret'>;
1424
1474
  /** App-specific PII in plain language, e.g. `'internal case numbers like CASE-12345'`. */
1425
1475
  customRules?: Array<string>;
1426
1476
  /**
1427
- * Model performing the screening. Defaults to {@link DEFAULT_PII_CLASSIFIER_MODEL}, or the app's best
1428
- * available model when that one is unavailable. Each attempt is bounded at a minute, so an override has
1429
- * to answer within it.
1477
+ * Classifier override. Null restores the default model. Runtime inspection uses chat.pii;
1478
+ * legacy input rejection retains its existing classifier selection.
1430
1479
  */
1431
- classifierModel?: AiChatModelSelection;
1480
+ classifierModel?: AiChatModelSelection | null;
1432
1481
  /** Literal values that never count as PII, e.g. a shared support address. */
1433
1482
  allowList?: Array<string>;
1483
+ /** Text boundaries to inspect. Defaults to input. Explicit scopes enable runtime inspection. */
1484
+ scopes?: Array<AiSecurityScope>;
1485
+ /** Effort for runtime inspection; omitted, uses the model's default. */
1486
+ reasoningEffort?: AiReasoningEffort;
1487
+ /** Runtime screening timeout, 1000 to 300000 milliseconds. Defaults to 60000. */
1488
+ timeoutMs?: number;
1434
1489
  };
1435
1490
  /**
1436
1491
  * Outcome of screening one prompt. On a detection the prompt is replaced by {@link redactedPrompt}
@@ -51,7 +51,7 @@ export declare const OPENAI_CHAT_MODEL_NAMES: readonly ["gpt-5.6-sol", "gpt-5.6-
51
51
  * Public Gemini chat model names (active models only).
52
52
  * @category AI
53
53
  */
54
- export declare const GEMINI_CHAT_MODEL_NAMES: readonly ["gemini-4-argon", "gemini-3.8-flash", "gemini-3.5-flash-lite"];
54
+ export declare const GEMINI_CHAT_MODEL_NAMES: readonly ["gemini-4-carbon", "gemini-4-argon", "gemini-4-hydrogen", "gemini-3.8-flash", "gemini-3.5-flash-lite"];
55
55
  /**
56
56
  * Public Grok chat model names (active models only).
57
57
  * @category AI
@@ -61,12 +61,12 @@ export declare const GROK_CHAT_MODEL_NAMES: readonly ["grok-4.6", "grok-4-1-fast
61
61
  * Public Anthropic chat model names (active models only).
62
62
  * @category AI
63
63
  */
64
- export declare const ANTHROPIC_CHAT_MODEL_NAMES: readonly ["claude-fable-5-1", "claude-haiku-5-5", "claude-opus-5-5", "claude-sonnet-5-5"];
64
+ export declare const ANTHROPIC_CHAT_MODEL_NAMES: readonly ["claude-fable-5-2", "claude-haiku-5-5", "claude-opus-5-5", "claude-sonnet-5-5"];
65
65
  /**
66
66
  * The supported AI model names.
67
67
  * @category AI
68
68
  */
69
- export declare const VENDOR_AI_CHAT_MODEL_NAMES: readonly ["gpt-5.6-sol", "gpt-5.6-luna", "gpt-6-astra", "gpt-6-luna", "gpt-6.1-sol", "gpt-6.1-terra", "claude-fable-5-1", "claude-haiku-5-5", "claude-opus-5-5", "claude-sonnet-5-5", "gemini-4-argon", "gemini-3.8-flash", "gemini-3.5-flash-lite", "grok-4.6", "grok-4-1-fast-reasoning", "grok-4-1-fast-non-reasoning"];
69
+ export declare const VENDOR_AI_CHAT_MODEL_NAMES: readonly ["gpt-5.6-sol", "gpt-5.6-luna", "gpt-6-astra", "gpt-6-luna", "gpt-6.1-sol", "gpt-6.1-terra", "claude-fable-5-2", "claude-haiku-5-5", "claude-opus-5-5", "claude-sonnet-5-5", "gemini-4-carbon", "gemini-4-argon", "gemini-4-hydrogen", "gemini-3.8-flash", "gemini-3.5-flash-lite", "grok-4.6", "grok-4-1-fast-reasoning", "grok-4-1-fast-non-reasoning"];
70
70
  /** Checks if the given model name is a global AI chat model name. */
71
71
  export declare function isVendorAiChatModelName(modelName: unknown): modelName is VendorAiChatModelName;
72
72
  /**
@@ -1,6 +1,6 @@
1
1
  import { AiChatModelSelection, AiReasoningEffort, ContextImageFailure, UpsertContextErrorCode, UpsertContextStatusError } from './ai-agent.public-types';
2
2
  import { AiEmbeddingsModelSelection, AiRerankProvider } from './ai-common.public-types';
3
- import { AiContextId, AiKnowledgeBaseId, AppId } from './communication.public-types';
3
+ import { AiContextId, AiKnowledgeBaseId, AppId, IntegrationId } from './communication.public-types';
4
4
  import { DocumentExtractionMethod } from './extraction.public-types';
5
5
  import { MetadataAndFilter, MetadataFieldFilter, MetadataOrFilter, MetadataSimpleFilter, MetadataValue, MetadataValueArray } from './metadata-filter.public-types';
6
6
  /**
@@ -55,13 +55,68 @@ export interface AiKnowledgeBase {
55
55
  */
56
56
  contextualIngestUsage?: KnowledgeBaseGraphUsage;
57
57
  /**
58
- * Per-caller access control over retrieval. Omitted ⇒ `'none'`: stored scopes are ignored and every
59
- * caller sees every chunk.
58
+ * Per-caller access control over retrieval. Omitted ⇒ `'none'`: stored scopes are ignored, and only
59
+ * API-key callers may call `search` or `downloadContext` on the knowledge base.
60
60
  */
61
61
  accessControl?: AiKnowledgeBaseAccessControl;
62
+ /**
63
+ * Binds the knowledge base to content that lives outside Squid. Such a knowledge base is read-only: its
64
+ * content cannot be upserted or deleted, and searches run against the source. It is set by the integration
65
+ * whose `knowledgeBaseId` names the knowledge base, never by an upsert.
66
+ */
67
+ externalSource?: AiKnowledgeBaseExternalSource;
62
68
  /** The timestamp the knowledge base was last updated */
63
69
  updatedAt: Date;
64
70
  }
71
+ /**
72
+ * How an external source restricts a read to what its caller may see.
73
+ *
74
+ * - `'none'`: the source has no document-level security.
75
+ * - `'callerScopes'`: a record is visible when it holds one of the caller's scopes, which the knowledge base's
76
+ * `accessControl.scopeResolver` resolves.
77
+ * - `'callerToken'`: the source enforces its own ACLs with the caller's token, supplied per request in
78
+ * `integrationAccessTokens` under the integration's id. Squid's own reads see only the records every caller
79
+ * may read.
80
+ *
81
+ * @category AI
82
+ */
83
+ export type AiKnowledgeBaseExternalDocumentSecurity = 'none' | 'callerScopes' | 'callerToken';
84
+ /**
85
+ * What Squid knows about an external source whatever its type. The integration's connector reports it when the
86
+ * integration is saved.
87
+ * @category AI
88
+ */
89
+ export interface AiKnowledgeBaseExternalSourceTraits {
90
+ /** A one-line name of the source for people and agents, such as `Azure AI Search index "handbook"`. */
91
+ label: string;
92
+ /** What the integration reads in the source, such as an index name. Fixed once the knowledge base is bound. */
93
+ target: string;
94
+ /** How a read is restricted to what its caller may see. */
95
+ documentSecurity: AiKnowledgeBaseExternalDocumentSecurity;
96
+ /** True when a document spans several records of the source. */
97
+ chunked: boolean;
98
+ /** True when the source embeds the text of a vector query itself. */
99
+ embedsQueries: boolean;
100
+ /** True when the source records when each record last changed, so a sync reads only what changed. */
101
+ incrementalSync: boolean;
102
+ /** The source fields the knowledge base exposes as metadata. */
103
+ metadataFields: Array<string>;
104
+ }
105
+ /**
106
+ * Where the content of an external, read-only knowledge base lives. Squid reads the source with the access the
107
+ * integration grants and never modifies it.
108
+ * @category AI
109
+ */
110
+ export interface AiKnowledgeBaseExternalSource {
111
+ /** The type of the integration that serves the source. */
112
+ type: string;
113
+ /** The integration that holds the connection to the source. */
114
+ integrationId: IntegrationId;
115
+ /** What Squid knows about the source whatever its type. */
116
+ traits: AiKnowledgeBaseExternalSourceTraits;
117
+ /** How the integration's connector reads the source. Only that connector reads them. */
118
+ settings: Record<string, unknown>;
119
+ }
65
120
  /**
66
121
  * The access-control modes a knowledge base can be in. See {@link AiKnowledgeBaseAccessControl}.
67
122
  * @category AI
@@ -90,7 +145,10 @@ export type AiKnowledgeBaseAccessControlMode = (typeof AI_KB_ACCESS_CONTROL_MODE
90
145
  * @category AI
91
146
  */
92
147
  export interface AiKnowledgeBaseAccessControl {
93
- /** `'none'` (the default) ignores stored scopes entirely; `'enforced'` intersects them per caller. */
148
+ /**
149
+ * `'none'` (the default) ignores stored scopes and admits only API-key callers to `search` and
150
+ * `downloadContext`; `'enforced'` intersects scopes per caller.
151
+ */
94
152
  mode: AiKnowledgeBaseAccessControlMode;
95
153
  /**
96
154
  * The backend function that resolves a caller into the access scopes they hold, as
@@ -1970,8 +2028,13 @@ export interface QueryKnowledgeBaseGraphResponse {
1970
2028
  tree?: KnowledgeBaseGraphQuerySubtreeNode;
1971
2029
  /** `docsUnder`: documents in the resolved node's closure (capped by `limit`). */
1972
2030
  documents?: Array<KnowledgeBaseGraphQueryDoc>;
1973
- /** `docsUnder`: the full closure size (compare with `documents.length` for truncation). */
2031
+ /**
2032
+ * `docsUnder`: the full closure size (compare with `documents.length` for truncation). Absent when the
2033
+ * knowledge base is bound to a chunked external index, which can count chunks only: see `totalChunks`.
2034
+ */
1974
2035
  totalDocs?: number;
2036
+ /** `docsUnder` on a chunked external index: the chunks under the node, of which `documents` lists the first. */
2037
+ totalChunks?: number;
1975
2038
  /** `conceptsOf`: the document's concept memberships. */
1976
2039
  concepts?: KnowledgeBaseGraphQueryConcepts;
1977
2040
  /** `neighborhood`: the entity subgraph around the resolved entity. */
@@ -2528,6 +2591,31 @@ export interface BulkIngestionSubscribeRequest {
2528
2591
  /** The id of the bulk-ingestion job to subscribe to. */
2529
2592
  jobId: string;
2530
2593
  }
2594
+ /**
2595
+ * Why bulk ingestion cannot stage contexts into a knowledge base: `BULK_INGESTION_DISABLED` when this
2596
+ * deployment cannot run bulk ingestion at all, `BULK_INGESTION_UNSUPPORTED_EMBEDDING_MODEL` when only this
2597
+ * knowledge base's embedding model rules it out.
2598
+ * @category AI
2599
+ */
2600
+ export type BulkIngestionUnavailableReason = 'BULK_INGESTION_DISABLED' | 'BULK_INGESTION_UNSUPPORTED_EMBEDDING_MODEL';
2601
+ /**
2602
+ * Request structure for checking whether bulk ingestion can stage contexts into a knowledge base.
2603
+ * @category AI
2604
+ */
2605
+ export interface BulkIngestionAvailabilityRequest {
2606
+ /** The id of the knowledge base to check. */
2607
+ knowledgeBaseId: AiKnowledgeBaseId;
2608
+ }
2609
+ /**
2610
+ * Response saying whether bulk ingestion can stage contexts into the requested knowledge base.
2611
+ * @category AI
2612
+ */
2613
+ export interface BulkIngestionAvailabilityResponse {
2614
+ /** Whether a bulk upsert into this knowledge base would be admitted. */
2615
+ available: boolean;
2616
+ /** Set when `available` is false. */
2617
+ unavailableReason?: BulkIngestionUnavailableReason;
2618
+ }
2531
2619
  /**
2532
2620
  * Request structure for minting presigned upload URLs for direct-to-storage bulk ingestion: the caller
2533
2621
  * PUTs each file's bytes straight to storage, then references it in {@link BulkIngestionContext} via
@@ -2562,3 +2650,140 @@ export interface BulkIngestionCreateUploadUrlsResponse {
2562
2650
  stagedObjectKey: string;
2563
2651
  }>;
2564
2652
  }
2653
+ /**
2654
+ * The sizes a synthetic-data run of a knowledge base comes in.
2655
+ * @category AI
2656
+ */
2657
+ export declare const AI_KNOWLEDGE_BASE_SYNTHETIC_DATA_SIZES: readonly ["S", "M", "L", "XL"];
2658
+ /**
2659
+ * How many documents a synthetic-data run writes: S 10, M 25, L 100, XL 500.
2660
+ * @category AI
2661
+ */
2662
+ export type AiKnowledgeBaseSyntheticDataSize = (typeof AI_KNOWLEDGE_BASE_SYNTHETIC_DATA_SIZES)[number];
2663
+ /**
2664
+ * What a synthetic-data run of a knowledge base writes.
2665
+ * @category AI
2666
+ */
2667
+ export interface AiKnowledgeBaseSyntheticDataOptions {
2668
+ /** What the documents should be about and look like. */
2669
+ prompt?: string;
2670
+ /** How many documents to write. */
2671
+ size: AiKnowledgeBaseSyntheticDataSize;
2672
+ }
2673
+ /**
2674
+ * The state of a synthetic-data run of a knowledge base.
2675
+ * @category AI
2676
+ */
2677
+ export type AiKnowledgeBaseSyntheticDataStatus = 'running' | 'completed' | 'cancelled' | 'failed';
2678
+ /**
2679
+ * The step a synthetic-data run of a knowledge base is at: reading the knowledge base and planning,
2680
+ * writing documents, or done.
2681
+ * @category AI
2682
+ */
2683
+ export type AiKnowledgeBaseSyntheticDataPhase = 'planning' | 'writing' | 'done';
2684
+ /**
2685
+ * A synthetic-data run of a knowledge base, which adds fictional documents to it in a dev environment.
2686
+ * @category AI
2687
+ */
2688
+ export interface AiKnowledgeBaseSyntheticDataRun {
2689
+ /** The knowledge base the run writes to. */
2690
+ knowledgeBaseId: AiKnowledgeBaseId;
2691
+ /** The id of the background job of the run. */
2692
+ jobId: string;
2693
+ /** The state of the run. */
2694
+ status: AiKnowledgeBaseSyntheticDataStatus;
2695
+ /** The step the run is at. */
2696
+ phase: AiKnowledgeBaseSyntheticDataPhase;
2697
+ /** What the run was asked to write. */
2698
+ options: AiKnowledgeBaseSyntheticDataOptions;
2699
+ /** The documents the run planned to write. */
2700
+ plannedDocuments: number;
2701
+ /** The ids of the documents the run added to the knowledge base. */
2702
+ contextIds: Array<AiContextId>;
2703
+ /** The documents written and left out, by the run's own checks or by the knowledge base. */
2704
+ rejectedDocuments: number;
2705
+ /** Why the latest of the rejected documents was left out. */
2706
+ lastRejection?: string;
2707
+ /** When the run started, in epoch milliseconds. */
2708
+ startedAt: number;
2709
+ /** When the run ended, in epoch milliseconds. */
2710
+ endedAt?: number;
2711
+ /** Why the run failed. */
2712
+ error?: string;
2713
+ }
2714
+ /**
2715
+ * The tiers of the semantic layer over an external source: 1 is the index catalog and facet concepts, 2 the
2716
+ * entity graph.
2717
+ * @category AI
2718
+ */
2719
+ export type KnowledgeBaseExternalSourceTier = 1 | 2;
2720
+ /**
2721
+ * One thing a tier of the semantic layer needs from an external source.
2722
+ * @category AI
2723
+ */
2724
+ export interface KnowledgeBaseExternalSourcePrerequisite {
2725
+ /** A stable identifier of the prerequisite, which the source's connector names. */
2726
+ id: string;
2727
+ /** The lowest tier that needs it. */
2728
+ tier: KnowledgeBaseExternalSourceTier;
2729
+ /** Whether the source provides it: `'unknown'` when the integration may not read what answers that. */
2730
+ status: 'met' | 'unmet' | 'unknown';
2731
+ /** True when the tier cannot run without it; false when the tier runs degraded. */
2732
+ required: boolean;
2733
+ /** What was found, and what it means for the tier. */
2734
+ message: string;
2735
+ }
2736
+ /**
2737
+ * Request structure for reading the state of an external knowledge base's semantic layer.
2738
+ * @category AI
2739
+ */
2740
+ export interface GetKnowledgeBaseExternalSourceStatusRequest {
2741
+ /** The id of the AiKnowledgeBase. */
2742
+ knowledgeBaseId: AiKnowledgeBaseId;
2743
+ }
2744
+ /**
2745
+ * Response structure for the state of an external knowledge base's semantic layer.
2746
+ * @category AI
2747
+ */
2748
+ export interface GetKnowledgeBaseExternalSourceStatusResponse {
2749
+ /** What each tier needs from the index, and whether it provides it, as the integration's latest save found. */
2750
+ prerequisites: Array<KnowledgeBaseExternalSourcePrerequisite>;
2751
+ /** The description of the index and its mapped fields that agents see. */
2752
+ indexCard?: string;
2753
+ /** When the index card and the facet concepts were last rebuilt, in epoch milliseconds. */
2754
+ catalogRefreshedAt?: number;
2755
+ /** Why the latest catalog refresh failed. */
2756
+ catalogError?: string;
2757
+ /** The state of the sync that keeps the entity graph in step with the index; absent without an entity graph. */
2758
+ sync?: KnowledgeBaseExternalSourceSyncStatus;
2759
+ }
2760
+ /**
2761
+ * The state of the sync between an external index and the entity graph built over it.
2762
+ * @category AI
2763
+ */
2764
+ export interface KnowledgeBaseExternalSourceSyncStatus {
2765
+ /** Documents the ledger tracks. */
2766
+ documents: number;
2767
+ /** When the latest scan of the index completed, in epoch milliseconds. */
2768
+ lastScanCompletedAt?: number;
2769
+ /** When a scan is running: when it started, in epoch milliseconds. */
2770
+ scanStartedAt?: number;
2771
+ /** When the next scan is due, in epoch milliseconds. */
2772
+ nextScanAt?: number;
2773
+ /** Documents the latest completed scan found added or changed. */
2774
+ lastScanUpserted?: number;
2775
+ /** Documents the latest completed scan pruned. */
2776
+ lastScanDeleted?: number;
2777
+ /** Whether scans read only changed records (the index has a timestamp field) or compare every record. */
2778
+ incremental: boolean;
2779
+ /** Why the latest scan failed. */
2780
+ error?: string;
2781
+ }
2782
+ /**
2783
+ * Request structure for refreshing an external knowledge base's semantic layer now.
2784
+ * @category AI
2785
+ */
2786
+ export interface RefreshKnowledgeBaseExternalSourceRequest {
2787
+ /** The id of the AiKnowledgeBase. */
2788
+ knowledgeBaseId: AiKnowledgeBaseId;
2789
+ }