@alvera-ai/platform-sdk 0.11.0 → 0.12.1
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/.agent/AGENTS.md +4 -0
- package/.agent/ai_sandbox.md +25 -0
- package/.agent/cookbook/talk-to-data.md +139 -0
- package/.agent/datalakes.md +55 -0
- package/LICENSE +93 -0
- package/README.md +1 -1
- package/dist/index.d.mts +139 -1
- package/dist/index.d.mts.map +1 -1
- package/dist/index.mjs +69 -1
- package/dist/index.mjs.map +1 -1
- package/package.json +1 -1
package/.agent/AGENTS.md
CHANGED
|
@@ -438,6 +438,10 @@ full wire shape.
|
|
|
438
438
|
built-in row-mapping Liquid templates.
|
|
439
439
|
- [invite-team](./cookbook/invite-team.md) — invite a teammate into your tenant
|
|
440
440
|
(root / tenantless / tenant-scoped sessions in one flow).
|
|
441
|
+
- [talk-to-data](./cookbook/talk-to-data.md) — turn a datalake conversational:
|
|
442
|
+
natural language → reviewable SQL (`datalakes.textToSql`, data-free by
|
|
443
|
+
construction) → read-only execution returning a `{ data, meta }` row page or a
|
|
444
|
+
CSV export (`datalakes.executeSql`).
|
|
441
445
|
|
|
442
446
|
## Utility namespaces
|
|
443
447
|
|
package/.agent/ai_sandbox.md
CHANGED
|
@@ -179,6 +179,31 @@ via consumer-authored fragments is structurally impossible: the
|
|
|
179
179
|
fragment is the WHERE *expression*, with values supplied via
|
|
180
180
|
positional bindings the platform builds.
|
|
181
181
|
|
|
182
|
+
### Datalake "talk to data" — `textToSql` + `executeSql`
|
|
183
|
+
|
|
184
|
+
The datalake BI surface (`api.datalakes.textToSql` /
|
|
185
|
+
`api.datalakes.executeSql`, see `datalakes.md` "Talk to data") is
|
|
186
|
+
the **full-statement** sibling of the WHERE-clause lane above, and
|
|
187
|
+
it sits inside the same Layer-3 boundary:
|
|
188
|
+
|
|
189
|
+
- **Generation is data-free by construction.** `textToSql` sends
|
|
190
|
+
only the natural-language `prompt` plus the datalake **schema**
|
|
191
|
+
to the LLM — never rows. The model returns SQL for review; no
|
|
192
|
+
datalake data ever crosses the LLM boundary, so generation is
|
|
193
|
+
safe in both `regulated` and `unregulated` mode. The two-call
|
|
194
|
+
split (generate, then execute) exists so a human or agent can
|
|
195
|
+
inspect and edit the SQL before any data is read.
|
|
196
|
+
- **Execution is read-only and mode-routed.** `executeSql` runs the
|
|
197
|
+
statement against the mode-appropriate schema with a read-only
|
|
198
|
+
connection: INSERT/UPDATE/DELETE/DDL are rejected (app-layer
|
|
199
|
+
`@deny` + a read-only DB transaction + an EXPLAIN preflight), and
|
|
200
|
+
`mode` (`regulated` vs `unregulated`) plus the session's tenant
|
|
201
|
+
(RLS) decide which schema and which rows are reachable — the same
|
|
202
|
+
Layer-1 compliance gates that govern every other read.
|
|
203
|
+
- **Pagination caps blast radius.** `page` / `page_size` map to a
|
|
204
|
+
server-side `LIMIT/OFFSET` window capped at the platform default,
|
|
205
|
+
so a single call cannot exfiltrate an unbounded result set.
|
|
206
|
+
|
|
182
207
|
## How the three layers compose
|
|
183
208
|
|
|
184
209
|
```
|
|
@@ -0,0 +1,139 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: "Capability: talk to your datalake — natural language → SQL → rows"
|
|
3
|
+
summary: A capability walk for datalake text-to-SQL. Generate a read-only SQL statement from a natural-language prompt (`api.datalakes.textToSql`) — only the prompt + schema cross the LLM boundary, never rows — then run it read-only and read back the page (`api.datalakes.executeSql`), with both the JSON `{ data, meta }` envelope and a CSV export. The BI surface on a datalake.
|
|
4
|
+
industry: foundation
|
|
5
|
+
slug: talk-to-data
|
|
6
|
+
vitest_source:
|
|
7
|
+
- integration-tests/tests/foundation/text-to-sql.test.ts
|
|
8
|
+
status: green
|
|
9
|
+
---
|
|
10
|
+
|
|
11
|
+
# Capability
|
|
12
|
+
|
|
13
|
+
**What you get:** a two-call BI surface on a datalake — describe what you want in
|
|
14
|
+
plain language, get back reviewable SQL, then run it read-only and read the rows.
|
|
15
|
+
|
|
16
|
+
The split is deliberate: `textToSql` *generates*, `executeSql` *runs*. A UI or
|
|
17
|
+
agent can show the SQL, let a human edit it, and re-run — and the generate step
|
|
18
|
+
is **data-free by construction** (only the prompt + the datalake schema reach the
|
|
19
|
+
LLM, never rows), so it is safe in both `regulated` and `unregulated` mode.
|
|
20
|
+
|
|
21
|
+
1. `datalakes.textToSql(...)` — natural language → `{ sql, model, provider, explanation }`.
|
|
22
|
+
2. `datalakes.executeSql(...)` — read-only execution → `{ data, meta }` (data is an
|
|
23
|
+
array-of-arrays row page aligned to `meta.columns`), or a CSV string with
|
|
24
|
+
`{ format: 'csv' }`.
|
|
25
|
+
|
|
26
|
+
See `datalakes.md` "Talk to data" for the wire reference and `ai_sandbox.md`
|
|
27
|
+
Layer 3 for why the boundary holds.
|
|
28
|
+
|
|
29
|
+
# Walkthrough
|
|
30
|
+
|
|
31
|
+
The `_setup/foundation.md` bootstrap left `api`, `tenantSlug`, and `datalakeSlug`
|
|
32
|
+
populated, pointing at a freshly-migrated foundation datalake.
|
|
33
|
+
|
|
34
|
+
## 001 — generate SQL from a natural-language prompt
|
|
35
|
+
|
|
36
|
+
`textToSql` runs ordered multi-provider LLM failover and returns the generated
|
|
37
|
+
`sql` plus the winning `model` / `provider` and a best-effort `explanation`
|
|
38
|
+
(`null` when the explainer is unavailable). It does **not** execute the SQL — it
|
|
39
|
+
hands it back for review. Nothing but the prompt and the datalake schema is sent
|
|
40
|
+
to the model, so no datalake rows leave the trust boundary.
|
|
41
|
+
|
|
42
|
+
```typescript
|
|
43
|
+
const { data: gen } = await api.datalakes.textToSql(tenantSlug, datalakeSlug, {
|
|
44
|
+
prompt: 'how many legal entities are there?',
|
|
45
|
+
mode: 'unregulated',
|
|
46
|
+
})
|
|
47
|
+
if (typeof gen.sql !== 'string' || gen.sql.trim() === '') {
|
|
48
|
+
throw new Error(`textToSql returned no SQL (got: ${JSON.stringify(gen.sql)})`)
|
|
49
|
+
}
|
|
50
|
+
if (typeof gen.model !== 'string' || typeof gen.provider !== 'string') {
|
|
51
|
+
throw new Error('textToSql response missing model/provider attribution')
|
|
52
|
+
}
|
|
53
|
+
// gen.explanation is best-effort plain-language prose, or null.
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
## 002 — run a read-only query and read back the page
|
|
57
|
+
|
|
58
|
+
`executeSql` runs the SQL **read-only** (INSERT/UPDATE/DELETE/DDL are rejected)
|
|
59
|
+
and returns `{ data, meta }`. `data` is an **array-of-arrays** row page — positional,
|
|
60
|
+
aligned to `meta.columns`, because arbitrary SQL can have duplicate / expression
|
|
61
|
+
column names. `meta` carries the structural + pagination fields. A deterministic
|
|
62
|
+
`SELECT 1 AS n` keeps this step independent of the generated SQL and seeded data.
|
|
63
|
+
|
|
64
|
+
The curated return is `ExecuteSqlResponse | string` (the CSV branch is a string),
|
|
65
|
+
so narrow with a `typeof` guard before reading the JSON envelope.
|
|
66
|
+
|
|
67
|
+
```typescript
|
|
68
|
+
const jsonResult = await api.datalakes.executeSql(tenantSlug, datalakeSlug, {
|
|
69
|
+
sql: 'SELECT 1 AS n',
|
|
70
|
+
mode: 'unregulated',
|
|
71
|
+
})
|
|
72
|
+
if (typeof jsonResult.data === 'string') {
|
|
73
|
+
throw new Error('expected the JSON envelope, got a CSV string')
|
|
74
|
+
}
|
|
75
|
+
const page = jsonResult.data
|
|
76
|
+
if (!Array.isArray(page.data) || !Array.isArray(page.data[0])) {
|
|
77
|
+
throw new Error('executeSql data is not an array-of-arrays')
|
|
78
|
+
}
|
|
79
|
+
if (page.meta.columns[0] !== 'n' || page.data[0][0] !== 1 || page.meta.num_rows !== 1) {
|
|
80
|
+
throw new Error(`unexpected SELECT 1 result: ${JSON.stringify(page)}`)
|
|
81
|
+
}
|
|
82
|
+
// page.meta also carries total_count, page, page_size, total_pages, duration_ms, command.
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
## 003 — export the same page as CSV
|
|
86
|
+
|
|
87
|
+
Pass `{ format: 'csv' }` to get the page as a CSV **string** instead of the JSON
|
|
88
|
+
envelope — the same read, content-negotiated for download.
|
|
89
|
+
|
|
90
|
+
```typescript
|
|
91
|
+
const csvResult = await api.datalakes.executeSql(
|
|
92
|
+
tenantSlug,
|
|
93
|
+
datalakeSlug,
|
|
94
|
+
{ sql: 'SELECT 1 AS n', mode: 'unregulated' },
|
|
95
|
+
{ format: 'csv' },
|
|
96
|
+
)
|
|
97
|
+
if (typeof csvResult.data !== 'string') {
|
|
98
|
+
throw new Error('expected a CSV string for { format: "csv" }')
|
|
99
|
+
}
|
|
100
|
+
const csv = csvResult.data
|
|
101
|
+
if (!/\bn\b/.test(csv) || !csv.includes('1')) {
|
|
102
|
+
throw new Error(`unexpected CSV body: ${JSON.stringify(csv)}`)
|
|
103
|
+
}
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
# Branches
|
|
107
|
+
|
|
108
|
+
- **Generation failure.** If every configured LLM provider fails, `textToSql`
|
|
109
|
+
returns `422` (`AlveraApiError`) — `Text-to-SQL generation failed for all
|
|
110
|
+
providers (...)`. Surface it; do not retry blindly.
|
|
111
|
+
- **Write SQL rejected.** `executeSql` with a non-read-only statement
|
|
112
|
+
(`INSERT`/`UPDATE`/`DELETE`/DDL) is rejected `422` — the read-only boundary is
|
|
113
|
+
enforced at the app `@deny` regex, a read-only DB transaction, and an EXPLAIN
|
|
114
|
+
preflight.
|
|
115
|
+
- **Pagination.** Pass `page` / `page_size` to window large result sets;
|
|
116
|
+
`meta.total_count` / `meta.total_pages` describe the full set (`page_size` is
|
|
117
|
+
capped server-side).
|
|
118
|
+
|
|
119
|
+
# Rollback
|
|
120
|
+
|
|
121
|
+
Nothing to tear down — both calls are read-only (or generate-only). The
|
|
122
|
+
`_setup/foundation.md` tenant + datalake are reset with `mix ecto.reset` on the
|
|
123
|
+
platform; per-run `runSuffix` names avoid collisions across reruns.
|
|
124
|
+
|
|
125
|
+
# Outcome
|
|
126
|
+
|
|
127
|
+
A datalake becomes conversational: a prompt yields reviewable SQL with provider
|
|
128
|
+
attribution and a plain-language explanation, that SQL runs read-only, and the
|
|
129
|
+
page comes back either as a structured `{ data, meta }` envelope or a CSV export
|
|
130
|
+
— all without any datalake row ever reaching the LLM.
|
|
131
|
+
|
|
132
|
+
# See also
|
|
133
|
+
|
|
134
|
+
- `.agent/datalakes.md` — "Talk to data" (`textToSql` / `executeSql` wire shape)
|
|
135
|
+
and §6 gotcha on the array-of-arrays `data`.
|
|
136
|
+
- `.agent/ai_sandbox.md` — Layer 3 SQL boundary: how generation stays data-free
|
|
137
|
+
and execution stays read-only + mode-routed.
|
|
138
|
+
- `integration-tests/tests/foundation/text-to-sql.test.ts` — the green vitest
|
|
139
|
+
these snippets are lifted from.
|
package/.agent/datalakes.md
CHANGED
|
@@ -586,6 +586,52 @@ for (const name of catalog.datasets) {
|
|
|
586
586
|
}
|
|
587
587
|
```
|
|
588
588
|
|
|
589
|
+
### Talk to data — `textToSql` + `executeSql`
|
|
590
|
+
|
|
591
|
+
Two query methods turn the datalake into a BI surface: natural language → SQL →
|
|
592
|
+
rows. They are **split on purpose** so an agent or UI can show, edit, and re-run
|
|
593
|
+
the SQL between the two calls.
|
|
594
|
+
|
|
595
|
+
| Method | Returns |
|
|
596
|
+
|------------------------------------------------------------|-----------------------------------------------------------|
|
|
597
|
+
| `.textToSql(tenantSlug, datalakeSlug, body)` | `{ sql, model, provider, explanation }` |
|
|
598
|
+
| `.executeSql(tenantSlug, datalakeSlug, body, options?)` | `{ data, meta }` — or a CSV **string** with `{ format: 'csv' }` |
|
|
599
|
+
|
|
600
|
+
- **`textToSql`** body is `{ prompt, mode }` (`mode` ∈ `'regulated' | 'unregulated'`,
|
|
601
|
+
selecting which schema to target). It runs ordered multi-provider LLM failover and
|
|
602
|
+
returns the generated `sql`, the winning `model` + `provider`, and a best-effort
|
|
603
|
+
`explanation` (`null` when the explainer is unavailable). **Only the prompt + the
|
|
604
|
+
schema cross the LLM boundary — never datalake rows**, so it is safe in both modes.
|
|
605
|
+
It returns SQL for review; it does **not** execute it.
|
|
606
|
+
- **`executeSql`** body is `{ sql, mode, page?, page_size? }`. It runs the SQL
|
|
607
|
+
**read-only** (INSERT/UPDATE/DELETE/DDL are rejected) on the mode-appropriate
|
|
608
|
+
schema, with Flop-inspired pagination (`page_size` capped server-side). The JSON
|
|
609
|
+
shape is `{ data, meta }`; pass `options = { format: 'csv' }` to get the page as a
|
|
610
|
+
CSV string attachment instead.
|
|
611
|
+
|
|
612
|
+
```typescript
|
|
613
|
+
const { data: gen } = await api.datalakes.textToSql(tenantSlug, datalakeSlug, {
|
|
614
|
+
prompt: 'count contacts created this month',
|
|
615
|
+
mode: 'unregulated',
|
|
616
|
+
})
|
|
617
|
+
// gen.sql — review / edit before running
|
|
618
|
+
|
|
619
|
+
const { data: page } = await api.datalakes.executeSql(tenantSlug, datalakeSlug, {
|
|
620
|
+
sql: gen.sql,
|
|
621
|
+
mode: 'unregulated',
|
|
622
|
+
page: 1,
|
|
623
|
+
page_size: 100,
|
|
624
|
+
})
|
|
625
|
+
// page.data — array-of-arrays rows, aligned to page.meta.columns
|
|
626
|
+
// page.meta — { columns, num_rows, total_count, page, page_size, total_pages, duration_ms, command }
|
|
627
|
+
|
|
628
|
+
const { data: csv } = await api.datalakes.executeSql(
|
|
629
|
+
tenantSlug, datalakeSlug,
|
|
630
|
+
{ sql: gen.sql, mode: 'unregulated' },
|
|
631
|
+
{ format: 'csv' },
|
|
632
|
+
) // csv is a string, not the JSON envelope
|
|
633
|
+
```
|
|
634
|
+
|
|
589
635
|
## 6. Gotchas
|
|
590
636
|
|
|
591
637
|
1. **`create()` does NOT auto-enqueue migration.** The create response
|
|
@@ -712,3 +758,12 @@ for (const name of catalog.datasets) {
|
|
|
712
758
|
`"password"` — and consequently requires both `*_user` and
|
|
713
759
|
`*_pass` to be supplied. The IAM-role relaxation in §2 applies
|
|
714
760
|
only when `auth_method` is explicitly `"iam_role"`.
|
|
761
|
+
|
|
762
|
+
13. **`executeSql` rows are array-of-arrays, not objects.** `data` is
|
|
763
|
+
`Array<Array<unknown>>` — a positional row page with **no column
|
|
764
|
+
keys**, because arbitrary SQL can yield duplicate or expression
|
|
765
|
+
column names that have no safe object key. Read column names from
|
|
766
|
+
`meta.columns` and index rows positionally (`row[i]` ↔
|
|
767
|
+
`meta.columns[i]`); never assume `row.someColumn`. The `?format=csv`
|
|
768
|
+
branch returns a CSV **string** with no `meta` envelope — for the
|
|
769
|
+
structural metadata, use the JSON call.
|
package/LICENSE
ADDED
|
@@ -0,0 +1,93 @@
|
|
|
1
|
+
Elastic License 2.0
|
|
2
|
+
|
|
3
|
+
URL: https://www.elastic.co/licensing/elastic-license
|
|
4
|
+
|
|
5
|
+
## Acceptance
|
|
6
|
+
|
|
7
|
+
By using the software, you agree to all of the terms and conditions below.
|
|
8
|
+
|
|
9
|
+
## Copyright License
|
|
10
|
+
|
|
11
|
+
The licensor grants you a non-exclusive, royalty-free, worldwide,
|
|
12
|
+
non-sublicensable, non-transferable license to use, copy, distribute, make
|
|
13
|
+
available, and prepare derivative works of the software, in each case subject to
|
|
14
|
+
the limitations and conditions below.
|
|
15
|
+
|
|
16
|
+
## Limitations
|
|
17
|
+
|
|
18
|
+
You may not provide the software to third parties as a hosted or managed
|
|
19
|
+
service, where the service provides users with access to any substantial set of
|
|
20
|
+
the features or functionality of the software.
|
|
21
|
+
|
|
22
|
+
You may not move, change, disable, or circumvent the license key functionality
|
|
23
|
+
in the software, and you may not remove or obscure any functionality in the
|
|
24
|
+
software that is protected by the license key.
|
|
25
|
+
|
|
26
|
+
You may not alter, remove, or obscure any licensing, copyright, or other notices
|
|
27
|
+
of the licensor in the software. Any use of the licensor’s trademarks is subject
|
|
28
|
+
to applicable law.
|
|
29
|
+
|
|
30
|
+
## Patents
|
|
31
|
+
|
|
32
|
+
The licensor grants you a license, under any patent claims the licensor can
|
|
33
|
+
license, or becomes able to license, to make, have made, use, sell, offer for
|
|
34
|
+
sale, import and have imported the software, in each case subject to the
|
|
35
|
+
limitations and conditions in this license. This license does not cover any
|
|
36
|
+
patent claims that you cause to be infringed by modifications or additions to
|
|
37
|
+
the software. If you or your company make any written claim that the software
|
|
38
|
+
infringes or contributes to infringement of any patent, your patent license for
|
|
39
|
+
the software granted under these terms ends immediately. If your company makes
|
|
40
|
+
such a claim, your patent license ends immediately for work on behalf of your
|
|
41
|
+
company.
|
|
42
|
+
|
|
43
|
+
## Notices
|
|
44
|
+
|
|
45
|
+
You must ensure that anyone who gets a copy of any part of the software from you
|
|
46
|
+
also gets a copy of these terms.
|
|
47
|
+
|
|
48
|
+
If you modify the software, you must include in any modified copies of the
|
|
49
|
+
software prominent notices stating that you have modified the software.
|
|
50
|
+
|
|
51
|
+
## No Other Rights
|
|
52
|
+
|
|
53
|
+
These terms do not imply any licenses other than those expressly granted in
|
|
54
|
+
these terms.
|
|
55
|
+
|
|
56
|
+
## Termination
|
|
57
|
+
|
|
58
|
+
If you use the software in violation of these terms, such use is not licensed,
|
|
59
|
+
and your licenses will automatically terminate. If the licensor provides you
|
|
60
|
+
with a notice of your violation, and you cease all violation of this license no
|
|
61
|
+
later than 30 days after you receive that notice, your licenses will be
|
|
62
|
+
reinstated retroactively. However, if you violate these terms after such
|
|
63
|
+
reinstatement, any additional violation of these terms will cause your licenses
|
|
64
|
+
to terminate automatically and permanently.
|
|
65
|
+
|
|
66
|
+
## No Liability
|
|
67
|
+
|
|
68
|
+
*As far as the law allows, the software comes as is, without any warranty or
|
|
69
|
+
condition, and the licensor will not be liable to you for any damages arising
|
|
70
|
+
out of these terms or the use or nature of the software, under any kind of
|
|
71
|
+
legal claim.*
|
|
72
|
+
|
|
73
|
+
## Definitions
|
|
74
|
+
|
|
75
|
+
The **licensor** is the entity offering these terms, and the **software** is the
|
|
76
|
+
software the licensor makes available under these terms, including any portion
|
|
77
|
+
of it.
|
|
78
|
+
|
|
79
|
+
**you** refers to the individual or entity agreeing to these terms.
|
|
80
|
+
|
|
81
|
+
**your company** is any legal entity, sole proprietorship, or other kind of
|
|
82
|
+
organization that you work for, plus all organizations that have control over,
|
|
83
|
+
are under the control of, or are under common control with that
|
|
84
|
+
organization. **control** means ownership of substantially all the assets of an
|
|
85
|
+
entity, or the power to direct its management and policies by vote, contract, or
|
|
86
|
+
otherwise. Control can be direct or indirect.
|
|
87
|
+
|
|
88
|
+
**your licenses** are all the licenses granted to you for the software under
|
|
89
|
+
these terms.
|
|
90
|
+
|
|
91
|
+
**use** means anything you do with the software requiring one of your licenses.
|
|
92
|
+
|
|
93
|
+
**trademark** means trademarks, service marks, and similar rights.
|
package/README.md
CHANGED
|
@@ -132,7 +132,7 @@ Every resource is a typed namespace on the client (`api.<resource>.<verb>`):
|
|
|
132
132
|
| `tenants` | `list`, `create` |
|
|
133
133
|
| `invitations` | `list`, `create`, `accept` |
|
|
134
134
|
| `datasets` | `search`, `metadata`, `createUserSearch` |
|
|
135
|
-
| `datalakes` | `list`, `get`, `create`, `metadata`, `migrate`, `createUploadLink`, `createDownloadLink`
|
|
135
|
+
| `datalakes` | `list`, `get`, `create`, `metadata`, `migrate`, `createUploadLink`, `createDownloadLink`, `textToSql`, `executeSql` |
|
|
136
136
|
| `dataSources` | `list`, `create`, `update` |
|
|
137
137
|
| `tools` | `list`, `get`, `create`, `update`, `delete`, `testInvocation` |
|
|
138
138
|
| `genericTables` | `list`, `create` |
|
package/dist/index.d.mts
CHANGED
|
@@ -22,6 +22,21 @@ declare const DEFAULT_ENVIRONMENT: "prod";
|
|
|
22
22
|
type EnvironmentName = keyof typeof ENVIRONMENTS;
|
|
23
23
|
//#endregion
|
|
24
24
|
//#region src/generated/types.gen.d.ts
|
|
25
|
+
/**
|
|
26
|
+
* TextToSqlRequest
|
|
27
|
+
*
|
|
28
|
+
* Natural-language prompt to generate datalake SQL for, plus the data access mode.
|
|
29
|
+
*/
|
|
30
|
+
type TextToSqlRequest = {
|
|
31
|
+
/**
|
|
32
|
+
* Which datalake schema to target: `unregulated` (tokenized) or `regulated` (raw)
|
|
33
|
+
*/
|
|
34
|
+
mode: 'regulated' | 'unregulated';
|
|
35
|
+
/**
|
|
36
|
+
* Natural-language description of the desired query
|
|
37
|
+
*/
|
|
38
|
+
prompt: string;
|
|
39
|
+
};
|
|
25
40
|
/**
|
|
26
41
|
* UserSearchResponse
|
|
27
42
|
*
|
|
@@ -1055,6 +1070,49 @@ type ToolAwsLambdaResponse = AwsLambdaResponse & {
|
|
|
1055
1070
|
type ToolManualUploadResponse = ManualUploadResponse & {
|
|
1056
1071
|
tool_body_type: 'manual_upload';
|
|
1057
1072
|
};
|
|
1073
|
+
/**
|
|
1074
|
+
* ExecuteSqlMeta
|
|
1075
|
+
*
|
|
1076
|
+
* Structural and pagination metadata for an `execute-sql` result — enough for an agent to
|
|
1077
|
+
* reason about the shape of the result without scanning the rows. The pagination fields
|
|
1078
|
+
* (`page`, `page_size`, `total_count`, `total_pages`) mirror `PaginationMeta`; their values
|
|
1079
|
+
* come from the Lotus window result, not Flop.
|
|
1080
|
+
*
|
|
1081
|
+
*/
|
|
1082
|
+
type ExecuteSqlMeta = {
|
|
1083
|
+
/**
|
|
1084
|
+
* Result column names, in order
|
|
1085
|
+
*/
|
|
1086
|
+
columns: Array<string>;
|
|
1087
|
+
/**
|
|
1088
|
+
* SQL command tag (e.g. `SELECT`)
|
|
1089
|
+
*/
|
|
1090
|
+
command?: string | null;
|
|
1091
|
+
/**
|
|
1092
|
+
* Query execution time in milliseconds
|
|
1093
|
+
*/
|
|
1094
|
+
duration_ms?: number | null;
|
|
1095
|
+
/**
|
|
1096
|
+
* Rows returned in this page
|
|
1097
|
+
*/
|
|
1098
|
+
num_rows: number;
|
|
1099
|
+
/**
|
|
1100
|
+
* 1-based page number
|
|
1101
|
+
*/
|
|
1102
|
+
page: number;
|
|
1103
|
+
/**
|
|
1104
|
+
* Rows per page actually applied (after capping)
|
|
1105
|
+
*/
|
|
1106
|
+
page_size: number;
|
|
1107
|
+
/**
|
|
1108
|
+
* Total rows across all pages (null if uncounted)
|
|
1109
|
+
*/
|
|
1110
|
+
total_count: number | null;
|
|
1111
|
+
/**
|
|
1112
|
+
* Total pages (null if uncounted)
|
|
1113
|
+
*/
|
|
1114
|
+
total_pages: number | null;
|
|
1115
|
+
};
|
|
1058
1116
|
/**
|
|
1059
1117
|
* UpdatePageRequest
|
|
1060
1118
|
*
|
|
@@ -1925,6 +1983,31 @@ type DataSourceRequest = {
|
|
|
1925
1983
|
*/
|
|
1926
1984
|
uri: string;
|
|
1927
1985
|
};
|
|
1986
|
+
/**
|
|
1987
|
+
* ExecuteSqlRequest
|
|
1988
|
+
*
|
|
1989
|
+
* A read-only SQL statement to execute against the datalake, the data access mode, and
|
|
1990
|
+
* optional Flop-inspired pagination. `page_size` is capped server-side.
|
|
1991
|
+
*
|
|
1992
|
+
*/
|
|
1993
|
+
type ExecuteSqlRequest = {
|
|
1994
|
+
/**
|
|
1995
|
+
* Which datalake schema to query: `unregulated` (tokenized) or `regulated` (raw)
|
|
1996
|
+
*/
|
|
1997
|
+
mode: 'regulated' | 'unregulated';
|
|
1998
|
+
/**
|
|
1999
|
+
* 1-based page number
|
|
2000
|
+
*/
|
|
2001
|
+
page?: number | null;
|
|
2002
|
+
/**
|
|
2003
|
+
* Rows per page (capped at the server's default page size)
|
|
2004
|
+
*/
|
|
2005
|
+
page_size?: number | null;
|
|
2006
|
+
/**
|
|
2007
|
+
* Read-only SQL statement to execute
|
|
2008
|
+
*/
|
|
2009
|
+
sql: string;
|
|
2010
|
+
};
|
|
1928
2011
|
/**
|
|
1929
2012
|
* ToolManualUploadRequest
|
|
1930
2013
|
*/
|
|
@@ -3212,6 +3295,21 @@ type IngestFileRequest = {
|
|
|
3212
3295
|
*/
|
|
3213
3296
|
key: string;
|
|
3214
3297
|
};
|
|
3298
|
+
/**
|
|
3299
|
+
* ExecuteSqlResponse
|
|
3300
|
+
*
|
|
3301
|
+
* Read-only SQL result. `data` is the page of rows as an array-of-arrays (tabular, since
|
|
3302
|
+
* arbitrary SQL can have duplicate or expression column names that object keys would
|
|
3303
|
+
* collapse); the column names and pagination live in `meta`.
|
|
3304
|
+
*
|
|
3305
|
+
*/
|
|
3306
|
+
type ExecuteSqlResponse = {
|
|
3307
|
+
/**
|
|
3308
|
+
* Page of result rows; each row is an array of cell values aligned to `meta.columns`
|
|
3309
|
+
*/
|
|
3310
|
+
data: Array<Array<unknown>>;
|
|
3311
|
+
meta: ExecuteSqlMeta;
|
|
3312
|
+
};
|
|
3215
3313
|
/**
|
|
3216
3314
|
* ToolCloudWatchLogGroupResponse
|
|
3217
3315
|
*/
|
|
@@ -3438,6 +3536,32 @@ type ConnectedAppResponse = {
|
|
|
3438
3536
|
url: string;
|
|
3439
3537
|
}>;
|
|
3440
3538
|
};
|
|
3539
|
+
/**
|
|
3540
|
+
* TextToSqlResponse
|
|
3541
|
+
*
|
|
3542
|
+
* Generated SQL for a natural-language prompt. `explanation` is a best-effort plain-language
|
|
3543
|
+
* description of the SQL (`null` if the explainer was unavailable). The SQL is returned for
|
|
3544
|
+
* review/editing; run it via `POST .../execute-sql`.
|
|
3545
|
+
*
|
|
3546
|
+
*/
|
|
3547
|
+
type TextToSqlResponse = {
|
|
3548
|
+
/**
|
|
3549
|
+
* Plain-language explanation of what the SQL does; null when unavailable
|
|
3550
|
+
*/
|
|
3551
|
+
explanation: string | null;
|
|
3552
|
+
/**
|
|
3553
|
+
* The model that produced the SQL (e.g. `anthropic:claude-opus-4`)
|
|
3554
|
+
*/
|
|
3555
|
+
model: string;
|
|
3556
|
+
/**
|
|
3557
|
+
* The provider that produced the SQL (e.g. `anthropic`, `ollama`)
|
|
3558
|
+
*/
|
|
3559
|
+
provider: string;
|
|
3560
|
+
/**
|
|
3561
|
+
* The generated SQL statement
|
|
3562
|
+
*/
|
|
3563
|
+
sql: string;
|
|
3564
|
+
};
|
|
3441
3565
|
/**
|
|
3442
3566
|
* AgenticWorkflowListResponse
|
|
3443
3567
|
*
|
|
@@ -6170,6 +6294,20 @@ declare function _buildApi(myClient: Client): {
|
|
|
6170
6294
|
request: Request;
|
|
6171
6295
|
response: Response;
|
|
6172
6296
|
}>;
|
|
6297
|
+
textToSql: (tenantSlug: string, datalakeSlug: string, body: TextToSqlRequest) => Promise<{
|
|
6298
|
+
data: TextToSqlResponse;
|
|
6299
|
+
request: Request;
|
|
6300
|
+
response: Response;
|
|
6301
|
+
}>;
|
|
6302
|
+
executeSql: (tenantSlug: string, datalakeSlug: string, body: ExecuteSqlRequest, options?: {
|
|
6303
|
+
format?: "csv";
|
|
6304
|
+
}) => Promise<Omit<Awaited<Promise<{
|
|
6305
|
+
data: ExecuteSqlResponse;
|
|
6306
|
+
request: Request;
|
|
6307
|
+
response: Response;
|
|
6308
|
+
}>>, "data"> & {
|
|
6309
|
+
data: ExecuteSqlResponse | string;
|
|
6310
|
+
}>;
|
|
6173
6311
|
};
|
|
6174
6312
|
dataSources: {
|
|
6175
6313
|
list: (tenantSlug: string, datalakeSlug: string, query?: PlatformApiDataSourceControllerIndexData["query"]) => Promise<{
|
|
@@ -6694,5 +6832,5 @@ declare function _buildApi(myClient: Client): {
|
|
|
6694
6832
|
//#region src/index.d.ts
|
|
6695
6833
|
declare function isEnvironmentName(name: string): name is EnvironmentName;
|
|
6696
6834
|
//#endregion
|
|
6697
|
-
export { type ActionStatusUpdaterCloudWatchQueryRequest, type ActionStatusUpdaterResponse, type ActionStatusUpdaterRestCallRequest, ActionType, type AgenticWorkflowListResponse, type AgenticWorkflowRequestWritable, type AgenticWorkflowResponse, type AiAgentResponse, type AlveraApiError, type AlveraClient, type ApiConfig, type ApiDebugConfig, type BatchLogListResponse, type BatchLogResponse, type ConnectedAppListResponse, type ConnectedAppRequestWritable, type ConnectedAppResponse, type CreateActionStatusUpdaterRequest, type CreateAiAgentRequest, type CreateGenericTableRequest, type CreateSessionParams, DEFAULT_ENVIRONMENT, type DataActivationClientListResponse, type DataActivationClientLogListResponse, type DataActivationClientLogResponse, type DataActivationClientRequestWritable, type DataActivationClientResponse, type DataSourceRequest, type DataSourceRequestWritable, type DataSourceResponse, type DatalakeRequestWritable, type DatalakeResponse, type DatasetMetadataOptions, type DatasetSearchOptions, type DatasetSearchResponse, type DownloadUrlResponse, ENVIRONMENTS, type EnvironmentName, type ErrorResponse, type ExecuteActionRequest, type ExecuteActionResponse, type GenericTableColumnRequest, type GenericTableColumnResponse, type GenericTableResponse, type IngestFileRequest, type IngestRequest, type InteroperabilityContractAiAgentRequestWritable, type InteroperabilityContractListResponse, type InteroperabilityContractRequestWritable, type InteroperabilityContractResponse, type InteroperabilityRunRequest, type InteroperabilityRunResponse, type MdmVerifyRequest, type MdmVerifyResponse, type PaginationMeta, type PlatformApi, type ResolvePageRequest, type RunManuallyRequestWritable, type RunManuallyResponse, type RunWorkflowRequest, type RunWorkflowResponse, type SessionResponse, type SessionResult, type SyncRoutesResponse, type TemplateConfig, type TenantListResponse, type TenantResponse, ToolIntent, type ToolRequest, type ToolRequestWritable, type ToolResponse, type UpdatePageRequest, type UploadLinkRequest, type UploadLinkResponse, type WorkflowAiAgentRequestWritable, type WorkflowLogListResponse, type WorkflowLogResponse, createIsolatedPlatformApi, createPlatformApi, createSession, isEnvironmentName, revokeSession };
|
|
6835
|
+
export { type ActionStatusUpdaterCloudWatchQueryRequest, type ActionStatusUpdaterResponse, type ActionStatusUpdaterRestCallRequest, ActionType, type AgenticWorkflowListResponse, type AgenticWorkflowRequestWritable, type AgenticWorkflowResponse, type AiAgentResponse, type AlveraApiError, type AlveraClient, type ApiConfig, type ApiDebugConfig, type BatchLogListResponse, type BatchLogResponse, type ConnectedAppListResponse, type ConnectedAppRequestWritable, type ConnectedAppResponse, type CreateActionStatusUpdaterRequest, type CreateAiAgentRequest, type CreateGenericTableRequest, type CreateSessionParams, DEFAULT_ENVIRONMENT, type DataActivationClientListResponse, type DataActivationClientLogListResponse, type DataActivationClientLogResponse, type DataActivationClientRequestWritable, type DataActivationClientResponse, type DataSourceRequest, type DataSourceRequestWritable, type DataSourceResponse, type DatalakeRequestWritable, type DatalakeResponse, type DatasetMetadataOptions, type DatasetSearchOptions, type DatasetSearchResponse, type DownloadUrlResponse, ENVIRONMENTS, type EnvironmentName, type ErrorResponse, type ExecuteActionRequest, type ExecuteActionResponse, type ExecuteSqlMeta, type ExecuteSqlRequest, type ExecuteSqlResponse, type GenericTableColumnRequest, type GenericTableColumnResponse, type GenericTableResponse, type IngestFileRequest, type IngestRequest, type InteroperabilityContractAiAgentRequestWritable, type InteroperabilityContractListResponse, type InteroperabilityContractRequestWritable, type InteroperabilityContractResponse, type InteroperabilityRunRequest, type InteroperabilityRunResponse, type MdmVerifyRequest, type MdmVerifyResponse, type PaginationMeta, type PlatformApi, type ResolvePageRequest, type RunManuallyRequestWritable, type RunManuallyResponse, type RunWorkflowRequest, type RunWorkflowResponse, type SessionResponse, type SessionResult, type SyncRoutesResponse, type TemplateConfig, type TenantListResponse, type TenantResponse, type TextToSqlRequest, type TextToSqlResponse, ToolIntent, type ToolRequest, type ToolRequestWritable, type ToolResponse, type UpdatePageRequest, type UploadLinkRequest, type UploadLinkResponse, type WorkflowAiAgentRequestWritable, type WorkflowLogListResponse, type WorkflowLogResponse, createIsolatedPlatformApi, createPlatformApi, createSession, isEnvironmentName, revokeSession };
|
|
6698
6836
|
//# sourceMappingURL=index.d.mts.map
|