@vxil/sdk 0.37.1 → 0.38.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/dist/index.d.ts +84 -12
- package/package.json +1 -1
package/dist/index.d.ts
CHANGED
|
@@ -1519,6 +1519,12 @@ export interface AiUsage {
|
|
|
1519
1519
|
* need no adjustment — these are for your own visibility. */
|
|
1520
1520
|
cache_creation_input_tokens?: number;
|
|
1521
1521
|
cache_read_input_tokens?: number;
|
|
1522
|
+
/** Thinking / reasoning tokens, present only when the provider reports them
|
|
1523
|
+
* (Gemini, and Anthropic when it sends a breakdown). Already INSIDE
|
|
1524
|
+
* `output_tokens` — a breakdown, never added again. Like the cache counts,
|
|
1525
|
+
* these are on the generation record and the `?since=` usage frame too, and
|
|
1526
|
+
* never change metering. */
|
|
1527
|
+
thinking_tokens?: number;
|
|
1522
1528
|
}
|
|
1523
1529
|
/** One tool invocation the model asked for (tool-use passthrough — vxil relays,
|
|
1524
1530
|
* YOU execute). Echo `id` back as `tool_call_id` on the `role:'tool'` turn. */
|
|
@@ -1541,6 +1547,13 @@ export type AiThinkingLevel = 'minimal' | 'low' | 'medium' | 'high';
|
|
|
1541
1547
|
* with `ai.templates.put`) → `features.ai.defaults.mediaResolution` → the
|
|
1542
1548
|
* model's own default. */
|
|
1543
1549
|
export type AiMediaResolution = 'low' | 'medium' | 'high';
|
|
1550
|
+
/** Anthropic effort for `ai.generate` / `stream` / `generateAsync` (`effort`):
|
|
1551
|
+
* how much the model thinks and spends before it answers. Sent to Anthropic
|
|
1552
|
+
* only, as `output_config.effort` — every other provider ignores it; omitted →
|
|
1553
|
+
* `features.ai.defaults.effort` → the model's own default. A level a model does
|
|
1554
|
+
* not accept is the provider's own error. Thinking tokens are billed as output
|
|
1555
|
+
* tokens. Never derived from `thinking_level`. */
|
|
1556
|
+
export type AiEffort = 'low' | 'medium' | 'high' | 'xhigh' | 'max';
|
|
1544
1557
|
/** A prior conversation turn for the tool-calling round-trip: assistant turns
|
|
1545
1558
|
* carry the tool_calls they made; `role:'tool'` turns carry one call's result
|
|
1546
1559
|
* (`tool_call_id` correlates it; `name` is the tool's name). */
|
|
@@ -1582,8 +1595,9 @@ export interface AiStreamHandle {
|
|
|
1582
1595
|
/** Frames delivered over the ai-<generation_id> realtime channel and the
|
|
1583
1596
|
* ?since= replay buffer (the WS envelope is { event, data } — `event` is the
|
|
1584
1597
|
* frame type; replayed frames carry it as `type`). `title` arrives early when
|
|
1585
|
-
* the stream was requested with title/title_template;
|
|
1586
|
-
* frame carries done:true
|
|
1598
|
+
* the stream was requested with title/title_template; the terminal frame —
|
|
1599
|
+
* usage, or the error frame — carries done:true, so narrow a usage frame with
|
|
1600
|
+
* `'usage' in frame`, not `frame.done`. */
|
|
1587
1601
|
export type AiStreamFrame = {
|
|
1588
1602
|
type?: 'token';
|
|
1589
1603
|
seq: number;
|
|
@@ -1596,10 +1610,38 @@ export type AiStreamFrame = {
|
|
|
1596
1610
|
type?: 'usage';
|
|
1597
1611
|
seq: number;
|
|
1598
1612
|
done: true;
|
|
1613
|
+
/** the provider's own finish word (only `tool_use` is normalised), or
|
|
1614
|
+
* `schema_mismatch` when a structured answer failed its schema */
|
|
1599
1615
|
finish: string;
|
|
1600
1616
|
usage: AiUsage;
|
|
1601
1617
|
tool_calls?: AiToolCall[];
|
|
1618
|
+
/** the structured-output repair fixed the answer */
|
|
1619
|
+
repaired?: boolean;
|
|
1620
|
+
/** the stored answer was cut at 262,144 characters (vxil's storage cut,
|
|
1621
|
+
* not a token cut) */
|
|
1622
|
+
truncated?: boolean;
|
|
1623
|
+
}
|
|
1624
|
+
/** The terminal failure frame. Live on `ai-<generation_id>`: `{ done,
|
|
1625
|
+
* message }` from a stream, `{ seq: 1, done, message, error_class }` from a
|
|
1626
|
+
* job-lane run — never a hint. Replayed by `?since=` for a failed job-lane
|
|
1627
|
+
* generation, with `hint` (the provider's own error text, up to 200
|
|
1628
|
+
* characters) for API-key callers only — never for an end-user session. */
|
|
1629
|
+
| {
|
|
1630
|
+
type?: 'error';
|
|
1631
|
+
seq?: number;
|
|
1632
|
+
done: true;
|
|
1633
|
+
message: string;
|
|
1634
|
+
error_class?: string | null;
|
|
1635
|
+
hint?: string;
|
|
1602
1636
|
};
|
|
1637
|
+
/** The request's `repair` (`ai.generate` / `generateAsync`, with a response
|
|
1638
|
+
* schema): `false` = no repair call — an invalid answer is
|
|
1639
|
+
* `output_schema_mismatch` after ONE call. Omitted / `true` = one repair call
|
|
1640
|
+
* when it can help; never after a refusal, a safety stop, a length cut or an
|
|
1641
|
+
* empty answer, which keep the provider's own finish word (`refusal`,
|
|
1642
|
+
* `max_tokens`, `MAX_TOKENS`, `length`, `content_filter`, …) on the record
|
|
1643
|
+
* and the frame, and in the sync 422's `details.finish`. */
|
|
1644
|
+
export type AiRepair = boolean;
|
|
1603
1645
|
/** The live-only `token_expiring` event (never seq'd, never replayed): fired
|
|
1604
1646
|
* ~30s before each 300s connect-token window ends on a long stream. Re-mint
|
|
1605
1647
|
* via ai.remintToken() and reconnect with ?since=<last seen seq>. */
|
|
@@ -1649,13 +1691,20 @@ export interface AiGenerationRecord {
|
|
|
1649
1691
|
provider: string;
|
|
1650
1692
|
model: string;
|
|
1651
1693
|
template: string | null;
|
|
1652
|
-
|
|
1653
|
-
|
|
1654
|
-
|
|
1655
|
-
|
|
1694
|
+
/** input / output, plus `cache_creation_input_tokens`,
|
|
1695
|
+
* `cache_read_input_tokens` and `thinking_tokens` when Anthropic or
|
|
1696
|
+
* Gemini report them (cache counts: Anthropic; thinking: either; absent
|
|
1697
|
+
* otherwise, never 0) — summed over the first call and the repair */
|
|
1698
|
+
usage: AiUsage;
|
|
1656
1699
|
cached: boolean;
|
|
1700
|
+
/** the structured-output repair call fixed the answer (optional: a server
|
|
1701
|
+
* before 2026-11 does not send it) */
|
|
1702
|
+
repaired?: boolean;
|
|
1657
1703
|
created_at: string;
|
|
1658
1704
|
settled_at: string | null;
|
|
1705
|
+
/** `finish` is the provider's own word (only `tool_use` is normalised) or
|
|
1706
|
+
* `schema_mismatch`; `truncated` is vxil's 262,144-character storage cut,
|
|
1707
|
+
* not a token cut */
|
|
1659
1708
|
result: {
|
|
1660
1709
|
text: string;
|
|
1661
1710
|
finish: string;
|
|
@@ -1665,11 +1714,23 @@ export interface AiGenerationRecord {
|
|
|
1665
1714
|
* user was erased) · `not_recorded` (not settled yet, or a sync/stream
|
|
1666
1715
|
* generation) */
|
|
1667
1716
|
result_state: 'stored' | 'purged' | 'not_recorded';
|
|
1668
|
-
/** a job-lane generation's
|
|
1669
|
-
*
|
|
1670
|
-
*
|
|
1671
|
-
*
|
|
1672
|
-
|
|
1717
|
+
/** a job-lane generation's execution attempts — one per attempt, timing
|
|
1718
|
+
* its FIRST provider call (the repair's own time is `repair_ms`), with the
|
|
1719
|
+
* upstream HTTP status and error class — oldest first, at most 10 kept. A
|
|
1720
|
+
* retried attempt shows up here with the status the model provider
|
|
1721
|
+
* answered. Empty on a sync/stream generation and before the first call
|
|
1722
|
+
* returned */
|
|
1723
|
+
attempts?: AiGenerationAttempt[];
|
|
1724
|
+
}
|
|
1725
|
+
/** One execution attempt on GET /v1/ai/generations/{id}. */
|
|
1726
|
+
export interface AiGenerationAttempt extends GenerationProviderAttempt {
|
|
1727
|
+
/** the structured-output repair call's time, in ms, on the settling
|
|
1728
|
+
* attempt when a repair ran */
|
|
1729
|
+
repair_ms?: number;
|
|
1730
|
+
/** on a failed or released attempt: the provider's own error text, up to
|
|
1731
|
+
* 200 characters (vxil never adds the prompt). API-key callers only —
|
|
1732
|
+
* never on an end-user session's read */
|
|
1733
|
+
hint?: string;
|
|
1673
1734
|
}
|
|
1674
1735
|
/** The `data` of `job.generation.queued` (guide ch. 6, jobs): the run was accepted. */
|
|
1675
1736
|
export interface JobGenerationQueuedEventPayload {
|
|
@@ -7096,6 +7157,8 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
|
|
|
7096
7157
|
thinking_level?: AiThinkingLevel;
|
|
7097
7158
|
/** Gemini per-image / per-page token budget — see AiMediaResolution. */
|
|
7098
7159
|
media_resolution?: AiMediaResolution;
|
|
7160
|
+
/** Anthropic effort — see AiEffort. */
|
|
7161
|
+
effort?: AiEffort;
|
|
7099
7162
|
tools?: Array<{
|
|
7100
7163
|
name: string;
|
|
7101
7164
|
description?: string;
|
|
@@ -7112,6 +7175,8 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
|
|
|
7112
7175
|
* still-invalid result is a 422 `output_schema_mismatch` (billed). Wins
|
|
7113
7176
|
* over the template's stored schema. */
|
|
7114
7177
|
response_schema?: Record<string, unknown>;
|
|
7178
|
+
/** See AiRepair: `false` = no repair call on an invalid structured answer. */
|
|
7179
|
+
repair?: AiRepair;
|
|
7115
7180
|
images?: string[];
|
|
7116
7181
|
/** DOCUMENT inputs (pdf / plain text), up to 8 refs, each a public https
|
|
7117
7182
|
* URL, a `data:application/pdf;base64,…` (or `text/plain`) URL, or
|
|
@@ -7158,6 +7223,8 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
|
|
|
7158
7223
|
thinking_level?: AiThinkingLevel;
|
|
7159
7224
|
/** Gemini per-image / per-page token budget — see AiMediaResolution. */
|
|
7160
7225
|
media_resolution?: AiMediaResolution;
|
|
7226
|
+
/** Anthropic effort — see AiEffort. */
|
|
7227
|
+
effort?: AiEffort;
|
|
7161
7228
|
tools?: Array<{
|
|
7162
7229
|
name: string;
|
|
7163
7230
|
description?: string;
|
|
@@ -7197,6 +7264,8 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
|
|
|
7197
7264
|
thinking_level?: AiThinkingLevel;
|
|
7198
7265
|
/** Gemini per-image / per-page token budget — see AiMediaResolution. */
|
|
7199
7266
|
media_resolution?: AiMediaResolution;
|
|
7267
|
+
/** Anthropic effort — see AiEffort. */
|
|
7268
|
+
effort?: AiEffort;
|
|
7200
7269
|
tools?: Array<{
|
|
7201
7270
|
name: string;
|
|
7202
7271
|
description?: string;
|
|
@@ -7207,8 +7276,11 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
|
|
|
7207
7276
|
/** JSON Schema the completion must satisfy — same contract as
|
|
7208
7277
|
* `generate`; the validated answer lands in the replay buffer (a
|
|
7209
7278
|
* schema-mismatch delivers finish:'schema_mismatch' on the terminal
|
|
7210
|
-
* usage frame
|
|
7279
|
+
* usage frame, or the provider's own word when the answer could not be
|
|
7280
|
+
* repaired). */
|
|
7211
7281
|
response_schema?: Record<string, unknown>;
|
|
7282
|
+
/** See AiRepair: `false` = no repair call on an invalid structured answer. */
|
|
7283
|
+
repair?: AiRepair;
|
|
7212
7284
|
images?: string[];
|
|
7213
7285
|
/** DOCUMENT inputs (pdf / plain text), up to 8 refs, each a public https
|
|
7214
7286
|
* URL, a `data:application/pdf;base64,…` (or `text/plain`) URL, or
|
package/package.json
CHANGED