@squidcloud/freshdesk-client 1.0.511 → 1.0.513

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,1034 @@
1
+ import { AiKnowledgeBaseId, IntegrationId } from './communication.public-types';
2
+ /**
3
+ * Id of an ontology.
4
+ * @category AI
5
+ */
6
+ export type AiOntologyId = string;
7
+ /**
8
+ * Review state of an ontology relationship. Only accepted relationships reach models. Imports and generation save
9
+ * `accepted` rows; a row without `reviewedAt` and with a source other than `human` is unreviewed.
10
+ * @category AI
11
+ */
12
+ export type AiOntologyRelationshipStatus = 'suggested' | 'accepted' | 'rejected';
13
+ /**
14
+ * Where an ontology relationship came from. `declared` covers declared and manual schema associations.
15
+ * @category AI
16
+ */
17
+ export type AiOntologyRelationshipSource = 'declared' | 'inferred' | 'ai' | 'human';
18
+ /**
19
+ * How many rows one side of a relationship can match.
20
+ * @category AI
21
+ */
22
+ export type AiOntologyCardinality = 'ONE' | 'MANY';
23
+ /**
24
+ * One side of an ontology relationship.
25
+ * @category AI
26
+ */
27
+ export interface AiOntologyRelationshipEnd {
28
+ /** The integration that holds the table. */
29
+ integrationId: IntegrationId;
30
+ /** The table or collection name. */
31
+ table: string;
32
+ /** The columns or fields the side joins on, aligned by position with the other side's. */
33
+ columns: string[];
34
+ /** How many rows of this side match one row of the other side. */
35
+ cardinality: AiOntologyCardinality;
36
+ /** The navigation property of this side, used by semantic-layer integrations. */
37
+ propertyName?: string;
38
+ }
39
+ /**
40
+ * Limits a relationship to rows where a column holds one value.
41
+ * @category AI
42
+ */
43
+ export interface AiOntologyRelationshipCondition {
44
+ /** The column that is tested. */
45
+ field: string;
46
+ /** The value the column holds. */
47
+ value: string | number | boolean;
48
+ }
49
+ /**
50
+ * Two columns, one on each side of a relationship.
51
+ * @category AI
52
+ */
53
+ export interface AiOntologyColumnPair {
54
+ /** A column of the referencing side's table. */
55
+ fromColumn: string;
56
+ /** A column of the referenced side's table. */
57
+ toColumn: string;
58
+ }
59
+ /**
60
+ * The outcome of the last run that generated relationships, business entities or properties, or refreshed the
61
+ * knowledge bases.
62
+ * @category AI
63
+ */
64
+ export interface AiOntologyGenerationRun {
65
+ /** Whether the run is still going, finished or failed. */
66
+ status: 'running' | 'completed' | 'failed';
67
+ /** Start time in epoch milliseconds. */
68
+ startedAt: number;
69
+ /** End time in epoch milliseconds. */
70
+ endedAt?: number;
71
+ /** How many relationships the run added. A run only adds: it never removes a stored row. */
72
+ relationshipsAdded: number;
73
+ /**
74
+ * How many unreviewed imported relationships labelled with their association name the run gave a business label. It
75
+ * changes nothing else of a stored row.
76
+ */
77
+ relationshipsRenamed?: number;
78
+ /** How many business entities the run added. */
79
+ entitiesAdded: number;
80
+ /** How many properties the run added. */
81
+ propertiesAdded: number;
82
+ /** Things the run left out. */
83
+ warnings: string[];
84
+ /** The failure, when the run failed. */
85
+ error?: string;
86
+ }
87
+ /**
88
+ * A named ontology: databases, the relationships between their tables and the business entities those tables hold.
89
+ * @category AI
90
+ */
91
+ export interface AiOntology {
92
+ /** Unique id of the ontology. */
93
+ id: AiOntologyId;
94
+ /** Name of the ontology. */
95
+ name: string;
96
+ /** What the ontology describes. */
97
+ description: string;
98
+ /** The databases attached to the ontology. */
99
+ integrationIds: IntegrationId[];
100
+ /** The knowledge bases attached to the ontology, each with a knowledge graph. */
101
+ knowledgeBaseIds: AiKnowledgeBaseId[];
102
+ /** The last run that generated relationships, business entities or properties. */
103
+ lastGenerationRun?: AiOntologyGenerationRun;
104
+ /** Number of accepted relationships. Set only on the ontologies of a list. */
105
+ acceptedRelationshipCount?: number;
106
+ /** Number of accepted business entities. Set only on the ontologies of a list. */
107
+ acceptedEntityCount?: number;
108
+ /** Creation time in epoch milliseconds. */
109
+ createdAt: number;
110
+ /** Last update time in epoch milliseconds. */
111
+ updatedAt: number;
112
+ }
113
+ /**
114
+ * A relationship between two tables of an ontology.
115
+ * @category AI
116
+ */
117
+ export interface AiOntologyRelationship {
118
+ /** Unique id of the relationship. */
119
+ id: string;
120
+ /** The ontology the relationship belongs to. */
121
+ ontologyId: AiOntologyId;
122
+ /** Identifies the link; a link written in either direction has one signature. */
123
+ signature: string;
124
+ /** The referencing side. */
125
+ from: AiOntologyRelationshipEnd;
126
+ /** The referenced side. */
127
+ to: AiOntologyRelationshipEnd;
128
+ /** Short verb phrase, such as "placed by". */
129
+ label: string;
130
+ /** What the relationship means. */
131
+ description?: string;
132
+ /** Review state. A row without `reviewedAt` and with a source other than `human` is unreviewed. */
133
+ status: AiOntologyRelationshipStatus;
134
+ /** Where the relationship came from. */
135
+ source: AiOntologyRelationshipSource;
136
+ /** From 0 to 1, when inference or a model proposed the relationship. */
137
+ confidence?: number;
138
+ /** Why the relationship was proposed. */
139
+ reasoning?: string;
140
+ /** Limits the relationship to rows where a column holds one value. */
141
+ condition?: AiOntologyRelationshipCondition;
142
+ /** How a query in the database's own language traverses the relationship. */
143
+ queryHint?: string;
144
+ /** The name of the schema association the relationship was imported from. */
145
+ associationName?: string;
146
+ /** The business entity a caller chose for the referencing side, as stored; it may since have become invalid. */
147
+ fromEntityId?: string;
148
+ /** The business entity a caller chose for the referenced side, as stored; it may since have become invalid. */
149
+ toEntityId?: string;
150
+ /**
151
+ * Output only: the entity of the referencing side on this read. The stored choice when it is still eligible, else
152
+ * none; with no choice stored, the only eligible entity that has the table as a member, else the only one that has it
153
+ * as a supporting table. An eligible entity is in the ontology, not rejected, and has the side's table as a member or
154
+ * a supporting table.
155
+ */
156
+ resolvedFromEntityId?: string;
157
+ /** Output only: the entity of the referenced side on this read, resolved as `resolvedFromEntityId` is. */
158
+ resolvedToEntityId?: string;
159
+ /** Column pairs whose values should agree once the join columns match; a record that differs is a possible match. */
160
+ confirmationColumns?: AiOntologyColumnPair[];
161
+ /** Creation time in epoch milliseconds. */
162
+ createdAt: number;
163
+ /** Last update time in epoch milliseconds. */
164
+ updatedAt: number;
165
+ /** Who accepted or rejected the relationship. The caller's claim, not an authenticated identity. */
166
+ reviewedBy?: string;
167
+ /** When the relationship was reviewed, in epoch milliseconds. */
168
+ reviewedAt?: number;
169
+ }
170
+ /**
171
+ * The editable fields of an ontology relationship.
172
+ * @category AI
173
+ */
174
+ export interface AiOntologyRelationshipInput {
175
+ /** The referencing side. Cardinality defaults to `MANY` in the service. */
176
+ from: AiOntologyRelationshipEnd;
177
+ /** The referenced side. Cardinality defaults to `ONE` in the service. */
178
+ to: AiOntologyRelationshipEnd;
179
+ /** Short verb phrase, such as "placed by". */
180
+ label: string;
181
+ /** What the relationship means. */
182
+ description?: string;
183
+ /**
184
+ * The entity of the referencing side: one of the ontology, not rejected, with the side's table as a member or a
185
+ * supporting table. On update an omitted value, or the stored one sent back, is kept without being checked again;
186
+ * `null` clears it. When the update moves the side to another table, a value sent is checked, and an omitted one
187
+ * the new table makes invalid is removed.
188
+ */
189
+ fromEntityId?: string | null;
190
+ /** The entity of the referenced side, set as `fromEntityId` is. */
191
+ toEntityId?: string | null;
192
+ /**
193
+ * Columns, at most `maxConfirmationColumnPairs` pairs, whose values should agree once the join columns match. Each
194
+ * column must exist in its side's table. On update an omitted value, or the stored pairs sent back while both sides
195
+ * stay, is kept without being checked again; `[]` clears them.
196
+ */
197
+ confirmationColumns?: AiOntologyColumnPair[];
198
+ }
199
+ /**
200
+ * Response that carries the ontologies of the application.
201
+ * @category AI
202
+ */
203
+ export interface ListAiOntologiesResponse {
204
+ /** The ontologies. */
205
+ ontologies: AiOntology[];
206
+ }
207
+ /**
208
+ * Request to get one ontology.
209
+ * @category AI
210
+ */
211
+ export interface GetAiOntologyRequest {
212
+ /** Id of the ontology. */
213
+ id: AiOntologyId;
214
+ }
215
+ /**
216
+ * Response to {@link GetAiOntologyRequest}.
217
+ * @category AI
218
+ */
219
+ export interface GetAiOntologyResponse {
220
+ /** The ontology, or undefined when it does not exist. */
221
+ ontology?: AiOntology;
222
+ }
223
+ /**
224
+ * Response that carries one ontology.
225
+ * @category AI
226
+ */
227
+ export interface AiOntologyResponse {
228
+ /** The ontology. */
229
+ ontology: AiOntology;
230
+ /** Things the request left out, such as imported relationships past the relationship limit. */
231
+ warnings: string[];
232
+ }
233
+ /**
234
+ * Request to create an ontology.
235
+ * @category AI
236
+ */
237
+ export interface CreateAiOntologyRequest {
238
+ /** Name of the ontology. */
239
+ name: string;
240
+ /** What the ontology describes. */
241
+ description?: string;
242
+ /** The databases to attach. */
243
+ integrationIds?: IntegrationId[];
244
+ /**
245
+ * The knowledge bases to attach, at most `maxKnowledgeBasesPerOntology`. Each must have a knowledge graph whose topics
246
+ * every caller may read (`ONTOLOGY_KNOWLEDGE_BASE_HAS_NO_GRAPH`: no graph, or document-level security on an external
247
+ * source) and no enforced access control (`ONTOLOGY_KNOWLEDGE_BASE_ACCESS_RESTRICTED`).
248
+ */
249
+ knowledgeBaseIds?: AiKnowledgeBaseId[];
250
+ }
251
+ /**
252
+ * Request to update an ontology. It replaces the name, the description, the attached databases and, when given, the
253
+ * attached knowledge bases.
254
+ * @category AI
255
+ */
256
+ export interface UpdateAiOntologyRequest {
257
+ /** Id of the ontology. */
258
+ id: AiOntologyId;
259
+ /** Name of the ontology. */
260
+ name: string;
261
+ /** What the ontology describes. */
262
+ description: string;
263
+ /** The databases to attach. */
264
+ integrationIds: IntegrationId[];
265
+ /**
266
+ * The knowledge bases to attach, as in {@link CreateAiOntologyRequest}. Omitted keeps the attached ones. A detached
267
+ * knowledge base loses what the ontology stored about it.
268
+ */
269
+ knowledgeBaseIds?: AiKnowledgeBaseId[];
270
+ }
271
+ /**
272
+ * Request to delete an ontology with its relationships, entities and properties.
273
+ * @category AI
274
+ */
275
+ export interface DeleteAiOntologyRequest {
276
+ /** Id of the ontology. */
277
+ id: AiOntologyId;
278
+ }
279
+ /**
280
+ * Request to list the relationships of an ontology.
281
+ * @category AI
282
+ */
283
+ export interface ListAiOntologyRelationshipsRequest {
284
+ /** Id of the ontology. */
285
+ ontologyId: AiOntologyId;
286
+ /** Returns only relationships in this state. */
287
+ status?: AiOntologyRelationshipStatus;
288
+ }
289
+ /**
290
+ * Response to {@link ListAiOntologyRelationshipsRequest}.
291
+ * @category AI
292
+ */
293
+ export interface ListAiOntologyRelationshipsResponse {
294
+ /** The matching relationships. */
295
+ relationships: AiOntologyRelationship[];
296
+ }
297
+ /**
298
+ * Whether a linked row agrees with its starting record on the relationship's confirmation columns. Dates and
299
+ * timestamps agree when they fall on the same calendar day; the time of day is ignored.
300
+ * @category AI
301
+ */
302
+ export type AiOntologyFollowMatch = 'confirmed' | 'mismatch' | 'unverifiable' | 'unchecked';
303
+ /**
304
+ * A comparison a followed relationship applies to the linked rows.
305
+ * @category AI
306
+ */
307
+ export type AiOntologyFollowFilterOperator = 'eq' | 'in' | 'gt' | 'gte' | 'lt' | 'lte';
308
+ /**
309
+ * Keeps only the linked rows whose column satisfies the comparison. A date or timestamp compares by calendar day,
310
+ * ignoring the time of day.
311
+ * @category AI
312
+ */
313
+ export interface AiOntologyFollowFilter {
314
+ /** The linked column that is tested. */
315
+ column: string;
316
+ /** How the column is compared with the value. */
317
+ operator: AiOntologyFollowFilterOperator;
318
+ /** The value to compare with; an array for `in`. */
319
+ value: unknown;
320
+ }
321
+ /**
322
+ * Two columns, one in the starting table and one in the linked table.
323
+ * @category AI
324
+ */
325
+ export interface AiOntologyFollowColumnPair {
326
+ /** A column of the starting table. */
327
+ startColumn: string;
328
+ /** A column of the linked table. */
329
+ linkedColumn: string;
330
+ }
331
+ /**
332
+ * A confirmation pair whose two values differ.
333
+ * @category AI
334
+ */
335
+ export interface AiOntologyFollowMismatch extends AiOntologyFollowColumnPair {
336
+ /** The value in the starting record. */
337
+ startValue: unknown;
338
+ /** The value in the linked row. */
339
+ linkedValue: unknown;
340
+ }
341
+ /**
342
+ * One linked row of a followed relationship.
343
+ * @category AI
344
+ */
345
+ export interface AiOntologyFollowRow {
346
+ /** Whether the row agrees with its starting record on the confirmation columns. */
347
+ match: AiOntologyFollowMatch;
348
+ /** The returned columns of the linked row. */
349
+ values: Record<string, unknown>;
350
+ /** The confirmation pairs that differ; set only when `match` is `mismatch`. */
351
+ mismatches?: AiOntologyFollowMismatch[];
352
+ }
353
+ /**
354
+ * The row count and column sums of the linked rows with one match.
355
+ * @category AI
356
+ */
357
+ export interface AiOntologyFollowTotals {
358
+ /** The number of linked rows. */
359
+ count: number;
360
+ /** The sum of each requested column. */
361
+ sums: Record<string, number>;
362
+ }
363
+ /**
364
+ * Request to follow a relationship from rows of one of its tables to the rows on the other side.
365
+ * @category AI
366
+ */
367
+ export interface FollowAiOntologyRelationshipRequest {
368
+ /** The ontology the relationship belongs to. */
369
+ ontologyId: AiOntologyId;
370
+ /** The id or the label of the relationship. */
371
+ relationship: string;
372
+ /** The table to start from, as `<integrationId>.<table>`. */
373
+ startTable: string;
374
+ /** The column of the starting table that holds the values. */
375
+ startColumn: string;
376
+ /** The values that pick the starting records. */
377
+ startValues: Array<string | number | boolean>;
378
+ /** The side of the relationship the starting table is; required when both sides are one table. */
379
+ startSide?: 'from' | 'to';
380
+ /** The linked columns to return; all visible ones when omitted. */
381
+ columns?: string[];
382
+ /** Keeps only the linked rows that satisfy every filter. */
383
+ filters?: AiOntologyFollowFilter[];
384
+ /** The linked columns to sum per match. */
385
+ sum?: string[];
386
+ }
387
+ /**
388
+ * Response to {@link FollowAiOntologyRelationshipRequest}.
389
+ * @category AI
390
+ */
391
+ export interface FollowAiOntologyRelationshipResponse {
392
+ /** The id of the followed relationship. */
393
+ relationshipId: string;
394
+ /** The label of the followed relationship. */
395
+ label: string;
396
+ /** The table the records started from, as `<integrationId>.<table>`. */
397
+ startTable: string;
398
+ /** The table the rows were read from, as `<integrationId>.<table>`. */
399
+ linkedTable: string;
400
+ /** The columns the two tables were joined on. */
401
+ matchedOn: AiOntologyFollowColumnPair[];
402
+ /** The confirmation pairs that were read. */
403
+ confirmedOn: AiOntologyFollowColumnPair[];
404
+ /** The number of confirmation pairs that were not read because a column is hidden. */
405
+ hiddenConfirmationPairs: number;
406
+ /** The condition of the relationship, if it has one. */
407
+ condition?: AiOntologyRelationshipCondition;
408
+ /** The number of starting records found. */
409
+ startingRecords: number;
410
+ /** Row counts and sums per match, over every linked row that passed the filters, not only the returned ones. */
411
+ totalsByMatch: Partial<Record<AiOntologyFollowMatch, AiOntologyFollowTotals>>;
412
+ /** Whether the totals cover only confirmed rows or every row read. */
413
+ totalsCover: 'confirmed' | 'unchecked';
414
+ /** The linked rows, up to the returned-rows limit. */
415
+ rows: AiOntologyFollowRow[];
416
+ /** True when more linked rows matched than `rows` holds. A read over a cap fails, it does not truncate. */
417
+ truncated: boolean;
418
+ /** A short note for the reader on how to interpret the result. */
419
+ note: string;
420
+ }
421
+ /**
422
+ * Request to create an accepted relationship by hand.
423
+ * @category AI
424
+ */
425
+ export interface CreateAiOntologyRelationshipRequest extends AiOntologyRelationshipInput {
426
+ /** Id of the ontology. */
427
+ ontologyId: AiOntologyId;
428
+ /** The caller's claim of who they are, not an authenticated identity. */
429
+ actor?: string;
430
+ }
431
+ /**
432
+ * Request to update a relationship. It replaces the sides, label and description; an omitted `fromEntityId`,
433
+ * `toEntityId` or `confirmationColumns`, or one sent back as stored, keeps its stored value, except an entity id whose
434
+ * side moves to another table: see `fromEntityId`.
435
+ * @category AI
436
+ */
437
+ export interface UpdateAiOntologyRelationshipRequest extends AiOntologyRelationshipInput {
438
+ /** Id of the relationship. */
439
+ id: string;
440
+ }
441
+ /**
442
+ * Response that carries one relationship.
443
+ * @category AI
444
+ */
445
+ export interface AiOntologyRelationshipResponse {
446
+ /** The relationship. */
447
+ relationship: AiOntologyRelationship;
448
+ }
449
+ /**
450
+ * Request to delete a relationship.
451
+ * @category AI
452
+ */
453
+ export interface DeleteAiOntologyRelationshipRequest {
454
+ /** Id of the relationship. */
455
+ id: string;
456
+ }
457
+ /**
458
+ * Request to accept, reject or reset a relationship.
459
+ * @category AI
460
+ */
461
+ export interface ReviewAiOntologyRelationshipRequest {
462
+ /** Id of the relationship. */
463
+ id: string;
464
+ /**
465
+ * The decision. `reset` returns the relationship to suggested and clears `reviewedAt`, so the next import may refresh
466
+ * or delete an imported row.
467
+ */
468
+ decision: 'accept' | 'reject' | 'reset';
469
+ /** The caller's claim of who they are, not an authenticated identity. */
470
+ actor?: string;
471
+ }
472
+ /**
473
+ * Where a business entity came from.
474
+ * @category AI
475
+ */
476
+ export type AiOntologyEntitySource = 'ai' | 'human';
477
+ /**
478
+ * A table that holds the master records of a business entity, one row per real-world thing.
479
+ * @category AI
480
+ */
481
+ export interface AiOntologyEntityMember {
482
+ /** The integration that holds the table. */
483
+ integrationId: IntegrationId;
484
+ /** The table or collection name. */
485
+ table: string;
486
+ /** The columns that identify the thing; members of one entity are matched on them. */
487
+ keyColumns: string[];
488
+ }
489
+ /**
490
+ * What a supporting table holds about its entity: `detail` is child rows such as order lines, `link` maps the entity
491
+ * to another one, `measurement` is metrics over time, `lookup` is a small code or status table.
492
+ * @category AI
493
+ */
494
+ export declare const AI_ONTOLOGY_SUPPORTING_TABLE_KINDS: readonly ["detail", "link", "measurement", "lookup"];
495
+ /**
496
+ * The kind of a supporting table.
497
+ * @category AI
498
+ */
499
+ export type AiOntologySupportingTableKind = (typeof AI_ONTOLOGY_SUPPORTING_TABLE_KINDS)[number];
500
+ /**
501
+ * A table that holds more rows about a business entity, such as the lines of an order.
502
+ * @category AI
503
+ */
504
+ export interface AiOntologySupportingTable {
505
+ /** The integration that holds the table. */
506
+ integrationId: IntegrationId;
507
+ /** The table or collection name. */
508
+ table: string;
509
+ /** What the table holds about the entity. */
510
+ kind: AiOntologySupportingTableKind;
511
+ }
512
+ /**
513
+ * A business concept, such as Customer, with the tables that hold its master records.
514
+ * @category AI
515
+ */
516
+ export interface AiOntologyEntity {
517
+ /** Unique id of the entity. */
518
+ id: string;
519
+ /** The ontology the entity belongs to. */
520
+ ontologyId: AiOntologyId;
521
+ /** Name of the entity, unique in the ontology regardless of letter case. */
522
+ name: string;
523
+ /** What the entity means to the business. */
524
+ description: string;
525
+ /** The tables that hold the entity, most authoritative first. */
526
+ members: AiOntologyEntityMember[];
527
+ /**
528
+ * The tables around the members that hold more rows about the entity. A table hidden from agents may be listed; an
529
+ * agent that cannot read one of the tables sees the entity without its description.
530
+ */
531
+ supportingTables?: AiOntologySupportingTable[];
532
+ /** Review state. A row without `reviewedAt` and with a source other than `human` is unreviewed. */
533
+ status: AiOntologyRelationshipStatus;
534
+ /** Where the entity came from. */
535
+ source: AiOntologyEntitySource;
536
+ /** Why the entity was proposed. */
537
+ reasoning?: string;
538
+ /** Creation time in epoch milliseconds. */
539
+ createdAt: number;
540
+ /** Last update time in epoch milliseconds. */
541
+ updatedAt: number;
542
+ /** Who accepted or rejected the entity. The caller's claim, not an authenticated identity. */
543
+ reviewedBy?: string;
544
+ /** When the entity was reviewed, in epoch milliseconds. */
545
+ reviewedAt?: number;
546
+ }
547
+ /**
548
+ * The editable fields of a business entity.
549
+ * @category AI
550
+ */
551
+ export interface AiOntologyEntityInput {
552
+ /** Name of the entity. */
553
+ name: string;
554
+ /** What the entity means to the business. */
555
+ description: string;
556
+ /** The tables that hold the entity, most authoritative first. */
557
+ members: AiOntologyEntityMember[];
558
+ /** The supporting tables. When omitted on update the stored list is kept; an empty list clears it. */
559
+ supportingTables?: AiOntologySupportingTable[];
560
+ }
561
+ /**
562
+ * Request to list the business entities of an ontology.
563
+ * @category AI
564
+ */
565
+ export interface ListAiOntologyEntitiesRequest {
566
+ /** Id of the ontology. */
567
+ ontologyId: AiOntologyId;
568
+ /** Returns only entities in this state. */
569
+ status?: AiOntologyRelationshipStatus;
570
+ }
571
+ /**
572
+ * Response to {@link ListAiOntologyEntitiesRequest}.
573
+ * @category AI
574
+ */
575
+ export interface ListAiOntologyEntitiesResponse {
576
+ /** The matching entities. */
577
+ entities: AiOntologyEntity[];
578
+ }
579
+ /**
580
+ * Request to create an accepted business entity by hand.
581
+ * @category AI
582
+ */
583
+ export interface CreateAiOntologyEntityRequest extends AiOntologyEntityInput {
584
+ /** Id of the ontology. */
585
+ ontologyId: AiOntologyId;
586
+ /** The caller's claim of who they are, not an authenticated identity. */
587
+ actor?: string;
588
+ }
589
+ /**
590
+ * Request to update a business entity. It replaces the name, the description and the members.
591
+ * @category AI
592
+ */
593
+ export interface UpdateAiOntologyEntityRequest extends AiOntologyEntityInput {
594
+ /** Id of the entity. */
595
+ id: string;
596
+ }
597
+ /**
598
+ * Response that carries one business entity.
599
+ * @category AI
600
+ */
601
+ export interface AiOntologyEntityResponse {
602
+ /** The entity. */
603
+ entity: AiOntologyEntity;
604
+ }
605
+ /**
606
+ * Request to delete a business entity with its properties.
607
+ * @category AI
608
+ */
609
+ export interface DeleteAiOntologyEntityRequest {
610
+ /** Id of the entity. */
611
+ id: string;
612
+ }
613
+ /**
614
+ * Request to accept, reject or reset a business entity.
615
+ * @category AI
616
+ */
617
+ export interface ReviewAiOntologyEntityRequest {
618
+ /** Id of the entity. */
619
+ id: string;
620
+ /** The decision. `reset` returns the entity to suggested and clears `reviewedAt`. */
621
+ decision: ReviewAiOntologyRelationshipRequest['decision'];
622
+ /** The caller's claim of who they are, not an authenticated identity. */
623
+ actor?: string;
624
+ }
625
+ /**
626
+ * The value type of an entity property.
627
+ * @category AI
628
+ */
629
+ export type AiOntologyPropertyType = 'string' | 'number' | 'date' | 'boolean' | 'id';
630
+ /**
631
+ * What an entity property's values reveal: `pii` identifies a person, `phi` is health information and `confidential`
632
+ * is sensitive to the business. Advisory: Squid stores and shows it and enforces nothing on it.
633
+ * @category AI
634
+ */
635
+ export type AiOntologyPropertySensitivity = 'pii' | 'phi' | 'confidential';
636
+ /**
637
+ * The column that holds an entity property in one member or supporting table of its entity. A source on a supporting
638
+ * table is the property's only source (`ONTOLOGY_PROPERTY_SUPPORTING_SOURCE_ALONE`).
639
+ * @category AI
640
+ */
641
+ export interface AiOntologyPropertySource {
642
+ /** The integration that holds the table. */
643
+ integrationId: IntegrationId;
644
+ /** A member or supporting table of the entity. */
645
+ table: string;
646
+ /** The column that holds the property. */
647
+ column: string;
648
+ }
649
+ /**
650
+ * A named, typed business field of an entity, such as `date_of_birth`, with the column that holds it in each member
651
+ * table that has it.
652
+ * @category AI
653
+ */
654
+ export interface AiOntologyProperty {
655
+ /** Unique id of the property. */
656
+ id: string;
657
+ /** The ontology the property belongs to. */
658
+ ontologyId: AiOntologyId;
659
+ /** The entity the property belongs to. */
660
+ entityId: string;
661
+ /** Name of the property in snake_case, unique in its entity. */
662
+ name: string;
663
+ /** What the property means to the business; may be empty. */
664
+ description: string;
665
+ /** The value type. */
666
+ type: AiOntologyPropertyType;
667
+ /**
668
+ * The columns that hold the property, at most one per member or supporting table. A source on a supporting table is
669
+ * the only source (`ONTOLOGY_PROPERTY_SUPPORTING_SOURCE_ALONE`).
670
+ */
671
+ sources: AiOntologyPropertySource[];
672
+ /** More columns a generation run found for a reviewed or edited property; unused until an update moves them. */
673
+ suggestedSources?: AiOntologyPropertySource[];
674
+ /** What the values reveal; absent means unclassified, not safe. */
675
+ sensitivity?: AiOntologyPropertySensitivity;
676
+ /** `false` keeps the property from agents and AI queries; absent means visible. */
677
+ agentVisible?: boolean;
678
+ /** Review state. A row without `reviewedAt` and with a source other than `human` is unreviewed. */
679
+ status: AiOntologyRelationshipStatus;
680
+ /** Where the property came from. */
681
+ source: 'ai' | 'human';
682
+ /** Why the property was proposed. */
683
+ reasoning?: string;
684
+ /** Creation time in epoch milliseconds. */
685
+ createdAt: number;
686
+ /** Last update time in epoch milliseconds. */
687
+ updatedAt: number;
688
+ /** Who accepted or rejected the property. The caller's claim, not an authenticated identity. */
689
+ reviewedBy?: string;
690
+ /** When the property was reviewed, in epoch milliseconds. */
691
+ reviewedAt?: number;
692
+ }
693
+ /**
694
+ * Request to list the properties of an ontology.
695
+ * @category AI
696
+ */
697
+ export interface ListAiOntologyPropertiesRequest {
698
+ /** Id of the ontology. */
699
+ ontologyId: AiOntologyId;
700
+ /** Returns only the properties of this entity. */
701
+ entityId?: string;
702
+ /** Returns only properties in this state. */
703
+ status?: AiOntologyRelationshipStatus;
704
+ }
705
+ /**
706
+ * Response to {@link ListAiOntologyPropertiesRequest}.
707
+ * @category AI
708
+ */
709
+ export interface ListAiOntologyPropertiesResponse {
710
+ /** The matching properties. */
711
+ properties: AiOntologyProperty[];
712
+ }
713
+ /**
714
+ * Request to create a property of a business entity.
715
+ * @category AI
716
+ */
717
+ export interface CreateAiOntologyPropertyRequest {
718
+ /** Id of the entity. */
719
+ entityId: string;
720
+ /** Name of the property in snake_case. */
721
+ name: string;
722
+ /** What the property means to the business. */
723
+ description?: string;
724
+ /** The value type. */
725
+ type: AiOntologyPropertyType;
726
+ /**
727
+ * The columns that hold the property, at most one per member or supporting table. A source on a supporting table is
728
+ * the only source (`ONTOLOGY_PROPERTY_SUPPORTING_SOURCE_ALONE`).
729
+ */
730
+ sources: AiOntologyPropertySource[];
731
+ /** What the values reveal. */
732
+ sensitivity?: AiOntologyPropertySensitivity;
733
+ /** `false` keeps the property from agents and AI queries. */
734
+ agentVisible?: boolean;
735
+ /** Review state. Defaults to `accepted`. An accepted or rejected property is stored as reviewed. */
736
+ status?: AiOntologyRelationshipStatus;
737
+ /** Where the property came from. Defaults to `human`. */
738
+ source?: 'ai' | 'human';
739
+ }
740
+ /**
741
+ * Request to update a property. It replaces the name, description, type and sources; an omitted `sensitivity` or
742
+ * `agentVisible` keeps its stored value.
743
+ * @category AI
744
+ */
745
+ export interface UpdateAiOntologyPropertyRequest {
746
+ /** Id of the property. */
747
+ id: string;
748
+ /** Name of the property in snake_case. */
749
+ name: string;
750
+ /** What the property means to the business. */
751
+ description?: string;
752
+ /** The value type. */
753
+ type: AiOntologyPropertyType;
754
+ /**
755
+ * The columns that hold the property, at most one per member or supporting table. A source the property already
756
+ * stores is kept as stored, even when its table has left the entity or its column is hidden; a new one must be a
757
+ * visible column of a member or supporting table. A source on a supporting table is the only source
758
+ * (`ONTOLOGY_PROPERTY_SUPPORTING_SOURCE_ALONE`).
759
+ */
760
+ sources: AiOntologyPropertySource[];
761
+ /** What the values reveal. Omitted keeps the stored value; `null` clears it. */
762
+ sensitivity?: AiOntologyPropertySensitivity | null;
763
+ /** `false` keeps the property from agents and AI queries. Omitted keeps the stored value. */
764
+ agentVisible?: boolean;
765
+ }
766
+ /**
767
+ * Response that carries one property.
768
+ * @category AI
769
+ */
770
+ export interface AiOntologyPropertyResponse {
771
+ /** The property. */
772
+ property: AiOntologyProperty;
773
+ }
774
+ /**
775
+ * Request to delete a property.
776
+ * @category AI
777
+ */
778
+ export interface DeleteAiOntologyPropertyRequest {
779
+ /** Id of the property. */
780
+ id: string;
781
+ }
782
+ /**
783
+ * Request to accept, reject or reset properties.
784
+ * @category AI
785
+ */
786
+ export interface ReviewAiOntologyPropertiesRequest {
787
+ /** Ids of the properties. */
788
+ ids: string[];
789
+ /** The decision. `reset` returns the properties to suggested and clears `reviewedAt`. */
790
+ decision: ReviewAiOntologyRelationshipRequest['decision'];
791
+ /** The caller's claim of who they are, not an authenticated identity. */
792
+ actor?: string;
793
+ }
794
+ /**
795
+ * Response to {@link ReviewAiOntologyPropertiesRequest}.
796
+ * @category AI
797
+ */
798
+ export interface ReviewAiOntologyPropertiesResponse {
799
+ /** The properties the review changed. */
800
+ changed: AiOntologyProperty[];
801
+ /** The properties left as they were, with the reason. */
802
+ skipped: Array<{
803
+ id: string;
804
+ reason: string;
805
+ }>;
806
+ }
807
+ /**
808
+ * Request to generate the relationships, business entities and properties of an ontology. Answered by
809
+ * {@link AiOntologyResponse}.
810
+ * @category AI
811
+ */
812
+ export interface GenerateAiOntologyRequest {
813
+ /** Id of the ontology. */
814
+ ontologyId: AiOntologyId;
815
+ /** The status the run saves what it generates with. Defaults to `accepted`. */
816
+ saveAs?: AiOntologyGenerationSaveStatus;
817
+ /**
818
+ * Whether the run uses the stored ontology as its reference. Defaults to `true`: the model sees the stored rows and
819
+ * the run only adds to them, apart from what is derived: the schema import refreshes unreviewed imported
820
+ * relationships and removes those whose association is gone, and the knowledge base records are refreshed as
821
+ * {@link AiOntologyKnowledgeBase} describes. With `false` the run first deletes every relationship, business entity,
822
+ * property and knowledge base record, reviewed and hand-made ones included, and generates everything again. That is
823
+ * refused with `ONTOLOGY_HAS_NO_SOURCES` when nothing is attached, and fails, deleting nothing, when a database has
824
+ * no stored schema or a knowledge base is gone or may not be in an ontology.
825
+ */
826
+ usePreviousOntology?: boolean;
827
+ }
828
+ /**
829
+ * Request to generate only the properties of business entities of an ontology. Answered by
830
+ * {@link AiOntologyResponse}.
831
+ * @category AI
832
+ */
833
+ export interface GenerateAiOntologyPropertiesRequest {
834
+ /** Id of the ontology. */
835
+ ontologyId: AiOntologyId;
836
+ /** The entities to generate properties for, 1 to 50. Default: the entities that have no property yet. */
837
+ entityIds?: string[];
838
+ /** The status the run saves the properties with. Defaults to `accepted`. */
839
+ saveAs?: AiOntologyGenerationSaveStatus;
840
+ }
841
+ /**
842
+ * Request to refresh what an ontology stores about its attached knowledge bases, in a run of its own that saves its
843
+ * topic links as accepted. Answered by {@link AiOntologyResponse}.
844
+ * @category AI
845
+ */
846
+ export interface RefreshAiOntologyKnowledgeBasesRequest {
847
+ /** Id of the ontology. */
848
+ ontologyId: AiOntologyId;
849
+ }
850
+ /**
851
+ * The status a generation run saves what it generates with: `accepted` puts it to use at once, `suggested` keeps it
852
+ * from agents until a review accepts it. The topics and summary of a knowledge base have no status and are refreshed
853
+ * by every run.
854
+ * @category AI
855
+ */
856
+ export type AiOntologyGenerationSaveStatus = 'accepted' | 'suggested';
857
+ /**
858
+ * A root topic of the knowledge graph of an attached knowledge base.
859
+ * @category AI
860
+ */
861
+ export interface AiOntologyKnowledgeBaseTopic {
862
+ /** Name of the topic. */
863
+ name: string;
864
+ /** What the topic covers, cut to `maxKnowledgeBaseTopicDescriptionLength`. */
865
+ description?: string;
866
+ /** How many documents the topic holds. */
867
+ docCount: number;
868
+ }
869
+ /**
870
+ * A business entity whose records the documents of a topic of a knowledge base are about.
871
+ * @category AI
872
+ */
873
+ export interface AiOntologyKnowledgeBaseTopicLink {
874
+ /** Name of a topic of the record; it identifies the topic inside its knowledge base, since topic ids change. */
875
+ topicName: string;
876
+ /** Id of the entity. */
877
+ entityId: string;
878
+ /** Why the model linked them; absent on a link a person added. */
879
+ reasoning?: string;
880
+ /** Review state; agents see only accepted links. A link without `reviewedAt` is unreviewed. */
881
+ status: AiOntologyRelationshipStatus;
882
+ /** Who accepted or rejected the link. The caller's claim, not an authenticated identity. */
883
+ reviewedBy?: string;
884
+ /** When the link was reviewed, in epoch milliseconds. */
885
+ reviewedAt?: number;
886
+ }
887
+ /**
888
+ * What an ontology stores about one attached knowledge base. A run replaces the summary and topics. Of the links it
889
+ * replaces the unreviewed ones of the status it saves with, and none once a person set the links.
890
+ * @category AI
891
+ */
892
+ export interface AiOntologyKnowledgeBase {
893
+ /** The ontology. */
894
+ ontologyId: AiOntologyId;
895
+ /** The knowledge base. */
896
+ knowledgeBaseId: AiKnowledgeBaseId;
897
+ /** What the documents cover, written by a model; empty before the first summary. */
898
+ summary: string;
899
+ /** The root topics of the knowledge graph, most documents first. */
900
+ topics: AiOntologyKnowledgeBaseTopic[];
901
+ /**
902
+ * The business entities each topic's documents are about. Only links whose topic is in `topics` and whose entity
903
+ * exists are returned, so a refresh that replaces the topics drops the links of topics that are gone.
904
+ */
905
+ topicLinks: AiOntologyKnowledgeBaseTopicLink[];
906
+ /** When the last refresh started reading the topics, in epoch milliseconds. */
907
+ refreshedAt: number;
908
+ /** When a person last set the links, in epoch milliseconds; later runs then leave the links alone. */
909
+ linksEditedAt?: number;
910
+ /** Why the last refresh left something as it was. */
911
+ warning?: string;
912
+ }
913
+ /**
914
+ * Request to list what an ontology stores about its attached knowledge bases.
915
+ * @category AI
916
+ */
917
+ export interface ListAiOntologyKnowledgeBasesRequest {
918
+ /** Id of the ontology. */
919
+ ontologyId: AiOntologyId;
920
+ }
921
+ /**
922
+ * Response to {@link ListAiOntologyKnowledgeBasesRequest}.
923
+ * @category AI
924
+ */
925
+ export interface ListAiOntologyKnowledgeBasesResponse {
926
+ /** One record per attached knowledge base a generation run has read, in attached order. */
927
+ knowledgeBases: AiOntologyKnowledgeBase[];
928
+ }
929
+ /**
930
+ * Request to set the topic links of an attached knowledge base: the links named become the accepted links and every
931
+ * other link is removed. Later runs keep these links.
932
+ * @category AI
933
+ */
934
+ export interface UpdateAiOntologyKnowledgeBaseRequest {
935
+ /** Id of the ontology. */
936
+ ontologyId: AiOntologyId;
937
+ /** Id of an attached knowledge base that a refresh has read. */
938
+ knowledgeBaseId: AiKnowledgeBaseId;
939
+ /**
940
+ * The links, at most `maxKnowledgeBaseTopicLinks` and `maxEntitiesPerKnowledgeBaseTopic` per topic: each names a
941
+ * topic of the record and an entity of the ontology. An empty list clears the links.
942
+ */
943
+ topicLinks: Array<Pick<AiOntologyKnowledgeBaseTopicLink, 'topicName' | 'entityId'>>;
944
+ }
945
+ /**
946
+ * Request to accept, reject or reset topic links of an attached knowledge base. Answered by
947
+ * {@link AiOntologyKnowledgeBaseResponse}.
948
+ * @category AI
949
+ */
950
+ export interface ReviewAiOntologyKnowledgeBaseTopicLinksRequest {
951
+ /** Id of the ontology. */
952
+ ontologyId: AiOntologyId;
953
+ /** Id of an attached knowledge base that a run has read. */
954
+ knowledgeBaseId: AiKnowledgeBaseId;
955
+ /** The links to review, 1 to `maxKnowledgeBaseTopicLinks`, each one a link of the record. */
956
+ topicLinks: Array<Pick<AiOntologyKnowledgeBaseTopicLink, 'topicName' | 'entityId'>>;
957
+ /**
958
+ * The decision. `reset` returns the links to suggested and clears `reviewedAt`. Only a run that saves as suggested
959
+ * may then replace them, and none once a person set the links; a run that saves as accepted keeps them suggested.
960
+ */
961
+ decision: ReviewAiOntologyRelationshipRequest['decision'];
962
+ /** The caller's claim of who they are, not an authenticated identity. */
963
+ actor?: string;
964
+ }
965
+ /**
966
+ * Response that carries what an ontology stores about one knowledge base.
967
+ * @category AI
968
+ */
969
+ export interface AiOntologyKnowledgeBaseResponse {
970
+ /** The record of the knowledge base. */
971
+ knowledgeBase: AiOntologyKnowledgeBase;
972
+ }
973
+ /**
974
+ * Request to delete every relationship, business entity and property of an ontology, and what it stores about its
975
+ * knowledge bases, keeping the ontology with its databases and knowledge bases.
976
+ * @category AI
977
+ */
978
+ export interface ResetAiOntologyRequest {
979
+ /** Id of the ontology. */
980
+ id: AiOntologyId;
981
+ }
982
+ /**
983
+ * Size limits of an ontology.
984
+ * @category AI
985
+ */
986
+ export declare const AI_ONTOLOGY_LIMITS: {
987
+ readonly maxOntologies: 1000;
988
+ readonly maxIntegrationsPerOntology: 20;
989
+ readonly maxRelationships: 2000;
990
+ readonly maxEntities: 500;
991
+ readonly maxMembersPerEntity: 20;
992
+ readonly maxSupportingTablesPerEntity: 50;
993
+ readonly maxNameLength: 100;
994
+ readonly maxDescriptionLength: 2000;
995
+ readonly maxGeneratedDescriptionLength: 500;
996
+ readonly maxLabelLength: 200;
997
+ readonly maxReasoningLength: 2000;
998
+ readonly maxColumnsPerSide: 16;
999
+ readonly maxConfirmationColumnPairs: 10;
1000
+ readonly maxActorLength: 200;
1001
+ readonly maxTablesPerPrompt: 200;
1002
+ readonly maxColumnsPerTableInPrompt: 100;
1003
+ readonly maxToolCallsPerRun: 40;
1004
+ readonly maxSampleCallsPerPropertyPass: 8;
1005
+ readonly defaultSampleRows: 10;
1006
+ readonly maxSampleRows: 20;
1007
+ readonly maxSampleValueLength: 200;
1008
+ readonly maxSampleAnswerLength: 12000;
1009
+ readonly maxDescriptionLengthInPrompt: 300;
1010
+ readonly maxPromptChars: 300000;
1011
+ readonly maxPropertiesPerEntity: 100;
1012
+ readonly maxPropertiesPerOntology: 2000;
1013
+ readonly maxPropertySources: 20;
1014
+ readonly maxPropertyDescriptionLength: 500;
1015
+ readonly maxReviewedPropertiesPerCall: 200;
1016
+ readonly maxEntitiesPerPropertyPass: 5;
1017
+ readonly maxGeneratedPropertiesPerEntity: 30;
1018
+ readonly maxEntitiesPerPropertyRun: 50;
1019
+ readonly maxFollowStartValues: 100;
1020
+ readonly maxFollowStartRecords: 500;
1021
+ readonly maxFollowKeyValues: 1000;
1022
+ readonly maxFollowLinkedRows: 5000;
1023
+ readonly maxFollowReturnedRows: 100;
1024
+ readonly maxFollowAgentRowsChars: 30000;
1025
+ readonly maxFollowLinkedReads: 5;
1026
+ readonly maxKnowledgeBasesPerOntology: 5;
1027
+ readonly maxKnowledgeBaseTopics: 20;
1028
+ readonly maxKnowledgeBaseTopicDescriptionLength: 250;
1029
+ readonly maxKnowledgeBaseSummaryLength: 500;
1030
+ readonly maxKnowledgeBaseTopicLinks: 100;
1031
+ readonly maxEntitiesPerKnowledgeBaseTopic: 5;
1032
+ readonly maxKnowledgeBaseLinkReasoningLength: 300;
1033
+ readonly maxMembersPerEntityInLinkPrompt: 5;
1034
+ };