@colin_kerr/query-agent-client 0.0.0-stage → 0.1.0
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.
- package/LICENSE +21 -0
- package/README.md +20 -2
- package/dist/cjs/agent-client.d.ts +107 -0
- package/dist/cjs/agent-client.js +142 -0
- package/dist/cjs/agent-client.js.map +1 -0
- package/dist/cjs/caps.d.ts +43 -0
- package/dist/cjs/caps.js +51 -0
- package/dist/cjs/caps.js.map +1 -0
- package/dist/cjs/client.d.ts +145 -0
- package/dist/cjs/client.js +270 -0
- package/dist/cjs/client.js.map +1 -0
- package/dist/cjs/index.d.ts +11 -0
- package/dist/cjs/index.js +28 -0
- package/dist/cjs/index.js.map +1 -0
- package/dist/cjs/node/index.d.ts +27 -0
- package/dist/cjs/node/index.js +59 -0
- package/dist/cjs/node/index.js.map +1 -0
- package/dist/cjs/query-runner.d.ts +34 -0
- package/dist/cjs/query-runner.js +41 -0
- package/dist/cjs/query-runner.js.map +1 -0
- package/dist/cjs/result-pages.d.ts +69 -0
- package/dist/cjs/result-pages.js +176 -0
- package/dist/cjs/result-pages.js.map +1 -0
- package/dist/cjs/selection.d.ts +90 -0
- package/dist/cjs/selection.js +222 -0
- package/dist/cjs/selection.js.map +1 -0
- package/dist/cjs/startup-queries.json +182 -0
- package/dist/cjs/turn-api.d.ts +156 -0
- package/dist/cjs/turn-api.js +19 -0
- package/dist/cjs/turn-api.js.map +1 -0
- package/dist/esm/agent-client.d.ts +107 -0
- package/dist/esm/agent-client.js +134 -0
- package/dist/esm/agent-client.js.map +1 -0
- package/dist/esm/caps.d.ts +43 -0
- package/dist/esm/caps.js +48 -0
- package/dist/esm/caps.js.map +1 -0
- package/dist/esm/client.d.ts +145 -0
- package/dist/esm/client.js +260 -0
- package/dist/esm/client.js.map +1 -0
- package/dist/esm/index.d.ts +11 -0
- package/dist/esm/index.js +12 -0
- package/dist/esm/index.js.map +1 -0
- package/dist/esm/query-runner.d.ts +34 -0
- package/dist/esm/query-runner.js +38 -0
- package/dist/esm/query-runner.js.map +1 -0
- package/dist/esm/result-pages.d.ts +69 -0
- package/dist/esm/result-pages.js +172 -0
- package/dist/esm/result-pages.js.map +1 -0
- package/dist/esm/selection.d.ts +90 -0
- package/dist/esm/selection.js +212 -0
- package/dist/esm/selection.js.map +1 -0
- package/dist/esm/startup-queries.json +182 -0
- package/dist/esm/turn-api.d.ts +156 -0
- package/dist/esm/turn-api.js +16 -0
- package/dist/esm/turn-api.js.map +1 -0
- package/package.json +67 -4
|
@@ -0,0 +1,182 @@
|
|
|
1
|
+
{
|
|
2
|
+
"description": [
|
|
3
|
+
"The queries the client library runs on an iModel before the first question: the startup query list. It sends their rows with every turn, and the function writes them into the agent's instructions, matched by rule and id.",
|
|
4
|
+
"ecsql: any ECSql. {{in:list}} expands a list from `lists` to 'a', 'b'. {{like:expr:list}} expands to (expr LIKE '%a%' OR ...), and {{notlike:expr:list}} to (expr NOT LIKE '%a%' AND ...); a value that already contains % is used as written.",
|
|
5
|
+
"max: rows sent (default 20); the rest are counted, up to 500. A query that fails sends no rows and its error.",
|
|
6
|
+
"onlyIfEmpty: run only when the named queries of the same rule were empty (no rows, or a single 0). each: a second query run for every row sent, with the row's columns as {0}, {1}; its first value is sent with the row. Every `each` query runs to the end: there is no time limit, because the first context matters more than the seconds it takes.",
|
|
7
|
+
"Keep everything generic: no names or values from one iModel."
|
|
8
|
+
],
|
|
9
|
+
"lists": {
|
|
10
|
+
"connectorSchemaPatterns": [
|
|
11
|
+
"IFCDynamic%",
|
|
12
|
+
"%DgnCustomItemTypes%",
|
|
13
|
+
"BuildingDataGroup%",
|
|
14
|
+
"Cif%"
|
|
15
|
+
],
|
|
16
|
+
"standardDomainSchemas": [
|
|
17
|
+
"AecValueDefinitions",
|
|
18
|
+
"Analytical",
|
|
19
|
+
"ArchitecturalPhysical",
|
|
20
|
+
"Asset",
|
|
21
|
+
"BridgePhysical",
|
|
22
|
+
"BridgeStructuralPhysical",
|
|
23
|
+
"BuildingPhysical",
|
|
24
|
+
"BuildingSpatial",
|
|
25
|
+
"CivilPhysical",
|
|
26
|
+
"CivilSpatial",
|
|
27
|
+
"ClassificationSystems",
|
|
28
|
+
"Construction",
|
|
29
|
+
"DistributionSystems",
|
|
30
|
+
"DocumentMetadata",
|
|
31
|
+
"Earthwork",
|
|
32
|
+
"ElectricalPhysical",
|
|
33
|
+
"Fasteners",
|
|
34
|
+
"Functional",
|
|
35
|
+
"GeologicalModel",
|
|
36
|
+
"Grids",
|
|
37
|
+
"IoTDeviceFunctional",
|
|
38
|
+
"LinearReferencing",
|
|
39
|
+
"MechanicalPhysical",
|
|
40
|
+
"NetworkTopology",
|
|
41
|
+
"OpenSite",
|
|
42
|
+
"PhysicalMaterial",
|
|
43
|
+
"PipeworkPhysical",
|
|
44
|
+
"PlantPhysical",
|
|
45
|
+
"ProcessFunctional",
|
|
46
|
+
"ProcessPhysical",
|
|
47
|
+
"Profiles",
|
|
48
|
+
"QuantityTakeoffsAspects",
|
|
49
|
+
"RailPhysical",
|
|
50
|
+
"RailSpatial",
|
|
51
|
+
"RoadAttributions",
|
|
52
|
+
"RoadPhysical",
|
|
53
|
+
"RoadRailAlignment",
|
|
54
|
+
"RoadRailPhysical",
|
|
55
|
+
"RoadSpatial",
|
|
56
|
+
"SpatialComposition",
|
|
57
|
+
"StormSewerPhysical",
|
|
58
|
+
"StructuralAnalysis",
|
|
59
|
+
"StructuralConnections",
|
|
60
|
+
"StructuralMaterials",
|
|
61
|
+
"StructuralPhysical",
|
|
62
|
+
"Terrain",
|
|
63
|
+
"TerrainPhysical",
|
|
64
|
+
"WaterDistributionPhysical"
|
|
65
|
+
],
|
|
66
|
+
"classificationWords": [
|
|
67
|
+
"classification",
|
|
68
|
+
"uniclass",
|
|
69
|
+
"omniclass",
|
|
70
|
+
"uniformat"
|
|
71
|
+
],
|
|
72
|
+
"notClassificationWords": [
|
|
73
|
+
"load%classification",
|
|
74
|
+
"system%classification"
|
|
75
|
+
]
|
|
76
|
+
},
|
|
77
|
+
"queries": [
|
|
78
|
+
{
|
|
79
|
+
"rule": "connectors",
|
|
80
|
+
"id": "names",
|
|
81
|
+
"ecsql": "SELECT ConnectorName, COUNT(*) AS sources FROM bis.ExternalSource WHERE ConnectorName IS NOT NULL GROUP BY ConnectorName ORDER BY sources DESC",
|
|
82
|
+
"max": 8
|
|
83
|
+
},
|
|
84
|
+
{
|
|
85
|
+
"rule": "connectors",
|
|
86
|
+
"id": "schemas",
|
|
87
|
+
"ecsql": "SELECT Name FROM meta.ECSchemaDef WHERE {{like:Name:connectorSchemaPatterns}} ORDER BY Name",
|
|
88
|
+
"max": 8
|
|
89
|
+
},
|
|
90
|
+
{
|
|
91
|
+
"rule": "domain-schemas",
|
|
92
|
+
"id": "elements",
|
|
93
|
+
"ecsql": "SELECT s.Name, b.Name, SUM(n.cnt) AS n FROM (SELECT ECClassId AS cid, COUNT(*) AS cnt FROM bis.Element GROUP BY ECClassId) n JOIN meta.ClassHasAllBaseClasses h ON h.SourceECInstanceId = n.cid JOIN meta.ECClassDef b ON b.ECInstanceId = h.TargetECInstanceId JOIN meta.ECSchemaDef s ON s.ECInstanceId = b.Schema.Id WHERE s.Name IN ({{in:standardDomainSchemas}}) GROUP BY b.ECInstanceId ORDER BY s.Name, CASE WHEN b.Modifier = 1 THEN 1 ELSE 0 END, n DESC",
|
|
94
|
+
"max": 60
|
|
95
|
+
},
|
|
96
|
+
{
|
|
97
|
+
"rule": "domain-schemas",
|
|
98
|
+
"id": "aspects",
|
|
99
|
+
"ecsql": "SELECT s.Name, b.Name, SUM(n.cnt) AS n FROM (SELECT ECClassId AS cid, COUNT(*) AS cnt FROM bis.ElementAspect GROUP BY ECClassId) n JOIN meta.ClassHasAllBaseClasses h ON h.SourceECInstanceId = n.cid JOIN meta.ECClassDef b ON b.ECInstanceId = h.TargetECInstanceId JOIN meta.ECSchemaDef s ON s.ECInstanceId = b.Schema.Id WHERE s.Name IN ({{in:standardDomainSchemas}}) GROUP BY b.ECInstanceId ORDER BY s.Name, CASE WHEN b.Modifier = 1 THEN 1 ELSE 0 END, n DESC",
|
|
100
|
+
"max": 24
|
|
101
|
+
},
|
|
102
|
+
{
|
|
103
|
+
"rule": "domain-schemas",
|
|
104
|
+
"id": "relationships",
|
|
105
|
+
"ecsql": "SELECT s.Name, b.Name, SUM(n.cnt) AS n FROM (SELECT ECClassId AS cid, COUNT(*) AS cnt FROM bis.ElementRefersToElements GROUP BY ECClassId) n JOIN meta.ClassHasAllBaseClasses h ON h.SourceECInstanceId = n.cid JOIN meta.ECClassDef b ON b.ECInstanceId = h.TargetECInstanceId JOIN meta.ECSchemaDef s ON s.ECInstanceId = b.Schema.Id WHERE s.Name IN ({{in:standardDomainSchemas}}) GROUP BY b.ECInstanceId ORDER BY s.Name, CASE WHEN b.Modifier = 1 THEN 1 ELSE 0 END, n DESC",
|
|
106
|
+
"max": 24
|
|
107
|
+
},
|
|
108
|
+
{
|
|
109
|
+
"rule": "own-classes",
|
|
110
|
+
"id": "standard-bases",
|
|
111
|
+
"ecsql": "SELECT ec_classname(base.ECInstanceId) AS base, COUNT(*) AS classes, SUM(n.cnt) AS elements, MAX(c.Name) AS example FROM (SELECT ECClassId AS cid, COUNT(*) AS cnt FROM bis.Element GROUP BY ECClassId) n JOIN meta.ECClassDef c ON c.ECInstanceId = n.cid JOIN meta.ECSchemaDef cs ON cs.ECInstanceId = c.Schema.Id JOIN meta.ECClassDef base ON base.ECInstanceId = (SELECT b.ECInstanceId FROM meta.ClassHasAllBaseClasses h JOIN meta.ECClassDef b ON b.ECInstanceId = h.TargetECInstanceId JOIN meta.ECSchemaDef s ON s.ECInstanceId = b.Schema.Id WHERE h.SourceECInstanceId = n.cid AND s.Name IN ({{in:standardDomainSchemas}}) ORDER BY (SELECT COUNT(*) FROM meta.ClassHasAllBaseClasses d WHERE d.SourceECInstanceId = b.ECInstanceId) DESC LIMIT 1) WHERE cs.Name NOT IN ({{in:standardDomainSchemas}}) AND cs.Name NOT IN ('BisCore', 'Generic') AND n.cid NOT IN (SELECT SourceECInstanceId FROM meta.ClassHasAllBaseClasses WHERE TargetECInstanceId = ec_classid('BisCore', 'DefinitionElement')) GROUP BY base.ECInstanceId ORDER BY base.ECInstanceId"
|
|
112
|
+
},
|
|
113
|
+
{
|
|
114
|
+
"rule": "classification",
|
|
115
|
+
"id": "standard",
|
|
116
|
+
"ecsql": "SELECT COALESCE(s.UserLabel, s.CodeValue) AS systemName, COUNT(DISTINCT t.ECInstanceId) AS tables, COUNT(c.ECInstanceId) AS classifications FROM ClassificationSystems.ClassificationSystem s LEFT JOIN ClassificationSystems.ClassificationTable t ON t.Parent.Id = s.ECInstanceId LEFT JOIN ClassificationSystems.Classification c ON c.Model.Id = t.ECInstanceId GROUP BY s.ECInstanceId",
|
|
117
|
+
"max": 6
|
|
118
|
+
},
|
|
119
|
+
{
|
|
120
|
+
"rule": "classification",
|
|
121
|
+
"id": "classified",
|
|
122
|
+
"ecsql": "SELECT COUNT(DISTINCT SourceECInstanceId) FROM ClassificationSystems.ElementHasClassifications"
|
|
123
|
+
},
|
|
124
|
+
{
|
|
125
|
+
"rule": "classification",
|
|
126
|
+
"id": "properties",
|
|
127
|
+
"ecsql": "SELECT b.Name AS kind, p.Name, COUNT(*) AS classes, MIN(ec_classname(c.ECInstanceId)) AS exampleClass FROM meta.ECPropertyDef p JOIN meta.ECClassDef c ON c.ECInstanceId = p.Class.Id JOIN meta.ClassHasAllBaseClasses h ON h.SourceECInstanceId = c.ECInstanceId JOIN meta.ECClassDef b ON b.ECInstanceId = h.TargetECInstanceId JOIN meta.ECSchemaDef s ON s.ECInstanceId = b.Schema.Id WHERE s.Name = 'BisCore' AND b.Name IN ('GeometricElement3d', 'GeometricElement2d', 'DefinitionElement', 'ElementUniqueAspect', 'ElementMultiAspect') AND {{like:p.Name:classificationWords}} AND {{notlike:p.Name:notClassificationWords}} GROUP BY b.Name, p.Name ORDER BY classes DESC, p.Name",
|
|
128
|
+
"max": 6,
|
|
129
|
+
"each": "SELECT COUNT(*) FROM bis.[{0}] x WHERE x.$->[{1}] <> ''"
|
|
130
|
+
},
|
|
131
|
+
{
|
|
132
|
+
"rule": "core-domains",
|
|
133
|
+
"id": "3d-physical",
|
|
134
|
+
"ecsql": "SELECT COUNT(*) FROM bis.PhysicalElement"
|
|
135
|
+
},
|
|
136
|
+
{
|
|
137
|
+
"rule": "core-domains",
|
|
138
|
+
"id": "3d-spatial-location",
|
|
139
|
+
"ecsql": "SELECT COUNT(*) FROM bis.SpatialLocationElement"
|
|
140
|
+
},
|
|
141
|
+
{
|
|
142
|
+
"rule": "core-domains",
|
|
143
|
+
"id": "3d-graphics",
|
|
144
|
+
"ecsql": "SELECT COUNT(*) FROM bis.GraphicalElement3d"
|
|
145
|
+
},
|
|
146
|
+
{
|
|
147
|
+
"rule": "core-domains",
|
|
148
|
+
"id": "2d-graphics",
|
|
149
|
+
"ecsql": "SELECT COUNT(*) FROM bis.GeometricElement2d"
|
|
150
|
+
},
|
|
151
|
+
{
|
|
152
|
+
"rule": "core-domains",
|
|
153
|
+
"id": "drawings",
|
|
154
|
+
"ecsql": "SELECT COUNT(*) FROM bis.Drawing"
|
|
155
|
+
},
|
|
156
|
+
{
|
|
157
|
+
"rule": "core-domains",
|
|
158
|
+
"id": "sheets",
|
|
159
|
+
"ecsql": "SELECT COUNT(*) FROM bis.Sheet"
|
|
160
|
+
},
|
|
161
|
+
{
|
|
162
|
+
"rule": "core-domains",
|
|
163
|
+
"id": "functional",
|
|
164
|
+
"ecsql": "SELECT COUNT(*) FROM Functional.FunctionalElement"
|
|
165
|
+
},
|
|
166
|
+
{
|
|
167
|
+
"rule": "core-domains",
|
|
168
|
+
"id": "analytical",
|
|
169
|
+
"ecsql": "SELECT COUNT(*) FROM Analytical.AnalyticalElement"
|
|
170
|
+
},
|
|
171
|
+
{
|
|
172
|
+
"rule": "core-domains",
|
|
173
|
+
"id": "linear-referencing-linear-elements",
|
|
174
|
+
"ecsql": "SELECT COUNT(*) FROM LinearReferencing.ILinearElement"
|
|
175
|
+
},
|
|
176
|
+
{
|
|
177
|
+
"rule": "core-domains",
|
|
178
|
+
"id": "linear-referencing-located-elements",
|
|
179
|
+
"ecsql": "SELECT COUNT(*) FROM LinearReferencing.ILinearlyLocated"
|
|
180
|
+
}
|
|
181
|
+
]
|
|
182
|
+
}
|
|
@@ -0,0 +1,156 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The turn API's types: everything that travels between the client and the function, and nothing
|
|
3
|
+
* else. The agent's own state (its conversation with the model, its steps, notes and counters)
|
|
4
|
+
* travels only inside the sealed token, which the client cannot read.
|
|
5
|
+
*
|
|
6
|
+
* This module imports nothing, so the client library and the agent function each carry the same
|
|
7
|
+
* copy of it. Change both together.
|
|
8
|
+
*/
|
|
9
|
+
export interface ResultCaps {
|
|
10
|
+
/** How many rows may be shown. */
|
|
11
|
+
maxRows: number;
|
|
12
|
+
/** How many characters of formatted rows may be shown, across all of them. */
|
|
13
|
+
maxChars: number;
|
|
14
|
+
/** How long a single value may be before it is clipped. */
|
|
15
|
+
maxCellChars: number;
|
|
16
|
+
}
|
|
17
|
+
/**
|
|
18
|
+
* One query's result as the client sends it: the rows it read, up to the caps the function sent,
|
|
19
|
+
* or the query's error.
|
|
20
|
+
*
|
|
21
|
+
* The client stops where the function's format would stop, so it never reads or sends more than
|
|
22
|
+
* the model can be shown. A string longer than `maxCellChars` travels cut to that length, with
|
|
23
|
+
* its full length in `clipped`, so the function can say how much was cut.
|
|
24
|
+
*/
|
|
25
|
+
export interface QueryRows {
|
|
26
|
+
/** The query exactly as the response asked for it. */
|
|
27
|
+
ecsql: string;
|
|
28
|
+
columns?: string[];
|
|
29
|
+
rows?: unknown[][];
|
|
30
|
+
/** The cells cut to `maxCellChars`: row index, column index, full length. */
|
|
31
|
+
clipped?: [number, number, number][];
|
|
32
|
+
/** Which cap stopped the read, if either did. */
|
|
33
|
+
truncatedBy?: "rows" | "chars";
|
|
34
|
+
/** The query's error message, when it failed (at the start or part way through the rows). */
|
|
35
|
+
error?: string;
|
|
36
|
+
/** How long the client took to run and read it. */
|
|
37
|
+
ms: number;
|
|
38
|
+
}
|
|
39
|
+
/**
|
|
40
|
+
* One startup query's result as the client sends it: the rows to show, how many rows there were,
|
|
41
|
+
* and the value of the `each` query for each row shown.
|
|
42
|
+
*/
|
|
43
|
+
export interface StartupResult {
|
|
44
|
+
rule: string;
|
|
45
|
+
id: string;
|
|
46
|
+
/** The rows to show: at most the query's `max`. */
|
|
47
|
+
rows: unknown[][];
|
|
48
|
+
/** How many rows the query returned, counted up to the client's guard. */
|
|
49
|
+
count: number;
|
|
50
|
+
/** True when the count stopped at the guard, so there may be more. */
|
|
51
|
+
guarded?: boolean;
|
|
52
|
+
/** For each row shown, its `each` value: a count, or null when it could not be run. */
|
|
53
|
+
each?: (string | null)[];
|
|
54
|
+
/** Not run, because a query it depends on was not empty. */
|
|
55
|
+
skipped?: boolean;
|
|
56
|
+
/** The query failed (the class or schema is not in this file). It is then empty. */
|
|
57
|
+
error?: string;
|
|
58
|
+
ms: number;
|
|
59
|
+
}
|
|
60
|
+
export type StopReason = "answered" | "stuck" | "steps" | "aborted";
|
|
61
|
+
/**
|
|
62
|
+
* How much of an answer's rows an earlier question keeps for the questions after it. Smaller than a
|
|
63
|
+
* live result: enough for a count, a short list, or the top of a long one.
|
|
64
|
+
*/
|
|
65
|
+
export declare const HISTORY_CAPS: ResultCaps;
|
|
66
|
+
/** An earlier question of the chat, as the user saw it. */
|
|
67
|
+
export interface EarlierQuestion {
|
|
68
|
+
question: string;
|
|
69
|
+
answer: string;
|
|
70
|
+
query?: string;
|
|
71
|
+
/** The answer's query's rows, cut to `HISTORY_CAPS`, or its error. */
|
|
72
|
+
rows?: Pick<QueryRows, "columns" | "rows" | "clipped" | "truncatedBy" | "error">;
|
|
73
|
+
stoppedBecause: StopReason;
|
|
74
|
+
}
|
|
75
|
+
export interface SubmittedAnswer {
|
|
76
|
+
explanation: string;
|
|
77
|
+
query: string;
|
|
78
|
+
outcome: "answered" | "partial" | "not_found";
|
|
79
|
+
rowLimitIntended: boolean;
|
|
80
|
+
/** Read from a free-text answer's labelled last lines rather than submitted with the tool. */
|
|
81
|
+
via?: "labels";
|
|
82
|
+
}
|
|
83
|
+
/**
|
|
84
|
+
* How the answer is to be given, for a host with unified selection. Absent, or any other value, is
|
|
85
|
+
* the plain answer.
|
|
86
|
+
*
|
|
87
|
+
* - `auto`: the host selects elements from answers. The agent decides, question by question,
|
|
88
|
+
* whether the question asks to select elements. An answer whose rows are elements also returns
|
|
89
|
+
* their `ECInstanceId` and `ClassName`.
|
|
90
|
+
* - `select`: a host preference (the user set the app to select): every question is a request to
|
|
91
|
+
* select elements, and the answer's `query` is the selection. A host sets it from the user's
|
|
92
|
+
* choice, never from scanning the question.
|
|
93
|
+
*/
|
|
94
|
+
export type AnswerMode = "auto" | "select";
|
|
95
|
+
/** The answer modes, for checking a request's. */
|
|
96
|
+
export declare const ANSWER_MODES: readonly AnswerMode[];
|
|
97
|
+
/**
|
|
98
|
+
* What a finished answer is, in the `auto` and `select` modes (`TurnDone.resultType`). It tells
|
|
99
|
+
* the host what to do with the answer, not how the agent made it.
|
|
100
|
+
*
|
|
101
|
+
* - `selection`: the answer's `query` is the selection. Select its rows (`ECInstanceId`,
|
|
102
|
+
* `ClassName`); no rows, or `not_found`, clears the selection.
|
|
103
|
+
* - `answer`: an answer to show. Select its rows only when they have both key columns.
|
|
104
|
+
*/
|
|
105
|
+
export type ResultType = "selection" | "answer";
|
|
106
|
+
/** What the client sends for one turn: `POST /turn`. */
|
|
107
|
+
export interface TurnRequest {
|
|
108
|
+
question: string;
|
|
109
|
+
/** Whether the client has an iModel to query. Without one, `runQuery` is not offered. */
|
|
110
|
+
canQuery: boolean;
|
|
111
|
+
/** The open iModel: its name, and the rows of the startup query list, sent with every turn. */
|
|
112
|
+
imodel?: {
|
|
113
|
+
name: string;
|
|
114
|
+
startup?: StartupResult[];
|
|
115
|
+
};
|
|
116
|
+
/** What is in the query editor, which is context for "fix this" and "what does this do". */
|
|
117
|
+
editorText?: string;
|
|
118
|
+
/** The chat's earlier questions, oldest first, as the user saw them. The same in every turn of a run. */
|
|
119
|
+
earlier?: EarlierQuestion[];
|
|
120
|
+
/**
|
|
121
|
+
* The token from the last response: of this run, or, on a run's first turn, of the chat's last
|
|
122
|
+
* finished run. Absent on a chat's first turn. Opaque: the client stores it and sends it back.
|
|
123
|
+
*/
|
|
124
|
+
token?: string;
|
|
125
|
+
/** The rows, or the error, of each query the last response asked for. */
|
|
126
|
+
results?: QueryRows[];
|
|
127
|
+
/** The user stopped the run: the function handles the last reply's calls and ends it, with no LLM call. */
|
|
128
|
+
aborted?: boolean;
|
|
129
|
+
/** How the answer is to be given (`AnswerMode`). Sent with every turn of a run, the same each time. */
|
|
130
|
+
answerMode?: AnswerMode;
|
|
131
|
+
}
|
|
132
|
+
/** What the run ends with: the answer, as the user sees it. */
|
|
133
|
+
export interface TurnDone {
|
|
134
|
+
/** The final prose answer, which should carry exactly one fenced sql block. */
|
|
135
|
+
answer: string;
|
|
136
|
+
/** The query pulled out of the answer, if there was one. */
|
|
137
|
+
query?: string;
|
|
138
|
+
/** The answer as submitted with `submitAnswer`, when the run ended that way. */
|
|
139
|
+
structured?: SubmittedAnswer;
|
|
140
|
+
stoppedBecause: StopReason;
|
|
141
|
+
/** Names the run's record, where the function keeps one. */
|
|
142
|
+
runId: string;
|
|
143
|
+
/** In the `auto` and `select` modes: what the answer is (`ResultType`). */
|
|
144
|
+
resultType?: ResultType;
|
|
145
|
+
}
|
|
146
|
+
/** What the function sends back for one turn. */
|
|
147
|
+
export interface TurnResponse {
|
|
148
|
+
/** The token to send with the next turn: of this run, or, after `done`, of the chat's next question. */
|
|
149
|
+
token: string;
|
|
150
|
+
/** The queries to run before the next turn. When there are none, the client sends the next turn at once. */
|
|
151
|
+
queries: string[];
|
|
152
|
+
/** How much of each query's result to read. */
|
|
153
|
+
caps: ResultCaps;
|
|
154
|
+
/** Present when the run is over. */
|
|
155
|
+
done?: TurnDone;
|
|
156
|
+
}
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
/**
|
|
3
|
+
* The turn API's types: everything that travels between the client and the function, and nothing
|
|
4
|
+
* else. The agent's own state (its conversation with the model, its steps, notes and counters)
|
|
5
|
+
* travels only inside the sealed token, which the client cannot read.
|
|
6
|
+
*
|
|
7
|
+
* This module imports nothing, so the client library and the agent function each carry the same
|
|
8
|
+
* copy of it. Change both together.
|
|
9
|
+
*/
|
|
10
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
11
|
+
exports.ANSWER_MODES = exports.HISTORY_CAPS = void 0;
|
|
12
|
+
/**
|
|
13
|
+
* How much of an answer's rows an earlier question keeps for the questions after it. Smaller than a
|
|
14
|
+
* live result: enough for a count, a short list, or the top of a long one.
|
|
15
|
+
*/
|
|
16
|
+
exports.HISTORY_CAPS = { maxRows: 20, maxChars: 2_000, maxCellChars: 200 };
|
|
17
|
+
/** The answer modes, for checking a request's. */
|
|
18
|
+
exports.ANSWER_MODES = ["auto", "select"];
|
|
19
|
+
//# sourceMappingURL=turn-api.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"turn-api.js","sourceRoot":"","sources":["../../src/turn-api.ts"],"names":[],"mappings":";AAAA;;;;;;;GAOG;;;AA0DH;;;GAGG;AACU,QAAA,YAAY,GAAe,EAAE,OAAO,EAAE,EAAE,EAAE,QAAQ,EAAE,KAAK,EAAE,YAAY,EAAE,GAAG,EAAE,CAAC;AAkC5F,kDAAkD;AACrC,QAAA,YAAY,GAA0B,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC"}
|
|
@@ -0,0 +1,107 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The client a host starts for an open iModel: it runs the startup list when it starts, then
|
|
3
|
+
* answers questions by driving turns with the function.
|
|
4
|
+
*
|
|
5
|
+
* ```ts
|
|
6
|
+
* const client = AgentClient.start({ runQuery: queryRunner(imodel), imodelName, functionUrl });
|
|
7
|
+
* const run = await client.ask("How many pipes are there?", { onStatus });
|
|
8
|
+
* ```
|
|
9
|
+
*/
|
|
10
|
+
import { type RunRawQuery } from "./caps.js";
|
|
11
|
+
import { type AgentRun, type AnswerRows, type StartupList, type TurnCall } from "./client.js";
|
|
12
|
+
import { type InstanceKey, type RunSelection } from "./selection.js";
|
|
13
|
+
import type { AnswerMode, EarlierQuestion, QueryRows, ResultCaps, StartupResult } from "./turn-api.js";
|
|
14
|
+
/** The library's startup query list (`startup-queries.json`): what a client runs when it starts. */
|
|
15
|
+
export declare const DEFAULT_STARTUP_LIST: StartupList;
|
|
16
|
+
/** What the client is doing: what a host shows while it waits. */
|
|
17
|
+
export type AgentStatus = {
|
|
18
|
+
phase: "exploring";
|
|
19
|
+
} | {
|
|
20
|
+
phase: "thinking";
|
|
21
|
+
} | {
|
|
22
|
+
phase: "querying";
|
|
23
|
+
ecsql: string;
|
|
24
|
+
};
|
|
25
|
+
/** How much of an answer's rows the client reads for the host to show. */
|
|
26
|
+
export declare const ANSWER_CAPS: ResultCaps;
|
|
27
|
+
/**
|
|
28
|
+
* An answer's query's rows, read once with `ANSWER_CAPS`, or the error it gave; undefined when
|
|
29
|
+
* there is no query. What `AgentClient.ask` keeps on the run, for the host and for later questions.
|
|
30
|
+
*/
|
|
31
|
+
export declare function readAnswerRows(runQuery: RunRawQuery, query: string | undefined): Promise<AnswerRows | undefined>;
|
|
32
|
+
export interface AgentClientOptions {
|
|
33
|
+
/** How to run a query on the iModel: `queryRunner(imodel)`. Absent for questions about ECSql alone. */
|
|
34
|
+
runQuery?: RunRawQuery;
|
|
35
|
+
/** The iModel's name, as the agent is told it. */
|
|
36
|
+
imodelName?: string;
|
|
37
|
+
/** The function's base URL; `POST <url>/turn` is called. */
|
|
38
|
+
functionUrl?: string;
|
|
39
|
+
/** In place of `functionUrl`: how to send one turn (a test, or the function in the same process). */
|
|
40
|
+
turns?: TurnCall;
|
|
41
|
+
/** The user's access key for the function, sent with every turn (`FetchTurnsOptions.getAccessToken`). */
|
|
42
|
+
getAccessToken?: () => Promise<string | undefined>;
|
|
43
|
+
/** The startup query list. The library's own list by default. */
|
|
44
|
+
startupList?: StartupList;
|
|
45
|
+
/** Called when the startup list starts and ends. */
|
|
46
|
+
onExploring?: (exploring: boolean) => void;
|
|
47
|
+
/**
|
|
48
|
+
* How answers are to be given, for a host with unified selection (the turn API's `AnswerMode`):
|
|
49
|
+
*
|
|
50
|
+
* - `auto`: the host selects elements from answers. The agent decides, question by question,
|
|
51
|
+
* whether a question asks to select; `AgentRun.resultType` says what each answer is.
|
|
52
|
+
* - `select`: the user's preference that every question is a selection request.
|
|
53
|
+
*
|
|
54
|
+
* Set from the host's settings, never from the question: the client does not scan questions.
|
|
55
|
+
*/
|
|
56
|
+
answerMode?: AnswerMode;
|
|
57
|
+
}
|
|
58
|
+
export interface AskOptions {
|
|
59
|
+
/** The text in the host's query editor, if any. */
|
|
60
|
+
editorText?: string;
|
|
61
|
+
/** The chat's earlier questions (`earlierQuestion`), so a follow-up has their context. */
|
|
62
|
+
earlier?: readonly EarlierQuestion[];
|
|
63
|
+
/** The token of the chat's last finished run (`AgentRun.token`). Opaque: kept and sent back, never read. */
|
|
64
|
+
token?: string;
|
|
65
|
+
/** This question's answer mode, in place of the client's (`AgentClientOptions.answerMode`). */
|
|
66
|
+
answerMode?: AnswerMode;
|
|
67
|
+
onStatus?: (status: AgentStatus) => void;
|
|
68
|
+
signal?: AbortSignal;
|
|
69
|
+
}
|
|
70
|
+
export declare class AgentClient {
|
|
71
|
+
private readonly options;
|
|
72
|
+
private readonly turns;
|
|
73
|
+
private explored;
|
|
74
|
+
/** The startup list's rows: undefined when there is no iModel, or when the list could not run. */
|
|
75
|
+
readonly startup: Promise<StartupResult[] | undefined>;
|
|
76
|
+
private constructor();
|
|
77
|
+
/** Start the client: the startup list begins to run at once (see `startup`). */
|
|
78
|
+
static start(options: AgentClientOptions): AgentClient;
|
|
79
|
+
private explore;
|
|
80
|
+
/**
|
|
81
|
+
* Read a query's rows on the iModel, up to the caps given: for a host that shows an answer's
|
|
82
|
+
* results. Throws when there is no iModel, or the query fails.
|
|
83
|
+
*/
|
|
84
|
+
read(ecsql: string, caps?: ResultCaps): Promise<Pick<QueryRows, "columns" | "rows" | "clipped" | "truncatedBy">>;
|
|
85
|
+
/** Answer one question. While the startup list still runs, it waits for it, with the status `exploring`. */
|
|
86
|
+
ask(question: string, options?: AskOptions): Promise<AgentRun>;
|
|
87
|
+
/**
|
|
88
|
+
* The elements a query returns, read in full (its `ECInstanceId` or `id` column, and `ClassName`),
|
|
89
|
+
* handed to `onKeys` in chunks as they are read: for selecting all the elements of an answer.
|
|
90
|
+
* Never throws: a failure is the
|
|
91
|
+
* selection's `error`, as when there is no iModel.
|
|
92
|
+
*/
|
|
93
|
+
readSelection(ecsql: string, onKeys?: (keys: InstanceKey[]) => void | Promise<void>, signal?: AbortSignal): Promise<RunSelection>;
|
|
94
|
+
/**
|
|
95
|
+
* The instance keys of ids, for selecting them: each element once with its class, read in
|
|
96
|
+
* batches, and how many of the ids were not elements. Throws when there is no iModel.
|
|
97
|
+
*/
|
|
98
|
+
instanceKeys(ids: readonly string[]): Promise<{
|
|
99
|
+
keys: InstanceKey[];
|
|
100
|
+
notElements: number;
|
|
101
|
+
}>;
|
|
102
|
+
/**
|
|
103
|
+
* The answer's query's rows, read once when the run ends: the host shows them, and a later
|
|
104
|
+
* question of the chat sends the first of them (`earlierQuestion`).
|
|
105
|
+
*/
|
|
106
|
+
private answerRows;
|
|
107
|
+
}
|
|
@@ -0,0 +1,134 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The client a host starts for an open iModel: it runs the startup list when it starts, then
|
|
3
|
+
* answers questions by driving turns with the function.
|
|
4
|
+
*
|
|
5
|
+
* ```ts
|
|
6
|
+
* const client = AgentClient.start({ runQuery: queryRunner(imodel), imodelName, functionUrl });
|
|
7
|
+
* const run = await client.ask("How many pipes are there?", { onStatus });
|
|
8
|
+
* ```
|
|
9
|
+
*/
|
|
10
|
+
import { readCapped } from "./caps.js";
|
|
11
|
+
import { driveTurns, fetchTurns, runStartupQueries } from "./client.js";
|
|
12
|
+
import { instanceKeys, readSelection } from "./selection.js";
|
|
13
|
+
import { ResultPages } from "./result-pages.js";
|
|
14
|
+
import defaultList from "./startup-queries.json";
|
|
15
|
+
/** The library's startup query list (`startup-queries.json`): what a client runs when it starts. */
|
|
16
|
+
export const DEFAULT_STARTUP_LIST = defaultList;
|
|
17
|
+
/** How much of an answer's rows the client reads for the host to show. */
|
|
18
|
+
export const ANSWER_CAPS = { maxRows: 200, maxChars: 200_000, maxCellChars: 400 };
|
|
19
|
+
/**
|
|
20
|
+
* An answer's query's rows, read once with `ANSWER_CAPS`, or the error it gave; undefined when
|
|
21
|
+
* there is no query. What `AgentClient.ask` keeps on the run, for the host and for later questions.
|
|
22
|
+
*/
|
|
23
|
+
export async function readAnswerRows(runQuery, query) {
|
|
24
|
+
if (!query)
|
|
25
|
+
return undefined;
|
|
26
|
+
try {
|
|
27
|
+
return await readCapped(await runQuery(query), ANSWER_CAPS);
|
|
28
|
+
}
|
|
29
|
+
catch (err) {
|
|
30
|
+
return { error: err instanceof Error ? err.message : String(err) };
|
|
31
|
+
}
|
|
32
|
+
}
|
|
33
|
+
export class AgentClient {
|
|
34
|
+
options;
|
|
35
|
+
turns;
|
|
36
|
+
explored = false;
|
|
37
|
+
/** The startup list's rows: undefined when there is no iModel, or when the list could not run. */
|
|
38
|
+
startup;
|
|
39
|
+
constructor(options) {
|
|
40
|
+
this.options = options;
|
|
41
|
+
if (options.turns)
|
|
42
|
+
this.turns = options.turns;
|
|
43
|
+
else if (options.functionUrl)
|
|
44
|
+
this.turns = fetchTurns(options.functionUrl, { getAccessToken: options.getAccessToken });
|
|
45
|
+
else
|
|
46
|
+
throw new Error("AgentClient needs functionUrl, or turns.");
|
|
47
|
+
this.startup = this.explore();
|
|
48
|
+
}
|
|
49
|
+
/** Start the client: the startup list begins to run at once (see `startup`). */
|
|
50
|
+
static start(options) {
|
|
51
|
+
return new AgentClient(options);
|
|
52
|
+
}
|
|
53
|
+
async explore() {
|
|
54
|
+
const { runQuery } = this.options;
|
|
55
|
+
if (!runQuery)
|
|
56
|
+
return undefined;
|
|
57
|
+
this.options.onExploring?.(true);
|
|
58
|
+
try {
|
|
59
|
+
// A list that cannot run leaves the block out, and the agent works without it.
|
|
60
|
+
return (await runStartupQueries(this.options.startupList ?? DEFAULT_STARTUP_LIST, runQuery)).results;
|
|
61
|
+
}
|
|
62
|
+
catch {
|
|
63
|
+
return undefined;
|
|
64
|
+
}
|
|
65
|
+
finally {
|
|
66
|
+
this.explored = true;
|
|
67
|
+
this.options.onExploring?.(false);
|
|
68
|
+
}
|
|
69
|
+
}
|
|
70
|
+
/**
|
|
71
|
+
* Read a query's rows on the iModel, up to the caps given: for a host that shows an answer's
|
|
72
|
+
* results. Throws when there is no iModel, or the query fails.
|
|
73
|
+
*/
|
|
74
|
+
async read(ecsql, caps = ANSWER_CAPS) {
|
|
75
|
+
if (!this.options.runQuery)
|
|
76
|
+
throw new Error("No iModel is open.");
|
|
77
|
+
return readCapped(await this.options.runQuery(ecsql), caps);
|
|
78
|
+
}
|
|
79
|
+
/** Answer one question. While the startup list still runs, it waits for it, with the status `exploring`. */
|
|
80
|
+
async ask(question, options = {}) {
|
|
81
|
+
const { runQuery, imodelName } = this.options;
|
|
82
|
+
if (!this.explored && this.options.runQuery)
|
|
83
|
+
options.onStatus?.({ phase: "exploring" });
|
|
84
|
+
const startup = await this.startup;
|
|
85
|
+
// The host's choice of mode. The agent decides what each question gets; the client never scans it.
|
|
86
|
+
const answerMode = options.answerMode ?? this.options.answerMode;
|
|
87
|
+
const client = {
|
|
88
|
+
runQuery,
|
|
89
|
+
imodel: imodelName !== undefined ? { name: imodelName, startup } : undefined,
|
|
90
|
+
editorText: options.editorText,
|
|
91
|
+
earlier: options.earlier,
|
|
92
|
+
token: options.token,
|
|
93
|
+
answerMode,
|
|
94
|
+
onPhase: (phase, ecsql) => options.onStatus?.(phase === "querying" ? { phase, ecsql: ecsql ?? "" } : { phase }),
|
|
95
|
+
signal: options.signal,
|
|
96
|
+
};
|
|
97
|
+
const run = await driveTurns(question, client, this.turns);
|
|
98
|
+
const query = run.structured?.query || run.query;
|
|
99
|
+
const answerRows = await this.answerRows(query);
|
|
100
|
+
// All the rows, for a table: paged by the query reader, starting from the rows already read.
|
|
101
|
+
const results = query && runQuery && answerRows && answerRows.error === undefined
|
|
102
|
+
? new ResultPages(runQuery, query, { columns: answerRows.columns ?? [], rows: answerRows.rows ?? [], complete: answerRows.truncatedBy === undefined && !answerRows.clipped })
|
|
103
|
+
: undefined;
|
|
104
|
+
return { ...run, ...(answerMode ? { answerMode } : {}), ...(answerRows ? { answerRows } : {}), ...(results ? { results } : {}) };
|
|
105
|
+
}
|
|
106
|
+
/**
|
|
107
|
+
* The elements a query returns, read in full (its `ECInstanceId` or `id` column, and `ClassName`),
|
|
108
|
+
* handed to `onKeys` in chunks as they are read: for selecting all the elements of an answer.
|
|
109
|
+
* Never throws: a failure is the
|
|
110
|
+
* selection's `error`, as when there is no iModel.
|
|
111
|
+
*/
|
|
112
|
+
async readSelection(ecsql, onKeys, signal) {
|
|
113
|
+
if (!this.options.runQuery)
|
|
114
|
+
return { error: "No iModel is open." };
|
|
115
|
+
return readSelection(this.options.runQuery, ecsql, onKeys, signal);
|
|
116
|
+
}
|
|
117
|
+
/**
|
|
118
|
+
* The instance keys of ids, for selecting them: each element once with its class, read in
|
|
119
|
+
* batches, and how many of the ids were not elements. Throws when there is no iModel.
|
|
120
|
+
*/
|
|
121
|
+
async instanceKeys(ids) {
|
|
122
|
+
if (!this.options.runQuery)
|
|
123
|
+
throw new Error("No iModel is open.");
|
|
124
|
+
return instanceKeys(this.options.runQuery, ids);
|
|
125
|
+
}
|
|
126
|
+
/**
|
|
127
|
+
* The answer's query's rows, read once when the run ends: the host shows them, and a later
|
|
128
|
+
* question of the chat sends the first of them (`earlierQuestion`).
|
|
129
|
+
*/
|
|
130
|
+
async answerRows(query) {
|
|
131
|
+
return this.options.runQuery ? readAnswerRows(this.options.runQuery, query) : undefined;
|
|
132
|
+
}
|
|
133
|
+
}
|
|
134
|
+
//# sourceMappingURL=agent-client.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"agent-client.js","sourceRoot":"","sources":["../../src/agent-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,UAAU,EAAoB,MAAM,WAAW,CAAC;AACzD,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,iBAAiB,EAAuF,MAAM,aAAa,CAAC;AAC7J,OAAO,EAAE,YAAY,EAAE,aAAa,EAAuC,MAAM,gBAAgB,CAAC;AAClG,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,WAAW,MAAM,wBAAwB,CAAC;AAGjD,oGAAoG;AACpG,MAAM,CAAC,MAAM,oBAAoB,GAAG,WAA0B,CAAC;AAQ/D,0EAA0E;AAC1E,MAAM,CAAC,MAAM,WAAW,GAAe,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,EAAE,OAAO,EAAE,YAAY,EAAE,GAAG,EAAE,CAAC;AAE9F;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,QAAqB,EAAE,KAAyB;IACnF,IAAI,CAAC,KAAK;QACR,OAAO,SAAS,CAAC;IACnB,IAAI,CAAC;QACH,OAAO,MAAM,UAAU,CAAC,MAAM,QAAQ,CAAC,KAAK,CAAC,EAAE,WAAW,CAAC,CAAC;IAC9D,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO,EAAE,KAAK,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC;IACrE,CAAC;AACH,CAAC;AA0CD,MAAM,OAAO,WAAW;IAMe;IALpB,KAAK,CAAW;IACzB,QAAQ,GAAG,KAAK,CAAC;IACzB,kGAAkG;IAClF,OAAO,CAAuC;IAE9D,YAAqC,OAA2B;QAA3B,YAAO,GAAP,OAAO,CAAoB;QAC9D,IAAI,OAAO,CAAC,KAAK;YACf,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC;aACxB,IAAI,OAAO,CAAC,WAAW;YAC1B,IAAI,CAAC,KAAK,GAAG,UAAU,CAAC,OAAO,CAAC,WAAW,EAAE,EAAE,cAAc,EAAE,OAAO,CAAC,cAAc,EAAE,CAAC,CAAC;;YAEzF,MAAM,IAAI,KAAK,CAAC,0CAA0C,CAAC,CAAC;QAC9D,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,OAAO,EAAE,CAAC;IAChC,CAAC;IAED,gFAAgF;IACzE,MAAM,CAAC,KAAK,CAAC,OAA2B;QAC7C,OAAO,IAAI,WAAW,CAAC,OAAO,CAAC,CAAC;IAClC,CAAC;IAEO,KAAK,CAAC,OAAO;QACnB,MAAM,EAAE,QAAQ,EAAE,GAAG,IAAI,CAAC,OAAO,CAAC;QAClC,IAAI,CAAC,QAAQ;YACX,OAAO,SAAS,CAAC;QACnB,IAAI,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC,IAAI,CAAC,CAAC;QACjC,IAAI,CAAC;YACH,+EAA+E;YAC/E,OAAO,CAAC,MAAM,iBAAiB,CAAC,IAAI,CAAC,OAAO,CAAC,WAAW,IAAI,oBAAoB,EAAE,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC;QACvG,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,SAAS,CAAC;QACnB,CAAC;gBAAS,CAAC;YACT,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC;YACrB,IAAI,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,CAAC;QACpC,CAAC;IACH,CAAC;IAED;;;OAGG;IACI,KAAK,CAAC,IAAI,CAAC,KAAa,EAAE,OAAmB,WAAW;QAC7D,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ;YACxB,MAAM,IAAI,KAAK,CAAC,oBAAoB,CAAC,CAAC;QACxC,OAAO,UAAU,CAAC,MAAM,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,IAAI,CAAC,CAAC;IAC9D,CAAC;IAED,4GAA4G;IACrG,KAAK,CAAC,GAAG,CAAC,QAAgB,EAAE,UAAsB,EAAE;QACzD,MAAM,EAAE,QAAQ,EAAE,UAAU,EAAE,GAAG,IAAI,CAAC,OAAO,CAAC;QAC9C,IAAI,CAAC,IAAI,CAAC,QAAQ,IAAI,IAAI,CAAC,OAAO,CAAC,QAAQ;YACzC,OAAO,CAAC,QAAQ,EAAE,CAAC,EAAE,KAAK,EAAE,WAAW,EAAE,CAAC,CAAC;QAC7C,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC;QACnC,mGAAmG;QACnG,MAAM,UAAU,GAA2B,OAAO,CAAC,UAAU,IAAI,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC;QACzF,MAAM,MAAM,GAAkB;YAC5B,QAAQ;YACR,MAAM,EAAE,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,SAAS;YAC5E,UAAU,EAAE,OAAO,CAAC,UAAU;YAC9B,OAAO,EAAE,OAAO,CAAC,OAAO;YACxB,KAAK,EAAE,OAAO,CAAC,KAAK;YACpB,UAAU;YACV,OAAO,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE,CAAC,OAAO,CAAC,QAAQ,EAAE,CAAC,KAAK,KAAK,UAAU,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC;YAC/G,MAAM,EAAE,OAAO,CAAC,MAAM;SACvB,CAAC;QACF,MAAM,GAAG,GAAG,MAAM,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC;QAC3D,MAAM,KAAK,GAAG,GAAG,CAAC,UAAU,EAAE,KAAK,IAAI,GAAG,CAAC,KAAK,CAAC;QACjD,MAAM,UAAU,GAAG,MAAM,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC;QAChD,6FAA6F;QAC7F,MAAM,OAAO,GAAG,KAAK,IAAI,QAAQ,IAAI,UAAU,IAAI,UAAU,CAAC,KAAK,KAAK,SAAS;YAC/E,CAAC,CAAC,IAAI,WAAW,CAAC,QAAQ,EAAE,KAAK,EAAE,EAAE,OAAO,EAAE,UAAU,CAAC,OAAO,IAAI,EAAE,EAAE,IAAI,EAAE,UAAU,CAAC,IAAI,IAAI,EAAE,EAAE,QAAQ,EAAE,UAAU,CAAC,WAAW,KAAK,SAAS,IAAI,CAAC,UAAU,CAAC,OAAO,EAAE,CAAC;YAC7K,CAAC,CAAC,SAAS,CAAC;QACd,OAAO,EAAE,GAAG,GAAG,EAAE,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC;IACnI,CAAC;IAED;;;;;OAKG;IACI,KAAK,CAAC,aAAa,CAAC,KAAa,EAAE,MAAsD,EAAE,MAAoB;QACpH,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ;YACxB,OAAO,EAAE,KAAK,EAAE,oBAAoB,EAAE,CAAC;QACzC,OAAO,aAAa,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IACrE,CAAC;IAED;;;OAGG;IACI,KAAK,CAAC,YAAY,CAAC,GAAsB;QAC9C,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ;YACxB,MAAM,IAAI,KAAK,CAAC,oBAAoB,CAAC,CAAC;QACxC,OAAO,YAAY,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;IAClD,CAAC;IAED;;;OAGG;IACK,KAAK,CAAC,UAAU,CAAC,KAAyB;QAChD,OAAO,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,cAAc,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IAC1F,CAAC;CACF"}
|
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Reading a query's rows up to the caps the function sends: the client's half of the row format.
|
|
3
|
+
*
|
|
4
|
+
* The function writes the text the model sees from these rows. The two halves must agree exactly,
|
|
5
|
+
* so the rules here are the turn API's, and the function is tested against them.
|
|
6
|
+
*/
|
|
7
|
+
import type { QueryRows, ResultCaps } from "./turn-api.js";
|
|
8
|
+
/**
|
|
9
|
+
* One query's results, streamed, so the reader can stop once a cap is reached: nothing should
|
|
10
|
+
* read two million rows to find that only the first two hundred were wanted.
|
|
11
|
+
*
|
|
12
|
+
* The runner that builds this **must** abbreviate blobs (`abbreviateBlobs` on the reader).
|
|
13
|
+
*/
|
|
14
|
+
export interface RawQueryResult {
|
|
15
|
+
columns: string[];
|
|
16
|
+
rows: AsyncIterable<unknown[]>;
|
|
17
|
+
}
|
|
18
|
+
/**
|
|
19
|
+
* Which rows of a result to read, passed to the iTwin.js query reader as its own options
|
|
20
|
+
* (`QueryOptions.limit` and `restartToken`): the reader asks the backend for exactly these rows,
|
|
21
|
+
* so a page of a large result is read without reading the rows before it.
|
|
22
|
+
*/
|
|
23
|
+
export interface QueryPageOptions {
|
|
24
|
+
/** The rows to read: `count` rows from `offset`. */
|
|
25
|
+
limit?: {
|
|
26
|
+
offset: number;
|
|
27
|
+
count: number;
|
|
28
|
+
};
|
|
29
|
+
/** A newer query with the same token cancels this one (the reader's `restartToken`). */
|
|
30
|
+
restartToken?: string;
|
|
31
|
+
}
|
|
32
|
+
export type RunRawQuery = (ecsql: string, page?: QueryPageOptions) => Promise<RawQueryResult>;
|
|
33
|
+
/**
|
|
34
|
+
* Read a result up to the caps:
|
|
35
|
+
*
|
|
36
|
+
* 1. stop before a row once there are `maxRows` rows (`truncatedBy: "rows"`);
|
|
37
|
+
* 2. stop before a row whose line would take the total past `maxChars` (`truncatedBy: "chars"`),
|
|
38
|
+
* but always keep the first row. A line is the row as a JSON array, with each long string as
|
|
39
|
+
* the function will show it, plus one character; the total starts at the length of
|
|
40
|
+
* `columns: ` and the column names as a JSON array;
|
|
41
|
+
* 3. cut each string to `maxCellChars`, and add `[row, column, full length]` to `clipped`.
|
|
42
|
+
*/
|
|
43
|
+
export declare function readCapped(result: RawQueryResult, caps: ResultCaps): Promise<Pick<QueryRows, "columns" | "rows" | "clipped" | "truncatedBy">>;
|