@genex-ai/embed-sdk 0.25.0 → 0.27.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/README.md +175 -84
- package/dist/{chunk-THXJ4IMO.js → chunk-7SWNXF5V.js} +275 -17
- package/dist/{chunk-VPIQVRVS.js → chunk-MJPLBT3T.js} +15 -0
- package/dist/development.d.ts +20 -14
- package/dist/development.js +19 -10
- package/dist/index.d.ts +81 -19
- package/dist/index.js +4 -2
- package/dist/sentry.js +2 -2
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -26,7 +26,7 @@ generateButton.addEventListener('click', async () => {
|
|
|
26
26
|
if (!model) return;
|
|
27
27
|
const result = await generate({
|
|
28
28
|
modelId: model.id,
|
|
29
|
-
|
|
29
|
+
maxCredits: 5, // This call's ceiling in the player's credits — benchmark it (genex llm bench).
|
|
30
30
|
prompt: 'Invent a friendly creature. Return its name and color as JSON.',
|
|
31
31
|
outputFormat: 'json',
|
|
32
32
|
schema: {
|
|
@@ -50,7 +50,9 @@ trusted Genex parent to show its modal. Native WebViews and local-test identity
|
|
|
50
50
|
return `native_unsupported` and `local_test_unsupported` until they have supported
|
|
51
51
|
confirmation surfaces.
|
|
52
52
|
|
|
53
|
-
`GenerateOptions` requires `
|
|
53
|
+
`GenerateOptions` requires `maxCredits` (SDK **0.27.0+**; an integer from 1 to
|
|
54
|
+
1,000,000 — the call's ceiling in the player's credits; `estimateCoins`, its old
|
|
55
|
+
name, is still accepted as the same number), `modelId`, `prompt`, `outputFormat: 'text' | 'json'`,
|
|
54
56
|
optional bounded `schema`, `allowExternal` (default false), `idempotencyKey`,
|
|
55
57
|
`timeoutMs` (default ten minutes) and `grantId` — a standing budget the player
|
|
56
58
|
already approved, which removes the popup entirely (see *Standing budgets*). Reuse an idempotency key only for the same
|
|
@@ -64,28 +66,37 @@ but it does not imply that consumed work was free. `pending` with
|
|
|
64
66
|
`error: 'wait_timeout'` means the SDK stopped waiting; it does not cancel or charge
|
|
65
67
|
again. Persist `generationId` and resume with `waitForGeneration(id)`, or inspect
|
|
66
68
|
the current server state with `getGeneration(id)`. Results also carry the
|
|
67
|
-
server's `billingStatus: 'pending'|'final'`, `
|
|
68
|
-
`
|
|
69
|
-
available, including on failures
|
|
69
|
+
server's `billingStatus: 'pending'|'final'`, `currency`, `chargedCredits`,
|
|
70
|
+
`reservedCredits`, `maxCredits`, `chargedDisplayUsdCents` and
|
|
71
|
+
`reservedDisplayUsdCents` when available, including on failures (`chargedCoins`
|
|
72
|
+
and `reservedCoins` stay present, and 0, on a credit receipt, for code written
|
|
73
|
+
before credits). These USD amounts use the frozen credit value;
|
|
70
74
|
never derive them from an estimate or the current catalog. An execution can end
|
|
71
75
|
while billing remains pending. `waitForGeneration()` waits for execution;
|
|
72
76
|
continue reading `getGeneration(id)` for later billing settlement. Missing
|
|
73
77
|
receipt fields mean unavailable information, not zero cost.
|
|
74
78
|
|
|
75
|
-
|
|
76
|
-
the frozen request
|
|
77
|
-
|
|
78
|
-
`
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
79
|
+
**In-game calls are paid from the player's Genex credits and billed as used.**
|
|
80
|
+
The Genex modal shows the game, the frozen request and "billed as used, up to N
|
|
81
|
+
credits" with its USD equivalent before approval. New quotes carry
|
|
82
|
+
`quote.billingPolicy: 'metered-credits-v1'`, `kind: 'metered'`, `currency:
|
|
83
|
+
'credits'` and `quote.maxCredits` — the call's quoted maximum with the Genex
|
|
84
|
+
fee, never above your `maxCredits`. Approval holds that many credits; when the
|
|
85
|
+
call settles it is charged its REAL model cost plus the Genex fee, rounded up
|
|
86
|
+
to a whole credit (so a very small one-time call costs one credit), and the rest
|
|
87
|
+
is released. Model work that fails or is canceled is still charged for what it
|
|
88
|
+
used; a request the provider refused before any work, or verified zero model
|
|
89
|
+
cost, is free. `maxCredits` is a ceiling, not a price: it caps what one call
|
|
90
|
+
may reach and funds how long its answer may be. Every Genex API model needs a
|
|
91
|
+
positive ceiling, including Gemini and GLM. A player who has not verified their
|
|
92
|
+
email is refused (`credits_unverified`), one short of credits sees
|
|
93
|
+
`insufficient_credits`, and Genex may pause paid generation platform-wide
|
|
94
|
+
(`generation_paused`). Personal funding chosen in the trusted approval modal
|
|
95
|
+
costs nothing on Genex. Quotes issued before 0.27's server change — `declared-v1`,
|
|
96
|
+
a fixed coin price per started attempt — keep their terms.
|
|
97
|
+
|
|
98
|
+
The provider hard budget is derived from that ceiling after the frozen platform
|
|
99
|
+
fee, then capped by operator limits. Output is clipped to remaining funding;
|
|
89
100
|
an input that cannot fit is refused before a call. Unresolved provider expense
|
|
90
101
|
keeps billing pending and the reservation held until verified. The trusted UI
|
|
91
102
|
must acknowledge the quote's exact `billingPolicy` at confirmation; an old UI
|
|
@@ -96,10 +107,10 @@ unconfirmed zero-price API quote needs a fresh price review before coin approval
|
|
|
96
107
|
never silently replace its price or start a paid request during recovery.
|
|
97
108
|
|
|
98
109
|
With `allowExternal: true`, Genex can offer the configured personal plan matching
|
|
99
|
-
the selected model alongside
|
|
110
|
+
the selected model alongside credits: Claude for `anthropic/` models, ChatGPT for
|
|
100
111
|
`openai/` models, and neither for other models. This choice appears only in the
|
|
101
112
|
trusted Genex approval modal; never add a "Your Plan" model row in the game.
|
|
102
|
-
Each personal choice costs
|
|
113
|
+
Each personal choice costs nothing on Genex and its own plan and usage limits apply.
|
|
103
114
|
New quotes freeze the matching choices; connector metadata stays server-owned.
|
|
104
115
|
Old unapproved quotes are narrowed to the matching provider before confirmation;
|
|
105
116
|
approved personal requests retain their connector for recovery. Once chosen,
|
|
@@ -130,9 +141,9 @@ talkButton.addEventListener('click', async () => {
|
|
|
130
141
|
if (!grantId) {
|
|
131
142
|
const budget = await requestSpendGrant({
|
|
132
143
|
models: [model.id],
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
disclosure: { periodLabel: 'minute', estimatedCallsPerPeriod: 4,
|
|
144
|
+
perCallMaxCredits: 8, // Hard ceiling per call. The server refuses a call asking more.
|
|
145
|
+
perCallEstimateCredits: 2, // The honest per-call estimate, benchmarked first.
|
|
146
|
+
disclosure: { periodLabel: 'minute', estimatedCallsPerPeriod: 4, estimatedCreditsPerPeriod: 8 },
|
|
136
147
|
maxConcurrent: 2,
|
|
137
148
|
idempotencyKey: 'npc-conversation-budget',
|
|
138
149
|
});
|
|
@@ -156,13 +167,19 @@ posts no parent message and needs no user gesture**, so it works from a game
|
|
|
156
167
|
loop or a timer. Every other guard is unchanged: production play, a signed-in
|
|
157
168
|
player, a trusted parent origin, and no native or local-test surface. The
|
|
158
169
|
funding door was chosen once in the sheet, so `allowExternal` is ignored on a
|
|
159
|
-
budget call.
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
170
|
+
budget call. Every call is **billed as used on the budget**: its real model
|
|
171
|
+
cost plus the Genex fee accrues there, and the player's credits move one whole
|
|
172
|
+
credit at a time as calls add up — a call's own receipt carries
|
|
173
|
+
`metered.chargedUsdPicos` (what it added) and `chargedCredits: 0`, and when the
|
|
174
|
+
budget ends any remainder is one credit. The per-call ceiling is `maxCredits`,
|
|
175
|
+
at most the budget's `perCallMaxCredits`.
|
|
176
|
+
|
|
177
|
+
`getSpendGrant(id)` is the readout to draw in the game: `limitCredits`,
|
|
178
|
+
`spentCredits`, `heldCredits` (what the budget holds for calls not settled yet,
|
|
179
|
+
and for a remainder under one credit), `remainingCredits`, `limitCalls`,
|
|
180
|
+
`callCount`, `status` and the frozen `terms` (a budget approved before credits
|
|
181
|
+
reports the same in `limitCoins`/`spentCoins`/…, and a credit budget keeps
|
|
182
|
+
those at 0). Poll it on the
|
|
166
183
|
cadence your HUD needs — never derive the remaining budget from your own count
|
|
167
184
|
of calls, and never show a figure the server did not send. Store `grantId` the
|
|
168
185
|
way you store a `generationId`; `getSpendGrant()` recovers the budget after a
|
|
@@ -174,21 +191,25 @@ same lever on Genex, on every page, and theirs always outranks the game's.
|
|
|
174
191
|
**The disclosure is a promise, not a guess.** `disclosure` is what the Genex
|
|
175
192
|
sheet shows the player, attributed to your game — Genex prints a server-computed
|
|
176
193
|
worst case beside it, so an optimistic number is visible as one. Declare the
|
|
177
|
-
rate you actually expect, benchmark `
|
|
178
|
-
(see *Benchmark your own
|
|
179
|
-
ceiling. The server refuses a call whose
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
194
|
+
rate you actually expect, benchmark `perCallEstimateCredits` before you declare
|
|
195
|
+
it (see *Benchmark your own costs* below), and keep `perCallMaxCredits` a real
|
|
196
|
+
ceiling. The server refuses a call whose ceiling passes it
|
|
197
|
+
(`grant_price_unreasonable`) — that check is what replaces the popup, so a
|
|
198
|
+
budget is never a blank cheque. `perCallMaxCoins`, `perCallEstimateCoins` and
|
|
199
|
+
`estimatedCoinsPerPeriod` (before 0.27) are accepted as the same credit numbers.
|
|
200
|
+
The slider's bounds, the credit value, the fee and the recommended headroom all
|
|
201
|
+
come from the server; read them from `getGenerationModels()`
|
|
202
|
+
(`standingCreditGrant`, `usdCentsPerCredit`, `feeBps`,
|
|
203
|
+
`recommendedDeclaredHeadroomBps`) rather than typing any of them into the game.
|
|
185
204
|
|
|
186
205
|
**Handle the refusals as game states.** A budget ends for ordinary reasons and
|
|
187
206
|
the game should have believable copy for each:
|
|
188
207
|
`grant_limit_reached` (the player's limit is spent), `grant_stopped`,
|
|
189
208
|
`grant_expired`, `grant_not_active`, `grant_concurrency` and
|
|
190
209
|
`grant_rate_limited` (your own declared ceilings), `grant_insufficient_funds`
|
|
191
|
-
(the
|
|
210
|
+
(the player's credits ran low — the budget resumes when they top up),
|
|
211
|
+
`credits_unverified` (verify the email on Genex), `generation_paused` (Genex
|
|
212
|
+
paused paid generation; retry later),
|
|
192
213
|
`waiting_for_plan` (a personal plan's own rate limit; it resumes by itself),
|
|
193
214
|
`grant_price_unreasonable`, `grant_already_active`, `external_grant_active` and
|
|
194
215
|
`invalid_grant_limit`. `generationErrorMessage(code)` returns a player-facing
|
|
@@ -211,6 +232,62 @@ and something that survives a reload. Validate `result.output` against the shape
|
|
|
211
232
|
your game expects before using it, always. It is data, never authority for
|
|
212
233
|
coins, rewards or items.
|
|
213
234
|
|
|
235
|
+
## Streaming replies
|
|
236
|
+
|
|
237
|
+
SDK **0.26.0+**. `generateStream()` is `generate({ grantId })` answered as it is
|
|
238
|
+
written: the text arrives in pieces while the model writes it, instead of all at
|
|
239
|
+
once after the call. Use it for **dialogue and narration** a player watches
|
|
240
|
+
appear — an NPC's reply, a story beat. Keep `generate()` for answers the game
|
|
241
|
+
only acts on as a whole (a quest object, a list), and `judge()` for decisions.
|
|
242
|
+
|
|
243
|
+
```ts
|
|
244
|
+
import { generateStream, generationErrorMessage } from '@genex-ai/embed-sdk';
|
|
245
|
+
|
|
246
|
+
const reply = await generateStream({
|
|
247
|
+
...request, // the same options generate() takes
|
|
248
|
+
grantId, // required: only a standing budget streams
|
|
249
|
+
onDelta: (_piece, soFar) => bubble.setText(soFar),
|
|
250
|
+
});
|
|
251
|
+
if (reply.status === 'succeeded') applyGeneration(reply); // the answer
|
|
252
|
+
else showNotice(generationErrorMessage(reply.error));
|
|
253
|
+
```
|
|
254
|
+
|
|
255
|
+
It resolves to **the same result `generate()` gives** — status, output, receipt
|
|
256
|
+
— and that result, not the pieces, is the answer. Pieces are provisional: a call
|
|
257
|
+
can still fail after text has arrived (the model broke off, or a JSON answer
|
|
258
|
+
did not match the schema), so let the resolved status decide what the game
|
|
259
|
+
keeps. It is billed exactly as a budget `generate()` call is — as used, on the
|
|
260
|
+
budget — whether it succeeds, fails, or the player walks away mid-sentence.
|
|
261
|
+
|
|
262
|
+
For `outputFormat: 'json'`, `onPartialField(name, partialText)` reports the
|
|
263
|
+
**first top-level string property of `schema`** as far as the model has written
|
|
264
|
+
it — put the NPC's line first in the schema and it can appear word by word while
|
|
265
|
+
the rest of the object is still arriving. The object itself is parsed and
|
|
266
|
+
checked against the schema only once it is complete.
|
|
267
|
+
|
|
268
|
+
- **Grant-only.** Without `grantId` it resolves `failed` with
|
|
269
|
+
`stream_requires_grant` before the network: a one-time request waits on the
|
|
270
|
+
player's approval sheet, so there is nothing to stream. Every other guard is
|
|
271
|
+
a budget `generate()`'s — production play, a signed-in player, a trusted
|
|
272
|
+
parent, no popup and no user gesture — and so are the refusals
|
|
273
|
+
(`grant_concurrency`, `grant_limit_reached`, …). A stream holds one of the
|
|
274
|
+
budget's `maxConcurrent` slots until it has settled.
|
|
275
|
+
- **Sometimes it arrives whole.** A call the stand cannot start at once, a
|
|
276
|
+
retry of a call already running (the same `idempotencyKey`), or a budget on
|
|
277
|
+
the player's own plan is answered in one piece: the SDK waits for it the way
|
|
278
|
+
`generate()` does and calls `onDelta` once with the whole text.
|
|
279
|
+
- **`signal` stops the reading, not the call.** The model still finishes and the
|
|
280
|
+
call is charged; the result is `pending` with `stream_aborted` and the
|
|
281
|
+
`generationId` — `waitForGeneration(generationId)` recovers the answer. A
|
|
282
|
+
dropped connection is recovered the same way, automatically: Genex keeps
|
|
283
|
+
reading the model's reply after a client leaves and settles it either way.
|
|
284
|
+
|
|
285
|
+
The wire, for other clients: `POST /api/runtime/grants/:id/generations/stream`
|
|
286
|
+
with the embed token as a bearer answers `text/event-stream` — `start`
|
|
287
|
+
`{ generationId }`, `delta` `{ text }` (batched, at most every ~50 ms) and a
|
|
288
|
+
final `done` carrying the same view `GET /generations/:id` returns. EventSource
|
|
289
|
+
cannot send a POST or the token, so the SDK reads `fetch()`'s body.
|
|
290
|
+
|
|
214
291
|
## Judge during play
|
|
215
292
|
|
|
216
293
|
SDK **0.25.0+**. `generate()` writes; `judge()` decides. A game that needs to
|
|
@@ -220,19 +297,19 @@ classifier typed questions and gets calibrated probabilities back, typically in
|
|
|
220
297
|
about a third of a second. It writes no prose and invents no numbers, which is
|
|
221
298
|
exactly what makes it a steadier referee than a chat model asked to classify.
|
|
222
299
|
|
|
223
|
-
It is **grant-only** and **billed as used
|
|
224
|
-
|
|
225
|
-
add up
|
|
226
|
-
budget ends, a remainder is one
|
|
227
|
-
it when you request the budget:
|
|
300
|
+
It is **grant-only** and **billed as used**, on the same budget as its
|
|
301
|
+
generations: a call costs a small fraction of a credit, so it is never charged
|
|
302
|
+
a credit of its own. Calls add up on the budget, and a whole credit is taken
|
|
303
|
+
each time they reach one; when the budget ends, a remainder is one credit and
|
|
304
|
+
anything still held goes back. Ask for it when you request the budget:
|
|
228
305
|
|
|
229
306
|
```ts
|
|
230
307
|
import { requestSpendGrant, judge, generationErrorMessage } from '@genex-ai/embed-sdk';
|
|
231
308
|
|
|
232
309
|
const budget = await requestSpendGrant({
|
|
233
310
|
models: [model.id], // or [] for a judge-only budget
|
|
234
|
-
|
|
235
|
-
disclosure: { periodLabel: 'minute', estimatedCallsPerPeriod: 4,
|
|
311
|
+
perCallMaxCredits: 8, perCallEstimateCredits: 2,
|
|
312
|
+
disclosure: { periodLabel: 'minute', estimatedCallsPerPeriod: 4, estimatedCreditsPerPeriod: 8 },
|
|
236
313
|
judge: { enabled: true, estimatedCallsPerPeriod: 30 }, // honest checks per period
|
|
237
314
|
});
|
|
238
315
|
|
|
@@ -268,24 +345,26 @@ it opens no window. The answer arrives in the same response; reuse an
|
|
|
268
345
|
out (`timeoutMs`, 1000–20000) is `unknown` and billed at its maximum, because
|
|
269
346
|
the work may have run. The refusals to handle as game states:
|
|
270
347
|
`judge_requires_grant` (no budget), `judge_not_enabled` (the budget was approved
|
|
271
|
-
without the judge — request a new one), `
|
|
348
|
+
without the judge — request a new one), `judge_requires_credits` (and, on a
|
|
349
|
+
budget approved before credits, `judge_requires_coins`),
|
|
272
350
|
`judge_period_limit` (the checks reached the per-period ceiling the player was
|
|
273
351
|
shown — it rolls, so try again shortly), `judge_busy` and `judge_paused` (the
|
|
274
352
|
platform's, retry later), `request_too_large` (state and questions over the
|
|
275
353
|
byte bound), and every budget code above — `grant_concurrency` now also means
|
|
276
|
-
"fits once calls in flight land", never an ended budget. The receipt is on `verdict.billing` (`chargedCoins`
|
|
277
|
-
0; `chargedUsdPicos` is what this call added
|
|
278
|
-
`
|
|
354
|
+
"fits once calls in flight land", never an ended budget. The receipt is on `verdict.billing` (`chargedCredits` and `chargedCoins` are
|
|
355
|
+
always 0; `chargedUsdPicos` is what this call added; `billingPolicy` is
|
|
356
|
+
`metered-credits-v1`); the budget's `spentCredits` and `heldCredits` are the
|
|
357
|
+
numbers to show.
|
|
279
358
|
|
|
280
|
-
Benchmark on your own
|
|
281
|
-
`@genex-ai/embed-sdk/development` (same shape, `{
|
|
282
|
-
billed one whole
|
|
283
|
-
|
|
359
|
+
Benchmark on your own credits with `developmentJudge()` from
|
|
360
|
+
`@genex-ai/embed-sdk/development` (same shape, `{ maxCredits, request }`). It is
|
|
361
|
+
billed one whole credit a call — a player's budget, which meters, spends far
|
|
362
|
+
less for the same calls.
|
|
284
363
|
|
|
285
364
|
## Your subscription and the Genex player watcher
|
|
286
365
|
|
|
287
366
|
Both approval sheets can offer the player their own Claude or ChatGPT plan
|
|
288
|
-
beside
|
|
367
|
+
beside credits, when the selected model's provider matches. That choice lives in
|
|
289
368
|
the trusted Genex surface only — never add a plan row to the game's own model
|
|
290
369
|
picker, and never ask a player for a subscription credential. Genex neither
|
|
291
370
|
collects nor hosts them.
|
|
@@ -297,7 +376,7 @@ it, Genex shows them the one-time prompt: *"Install the Genex player watcher:
|
|
|
297
376
|
run `npx @genex-ai/cli-demo@latest player install` and approve it on Genex."*
|
|
298
377
|
The game does not install, start or speak to the watcher; it only reads
|
|
299
378
|
`watcherOnline` on a grant or generation view when Genex includes it. A
|
|
300
|
-
personal-plan result costs
|
|
379
|
+
personal-plan result costs nothing on Genex, is metered in requests rather than credits,
|
|
301
380
|
and arrives with `source: 'external'` and `modelProvenance: 'unverified'`:
|
|
302
381
|
user-supplied output, never proof that a particular model produced it, and
|
|
303
382
|
never authority for money or rewards. When the player's own plan hits its rate limit
|
|
@@ -309,8 +388,17 @@ to paid work.
|
|
|
309
388
|
SDK **0.21.0+** supports multi-step generation and usage receipts through an
|
|
310
389
|
operator-registered workflow. This requires the game's trusted server executor;
|
|
311
390
|
an ordinary creator API key cannot register a workflow or dispatch its steps.
|
|
312
|
-
|
|
313
|
-
|
|
391
|
+
**Which wallet a workflow bills is its executor's registration.** An executor
|
|
392
|
+
left on `funding: 'coins'` (every executor registered before credits, by
|
|
393
|
+
default) keeps the fixed-price coin terms below: `requestWorkflow()` requires the
|
|
394
|
+
fixed `estimateCoins` price, and offerings and quotes are `declared-v1` with a
|
|
395
|
+
multiplier of 2 or 3. An executor switched to `funding: 'credits'` issues
|
|
396
|
+
`metered-credits-v1` offerings and quotes instead — `estimatedCredits`,
|
|
397
|
+
`maxCredits`, `feeBps`, `currency: 'credits'`, coin fields 0, and the
|
|
398
|
+
registered `priceMultiplier` served unchanged but pricing nothing: the run is
|
|
399
|
+
billed its steps' real cost plus the Genex fee, rounded up to a whole credit.
|
|
400
|
+
Pass `maxCredits` (or `estimateCoins`, read as the same ceiling) to such a
|
|
401
|
+
workflow. A game must accept the new policy before its executor is switched.
|
|
314
402
|
|
|
315
403
|
```ts
|
|
316
404
|
import { getWorkflowOfferings, requestWorkflow, getEmbedToken } from '@genex-ai/embed-sdk';
|
|
@@ -357,14 +445,14 @@ Recovering local state never starts a fresh charge without another player click.
|
|
|
357
445
|
Read a fresh embed token when sending an approved run to the game backend; never
|
|
358
446
|
persist or log the token.
|
|
359
447
|
|
|
360
|
-
|
|
448
|
+
On a COIN executor, the catalog's `estimatedCoins` and `priceCoins` are suggested price aliases,
|
|
361
449
|
and its maximum describes operator limits. Choose the game's fixed attempt price
|
|
362
450
|
after development benchmarks, pass it as `estimateCoins`, and show coin plus USD.
|
|
363
451
|
The player's final approval always uses the server quote. Preserve the selected
|
|
364
452
|
model, bundle, funding, availability and operator-owned tariff; the game cannot
|
|
365
453
|
change provider prices, dispatch costs or settlement.
|
|
366
454
|
|
|
367
|
-
For new public workflow quotes, `maxCoins` is the same fixed amount as
|
|
455
|
+
For a coin executor's new public workflow quotes, `maxCoins` is the same fixed amount as
|
|
368
456
|
`priceCoins`, not a promise to bill actual usage. The operator-owned multiplier
|
|
369
457
|
(2 or 3, default 3) determines how much model work that fixed price can fund.
|
|
370
458
|
The whole started attempt is charged once, including failed or canceled work;
|
|
@@ -375,7 +463,7 @@ artifact; the browser cannot settle it.
|
|
|
375
463
|
Use `resumeWorkflow(generationId, { timeoutMs? })` directly from a click to
|
|
376
464
|
reopen a saved approval. It reads the original request without creating a quote
|
|
377
465
|
or requiring a new price, including pre-0.21 consumed and legacy approvals.
|
|
378
|
-
Use `requestWorkflow()` with
|
|
466
|
+
Use `requestWorkflow()` with `estimateCoins` (a coin executor) or `maxCredits` (a credit executor) for new operations.
|
|
379
467
|
|
|
380
468
|
Legacy quotes without `billingPolicy` retain their original fixed-price and
|
|
381
469
|
refund terms. Never replace a saved quote's policy with the current catalog's
|
|
@@ -402,11 +490,11 @@ The [runtime API contract](../../CLI_INTEGRATION.md#10-player-funded-runtime-gen
|
|
|
402
490
|
describes both APIs, executor authorization, recovery and connector endpoints.
|
|
403
491
|
|
|
404
492
|
|
|
405
|
-
## Benchmark your own
|
|
493
|
+
## Benchmark your own costs on the server
|
|
406
494
|
|
|
407
495
|
`npx genex llm bench` is the CLI door onto this lane: it runs the real model
|
|
408
|
-
against your own
|
|
409
|
-
the
|
|
496
|
+
against your own credits, reports what it actually cost and charged, and
|
|
497
|
+
recommends the per-call ceiling to declare. Reach for the API below when you want the samples in your
|
|
410
498
|
own script.
|
|
411
499
|
|
|
412
500
|
SDK **0.21.0+** provides `@genex-ai/embed-sdk/development`. Use it only in a
|
|
@@ -416,11 +504,13 @@ player wallet. Restricted API keys and personal-only offerings are refused.
|
|
|
416
504
|
Keep the credential out of game code, browser environment variables and logs;
|
|
417
505
|
the subpath is disabled for browser resolution and rejects browser execution.
|
|
418
506
|
|
|
419
|
-
`maxCoins` is
|
|
420
|
-
|
|
421
|
-
|
|
422
|
-
|
|
423
|
-
|
|
507
|
+
`maxCredits` (SDK 0.27.0+; `maxCoins` is the same number under its old name) is
|
|
508
|
+
an explicit positive maximum from your own credits. Development uses
|
|
509
|
+
`metered-credits-v1`: actual model usage plus the Genex fee, rounded up to a
|
|
510
|
+
whole credit per call, including failed usage, up to that maximum (a workflow
|
|
511
|
+
whose executor still bills coin uses `consumed-v1` on your coin wallet).
|
|
512
|
+
Gemini/GLM models are paid too. Actual zero cost is free; unknown expense
|
|
513
|
+
remains held. No personal or paid fallback occurs.
|
|
424
514
|
|
|
425
515
|
```ts
|
|
426
516
|
import { developmentGenerate } from '@genex-ai/embed-sdk/development';
|
|
@@ -429,7 +519,7 @@ const receipt = await developmentGenerate({
|
|
|
429
519
|
apiUrl: process.env.GENEX_API_URL!,
|
|
430
520
|
creatorToken: process.env.GENEX_CREATOR_TOKEN!,
|
|
431
521
|
projectId: process.env.GENEX_PROJECT_ID!,
|
|
432
|
-
|
|
522
|
+
maxCredits: 5,
|
|
433
523
|
request: {
|
|
434
524
|
modelId: 'your-configured-model-id',
|
|
435
525
|
prompt: 'Invent a friendly creature name.',
|
|
@@ -437,24 +527,25 @@ const receipt = await developmentGenerate({
|
|
|
437
527
|
idempotencyKey: 'calibration-sample-001',
|
|
438
528
|
},
|
|
439
529
|
});
|
|
440
|
-
// A 5-
|
|
441
|
-
//
|
|
442
|
-
|
|
530
|
+
// A 5-credit maximum can return chargedCredits: 1 for a small call. Use the
|
|
531
|
+
// actual cost of repeated samples (usage.costUsdPicos) and usage.fitCredits to
|
|
532
|
+
// choose the ceiling your game declares as maxCredits.
|
|
533
|
+
if (receipt.billingStatus === 'final') useForCalibration(receipt.chargedCredits, receipt.usage);
|
|
443
534
|
```
|
|
444
535
|
|
|
445
536
|
The full receipt includes execution status, output on success, charged/reserved
|
|
446
|
-
|
|
537
|
+
credits and USD, plus development-only `usage: { costUsdPicos, costUsd,
|
|
447
538
|
maxProviderUsdPicos, unknownProviderUsdPicos }`. Unknown cost is null rather
|
|
448
539
|
than zero; workflow cost aggregates known actual step costs and reports remaining
|
|
449
540
|
unknown exposure separately. No token counts are inferred: SDK 0.24.3+ types the
|
|
450
541
|
counts the provider REPORTED (`usage.inputTokens`, `usage.outputTokens`, null
|
|
451
|
-
when none), the call's own `usage.maxOutputTokens`, and `usage.
|
|
452
|
-
|
|
453
|
-
the stand's headroom. The
|
|
454
|
-
be, so
|
|
455
|
-
|
|
456
|
-
|
|
457
|
-
`
|
|
542
|
+
when none), the call's own `usage.maxOutputTokens`, and `usage.fitCredits` (SDK
|
|
543
|
+
0.27.0+; `usage.fitCoins` on a coin row) — the smallest per-call ceiling whose
|
|
544
|
+
funded output allowance holds that answer plus the stand's headroom. The
|
|
545
|
+
ceiling also decides how long the answer may be, so declare at least the p95
|
|
546
|
+
`fitCredits` of your settled samples, not the charged credits alone.
|
|
547
|
+
`usage.truncated` marks an answer the model had to stop writing (`error:
|
|
548
|
+
'provider_token_limit'`, still charged: re-run with a higher `maxCredits`), and `usage.fitExceedsCap` an answer longer than one call on that
|
|
458
549
|
stand may produce (ask for a shorter one). When the provider
|
|
459
550
|
refused the request before running it (a rejected key, an unknown model, a rate
|
|
460
551
|
limit — `error: 'provider_http_<status>'`), nothing is charged, the hold is
|
|
@@ -466,8 +557,8 @@ and every in-game call there answers `provider_http_401` until an operator
|
|
|
466
557
|
replaces it — check it before a benchmark, not after.
|
|
467
558
|
|
|
468
559
|
For a registered workflow, call `developmentRequestWorkflow({ apiUrl,
|
|
469
|
-
creatorToken, projectId, workflowId,
|
|
470
|
-
idempotencyKey? } })
|
|
560
|
+
creatorToken, projectId, workflowId, maxCredits, request: { offeringId, input,
|
|
561
|
+
idempotencyKey? } })` (on a coin executor the same number is its coin cap). It returns the accepted, claimed workflow immediately so
|
|
471
562
|
your trusted executor can enqueue it. After enqueueing, call
|
|
472
563
|
`waitForDevelopmentGeneration(config, id, timeoutMs?)`. Both generic and workflow
|
|
473
564
|
benchmarks are recoverable with `getDevelopmentGeneration(config, id)` and
|
|
@@ -6,9 +6,10 @@ import {
|
|
|
6
6
|
hasNativeMarker,
|
|
7
7
|
isGenerationId,
|
|
8
8
|
isGenerationTerminal,
|
|
9
|
+
parseGenerationStreamEvent,
|
|
9
10
|
readBridgeNativeCommand,
|
|
10
11
|
readNativeEntry
|
|
11
|
-
} from "./chunk-
|
|
12
|
+
} from "./chunk-MJPLBT3T.js";
|
|
12
13
|
|
|
13
14
|
// src/commerce.ts
|
|
14
15
|
var cfg = null;
|
|
@@ -117,6 +118,129 @@ async function buy(opts) {
|
|
|
117
118
|
return awaitOutcome(view.id, opts.timeoutMs ?? 18e4);
|
|
118
119
|
}
|
|
119
120
|
|
|
121
|
+
// src/stream.ts
|
|
122
|
+
function createSseParser(onEvent) {
|
|
123
|
+
let buffer = "";
|
|
124
|
+
let data = [];
|
|
125
|
+
let name = "";
|
|
126
|
+
const line = (text) => {
|
|
127
|
+
if (text === "") {
|
|
128
|
+
if (data.length) onEvent({ event: name || "message", data: data.join("\n") });
|
|
129
|
+
data = [];
|
|
130
|
+
name = "";
|
|
131
|
+
return;
|
|
132
|
+
}
|
|
133
|
+
if (text.startsWith(":")) return;
|
|
134
|
+
const colon = text.indexOf(":");
|
|
135
|
+
const field = colon === -1 ? text : text.slice(0, colon);
|
|
136
|
+
let value = colon === -1 ? "" : text.slice(colon + 1);
|
|
137
|
+
if (value.startsWith(" ")) value = value.slice(1);
|
|
138
|
+
if (field === "data") data.push(value);
|
|
139
|
+
else if (field === "event") name = value;
|
|
140
|
+
};
|
|
141
|
+
const drain = (final) => {
|
|
142
|
+
for (; ; ) {
|
|
143
|
+
const match = /\r\n|\r|\n/.exec(buffer);
|
|
144
|
+
if (!match) break;
|
|
145
|
+
if (match[0] === "\r" && match.index === buffer.length - 1 && !final) break;
|
|
146
|
+
line(buffer.slice(0, match.index));
|
|
147
|
+
buffer = buffer.slice(match.index + match[0].length);
|
|
148
|
+
}
|
|
149
|
+
if (final) {
|
|
150
|
+
if (buffer) line(buffer);
|
|
151
|
+
buffer = "";
|
|
152
|
+
line("");
|
|
153
|
+
}
|
|
154
|
+
};
|
|
155
|
+
return {
|
|
156
|
+
push(text) {
|
|
157
|
+
buffer += text;
|
|
158
|
+
drain(false);
|
|
159
|
+
},
|
|
160
|
+
end() {
|
|
161
|
+
drain(true);
|
|
162
|
+
}
|
|
163
|
+
};
|
|
164
|
+
}
|
|
165
|
+
function firstStringProperty(schema) {
|
|
166
|
+
if (!schema || typeof schema !== "object") return void 0;
|
|
167
|
+
const properties = schema.properties;
|
|
168
|
+
if (schema.type !== "object" || !properties || typeof properties !== "object" || Array.isArray(properties)) return void 0;
|
|
169
|
+
for (const [name, child] of Object.entries(properties)) {
|
|
170
|
+
if (child && typeof child === "object" && child.type === "string") return name;
|
|
171
|
+
}
|
|
172
|
+
return void 0;
|
|
173
|
+
}
|
|
174
|
+
var ESCAPES = { '"': '"', "\\": "\\", "/": "/", b: "\b", f: "\f", n: "\n", r: "\r", t: " " };
|
|
175
|
+
function readString(text, start) {
|
|
176
|
+
let value = "";
|
|
177
|
+
let i = start + 1;
|
|
178
|
+
while (i < text.length) {
|
|
179
|
+
const c = text[i];
|
|
180
|
+
if (c === '"') return { value, end: i + 1, complete: true };
|
|
181
|
+
if (c !== "\\") {
|
|
182
|
+
value += c;
|
|
183
|
+
i++;
|
|
184
|
+
continue;
|
|
185
|
+
}
|
|
186
|
+
const next = text[i + 1];
|
|
187
|
+
if (next === void 0) break;
|
|
188
|
+
if (next === "u") {
|
|
189
|
+
const hex = text.slice(i + 2, i + 6);
|
|
190
|
+
if (hex.length < 4) break;
|
|
191
|
+
if (!/^[0-9a-fA-F]{4}$/.test(hex)) return { value: withoutHalfPair(value), end: text.length, complete: false };
|
|
192
|
+
value += String.fromCharCode(parseInt(hex, 16));
|
|
193
|
+
i += 6;
|
|
194
|
+
continue;
|
|
195
|
+
}
|
|
196
|
+
value += ESCAPES[next] ?? next;
|
|
197
|
+
i += 2;
|
|
198
|
+
}
|
|
199
|
+
return { value: withoutHalfPair(value), end: text.length, complete: false };
|
|
200
|
+
}
|
|
201
|
+
function withoutHalfPair(value) {
|
|
202
|
+
return /[\uD800-\uDBFF]$/.test(value) ? value.slice(0, -1) : value;
|
|
203
|
+
}
|
|
204
|
+
function partialStringField(text, name) {
|
|
205
|
+
let i = 0;
|
|
206
|
+
const skip = () => {
|
|
207
|
+
while (i < text.length && /\s/.test(text[i])) i++;
|
|
208
|
+
};
|
|
209
|
+
skip();
|
|
210
|
+
if (text[i] !== "{") return void 0;
|
|
211
|
+
i++;
|
|
212
|
+
let depth = 1;
|
|
213
|
+
let expectKey = true;
|
|
214
|
+
while (i < text.length) {
|
|
215
|
+
const c = text[i];
|
|
216
|
+
if (c === '"') {
|
|
217
|
+
const read = readString(text, i);
|
|
218
|
+
if (depth === 1 && expectKey) {
|
|
219
|
+
if (!read.complete) return void 0;
|
|
220
|
+
i = read.end;
|
|
221
|
+
skip();
|
|
222
|
+
if (text[i] !== ":") return void 0;
|
|
223
|
+
i++;
|
|
224
|
+
skip();
|
|
225
|
+
expectKey = false;
|
|
226
|
+
if (read.value !== name) continue;
|
|
227
|
+
if (text[i] !== '"') return void 0;
|
|
228
|
+
return readString(text, i).value;
|
|
229
|
+
}
|
|
230
|
+
if (!read.complete) return void 0;
|
|
231
|
+
i = read.end;
|
|
232
|
+
continue;
|
|
233
|
+
}
|
|
234
|
+
if (c === "{" || c === "[") depth++;
|
|
235
|
+
else if (c === "}" || c === "]") {
|
|
236
|
+
depth--;
|
|
237
|
+
if (depth === 0) return void 0;
|
|
238
|
+
} else if (c === "," && depth === 1) expectKey = true;
|
|
239
|
+
i++;
|
|
240
|
+
}
|
|
241
|
+
return void 0;
|
|
242
|
+
}
|
|
243
|
+
|
|
120
244
|
// src/generation.ts
|
|
121
245
|
var config = null;
|
|
122
246
|
function _initGeneration(value) {
|
|
@@ -144,6 +268,14 @@ async function request(path, body) {
|
|
|
144
268
|
function validEstimateCoins(value) {
|
|
145
269
|
return Number.isSafeInteger(value) && value >= 0 && value <= 1e6;
|
|
146
270
|
}
|
|
271
|
+
function ceilingField(options) {
|
|
272
|
+
const credits = options.maxCredits, coins = options.estimateCoins;
|
|
273
|
+
if (credits !== void 0 && !validEstimateCoins(credits)) return { error: "invalid_max_credits" };
|
|
274
|
+
if (coins !== void 0 && !validEstimateCoins(coins)) return { error: "invalid_estimate_coins" };
|
|
275
|
+
if (credits === void 0 && coins === void 0) return { error: "invalid_max_credits" };
|
|
276
|
+
if (credits !== void 0 && coins !== void 0 && credits !== coins) return { error: "invalid_max_credits" };
|
|
277
|
+
return { field: credits !== void 0 ? { maxCredits: credits } : { estimateCoins: coins } };
|
|
278
|
+
}
|
|
147
279
|
function getGenerationModels() {
|
|
148
280
|
return request("/models");
|
|
149
281
|
}
|
|
@@ -175,6 +307,10 @@ function outcome(view) {
|
|
|
175
307
|
function billingReceipt(view) {
|
|
176
308
|
return {
|
|
177
309
|
...view.billingStatus !== void 0 ? { billingStatus: view.billingStatus } : {},
|
|
310
|
+
...view.currency !== void 0 ? { currency: view.currency } : {},
|
|
311
|
+
...view.maxCredits !== void 0 ? { maxCredits: view.maxCredits } : {},
|
|
312
|
+
...view.reservedCredits !== void 0 ? { reservedCredits: view.reservedCredits } : {},
|
|
313
|
+
...view.chargedCredits !== void 0 ? { chargedCredits: view.chargedCredits } : {},
|
|
178
314
|
...view.reservedCoins !== void 0 ? { reservedCoins: view.reservedCoins } : {},
|
|
179
315
|
...view.reservedDisplayUsdCents !== void 0 ? { reservedDisplayUsdCents: view.reservedDisplayUsdCents } : {},
|
|
180
316
|
...view.chargedCoins !== void 0 ? { chargedCoins: view.chargedCoins } : {},
|
|
@@ -216,8 +352,10 @@ function waitForGeneration(generationId, timeoutMs = 6e5) {
|
|
|
216
352
|
return poll(generationId, timeoutMs, outcome);
|
|
217
353
|
}
|
|
218
354
|
async function generate(options) {
|
|
219
|
-
|
|
220
|
-
|
|
355
|
+
const ceiling = ceilingField(options);
|
|
356
|
+
if ("error" in ceiling) return { status: "failed", error: ceiling.error };
|
|
357
|
+
const { timeoutMs, idempotencyKey, grantId, maxCredits: _credits, estimateCoins: _coins, ...rest } = options;
|
|
358
|
+
const input = { ...rest, ...ceiling.field };
|
|
221
359
|
if (grantId !== void 0) return generateUnderGrant(grantId, input, idempotencyKey, timeoutMs ?? 6e5);
|
|
222
360
|
return startGeneration(
|
|
223
361
|
"/generations",
|
|
@@ -227,13 +365,14 @@ async function generate(options) {
|
|
|
227
365
|
);
|
|
228
366
|
}
|
|
229
367
|
async function requestWorkflow(options) {
|
|
230
|
-
|
|
368
|
+
const ceiling = ceilingField(options);
|
|
369
|
+
if ("error" in ceiling) return { status: "failed", error: ceiling.error };
|
|
231
370
|
if (!isWorkflowIdentifier(options.workflowId)) return { status: "failed", error: "invalid_workflow_id" };
|
|
232
371
|
if (!isWorkflowIdentifier(options.offeringId)) return { status: "failed", error: "invalid_offering_id" };
|
|
233
372
|
return startGeneration(`/workflows/${encodeURIComponent(options.workflowId)}/requests`, {
|
|
234
373
|
offeringId: options.offeringId,
|
|
235
374
|
input: options.input,
|
|
236
|
-
|
|
375
|
+
...ceiling.field,
|
|
237
376
|
...options.allowExternal !== void 0 ? { allowExternal: options.allowExternal } : {},
|
|
238
377
|
idempotencyKey: options.idempotencyKey
|
|
239
378
|
}, options.timeoutMs ?? 6e5, authorizationOutcome, options);
|
|
@@ -285,7 +424,7 @@ async function startGeneration(path, body, timeoutMs, readOutcome, workflow, res
|
|
|
285
424
|
throw new Error("invalid_generation_response");
|
|
286
425
|
}
|
|
287
426
|
const result = readOutcome(view);
|
|
288
|
-
const needsReceipt = view.billingStatus === "pending" || view.quote?.billingPolicy !== void 0 && (view.chargedCoins ?? 0) > 0;
|
|
427
|
+
const needsReceipt = view.billingStatus === "pending" || view.quote?.billingPolicy !== void 0 && ((view.chargedCoins ?? 0) > 0 || (view.chargedCredits ?? 0) > 0);
|
|
289
428
|
if (result && result.status !== "authorized" && !needsReceipt) {
|
|
290
429
|
popup?.close();
|
|
291
430
|
return result;
|
|
@@ -313,9 +452,12 @@ function invalidGrantOptions(options) {
|
|
|
313
452
|
const judge2 = options.judge;
|
|
314
453
|
if (judge2 !== void 0 && (typeof judge2 !== "object" || judge2 === null || typeof judge2.enabled !== "boolean" || !validCount(judge2.estimatedCallsPerPeriod, 1, 1e5))) return "invalid_judge_terms";
|
|
315
454
|
if (!Array.isArray(options.models) || options.models.length < (judge2?.enabled ? 0 : 1) || options.models.length > 8 || options.models.some((id) => typeof id !== "string" || !id || id.length > 150) || new Set(options.models).size !== options.models.length) return "invalid_models";
|
|
316
|
-
|
|
455
|
+
const max = options.perCallMaxCredits ?? options.perCallMaxCoins;
|
|
456
|
+
const estimate = options.perCallEstimateCredits ?? options.perCallEstimateCoins;
|
|
457
|
+
if (!validCount(max, 1, 1e6) || estimate !== void 0 && (!validCount(estimate, 1, 1e6) || estimate > max) || options.perCallMaxCredits !== void 0 && options.perCallMaxCoins !== void 0 && options.perCallMaxCredits !== options.perCallMaxCoins || options.perCallEstimateCredits !== void 0 && options.perCallEstimateCoins !== void 0 && options.perCallEstimateCredits !== options.perCallEstimateCoins) return "invalid_declared_price";
|
|
317
458
|
const d = options.disclosure;
|
|
318
|
-
|
|
459
|
+
const perPeriod = d && typeof d === "object" ? d.estimatedCreditsPerPeriod ?? d.estimatedCoinsPerPeriod : void 0;
|
|
460
|
+
if (!d || typeof d !== "object" || !["minute", "hour", "session"].includes(d.periodLabel) || !validCount(d.estimatedCallsPerPeriod, 1, 1e4) || !validCount(perPeriod, 0, 1e6)) return "invalid_disclosure";
|
|
319
461
|
if (options.maxConcurrent !== void 0 && !validCount(options.maxConcurrent, 1, 8)) return "invalid_grant_terms";
|
|
320
462
|
if (options.maxCallsPerMinute !== void 0 && !validCount(options.maxCallsPerMinute, 1, 120)) return "invalid_grant_terms";
|
|
321
463
|
if (options.maxPendingExternal !== void 0 && !validCount(options.maxPendingExternal, 1, 8)) return "invalid_grant_terms";
|
|
@@ -372,15 +514,16 @@ async function requestSpendGrant(options) {
|
|
|
372
514
|
if ("status" in surface) return surface;
|
|
373
515
|
const { popup, dashboard, parentOrigin: parentOrigin2 } = surface;
|
|
374
516
|
try {
|
|
517
|
+
const estimate = options.perCallEstimateCredits ?? options.perCallEstimateCoins;
|
|
375
518
|
const view = await request("/grants", {
|
|
376
519
|
idempotencyKey: options.idempotencyKey ?? crypto.randomUUID(),
|
|
377
520
|
models: options.models,
|
|
378
|
-
|
|
379
|
-
|
|
521
|
+
perCallMaxCredits: options.perCallMaxCredits ?? options.perCallMaxCoins,
|
|
522
|
+
...estimate !== void 0 ? { perCallEstimateCredits: estimate } : {},
|
|
380
523
|
disclosure: {
|
|
381
524
|
periodLabel: options.disclosure.periodLabel,
|
|
382
525
|
estimatedCallsPerPeriod: options.disclosure.estimatedCallsPerPeriod,
|
|
383
|
-
|
|
526
|
+
estimatedCreditsPerPeriod: options.disclosure.estimatedCreditsPerPeriod ?? options.disclosure.estimatedCoinsPerPeriod
|
|
384
527
|
},
|
|
385
528
|
...options.maxConcurrent !== void 0 ? { maxConcurrent: options.maxConcurrent } : {},
|
|
386
529
|
...options.maxCallsPerMinute !== void 0 ? { maxCallsPerMinute: options.maxCallsPerMinute } : {},
|
|
@@ -423,6 +566,105 @@ async function generateUnderGrant(grantId, input, idempotencyKey, timeoutMs) {
|
|
|
423
566
|
return { status: "failed", error: error instanceof Error ? error.message : "generation_unavailable" };
|
|
424
567
|
}
|
|
425
568
|
}
|
|
569
|
+
async function generateStream(options) {
|
|
570
|
+
const ceiling = ceilingField(options);
|
|
571
|
+
if ("error" in ceiling) return { status: "failed", error: ceiling.error };
|
|
572
|
+
const { timeoutMs, idempotencyKey, grantId, onDelta, onPartialField, signal, allowExternal: _unused, maxCredits: _credits, estimateCoins: _coins, ...rest } = options;
|
|
573
|
+
const body = { ...rest, ...ceiling.field };
|
|
574
|
+
if (grantId === void 0 || grantId === null) return { status: "failed", error: "stream_requires_grant" };
|
|
575
|
+
if (!isGrantId(grantId)) return { status: "failed", error: "invalid_grant_id" };
|
|
576
|
+
const guarded = approvalGuards();
|
|
577
|
+
if ("status" in guarded) return guarded;
|
|
578
|
+
const c = must2();
|
|
579
|
+
const field = body.outputFormat === "json" && onPartialField ? firstStringProperty(body.schema) : void 0;
|
|
580
|
+
let generationId;
|
|
581
|
+
let soFar = "";
|
|
582
|
+
let shown;
|
|
583
|
+
const showField = (value) => {
|
|
584
|
+
if (!field || value === shown) return;
|
|
585
|
+
shown = value;
|
|
586
|
+
try {
|
|
587
|
+
onPartialField(field, value);
|
|
588
|
+
} catch {
|
|
589
|
+
}
|
|
590
|
+
};
|
|
591
|
+
const deliver = (text) => {
|
|
592
|
+
soFar += text;
|
|
593
|
+
try {
|
|
594
|
+
onDelta?.(text, soFar);
|
|
595
|
+
} catch {
|
|
596
|
+
}
|
|
597
|
+
if (field) {
|
|
598
|
+
const partial = partialStringField(soFar, field);
|
|
599
|
+
if (partial !== void 0) showField(partial);
|
|
600
|
+
}
|
|
601
|
+
};
|
|
602
|
+
const finish = (result) => {
|
|
603
|
+
if (result.status === "succeeded") {
|
|
604
|
+
const output = result.output;
|
|
605
|
+
if (typeof output === "string" && output.startsWith(soFar) && output.length > soFar.length) deliver(output.slice(soFar.length));
|
|
606
|
+
else if (field && output && typeof output === "object" && typeof output[field] === "string") showField(output[field]);
|
|
607
|
+
}
|
|
608
|
+
return result;
|
|
609
|
+
};
|
|
610
|
+
const aborted = () => ({ status: "pending", ...generationId ? { generationId } : {}, error: "stream_aborted" });
|
|
611
|
+
try {
|
|
612
|
+
const token = c.getToken();
|
|
613
|
+
if (!token) return { status: "failed", error: "no_player_session" };
|
|
614
|
+
const response = await fetch(`${c.apiUrl}/api/runtime/grants/${encodeURIComponent(grantId)}/generations/stream`, {
|
|
615
|
+
method: "POST",
|
|
616
|
+
credentials: "omit",
|
|
617
|
+
cache: "no-store",
|
|
618
|
+
headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json", Accept: "text/event-stream" },
|
|
619
|
+
body: JSON.stringify({ ...body, idempotencyKey: idempotencyKey ?? crypto.randomUUID() }),
|
|
620
|
+
...signal ? { signal } : {}
|
|
621
|
+
});
|
|
622
|
+
if (!response.ok) {
|
|
623
|
+
const refusal = await response.json().catch(() => ({}));
|
|
624
|
+
return { status: "failed", error: typeof refusal.error === "string" ? refusal.error : "generation_unavailable" };
|
|
625
|
+
}
|
|
626
|
+
if (!response.body || !(response.headers.get("content-type") ?? "").includes("text/event-stream")) throw new Error("invalid_generation_response");
|
|
627
|
+
let done;
|
|
628
|
+
const parser = createSseParser(({ event, data }) => {
|
|
629
|
+
const parsed = parseGenerationStreamEvent(event, data);
|
|
630
|
+
if (!parsed || done) return;
|
|
631
|
+
if (parsed.event === "start") generationId ??= parsed.data.generationId;
|
|
632
|
+
else if (parsed.event === "delta") deliver(parsed.data.text);
|
|
633
|
+
else done = parsed.data;
|
|
634
|
+
});
|
|
635
|
+
const reader = response.body.getReader();
|
|
636
|
+
const decoder = new TextDecoder();
|
|
637
|
+
try {
|
|
638
|
+
for (; ; ) {
|
|
639
|
+
const { value, done: ended } = await reader.read();
|
|
640
|
+
if (ended) break;
|
|
641
|
+
parser.push(decoder.decode(value, { stream: true }));
|
|
642
|
+
if (done) {
|
|
643
|
+
reader.cancel().catch(() => {
|
|
644
|
+
});
|
|
645
|
+
break;
|
|
646
|
+
}
|
|
647
|
+
}
|
|
648
|
+
if (!done) {
|
|
649
|
+
parser.push(decoder.decode());
|
|
650
|
+
parser.end();
|
|
651
|
+
}
|
|
652
|
+
} catch {
|
|
653
|
+
if (signal?.aborted) return aborted();
|
|
654
|
+
}
|
|
655
|
+
if (signal?.aborted) return aborted();
|
|
656
|
+
if (done) {
|
|
657
|
+
const view = done;
|
|
658
|
+
if (!isGenerationId(view.id) || view.grantId !== grantId || generationId !== void 0 && view.id !== generationId) throw new Error("invalid_generation_response");
|
|
659
|
+
return finish(outcome(view) ?? await poll(view.id, timeoutMs ?? 6e5, outcome));
|
|
660
|
+
}
|
|
661
|
+
if (generationId) return finish(await poll(generationId, timeoutMs ?? 6e5, outcome));
|
|
662
|
+
return { status: "failed", error: "generation_unavailable" };
|
|
663
|
+
} catch (error) {
|
|
664
|
+
if (signal?.aborted) return aborted();
|
|
665
|
+
return { status: "failed", error: error instanceof Error ? error.message : "generation_unavailable" };
|
|
666
|
+
}
|
|
667
|
+
}
|
|
426
668
|
var JUDGE_QUESTION_NAME = /^[A-Za-z][A-Za-z0-9_]{0,63}$/;
|
|
427
669
|
function invalidJudgeOptions(options) {
|
|
428
670
|
if (options.grantId === void 0 || options.grantId === null) return "judge_requires_grant";
|
|
@@ -483,11 +725,19 @@ function generationErrorMessage(code) {
|
|
|
483
725
|
return "We don\u2019t know how this one ended yet \u2014 it is still being settled. Check back in a moment.";
|
|
484
726
|
case "wait_timeout":
|
|
485
727
|
return "This is taking longer than usual. It is still running \u2014 check back in a moment.";
|
|
486
|
-
// --- the player's
|
|
728
|
+
// --- the player's credits -----------------------------------------------
|
|
729
|
+
case "insufficient_credits":
|
|
730
|
+
return "You don\u2019t have enough Genex credits for this request. Top up on Genex and try again.";
|
|
731
|
+
case "credits_unverified":
|
|
732
|
+
return "Verify your email on Genex to use your credits here.";
|
|
733
|
+
case "generation_paused":
|
|
734
|
+
return "Genex has paused generation for now. Try again later.";
|
|
735
|
+
case "payer_busy":
|
|
736
|
+
return "Genex is busy with your account for a moment. Try again shortly.";
|
|
487
737
|
case "insufficient_balance":
|
|
488
|
-
return "There isn\u2019t enough
|
|
738
|
+
return "There isn\u2019t enough in your Genex wallet for this request.";
|
|
489
739
|
case "grant_insufficient_funds":
|
|
490
|
-
return "Your budget paused because your Genex
|
|
740
|
+
return "Your budget paused because your Genex credits ran low. Top them up and it picks up again.";
|
|
491
741
|
// --- standing budgets ---------------------------------------------------
|
|
492
742
|
case "grant_limit_reached":
|
|
493
743
|
return "This budget has reached the limit you set. Set up a new one to keep going.";
|
|
@@ -516,7 +766,8 @@ function generationErrorMessage(code) {
|
|
|
516
766
|
case "judge_not_enabled":
|
|
517
767
|
return "This budget doesn\u2019t cover the game\u2019s quick checks. Set up a new one to keep going.";
|
|
518
768
|
case "judge_requires_coins":
|
|
519
|
-
|
|
769
|
+
case "judge_requires_credits":
|
|
770
|
+
return "The game\u2019s quick checks are paid from your Genex credits, not your own plan.";
|
|
520
771
|
case "invalid_judge_terms":
|
|
521
772
|
return "This budget request isn\u2019t valid, so nothing was requested.";
|
|
522
773
|
case "judge_period_limit":
|
|
@@ -525,6 +776,11 @@ function generationErrorMessage(code) {
|
|
|
525
776
|
return "The game\u2019s quick checks are busy right now. Try again in a moment.";
|
|
526
777
|
case "judge_paused":
|
|
527
778
|
return "The game\u2019s quick checks are paused for now. Try again later.";
|
|
779
|
+
// --- streamed replies -----------------------------------------------------
|
|
780
|
+
case "stream_requires_grant":
|
|
781
|
+
return "Live replies run under a budget you approve. Set one up to keep going.";
|
|
782
|
+
case "stream_aborted":
|
|
783
|
+
return "This reply stopped showing, but it is still finishing and is charged as usual. Check back in a moment.";
|
|
528
784
|
case "waiting_for_plan":
|
|
529
785
|
return "Your own plan is at its rate limit right now. This resumes on its own once the limit resets.";
|
|
530
786
|
// --- personal plans and the player watcher ------------------------------
|
|
@@ -575,7 +831,8 @@ function generationErrorMessage(code) {
|
|
|
575
831
|
return "That payment option doesn\u2019t match this request. Start it again.";
|
|
576
832
|
case "invalid_declared_price":
|
|
577
833
|
case "invalid_estimate_coins":
|
|
578
|
-
|
|
834
|
+
case "invalid_max_credits":
|
|
835
|
+
return "This request\u2019s spending limit isn\u2019t valid, so nothing was charged.";
|
|
579
836
|
// --- what the game asked for --------------------------------------------
|
|
580
837
|
case "model_not_allowed":
|
|
581
838
|
return "This budget doesn\u2019t cover that model. Choose one it does.";
|
|
@@ -646,7 +903,7 @@ var RETRY_FLAG = "genex:embed:retry";
|
|
|
646
903
|
var POPOVER_DISMISSED_FLAG = "genex:guest:popover-dismissed";
|
|
647
904
|
var LOCAL_AUTH_FLAG = "genex:embed:local-auth";
|
|
648
905
|
var PLAYER_ID_KEY = "genex:player";
|
|
649
|
-
var SDK_VERSION = "0.
|
|
906
|
+
var SDK_VERSION = "0.27.0";
|
|
650
907
|
var config2 = null;
|
|
651
908
|
var state = "pending";
|
|
652
909
|
var user = null;
|
|
@@ -1900,6 +2157,7 @@ export {
|
|
|
1900
2157
|
getSpendGrant,
|
|
1901
2158
|
stopSpendGrant,
|
|
1902
2159
|
requestSpendGrant,
|
|
2160
|
+
generateStream,
|
|
1903
2161
|
judge,
|
|
1904
2162
|
generationErrorMessage,
|
|
1905
2163
|
initEmbed,
|
|
@@ -232,6 +232,20 @@ function readNativeEntry(search) {
|
|
|
232
232
|
function isGenerationId(value) {
|
|
233
233
|
return typeof value === "string" && /^[A-Za-z0-9_-]{1,128}$/.test(value);
|
|
234
234
|
}
|
|
235
|
+
function parseGenerationStreamEvent(event, data) {
|
|
236
|
+
let value;
|
|
237
|
+
try {
|
|
238
|
+
value = JSON.parse(data);
|
|
239
|
+
} catch {
|
|
240
|
+
return void 0;
|
|
241
|
+
}
|
|
242
|
+
if (typeof value !== "object" || value === null || Array.isArray(value)) return void 0;
|
|
243
|
+
const fields = value;
|
|
244
|
+
if (event === "start") return isGenerationId(fields.generationId) ? { event, data: { generationId: fields.generationId } } : void 0;
|
|
245
|
+
if (event === "delta") return typeof fields.text === "string" ? { event, data: { text: fields.text } } : void 0;
|
|
246
|
+
if (event === "done") return isGenerationId(fields.id) && typeof fields.status === "string" ? { event, data: value } : void 0;
|
|
247
|
+
return void 0;
|
|
248
|
+
}
|
|
235
249
|
function isGenerationTerminal(status) {
|
|
236
250
|
return ["succeeded", "failed", "unknown", "canceled", "expired"].includes(status);
|
|
237
251
|
}
|
|
@@ -245,5 +259,6 @@ export {
|
|
|
245
259
|
hasNativeMarker,
|
|
246
260
|
readNativeEntry,
|
|
247
261
|
isGenerationId,
|
|
262
|
+
parseGenerationStreamEvent,
|
|
248
263
|
isGenerationTerminal
|
|
249
264
|
};
|
package/dist/development.d.ts
CHANGED
|
@@ -1,6 +1,11 @@
|
|
|
1
1
|
import { RuntimeJudgeQuestion, RuntimeWorkflowInput, RuntimeGenerationView } from '@genex/embed-protocol';
|
|
2
2
|
|
|
3
|
-
/**
|
|
3
|
+
/**
|
|
4
|
+
* Server-only benchmarks spend the authenticated creator's OWN CREDITS
|
|
5
|
+
* (`metered-credits-v1` since SDK 0.27: the real model cost plus the Genex fee,
|
|
6
|
+
* rounded up to a whole credit per call) — or, for a workflow whose executor
|
|
7
|
+
* still bills coin, their own coin wallet (`consumed-v1`).
|
|
8
|
+
*/
|
|
4
9
|
|
|
5
10
|
interface DevelopmentGenerationConfig {
|
|
6
11
|
apiUrl: string;
|
|
@@ -8,9 +13,14 @@ interface DevelopmentGenerationConfig {
|
|
|
8
13
|
creatorToken: string;
|
|
9
14
|
projectId: string;
|
|
10
15
|
}
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
16
|
+
/** The builder's own cap on one call: `maxCredits`, or the old `maxCoins` (the same number). */
|
|
17
|
+
interface DevelopmentCap {
|
|
18
|
+
/** Explicit maximum reservation in your own credits. Actual usage is charged. */
|
|
19
|
+
maxCredits?: number;
|
|
20
|
+
/** @deprecated Since 0.27: the same number as `maxCredits` (a coin workflow's coin cap). */
|
|
21
|
+
maxCoins?: number;
|
|
22
|
+
}
|
|
23
|
+
interface DevelopmentGenerationOptions extends DevelopmentGenerationConfig, DevelopmentCap {
|
|
14
24
|
request: {
|
|
15
25
|
modelId: string;
|
|
16
26
|
prompt: string;
|
|
@@ -21,9 +31,8 @@ interface DevelopmentGenerationOptions extends DevelopmentGenerationConfig {
|
|
|
21
31
|
/** Waiting time only; timeout returns the last server view without canceling. */
|
|
22
32
|
timeoutMs?: number;
|
|
23
33
|
}
|
|
24
|
-
interface DevelopmentWorkflowOptions extends DevelopmentGenerationConfig {
|
|
34
|
+
interface DevelopmentWorkflowOptions extends DevelopmentGenerationConfig, DevelopmentCap {
|
|
25
35
|
workflowId: string;
|
|
26
|
-
maxCoins: number;
|
|
27
36
|
request: {
|
|
28
37
|
offeringId: string;
|
|
29
38
|
input: RuntimeWorkflowInput;
|
|
@@ -32,10 +41,7 @@ interface DevelopmentWorkflowOptions extends DevelopmentGenerationConfig {
|
|
|
32
41
|
}
|
|
33
42
|
/** Create a generic benchmark and wait for execution and its actual-usage receipt. */
|
|
34
43
|
declare function developmentGenerate(options: DevelopmentGenerationOptions): Promise<RuntimeGenerationView>;
|
|
35
|
-
interface DevelopmentJudgeOptions extends DevelopmentGenerationConfig {
|
|
36
|
-
/** Explicit maximum reservation in your own coins. Each call is charged at the
|
|
37
|
-
* lane's one-coin minimum (`consumed-v1`), a refusal before any work at zero. */
|
|
38
|
-
maxCoins: number;
|
|
44
|
+
interface DevelopmentJudgeOptions extends DevelopmentGenerationConfig, DevelopmentCap {
|
|
39
45
|
request: {
|
|
40
46
|
state: unknown;
|
|
41
47
|
questions: Record<string, RuntimeJudgeQuestion>;
|
|
@@ -45,10 +51,10 @@ interface DevelopmentJudgeOptions extends DevelopmentGenerationConfig {
|
|
|
45
51
|
};
|
|
46
52
|
}
|
|
47
53
|
/**
|
|
48
|
-
* The judge on the creator's OWN
|
|
49
|
-
* a player's budget — which meters judge calls and moves whole
|
|
50
|
-
* they add up — a development call is
|
|
51
|
-
* bench here overstates what a budget would spend on the same calls.
|
|
54
|
+
* The judge on the creator's OWN credits, answered in the same response. Unlike
|
|
55
|
+
* a player's budget — which meters judge calls and moves a whole credit only as
|
|
56
|
+
* they add up to one — a development call is rounded up to a whole credit on
|
|
57
|
+
* its own, so a bench here overstates what a budget would spend on the same calls.
|
|
52
58
|
*/
|
|
53
59
|
declare function developmentJudge(options: DevelopmentJudgeOptions): Promise<RuntimeGenerationView>;
|
|
54
60
|
/** Returns the accepted workflow so its trusted executor can enqueue before waiting. */
|
package/dist/development.js
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
import {
|
|
2
2
|
isGenerationId,
|
|
3
3
|
isGenerationTerminal
|
|
4
|
-
} from "./chunk-
|
|
4
|
+
} from "./chunk-MJPLBT3T.js";
|
|
5
5
|
|
|
6
6
|
// src/development.ts
|
|
7
7
|
function assertIdentifier(value) {
|
|
@@ -17,8 +17,17 @@ function baseUrl(config) {
|
|
|
17
17
|
}
|
|
18
18
|
return url.origin + "/api/runtime/development/projects/" + encodeURIComponent(config.projectId);
|
|
19
19
|
}
|
|
20
|
-
function
|
|
21
|
-
|
|
20
|
+
function maximum(options) {
|
|
21
|
+
const valid = (value) => Number.isSafeInteger(value) && value > 0 && value <= 1e6;
|
|
22
|
+
if (options.maxCredits !== void 0) {
|
|
23
|
+
if (!valid(options.maxCredits) || options.maxCoins !== void 0 && options.maxCoins !== options.maxCredits) throw new Error("invalid_max_credits");
|
|
24
|
+
return { maxCredits: options.maxCredits };
|
|
25
|
+
}
|
|
26
|
+
if (!valid(options.maxCoins)) throw new Error(options.maxCoins === void 0 ? "invalid_max_credits" : "invalid_max_coins");
|
|
27
|
+
return { maxCoins: options.maxCoins };
|
|
28
|
+
}
|
|
29
|
+
function developmentTerms(view) {
|
|
30
|
+
return view.quote?.billingPolicy === "metered-credits-v1" && view.funding === "credits" || view.quote?.billingPolicy === "consumed-v1" && view.funding === "coins";
|
|
22
31
|
}
|
|
23
32
|
async function request(config, path, body) {
|
|
24
33
|
const response = await fetch(baseUrl(config) + path, {
|
|
@@ -32,14 +41,14 @@ async function request(config, path, body) {
|
|
|
32
41
|
const result = await response.json().catch(() => ({}));
|
|
33
42
|
if (!response.ok) throw new Error(typeof result.error === "string" ? result.error : "development_generation_unavailable");
|
|
34
43
|
const view = result;
|
|
35
|
-
if (!isGenerationId(view.id) || view.projectId !== config.projectId || view.development !== true || view
|
|
44
|
+
if (!isGenerationId(view.id) || view.projectId !== config.projectId || view.development !== true || !developmentTerms(view)) throw new Error("invalid_development_response");
|
|
36
45
|
return view;
|
|
37
46
|
}
|
|
38
47
|
async function developmentGenerate(options) {
|
|
39
|
-
|
|
48
|
+
const cap = maximum(options);
|
|
40
49
|
if (options.timeoutMs !== void 0 && (!Number.isFinite(options.timeoutMs) || options.timeoutMs < 0)) throw new Error("invalid_timeout");
|
|
41
50
|
const input = options.request;
|
|
42
|
-
const view = await request(options, "/generations", {
|
|
51
|
+
const view = await request(options, "/generations", { ...cap, request: {
|
|
43
52
|
modelId: input.modelId,
|
|
44
53
|
prompt: input.prompt,
|
|
45
54
|
outputFormat: input.outputFormat,
|
|
@@ -49,10 +58,10 @@ async function developmentGenerate(options) {
|
|
|
49
58
|
return wait(options, view, options.timeoutMs ?? 6e5);
|
|
50
59
|
}
|
|
51
60
|
async function developmentJudge(options) {
|
|
52
|
-
|
|
61
|
+
const cap = maximum(options);
|
|
53
62
|
const input = options.request;
|
|
54
63
|
if (!input || input.state === void 0 || !input.questions || typeof input.questions !== "object") throw new Error("invalid_request");
|
|
55
|
-
const view = await request(options, "/judgments", {
|
|
64
|
+
const view = await request(options, "/judgments", { ...cap, request: {
|
|
56
65
|
state: input.state,
|
|
57
66
|
questions: input.questions,
|
|
58
67
|
...input.timeoutMs === void 0 ? {} : { timeoutMs: input.timeoutMs },
|
|
@@ -62,11 +71,11 @@ async function developmentJudge(options) {
|
|
|
62
71
|
return view;
|
|
63
72
|
}
|
|
64
73
|
async function developmentRequestWorkflow(options) {
|
|
65
|
-
|
|
74
|
+
const cap = maximum(options);
|
|
66
75
|
assertIdentifier(options.workflowId);
|
|
67
76
|
assertIdentifier(options.request.offeringId);
|
|
68
77
|
const view = await request(options, "/workflows/" + encodeURIComponent(options.workflowId) + "/requests", {
|
|
69
|
-
|
|
78
|
+
...cap,
|
|
70
79
|
request: {
|
|
71
80
|
offeringId: options.request.offeringId,
|
|
72
81
|
input: options.request.input,
|
package/dist/index.d.ts
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import { RuntimeJudgeQuestion, RuntimeJudgeAnswer, RuntimeJudgmentView, RuntimeWorkflowInput, RuntimeGenerationBilling, RuntimeGenerationFunding, RuntimeGrantView, RuntimeGenerationView, RuntimeGenerationModels, RuntimeWorkflowOfferings } from '@genex/embed-protocol';
|
|
2
|
-
export { RuntimeBillingPolicy, RuntimeExternalProvider, RuntimeGenerationBilling, RuntimeGenerationFunding, RuntimeGenerationModels, RuntimeGenerationStatus, RuntimeGenerationView, RuntimeGrantJudgeTerms, RuntimeGrantStatus, RuntimeGrantTerms, RuntimeGrantView, RuntimeJudgeAnswer, RuntimeJudgeCriterion, RuntimeJudgeQuestion, RuntimeJudgmentView, RuntimeWorkflowInput, RuntimeWorkflowOfferings } from '@genex/embed-protocol';
|
|
2
|
+
export { RuntimeBillingPolicy, RuntimeCurrency, RuntimeExternalProvider, RuntimeGenerationBilling, RuntimeGenerationFunding, RuntimeGenerationModels, RuntimeGenerationStatus, RuntimeGenerationStreamEvent, RuntimeGenerationView, RuntimeGrantJudgeTerms, RuntimeGrantStatus, RuntimeGrantTerms, RuntimeGrantView, RuntimeJudgeAnswer, RuntimeJudgeCriterion, RuntimeJudgeQuestion, RuntimeJudgmentView, RuntimeWorkflowInput, RuntimeWorkflowOfferings } from '@genex/embed-protocol';
|
|
3
3
|
|
|
4
4
|
/** A thing the game sells. Resolved server-side; the game never sets a price. */
|
|
5
5
|
interface ShopItem {
|
|
@@ -122,8 +122,17 @@ declare function buy(opts: {
|
|
|
122
122
|
}): Promise<PurchaseResult>;
|
|
123
123
|
|
|
124
124
|
interface GenerateOptions {
|
|
125
|
-
/**
|
|
126
|
-
|
|
125
|
+
/**
|
|
126
|
+
* The call's CEILING in the player's Genex credits (SDK 0.27+). Not a price:
|
|
127
|
+
* the call is billed AS USED — its real model cost plus the Genex fee, and a
|
|
128
|
+
* one-time call rounds that up to a whole credit — and never past this. The
|
|
129
|
+
* ceiling also funds how long the answer may be, so benchmark it
|
|
130
|
+
* (`genex llm bench`) rather than guess. Pass this or `estimateCoins`.
|
|
131
|
+
*/
|
|
132
|
+
maxCredits?: number;
|
|
133
|
+
/** @deprecated Since 0.27: the same number as `maxCredits`, read by the server
|
|
134
|
+
* as the call's credit ceiling. Kept so games built on earlier versions work. */
|
|
135
|
+
estimateCoins?: number;
|
|
127
136
|
modelId: string;
|
|
128
137
|
prompt: string;
|
|
129
138
|
outputFormat: 'text' | 'json';
|
|
@@ -153,8 +162,15 @@ interface RuntimeGenerationResult extends RuntimeGenerationBilling {
|
|
|
153
162
|
error?: string;
|
|
154
163
|
}
|
|
155
164
|
interface RequestWorkflowOptions {
|
|
156
|
-
/**
|
|
157
|
-
|
|
165
|
+
/**
|
|
166
|
+
* The operation's ceiling. A workflow whose executor bills coin (the default
|
|
167
|
+
* for every executor registered before credits) reads it as its fixed coin
|
|
168
|
+
* price of a started attempt; one whose executor bills credits reads it as the
|
|
169
|
+
* credit ceiling of a request billed as used. Pass this or `maxCredits`.
|
|
170
|
+
*/
|
|
171
|
+
estimateCoins?: number;
|
|
172
|
+
/** The credit ceiling, for a workflow whose executor bills credits (SDK 0.27+). */
|
|
173
|
+
maxCredits?: number;
|
|
158
174
|
/** Offer configured personal Claude/ChatGPT funding on the same quote. Defaults off. */
|
|
159
175
|
allowExternal?: boolean;
|
|
160
176
|
workflowId: string;
|
|
@@ -205,16 +221,30 @@ interface SpendGrantDisclosure {
|
|
|
205
221
|
periodLabel: 'minute' | 'hour' | 'session';
|
|
206
222
|
/** Honest expected calls per period. The sheet shows the player a worst case beside it. */
|
|
207
223
|
estimatedCallsPerPeriod: number;
|
|
208
|
-
/** Honest expected
|
|
209
|
-
|
|
224
|
+
/** Honest expected credits per period, attributed to the game, never as a
|
|
225
|
+
* Genex figure (SDK 0.27+). Pass this or `estimatedCoinsPerPeriod`. */
|
|
226
|
+
estimatedCreditsPerPeriod?: number;
|
|
227
|
+
/** @deprecated Since 0.27: the same number as `estimatedCreditsPerPeriod`. */
|
|
228
|
+
estimatedCoinsPerPeriod?: number;
|
|
210
229
|
}
|
|
211
230
|
interface SpendGrantOptions {
|
|
212
231
|
/** Models this budget may spend on, from getGenerationModels(). One to eight. */
|
|
213
232
|
models: string[];
|
|
214
|
-
/**
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
233
|
+
/**
|
|
234
|
+
* Hard per-call CEILING in credits (SDK 0.27+): the server refuses a call
|
|
235
|
+
* whose `maxCredits` is higher. Calls are billed as used on the budget, so
|
|
236
|
+
* this bounds what one call may reach, not what it costs. Pass this or
|
|
237
|
+
* `perCallMaxCoins`.
|
|
238
|
+
*/
|
|
239
|
+
perCallMaxCredits?: number;
|
|
240
|
+
/** The honest per-call estimate, in credits, the disclosure and a personal
|
|
241
|
+
* plan's request count are built on — never a price. At most the ceiling;
|
|
242
|
+
* defaults to it. */
|
|
243
|
+
perCallEstimateCredits?: number;
|
|
244
|
+
/** @deprecated Since 0.27: the same number as `perCallMaxCredits`. */
|
|
245
|
+
perCallMaxCoins?: number;
|
|
246
|
+
/** @deprecated Since 0.27: the same number as `perCallEstimateCredits`. */
|
|
247
|
+
perCallEstimateCoins?: number;
|
|
218
248
|
disclosure: SpendGrantDisclosure;
|
|
219
249
|
/** Calls this budget may have in flight at once. Server default applies when omitted. */
|
|
220
250
|
maxConcurrent?: number;
|
|
@@ -222,14 +252,14 @@ interface SpendGrantOptions {
|
|
|
222
252
|
maxCallsPerMinute?: number;
|
|
223
253
|
/** Personal-plan jobs that may be queued at once. Server default applies when omitted. */
|
|
224
254
|
maxPendingExternal?: number;
|
|
225
|
-
/** Offer the player's own Claude/ChatGPT plan beside
|
|
255
|
+
/** Offer the player's own Claude/ChatGPT plan beside credits. Defaults off. */
|
|
226
256
|
allowExternal?: boolean;
|
|
227
257
|
/**
|
|
228
|
-
* The game also calls judge() — a fast classifier billed as used
|
|
229
|
-
*
|
|
230
|
-
* case for `estimatedCallsPerPeriod` calls per `disclosure.periodLabel`.
|
|
231
|
-
* budget with the judge is
|
|
232
|
-
* With `enabled: true`, `models` may be empty for a judge-only budget.
|
|
258
|
+
* The game also calls judge() — a fast classifier billed as used, like every
|
|
259
|
+
* call on the budget. The sheet tells the player so, beside the server's own
|
|
260
|
+
* worst case for `estimatedCallsPerPeriod` calls per `disclosure.periodLabel`.
|
|
261
|
+
* A budget with the judge is paid in credits: `allowExternal` offers nothing
|
|
262
|
+
* on it. With `enabled: true`, `models` may be empty for a judge-only budget.
|
|
233
263
|
*/
|
|
234
264
|
judge?: {
|
|
235
265
|
enabled: boolean;
|
|
@@ -267,6 +297,38 @@ declare function stopSpendGrant(grantId: string): Promise<RuntimeGrantView>;
|
|
|
267
297
|
* Store the id: getSpendGrant(id) recovers the budget after a reload.
|
|
268
298
|
*/
|
|
269
299
|
declare function requestSpendGrant(options: SpendGrantOptions): Promise<SpendGrantResult>;
|
|
300
|
+
interface GenerateStreamOptions extends GenerateOptions {
|
|
301
|
+
/** A standing budget from requestSpendGrant(). Required: only a budget streams. */
|
|
302
|
+
grantId: string;
|
|
303
|
+
/**
|
|
304
|
+
* Each piece of the answer as it arrives, and all of it so far. PROVISIONAL:
|
|
305
|
+
* a call can still fail after text has arrived (the model broke off, the
|
|
306
|
+
* JSON did not match the schema) — only the resolved result is the answer.
|
|
307
|
+
*/
|
|
308
|
+
onDelta?: (text: string, soFar: string) => void;
|
|
309
|
+
/**
|
|
310
|
+
* `outputFormat: 'json'` only: the FIRST top-level string property of
|
|
311
|
+
* `schema` (say, an NPC's `line`), as far as the model has written it, read
|
|
312
|
+
* leniently from the growing JSON — so dialogue can appear while the rest of
|
|
313
|
+
* the object is still arriving. Called only when the value grows.
|
|
314
|
+
*/
|
|
315
|
+
onPartialField?: (name: string, partialText: string) => void;
|
|
316
|
+
/**
|
|
317
|
+
* Stops READING the reply, not the call: the model still finishes and the
|
|
318
|
+
* call is charged as usual. Resolves `pending` with `stream_aborted`;
|
|
319
|
+
* waitForGeneration(generationId) recovers the answer.
|
|
320
|
+
*/
|
|
321
|
+
signal?: AbortSignal;
|
|
322
|
+
}
|
|
323
|
+
/**
|
|
324
|
+
* One call under a standing budget, streamed. No popup and no user gesture —
|
|
325
|
+
* the same guards as generate({ grantId }). A call the stand cannot start at
|
|
326
|
+
* once, a replay of a call already running, or a budget on the player's own
|
|
327
|
+
* plan is answered whole: the SDK polls it, and `onDelta` receives the text in
|
|
328
|
+
* one piece at the end. A dropped connection is polled too, because the server
|
|
329
|
+
* keeps reading the model's reply and settles it either way.
|
|
330
|
+
*/
|
|
331
|
+
declare function generateStream(options: GenerateStreamOptions): Promise<RuntimeGenerationResult>;
|
|
270
332
|
interface JudgeOptions {
|
|
271
333
|
/** A standing budget from requestSpendGrant({ judge: { enabled: true, … } }). Required. */
|
|
272
334
|
grantId: string;
|
|
@@ -286,7 +348,7 @@ interface JudgeResult {
|
|
|
286
348
|
/** One typed answer per question; present only on `succeeded`. */
|
|
287
349
|
answers?: Record<string, RuntimeJudgeAnswer>;
|
|
288
350
|
error?: string;
|
|
289
|
-
/** Where the call's money went: never a
|
|
351
|
+
/** Where the call's money went: never a credit of its own, always the budget's meter. */
|
|
290
352
|
billing?: RuntimeJudgmentView['billing'];
|
|
291
353
|
}
|
|
292
354
|
/**
|
|
@@ -567,4 +629,4 @@ declare function __resetForTests(overrides?: {
|
|
|
567
629
|
heartbeatIntervalMs?: number;
|
|
568
630
|
}): void;
|
|
569
631
|
|
|
570
|
-
export { type AuthState, type EmbedConfig, type EmbedEvent, type EmbedUser, type Entitlement, type GenerateOptions, type JudgeOptions, type JudgeResult, type Leaderboard, type LeaderboardEntry, type PlayerStateResult, type PurchaseResult, type PurchaseStatus, type RequestWorkflowOptions, type RuntimeGenerationResult, type RuntimeWorkflowAuthorization, type SaveStateResult, type ShopItem, type SpendGrantDisclosure, type SpendGrantOptions, type SpendGrantResult, type SubmitScoreResult, type WorldStateResult, __resetForTests, _stashTicketFromUrl, buy, consumeEntitlement, generate, generationErrorMessage, getAuthState, getColyseusAuth, getColyseusUrls, getEmbedToken, getEntitlements, getGeneration, getGenerationModels, getLeaderboard, getShop, getSpendGrant, getUser, getWorkflowOfferings, initEmbed, isEmbedded, judge, loadPlayerState, loadWorldState, on, requestSpendGrant, requestWorkflow, resumeWorkflow, savePlayerState, saveWorldState, stopSpendGrant, submitScore, waitForAuth, waitForGeneration, waitForPlayer };
|
|
632
|
+
export { type AuthState, type EmbedConfig, type EmbedEvent, type EmbedUser, type Entitlement, type GenerateOptions, type GenerateStreamOptions, type JudgeOptions, type JudgeResult, type Leaderboard, type LeaderboardEntry, type PlayerStateResult, type PurchaseResult, type PurchaseStatus, type RequestWorkflowOptions, type RuntimeGenerationResult, type RuntimeWorkflowAuthorization, type SaveStateResult, type ShopItem, type SpendGrantDisclosure, type SpendGrantOptions, type SpendGrantResult, type SubmitScoreResult, type WorldStateResult, __resetForTests, _stashTicketFromUrl, buy, consumeEntitlement, generate, generateStream, generationErrorMessage, getAuthState, getColyseusAuth, getColyseusUrls, getEmbedToken, getEntitlements, getGeneration, getGenerationModels, getLeaderboard, getShop, getSpendGrant, getUser, getWorkflowOfferings, initEmbed, isEmbedded, judge, loadPlayerState, loadWorldState, on, requestSpendGrant, requestWorkflow, resumeWorkflow, savePlayerState, saveWorldState, stopSpendGrant, submitScore, waitForAuth, waitForGeneration, waitForPlayer };
|
package/dist/index.js
CHANGED
|
@@ -4,6 +4,7 @@ import {
|
|
|
4
4
|
buy,
|
|
5
5
|
consumeEntitlement,
|
|
6
6
|
generate,
|
|
7
|
+
generateStream,
|
|
7
8
|
generationErrorMessage,
|
|
8
9
|
getAuthState,
|
|
9
10
|
getColyseusAuth,
|
|
@@ -33,14 +34,15 @@ import {
|
|
|
33
34
|
waitForAuth,
|
|
34
35
|
waitForGeneration,
|
|
35
36
|
waitForPlayer
|
|
36
|
-
} from "./chunk-
|
|
37
|
-
import "./chunk-
|
|
37
|
+
} from "./chunk-7SWNXF5V.js";
|
|
38
|
+
import "./chunk-MJPLBT3T.js";
|
|
38
39
|
export {
|
|
39
40
|
__resetForTests,
|
|
40
41
|
_stashTicketFromUrl,
|
|
41
42
|
buy,
|
|
42
43
|
consumeEntitlement,
|
|
43
44
|
generate,
|
|
45
|
+
generateStream,
|
|
44
46
|
generationErrorMessage,
|
|
45
47
|
getAuthState,
|
|
46
48
|
getColyseusAuth,
|
package/dist/sentry.js
CHANGED
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@genex-ai/embed-sdk",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.27.0",
|
|
4
4
|
"description": "Player identity + durable game state for genex games \u2014 signed-in or guest play, per-player save slots, shared world state, and soft-trust leaderboards.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "./dist/index.js",
|