@genex-ai/embed-sdk 0.26.0 → 0.28.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 +159 -89
- package/dist/{chunk-KEPAMDTE.js → chunk-WSJ5XPEF.js} +65 -23
- package/dist/development.d.ts +25 -15
- package/dist/development.js +23 -11
- package/dist/index.d.ts +63 -19
- package/dist/index.js +1 -1
- package/dist/sentry.js +1 -1
- 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,42 +50,85 @@ 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 `
|
|
54
|
-
|
|
55
|
-
|
|
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'`,
|
|
56
|
+
optional bounded `schema`, `maxOutputTokens` (SDK **0.28.0+**, see *How long a
|
|
57
|
+
call may be*), `allowExternal` (default false), `idempotencyKey`,
|
|
58
|
+
`timeoutMs` (default twenty minutes since 0.28.0; ten before) and `grantId` — a standing budget the player
|
|
56
59
|
already approved, which removes the popup entirely (see *Standing budgets*). Reuse an idempotency key only for the same
|
|
57
60
|
operation; store it if you need retries to survive a reload. Only models returned
|
|
58
61
|
by Genex are accepted. This first adapter generates text and JSON, including
|
|
59
62
|
creature descriptions, dialogue, rules and other structured game data.
|
|
60
63
|
|
|
64
|
+
### How long a call may be
|
|
65
|
+
|
|
66
|
+
SDK **0.28.0+**. A call's size is the stand's, served by
|
|
67
|
+
`getGenerationModels()` as `limits`: `maxPromptBytes` and `maxSchemaBytes`
|
|
68
|
+
(UTF-8 bytes), `defaultOutputTokens` (the answer's budget when you name none),
|
|
69
|
+
`maxOutputTokens` (the most you may ask for) and `maxOutputBytes` (the answer,
|
|
70
|
+
JSON-encoded). Read them; do not copy numbers into the game. A game that writes
|
|
71
|
+
long answers — generated code, a whole scene — asks for room:
|
|
72
|
+
|
|
73
|
+
```ts
|
|
74
|
+
const { limits } = await getGenerationModels();
|
|
75
|
+
const reply = await generate({
|
|
76
|
+
...request, // modelId, prompt, outputFormat
|
|
77
|
+
maxOutputTokens: Math.min(24_000, limits?.maxOutputTokens ?? 24_000),
|
|
78
|
+
maxCredits: benchmarkedCeiling, // must FUND that length
|
|
79
|
+
grantId,
|
|
80
|
+
});
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
`maxOutputTokens` is a ceiling, not a purchase: the call is quoted on it, and
|
|
84
|
+
the answer gets only as many tokens as `maxCredits` funds (the ceiling also
|
|
85
|
+
buys the length). Under a budget the call's ceiling still may not pass the
|
|
86
|
+
`perCallMaxCredits` the player approved. Benchmark with the same
|
|
87
|
+
`maxOutputTokens` (`developmentGenerate({ request: { maxOutputTokens } })`).
|
|
88
|
+
Over a limit the call fails before anything is quoted or charged:
|
|
89
|
+
`prompt_too_large`, `schema_too_large` or `output_tokens_too_large`; a malformed
|
|
90
|
+
`maxOutputTokens` is `invalid_max_output_tokens` before the network. The server
|
|
91
|
+
gives a call time in proportion to the output it may write (minutes for the
|
|
92
|
+
longest answers), so the default wait is twenty minutes; answers that take
|
|
93
|
+
minutes are best streamed (`generateStream()`).
|
|
94
|
+
|
|
61
95
|
SDK **0.21.0+** returns the execution `status`, optional `generationId`, and
|
|
62
96
|
`output` plus `source` on success. Cancellation is a normal `canceled` result,
|
|
63
97
|
but it does not imply that consumed work was free. `pending` with
|
|
64
98
|
`error: 'wait_timeout'` means the SDK stopped waiting; it does not cancel or charge
|
|
65
99
|
again. Persist `generationId` and resume with `waitForGeneration(id)`, or inspect
|
|
66
100
|
the current server state with `getGeneration(id)`. Results also carry the
|
|
67
|
-
server's `billingStatus: 'pending'|'final'`, `
|
|
68
|
-
`
|
|
69
|
-
available, including on failures
|
|
101
|
+
server's `billingStatus: 'pending'|'final'`, `currency`, `chargedCredits`,
|
|
102
|
+
`reservedCredits`, `maxCredits`, `chargedDisplayUsdCents` and
|
|
103
|
+
`reservedDisplayUsdCents` when available, including on failures (`chargedCoins`
|
|
104
|
+
and `reservedCoins` stay present, and 0, on a credit receipt, for code written
|
|
105
|
+
before credits). These USD amounts use the frozen credit value;
|
|
70
106
|
never derive them from an estimate or the current catalog. An execution can end
|
|
71
107
|
while billing remains pending. `waitForGeneration()` waits for execution;
|
|
72
108
|
continue reading `getGeneration(id)` for later billing settlement. Missing
|
|
73
109
|
receipt fields mean unavailable information, not zero cost.
|
|
74
110
|
|
|
75
|
-
|
|
76
|
-
the frozen request
|
|
77
|
-
|
|
78
|
-
`
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
111
|
+
**In-game calls are paid from the player's Genex credits and billed as used.**
|
|
112
|
+
The Genex modal shows the game, the frozen request and "billed as used, up to N
|
|
113
|
+
credits" with its USD equivalent before approval. New quotes carry
|
|
114
|
+
`quote.billingPolicy: 'metered-credits-v1'`, `kind: 'metered'`, `currency:
|
|
115
|
+
'credits'` and `quote.maxCredits` — the call's quoted maximum with the Genex
|
|
116
|
+
fee, never above your `maxCredits`. Approval holds that many credits; when the
|
|
117
|
+
call settles it is charged its REAL model cost plus the Genex fee, rounded up
|
|
118
|
+
to a whole credit (so a very small one-time call costs one credit), and the rest
|
|
119
|
+
is released. Model work that fails or is canceled is still charged for what it
|
|
120
|
+
used; a request the provider refused before any work, or verified zero model
|
|
121
|
+
cost, is free. `maxCredits` is a ceiling, not a price: it caps what one call
|
|
122
|
+
may reach and funds how long its answer may be. Every Genex API model needs a
|
|
123
|
+
positive ceiling, including Gemini and GLM. A player who has not verified their
|
|
124
|
+
email is refused (`credits_unverified`), one short of credits sees
|
|
125
|
+
`insufficient_credits`, and Genex may pause paid generation platform-wide
|
|
126
|
+
(`generation_paused`). Personal funding chosen in the trusted approval modal
|
|
127
|
+
costs nothing on Genex. Quotes issued before 0.27's server change — `declared-v1`,
|
|
128
|
+
a fixed coin price per started attempt — keep their terms.
|
|
129
|
+
|
|
130
|
+
The provider hard budget is derived from that ceiling after the frozen platform
|
|
131
|
+
fee, then capped by operator limits. Output is clipped to remaining funding;
|
|
89
132
|
an input that cannot fit is refused before a call. Unresolved provider expense
|
|
90
133
|
keeps billing pending and the reservation held until verified. The trusted UI
|
|
91
134
|
must acknowledge the quote's exact `billingPolicy` at confirmation; an old UI
|
|
@@ -96,10 +139,10 @@ unconfirmed zero-price API quote needs a fresh price review before coin approval
|
|
|
96
139
|
never silently replace its price or start a paid request during recovery.
|
|
97
140
|
|
|
98
141
|
With `allowExternal: true`, Genex can offer the configured personal plan matching
|
|
99
|
-
the selected model alongside
|
|
142
|
+
the selected model alongside credits: Claude for `anthropic/` models, ChatGPT for
|
|
100
143
|
`openai/` models, and neither for other models. This choice appears only in the
|
|
101
144
|
trusted Genex approval modal; never add a "Your Plan" model row in the game.
|
|
102
|
-
Each personal choice costs
|
|
145
|
+
Each personal choice costs nothing on Genex and its own plan and usage limits apply.
|
|
103
146
|
New quotes freeze the matching choices; connector metadata stays server-owned.
|
|
104
147
|
Old unapproved quotes are narrowed to the matching provider before confirmation;
|
|
105
148
|
approved personal requests retain their connector for recovery. Once chosen,
|
|
@@ -130,9 +173,9 @@ talkButton.addEventListener('click', async () => {
|
|
|
130
173
|
if (!grantId) {
|
|
131
174
|
const budget = await requestSpendGrant({
|
|
132
175
|
models: [model.id],
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
disclosure: { periodLabel: 'minute', estimatedCallsPerPeriod: 4,
|
|
176
|
+
perCallMaxCredits: 8, // Hard ceiling per call. The server refuses a call asking more.
|
|
177
|
+
perCallEstimateCredits: 2, // The honest per-call estimate, benchmarked first.
|
|
178
|
+
disclosure: { periodLabel: 'minute', estimatedCallsPerPeriod: 4, estimatedCreditsPerPeriod: 8 },
|
|
136
179
|
maxConcurrent: 2,
|
|
137
180
|
idempotencyKey: 'npc-conversation-budget',
|
|
138
181
|
});
|
|
@@ -156,13 +199,19 @@ posts no parent message and needs no user gesture**, so it works from a game
|
|
|
156
199
|
loop or a timer. Every other guard is unchanged: production play, a signed-in
|
|
157
200
|
player, a trusted parent origin, and no native or local-test surface. The
|
|
158
201
|
funding door was chosen once in the sheet, so `allowExternal` is ignored on a
|
|
159
|
-
budget call.
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
202
|
+
budget call. Every call is **billed as used on the budget**: its real model
|
|
203
|
+
cost plus the Genex fee accrues there, and the player's credits move one whole
|
|
204
|
+
credit at a time as calls add up — a call's own receipt carries
|
|
205
|
+
`metered.chargedUsdPicos` (what it added) and `chargedCredits: 0`, and when the
|
|
206
|
+
budget ends any remainder is one credit. The per-call ceiling is `maxCredits`,
|
|
207
|
+
at most the budget's `perCallMaxCredits`.
|
|
208
|
+
|
|
209
|
+
`getSpendGrant(id)` is the readout to draw in the game: `limitCredits`,
|
|
210
|
+
`spentCredits`, `heldCredits` (what the budget holds for calls not settled yet,
|
|
211
|
+
and for a remainder under one credit), `remainingCredits`, `limitCalls`,
|
|
212
|
+
`callCount`, `status` and the frozen `terms` (a budget approved before credits
|
|
213
|
+
reports the same in `limitCoins`/`spentCoins`/…, and a credit budget keeps
|
|
214
|
+
those at 0). Poll it on the
|
|
166
215
|
cadence your HUD needs — never derive the remaining budget from your own count
|
|
167
216
|
of calls, and never show a figure the server did not send. Store `grantId` the
|
|
168
217
|
way you store a `generationId`; `getSpendGrant()` recovers the budget after a
|
|
@@ -174,21 +223,25 @@ same lever on Genex, on every page, and theirs always outranks the game's.
|
|
|
174
223
|
**The disclosure is a promise, not a guess.** `disclosure` is what the Genex
|
|
175
224
|
sheet shows the player, attributed to your game — Genex prints a server-computed
|
|
176
225
|
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
|
-
|
|
226
|
+
rate you actually expect, benchmark `perCallEstimateCredits` before you declare
|
|
227
|
+
it (see *Benchmark your own costs* below), and keep `perCallMaxCredits` a real
|
|
228
|
+
ceiling. The server refuses a call whose ceiling passes it
|
|
229
|
+
(`grant_price_unreasonable`) — that check is what replaces the popup, so a
|
|
230
|
+
budget is never a blank cheque. `perCallMaxCoins`, `perCallEstimateCoins` and
|
|
231
|
+
`estimatedCoinsPerPeriod` (before 0.27) are accepted as the same credit numbers.
|
|
232
|
+
The slider's bounds, the credit value, the fee and the recommended headroom all
|
|
233
|
+
come from the server; read them from `getGenerationModels()`
|
|
234
|
+
(`standingCreditGrant`, `usdCentsPerCredit`, `feeBps`,
|
|
235
|
+
`recommendedDeclaredHeadroomBps`) rather than typing any of them into the game.
|
|
185
236
|
|
|
186
237
|
**Handle the refusals as game states.** A budget ends for ordinary reasons and
|
|
187
238
|
the game should have believable copy for each:
|
|
188
239
|
`grant_limit_reached` (the player's limit is spent), `grant_stopped`,
|
|
189
240
|
`grant_expired`, `grant_not_active`, `grant_concurrency` and
|
|
190
241
|
`grant_rate_limited` (your own declared ceilings), `grant_insufficient_funds`
|
|
191
|
-
(the
|
|
242
|
+
(the player's credits ran low — the budget resumes when they top up),
|
|
243
|
+
`credits_unverified` (verify the email on Genex), `generation_paused` (Genex
|
|
244
|
+
paused paid generation; retry later),
|
|
192
245
|
`waiting_for_plan` (a personal plan's own rate limit; it resumes by itself),
|
|
193
246
|
`grant_price_unreasonable`, `grant_already_active`, `external_grant_active` and
|
|
194
247
|
`invalid_grant_limit`. `generationErrorMessage(code)` returns a player-facing
|
|
@@ -235,8 +288,8 @@ It resolves to **the same result `generate()` gives** — status, output, receip
|
|
|
235
288
|
— and that result, not the pieces, is the answer. Pieces are provisional: a call
|
|
236
289
|
can still fail after text has arrived (the model broke off, or a JSON answer
|
|
237
290
|
did not match the schema), so let the resolved status decide what the game
|
|
238
|
-
keeps.
|
|
239
|
-
it succeeds, fails, or the player walks away mid-sentence.
|
|
291
|
+
keeps. It is billed exactly as a budget `generate()` call is — as used, on the
|
|
292
|
+
budget — whether it succeeds, fails, or the player walks away mid-sentence.
|
|
240
293
|
|
|
241
294
|
For `outputFormat: 'json'`, `onPartialField(name, partialText)` reports the
|
|
242
295
|
**first top-level string property of `schema`** as far as the model has written
|
|
@@ -276,19 +329,19 @@ classifier typed questions and gets calibrated probabilities back, typically in
|
|
|
276
329
|
about a third of a second. It writes no prose and invents no numbers, which is
|
|
277
330
|
exactly what makes it a steadier referee than a chat model asked to classify.
|
|
278
331
|
|
|
279
|
-
It is **grant-only** and **billed as used
|
|
280
|
-
|
|
281
|
-
add up
|
|
282
|
-
budget ends, a remainder is one
|
|
283
|
-
it when you request the budget:
|
|
332
|
+
It is **grant-only** and **billed as used**, on the same budget as its
|
|
333
|
+
generations: a call costs a small fraction of a credit, so it is never charged
|
|
334
|
+
a credit of its own. Calls add up on the budget, and a whole credit is taken
|
|
335
|
+
each time they reach one; when the budget ends, a remainder is one credit and
|
|
336
|
+
anything still held goes back. Ask for it when you request the budget:
|
|
284
337
|
|
|
285
338
|
```ts
|
|
286
339
|
import { requestSpendGrant, judge, generationErrorMessage } from '@genex-ai/embed-sdk';
|
|
287
340
|
|
|
288
341
|
const budget = await requestSpendGrant({
|
|
289
342
|
models: [model.id], // or [] for a judge-only budget
|
|
290
|
-
|
|
291
|
-
disclosure: { periodLabel: 'minute', estimatedCallsPerPeriod: 4,
|
|
343
|
+
perCallMaxCredits: 8, perCallEstimateCredits: 2,
|
|
344
|
+
disclosure: { periodLabel: 'minute', estimatedCallsPerPeriod: 4, estimatedCreditsPerPeriod: 8 },
|
|
292
345
|
judge: { enabled: true, estimatedCallsPerPeriod: 30 }, // honest checks per period
|
|
293
346
|
});
|
|
294
347
|
|
|
@@ -324,24 +377,26 @@ it opens no window. The answer arrives in the same response; reuse an
|
|
|
324
377
|
out (`timeoutMs`, 1000–20000) is `unknown` and billed at its maximum, because
|
|
325
378
|
the work may have run. The refusals to handle as game states:
|
|
326
379
|
`judge_requires_grant` (no budget), `judge_not_enabled` (the budget was approved
|
|
327
|
-
without the judge — request a new one), `
|
|
380
|
+
without the judge — request a new one), `judge_requires_credits` (and, on a
|
|
381
|
+
budget approved before credits, `judge_requires_coins`),
|
|
328
382
|
`judge_period_limit` (the checks reached the per-period ceiling the player was
|
|
329
383
|
shown — it rolls, so try again shortly), `judge_busy` and `judge_paused` (the
|
|
330
384
|
platform's, retry later), `request_too_large` (state and questions over the
|
|
331
385
|
byte bound), and every budget code above — `grant_concurrency` now also means
|
|
332
|
-
"fits once calls in flight land", never an ended budget. The receipt is on `verdict.billing` (`chargedCoins`
|
|
333
|
-
0; `chargedUsdPicos` is what this call added
|
|
334
|
-
`
|
|
386
|
+
"fits once calls in flight land", never an ended budget. The receipt is on `verdict.billing` (`chargedCredits` and `chargedCoins` are
|
|
387
|
+
always 0; `chargedUsdPicos` is what this call added; `billingPolicy` is
|
|
388
|
+
`metered-credits-v1`); the budget's `spentCredits` and `heldCredits` are the
|
|
389
|
+
numbers to show.
|
|
335
390
|
|
|
336
|
-
Benchmark on your own
|
|
337
|
-
`@genex-ai/embed-sdk/development` (same shape, `{
|
|
338
|
-
billed one whole
|
|
339
|
-
|
|
391
|
+
Benchmark on your own credits with `developmentJudge()` from
|
|
392
|
+
`@genex-ai/embed-sdk/development` (same shape, `{ maxCredits, request }`). It is
|
|
393
|
+
billed one whole credit a call — a player's budget, which meters, spends far
|
|
394
|
+
less for the same calls.
|
|
340
395
|
|
|
341
396
|
## Your subscription and the Genex player watcher
|
|
342
397
|
|
|
343
398
|
Both approval sheets can offer the player their own Claude or ChatGPT plan
|
|
344
|
-
beside
|
|
399
|
+
beside credits, when the selected model's provider matches. That choice lives in
|
|
345
400
|
the trusted Genex surface only — never add a plan row to the game's own model
|
|
346
401
|
picker, and never ask a player for a subscription credential. Genex neither
|
|
347
402
|
collects nor hosts them.
|
|
@@ -353,7 +408,7 @@ it, Genex shows them the one-time prompt: *"Install the Genex player watcher:
|
|
|
353
408
|
run `npx @genex-ai/cli-demo@latest player install` and approve it on Genex."*
|
|
354
409
|
The game does not install, start or speak to the watcher; it only reads
|
|
355
410
|
`watcherOnline` on a grant or generation view when Genex includes it. A
|
|
356
|
-
personal-plan result costs
|
|
411
|
+
personal-plan result costs nothing on Genex, is metered in requests rather than credits,
|
|
357
412
|
and arrives with `source: 'external'` and `modelProvenance: 'unverified'`:
|
|
358
413
|
user-supplied output, never proof that a particular model produced it, and
|
|
359
414
|
never authority for money or rewards. When the player's own plan hits its rate limit
|
|
@@ -365,8 +420,17 @@ to paid work.
|
|
|
365
420
|
SDK **0.21.0+** supports multi-step generation and usage receipts through an
|
|
366
421
|
operator-registered workflow. This requires the game's trusted server executor;
|
|
367
422
|
an ordinary creator API key cannot register a workflow or dispatch its steps.
|
|
368
|
-
|
|
369
|
-
|
|
423
|
+
**Which wallet a workflow bills is its executor's registration.** An executor
|
|
424
|
+
left on `funding: 'coins'` (every executor registered before credits, by
|
|
425
|
+
default) keeps the fixed-price coin terms below: `requestWorkflow()` requires the
|
|
426
|
+
fixed `estimateCoins` price, and offerings and quotes are `declared-v1` with a
|
|
427
|
+
multiplier of 2 or 3. An executor switched to `funding: 'credits'` issues
|
|
428
|
+
`metered-credits-v1` offerings and quotes instead — `estimatedCredits`,
|
|
429
|
+
`maxCredits`, `feeBps`, `currency: 'credits'`, coin fields 0, and the
|
|
430
|
+
registered `priceMultiplier` served unchanged but pricing nothing: the run is
|
|
431
|
+
billed its steps' real cost plus the Genex fee, rounded up to a whole credit.
|
|
432
|
+
Pass `maxCredits` (or `estimateCoins`, read as the same ceiling) to such a
|
|
433
|
+
workflow. A game must accept the new policy before its executor is switched.
|
|
370
434
|
|
|
371
435
|
```ts
|
|
372
436
|
import { getWorkflowOfferings, requestWorkflow, getEmbedToken } from '@genex-ai/embed-sdk';
|
|
@@ -413,14 +477,14 @@ Recovering local state never starts a fresh charge without another player click.
|
|
|
413
477
|
Read a fresh embed token when sending an approved run to the game backend; never
|
|
414
478
|
persist or log the token.
|
|
415
479
|
|
|
416
|
-
|
|
480
|
+
On a COIN executor, the catalog's `estimatedCoins` and `priceCoins` are suggested price aliases,
|
|
417
481
|
and its maximum describes operator limits. Choose the game's fixed attempt price
|
|
418
482
|
after development benchmarks, pass it as `estimateCoins`, and show coin plus USD.
|
|
419
483
|
The player's final approval always uses the server quote. Preserve the selected
|
|
420
484
|
model, bundle, funding, availability and operator-owned tariff; the game cannot
|
|
421
485
|
change provider prices, dispatch costs or settlement.
|
|
422
486
|
|
|
423
|
-
For new public workflow quotes, `maxCoins` is the same fixed amount as
|
|
487
|
+
For a coin executor's new public workflow quotes, `maxCoins` is the same fixed amount as
|
|
424
488
|
`priceCoins`, not a promise to bill actual usage. The operator-owned multiplier
|
|
425
489
|
(2 or 3, default 3) determines how much model work that fixed price can fund.
|
|
426
490
|
The whole started attempt is charged once, including failed or canceled work;
|
|
@@ -431,7 +495,7 @@ artifact; the browser cannot settle it.
|
|
|
431
495
|
Use `resumeWorkflow(generationId, { timeoutMs? })` directly from a click to
|
|
432
496
|
reopen a saved approval. It reads the original request without creating a quote
|
|
433
497
|
or requiring a new price, including pre-0.21 consumed and legacy approvals.
|
|
434
|
-
Use `requestWorkflow()` with
|
|
498
|
+
Use `requestWorkflow()` with `estimateCoins` (a coin executor) or `maxCredits` (a credit executor) for new operations.
|
|
435
499
|
|
|
436
500
|
Legacy quotes without `billingPolicy` retain their original fixed-price and
|
|
437
501
|
refund terms. Never replace a saved quote's policy with the current catalog's
|
|
@@ -458,11 +522,11 @@ The [runtime API contract](../../CLI_INTEGRATION.md#10-player-funded-runtime-gen
|
|
|
458
522
|
describes both APIs, executor authorization, recovery and connector endpoints.
|
|
459
523
|
|
|
460
524
|
|
|
461
|
-
## Benchmark your own
|
|
525
|
+
## Benchmark your own costs on the server
|
|
462
526
|
|
|
463
527
|
`npx genex llm bench` is the CLI door onto this lane: it runs the real model
|
|
464
|
-
against your own
|
|
465
|
-
the
|
|
528
|
+
against your own credits, reports what it actually cost and charged, and
|
|
529
|
+
recommends the per-call ceiling to declare. Reach for the API below when you want the samples in your
|
|
466
530
|
own script.
|
|
467
531
|
|
|
468
532
|
SDK **0.21.0+** provides `@genex-ai/embed-sdk/development`. Use it only in a
|
|
@@ -472,11 +536,13 @@ player wallet. Restricted API keys and personal-only offerings are refused.
|
|
|
472
536
|
Keep the credential out of game code, browser environment variables and logs;
|
|
473
537
|
the subpath is disabled for browser resolution and rejects browser execution.
|
|
474
538
|
|
|
475
|
-
`maxCoins` is
|
|
476
|
-
|
|
477
|
-
|
|
478
|
-
|
|
479
|
-
|
|
539
|
+
`maxCredits` (SDK 0.27.0+; `maxCoins` is the same number under its old name) is
|
|
540
|
+
an explicit positive maximum from your own credits. Development uses
|
|
541
|
+
`metered-credits-v1`: actual model usage plus the Genex fee, rounded up to a
|
|
542
|
+
whole credit per call, including failed usage, up to that maximum (a workflow
|
|
543
|
+
whose executor still bills coin uses `consumed-v1` on your coin wallet).
|
|
544
|
+
Gemini/GLM models are paid too. Actual zero cost is free; unknown expense
|
|
545
|
+
remains held. No personal or paid fallback occurs.
|
|
480
546
|
|
|
481
547
|
```ts
|
|
482
548
|
import { developmentGenerate } from '@genex-ai/embed-sdk/development';
|
|
@@ -485,33 +551,37 @@ const receipt = await developmentGenerate({
|
|
|
485
551
|
apiUrl: process.env.GENEX_API_URL!,
|
|
486
552
|
creatorToken: process.env.GENEX_CREATOR_TOKEN!,
|
|
487
553
|
projectId: process.env.GENEX_PROJECT_ID!,
|
|
488
|
-
|
|
554
|
+
maxCredits: 5,
|
|
489
555
|
request: {
|
|
490
556
|
modelId: 'your-configured-model-id',
|
|
491
557
|
prompt: 'Invent a friendly creature name.',
|
|
492
558
|
outputFormat: 'text',
|
|
559
|
+
// maxOutputTokens: 24_000, // 0.28.0+: bench exactly what the game will ask for
|
|
493
560
|
idempotencyKey: 'calibration-sample-001',
|
|
494
561
|
},
|
|
495
562
|
});
|
|
496
|
-
// A 5-
|
|
497
|
-
//
|
|
498
|
-
|
|
563
|
+
// A 5-credit maximum can return chargedCredits: 1 for a small call. Use the
|
|
564
|
+
// actual cost of repeated samples (usage.costUsdPicos) and usage.fitCredits to
|
|
565
|
+
// choose the ceiling your game declares as maxCredits.
|
|
566
|
+
if (receipt.billingStatus === 'final') useForCalibration(receipt.chargedCredits, receipt.usage);
|
|
499
567
|
```
|
|
500
568
|
|
|
501
569
|
The full receipt includes execution status, output on success, charged/reserved
|
|
502
|
-
|
|
570
|
+
credits and USD, plus development-only `usage: { costUsdPicos, costUsd,
|
|
503
571
|
maxProviderUsdPicos, unknownProviderUsdPicos }`. Unknown cost is null rather
|
|
504
572
|
than zero; workflow cost aggregates known actual step costs and reports remaining
|
|
505
573
|
unknown exposure separately. No token counts are inferred: SDK 0.24.3+ types the
|
|
506
574
|
counts the provider REPORTED (`usage.inputTokens`, `usage.outputTokens`, null
|
|
507
|
-
when none), the call's own `usage.maxOutputTokens`, and `usage.
|
|
508
|
-
|
|
509
|
-
the stand's headroom. The
|
|
510
|
-
be, so
|
|
511
|
-
|
|
512
|
-
|
|
513
|
-
|
|
514
|
-
|
|
575
|
+
when none), the call's own `usage.maxOutputTokens`, and `usage.fitCredits` (SDK
|
|
576
|
+
0.27.0+; `usage.fitCoins` on a coin row) — the smallest per-call ceiling whose
|
|
577
|
+
funded output allowance holds that answer plus the stand's headroom. The
|
|
578
|
+
ceiling also decides how long the answer may be, so declare at least the p95
|
|
579
|
+
`fitCredits` of your settled samples, not the charged credits alone.
|
|
580
|
+
`usage.truncated` marks an answer the model had to stop writing (`error:
|
|
581
|
+
'provider_token_limit'`, still charged: re-run with a higher `maxCredits`), and
|
|
582
|
+
`usage.fitExceedsCap` an answer longer than the output cap the call asked for
|
|
583
|
+
(its `maxOutputTokens`, else the stand's default): ask for more room, up to
|
|
584
|
+
`limits.maxOutputTokens`, or for a shorter answer. When the provider
|
|
515
585
|
refused the request before running it (a rejected key, an unknown model, a rate
|
|
516
586
|
limit — `error: 'provider_http_<status>'`), nothing is charged, the hold is
|
|
517
587
|
released, and SDK 0.24.2+ types `providerMessage`: the provider's own words,
|
|
@@ -522,8 +592,8 @@ and every in-game call there answers `provider_http_401` until an operator
|
|
|
522
592
|
replaces it — check it before a benchmark, not after.
|
|
523
593
|
|
|
524
594
|
For a registered workflow, call `developmentRequestWorkflow({ apiUrl,
|
|
525
|
-
creatorToken, projectId, workflowId,
|
|
526
|
-
idempotencyKey? } })
|
|
595
|
+
creatorToken, projectId, workflowId, maxCredits, request: { offeringId, input,
|
|
596
|
+
idempotencyKey? } })` (on a coin executor the same number is its coin cap). It returns the accepted, claimed workflow immediately so
|
|
527
597
|
your trusted executor can enqueue it. After enqueueing, call
|
|
528
598
|
`waitForDevelopmentGeneration(config, id, timeoutMs?)`. Both generic and workflow
|
|
529
599
|
benchmarks are recoverable with `getDevelopmentGeneration(config, id)` and
|
|
@@ -268,6 +268,18 @@ async function request(path, body) {
|
|
|
268
268
|
function validEstimateCoins(value) {
|
|
269
269
|
return Number.isSafeInteger(value) && value >= 0 && value <= 1e6;
|
|
270
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
|
+
}
|
|
279
|
+
function validMaxOutputTokens(value) {
|
|
280
|
+
return value === void 0 || Number.isSafeInteger(value) && value >= 1;
|
|
281
|
+
}
|
|
282
|
+
var GENERATION_WAIT_MS = 12e5;
|
|
271
283
|
function getGenerationModels() {
|
|
272
284
|
return request("/models");
|
|
273
285
|
}
|
|
@@ -299,6 +311,10 @@ function outcome(view) {
|
|
|
299
311
|
function billingReceipt(view) {
|
|
300
312
|
return {
|
|
301
313
|
...view.billingStatus !== void 0 ? { billingStatus: view.billingStatus } : {},
|
|
314
|
+
...view.currency !== void 0 ? { currency: view.currency } : {},
|
|
315
|
+
...view.maxCredits !== void 0 ? { maxCredits: view.maxCredits } : {},
|
|
316
|
+
...view.reservedCredits !== void 0 ? { reservedCredits: view.reservedCredits } : {},
|
|
317
|
+
...view.chargedCredits !== void 0 ? { chargedCredits: view.chargedCredits } : {},
|
|
302
318
|
...view.reservedCoins !== void 0 ? { reservedCoins: view.reservedCoins } : {},
|
|
303
319
|
...view.reservedDisplayUsdCents !== void 0 ? { reservedDisplayUsdCents: view.reservedDisplayUsdCents } : {},
|
|
304
320
|
...view.chargedCoins !== void 0 ? { chargedCoins: view.chargedCoins } : {},
|
|
@@ -335,29 +351,33 @@ async function poll(generationId, timeoutMs, readOutcome, popup) {
|
|
|
335
351
|
}
|
|
336
352
|
return { status: "pending", generationId, error: "wait_timeout" };
|
|
337
353
|
}
|
|
338
|
-
function waitForGeneration(generationId, timeoutMs =
|
|
354
|
+
function waitForGeneration(generationId, timeoutMs = GENERATION_WAIT_MS) {
|
|
339
355
|
if (!isGenerationId(generationId)) return Promise.resolve({ status: "failed", error: "invalid_generation_id" });
|
|
340
356
|
return poll(generationId, timeoutMs, outcome);
|
|
341
357
|
}
|
|
342
358
|
async function generate(options) {
|
|
343
|
-
|
|
344
|
-
|
|
345
|
-
if (
|
|
359
|
+
const ceiling = ceilingField(options);
|
|
360
|
+
if ("error" in ceiling) return { status: "failed", error: ceiling.error };
|
|
361
|
+
if (!validMaxOutputTokens(options.maxOutputTokens)) return { status: "failed", error: "invalid_max_output_tokens" };
|
|
362
|
+
const { timeoutMs, idempotencyKey, grantId, maxCredits: _credits, estimateCoins: _coins, ...rest } = options;
|
|
363
|
+
const input = { ...rest, ...ceiling.field };
|
|
364
|
+
if (grantId !== void 0) return generateUnderGrant(grantId, input, idempotencyKey, timeoutMs ?? GENERATION_WAIT_MS);
|
|
346
365
|
return startGeneration(
|
|
347
366
|
"/generations",
|
|
348
367
|
{ ...input, idempotencyKey },
|
|
349
|
-
timeoutMs ??
|
|
368
|
+
timeoutMs ?? GENERATION_WAIT_MS,
|
|
350
369
|
outcome
|
|
351
370
|
);
|
|
352
371
|
}
|
|
353
372
|
async function requestWorkflow(options) {
|
|
354
|
-
|
|
373
|
+
const ceiling = ceilingField(options);
|
|
374
|
+
if ("error" in ceiling) return { status: "failed", error: ceiling.error };
|
|
355
375
|
if (!isWorkflowIdentifier(options.workflowId)) return { status: "failed", error: "invalid_workflow_id" };
|
|
356
376
|
if (!isWorkflowIdentifier(options.offeringId)) return { status: "failed", error: "invalid_offering_id" };
|
|
357
377
|
return startGeneration(`/workflows/${encodeURIComponent(options.workflowId)}/requests`, {
|
|
358
378
|
offeringId: options.offeringId,
|
|
359
379
|
input: options.input,
|
|
360
|
-
|
|
380
|
+
...ceiling.field,
|
|
361
381
|
...options.allowExternal !== void 0 ? { allowExternal: options.allowExternal } : {},
|
|
362
382
|
idempotencyKey: options.idempotencyKey
|
|
363
383
|
}, options.timeoutMs ?? 6e5, authorizationOutcome, options);
|
|
@@ -409,7 +429,7 @@ async function startGeneration(path, body, timeoutMs, readOutcome, workflow, res
|
|
|
409
429
|
throw new Error("invalid_generation_response");
|
|
410
430
|
}
|
|
411
431
|
const result = readOutcome(view);
|
|
412
|
-
const needsReceipt = view.billingStatus === "pending" || view.quote?.billingPolicy !== void 0 && (view.chargedCoins ?? 0) > 0;
|
|
432
|
+
const needsReceipt = view.billingStatus === "pending" || view.quote?.billingPolicy !== void 0 && ((view.chargedCoins ?? 0) > 0 || (view.chargedCredits ?? 0) > 0);
|
|
413
433
|
if (result && result.status !== "authorized" && !needsReceipt) {
|
|
414
434
|
popup?.close();
|
|
415
435
|
return result;
|
|
@@ -437,9 +457,12 @@ function invalidGrantOptions(options) {
|
|
|
437
457
|
const judge2 = options.judge;
|
|
438
458
|
if (judge2 !== void 0 && (typeof judge2 !== "object" || judge2 === null || typeof judge2.enabled !== "boolean" || !validCount(judge2.estimatedCallsPerPeriod, 1, 1e5))) return "invalid_judge_terms";
|
|
439
459
|
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";
|
|
440
|
-
|
|
460
|
+
const max = options.perCallMaxCredits ?? options.perCallMaxCoins;
|
|
461
|
+
const estimate = options.perCallEstimateCredits ?? options.perCallEstimateCoins;
|
|
462
|
+
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";
|
|
441
463
|
const d = options.disclosure;
|
|
442
|
-
|
|
464
|
+
const perPeriod = d && typeof d === "object" ? d.estimatedCreditsPerPeriod ?? d.estimatedCoinsPerPeriod : void 0;
|
|
465
|
+
if (!d || typeof d !== "object" || !["minute", "hour", "session"].includes(d.periodLabel) || !validCount(d.estimatedCallsPerPeriod, 1, 1e4) || !validCount(perPeriod, 0, 1e6)) return "invalid_disclosure";
|
|
443
466
|
if (options.maxConcurrent !== void 0 && !validCount(options.maxConcurrent, 1, 8)) return "invalid_grant_terms";
|
|
444
467
|
if (options.maxCallsPerMinute !== void 0 && !validCount(options.maxCallsPerMinute, 1, 120)) return "invalid_grant_terms";
|
|
445
468
|
if (options.maxPendingExternal !== void 0 && !validCount(options.maxPendingExternal, 1, 8)) return "invalid_grant_terms";
|
|
@@ -496,15 +519,16 @@ async function requestSpendGrant(options) {
|
|
|
496
519
|
if ("status" in surface) return surface;
|
|
497
520
|
const { popup, dashboard, parentOrigin: parentOrigin2 } = surface;
|
|
498
521
|
try {
|
|
522
|
+
const estimate = options.perCallEstimateCredits ?? options.perCallEstimateCoins;
|
|
499
523
|
const view = await request("/grants", {
|
|
500
524
|
idempotencyKey: options.idempotencyKey ?? crypto.randomUUID(),
|
|
501
525
|
models: options.models,
|
|
502
|
-
|
|
503
|
-
|
|
526
|
+
perCallMaxCredits: options.perCallMaxCredits ?? options.perCallMaxCoins,
|
|
527
|
+
...estimate !== void 0 ? { perCallEstimateCredits: estimate } : {},
|
|
504
528
|
disclosure: {
|
|
505
529
|
periodLabel: options.disclosure.periodLabel,
|
|
506
530
|
estimatedCallsPerPeriod: options.disclosure.estimatedCallsPerPeriod,
|
|
507
|
-
|
|
531
|
+
estimatedCreditsPerPeriod: options.disclosure.estimatedCreditsPerPeriod ?? options.disclosure.estimatedCoinsPerPeriod
|
|
508
532
|
},
|
|
509
533
|
...options.maxConcurrent !== void 0 ? { maxConcurrent: options.maxConcurrent } : {},
|
|
510
534
|
...options.maxCallsPerMinute !== void 0 ? { maxCallsPerMinute: options.maxCallsPerMinute } : {},
|
|
@@ -548,8 +572,11 @@ async function generateUnderGrant(grantId, input, idempotencyKey, timeoutMs) {
|
|
|
548
572
|
}
|
|
549
573
|
}
|
|
550
574
|
async function generateStream(options) {
|
|
551
|
-
|
|
552
|
-
|
|
575
|
+
const ceiling = ceilingField(options);
|
|
576
|
+
if ("error" in ceiling) return { status: "failed", error: ceiling.error };
|
|
577
|
+
if (!validMaxOutputTokens(options.maxOutputTokens)) return { status: "failed", error: "invalid_max_output_tokens" };
|
|
578
|
+
const { timeoutMs, idempotencyKey, grantId, onDelta, onPartialField, signal, allowExternal: _unused, maxCredits: _credits, estimateCoins: _coins, ...rest } = options;
|
|
579
|
+
const body = { ...rest, ...ceiling.field };
|
|
553
580
|
if (grantId === void 0 || grantId === null) return { status: "failed", error: "stream_requires_grant" };
|
|
554
581
|
if (!isGrantId(grantId)) return { status: "failed", error: "invalid_grant_id" };
|
|
555
582
|
const guarded = approvalGuards();
|
|
@@ -635,9 +662,9 @@ async function generateStream(options) {
|
|
|
635
662
|
if (done) {
|
|
636
663
|
const view = done;
|
|
637
664
|
if (!isGenerationId(view.id) || view.grantId !== grantId || generationId !== void 0 && view.id !== generationId) throw new Error("invalid_generation_response");
|
|
638
|
-
return finish(outcome(view) ?? await poll(view.id, timeoutMs ??
|
|
665
|
+
return finish(outcome(view) ?? await poll(view.id, timeoutMs ?? GENERATION_WAIT_MS, outcome));
|
|
639
666
|
}
|
|
640
|
-
if (generationId) return finish(await poll(generationId, timeoutMs ??
|
|
667
|
+
if (generationId) return finish(await poll(generationId, timeoutMs ?? GENERATION_WAIT_MS, outcome));
|
|
641
668
|
return { status: "failed", error: "generation_unavailable" };
|
|
642
669
|
} catch (error) {
|
|
643
670
|
if (signal?.aborted) return aborted();
|
|
@@ -704,11 +731,19 @@ function generationErrorMessage(code) {
|
|
|
704
731
|
return "We don\u2019t know how this one ended yet \u2014 it is still being settled. Check back in a moment.";
|
|
705
732
|
case "wait_timeout":
|
|
706
733
|
return "This is taking longer than usual. It is still running \u2014 check back in a moment.";
|
|
707
|
-
// --- the player's
|
|
734
|
+
// --- the player's credits -----------------------------------------------
|
|
735
|
+
case "insufficient_credits":
|
|
736
|
+
return "You don\u2019t have enough Genex credits for this request. Top up on Genex and try again.";
|
|
737
|
+
case "credits_unverified":
|
|
738
|
+
return "Verify your email on Genex to use your credits here.";
|
|
739
|
+
case "generation_paused":
|
|
740
|
+
return "Genex has paused generation for now. Try again later.";
|
|
741
|
+
case "payer_busy":
|
|
742
|
+
return "Genex is busy with your account for a moment. Try again shortly.";
|
|
708
743
|
case "insufficient_balance":
|
|
709
|
-
return "There isn\u2019t enough
|
|
744
|
+
return "There isn\u2019t enough in your Genex wallet for this request.";
|
|
710
745
|
case "grant_insufficient_funds":
|
|
711
|
-
return "Your budget paused because your Genex
|
|
746
|
+
return "Your budget paused because your Genex credits ran low. Top them up and it picks up again.";
|
|
712
747
|
// --- standing budgets ---------------------------------------------------
|
|
713
748
|
case "grant_limit_reached":
|
|
714
749
|
return "This budget has reached the limit you set. Set up a new one to keep going.";
|
|
@@ -737,7 +772,8 @@ function generationErrorMessage(code) {
|
|
|
737
772
|
case "judge_not_enabled":
|
|
738
773
|
return "This budget doesn\u2019t cover the game\u2019s quick checks. Set up a new one to keep going.";
|
|
739
774
|
case "judge_requires_coins":
|
|
740
|
-
|
|
775
|
+
case "judge_requires_credits":
|
|
776
|
+
return "The game\u2019s quick checks are paid from your Genex credits, not your own plan.";
|
|
741
777
|
case "invalid_judge_terms":
|
|
742
778
|
return "This budget request isn\u2019t valid, so nothing was requested.";
|
|
743
779
|
case "judge_period_limit":
|
|
@@ -801,7 +837,8 @@ function generationErrorMessage(code) {
|
|
|
801
837
|
return "That payment option doesn\u2019t match this request. Start it again.";
|
|
802
838
|
case "invalid_declared_price":
|
|
803
839
|
case "invalid_estimate_coins":
|
|
804
|
-
|
|
840
|
+
case "invalid_max_credits":
|
|
841
|
+
return "This request\u2019s spending limit isn\u2019t valid, so nothing was charged.";
|
|
805
842
|
// --- what the game asked for --------------------------------------------
|
|
806
843
|
case "model_not_allowed":
|
|
807
844
|
return "This budget doesn\u2019t cover that model. Choose one it does.";
|
|
@@ -822,9 +859,14 @@ function generationErrorMessage(code) {
|
|
|
822
859
|
case "provider_token_limit":
|
|
823
860
|
return "The model ran out of room before a usable answer was ready. The attempt is still charged.";
|
|
824
861
|
case "request_too_large":
|
|
862
|
+
case "prompt_too_large":
|
|
863
|
+
case "schema_too_large":
|
|
825
864
|
return "That request is too long. Shorten it and try again.";
|
|
865
|
+
case "output_tokens_too_large":
|
|
866
|
+
return "This request asks for a longer answer than Genex allows. Ask for a shorter one.";
|
|
826
867
|
case "invalid_request":
|
|
827
868
|
case "invalid_schema":
|
|
869
|
+
case "invalid_max_output_tokens":
|
|
828
870
|
return "This request wasn\u2019t something Genex could accept.";
|
|
829
871
|
case "generation_limit":
|
|
830
872
|
return "As many requests are running as Genex allows at once. Wait for one to finish.";
|
|
@@ -872,7 +914,7 @@ var RETRY_FLAG = "genex:embed:retry";
|
|
|
872
914
|
var POPOVER_DISMISSED_FLAG = "genex:guest:popover-dismissed";
|
|
873
915
|
var LOCAL_AUTH_FLAG = "genex:embed:local-auth";
|
|
874
916
|
var PLAYER_ID_KEY = "genex:player";
|
|
875
|
-
var SDK_VERSION = "0.
|
|
917
|
+
var SDK_VERSION = "0.28.0";
|
|
876
918
|
var config2 = null;
|
|
877
919
|
var state = "pending";
|
|
878
920
|
var user = null;
|
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,22 +13,30 @@ 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;
|
|
17
27
|
outputFormat: 'text' | 'json';
|
|
18
28
|
schema?: Record<string, unknown>;
|
|
29
|
+
/** The most output tokens the benchmarked call may write, exactly as the
|
|
30
|
+
* game will ask (`generate({ maxOutputTokens })`); omit for the stand's default. */
|
|
31
|
+
maxOutputTokens?: number;
|
|
19
32
|
idempotencyKey?: string;
|
|
20
33
|
};
|
|
21
|
-
/** Waiting time only; timeout returns the last server view without canceling.
|
|
34
|
+
/** Waiting time only; timeout returns the last server view without canceling.
|
|
35
|
+
* Defaults to 20 minutes, longer than the lane's longest dispatch. */
|
|
22
36
|
timeoutMs?: number;
|
|
23
37
|
}
|
|
24
|
-
interface DevelopmentWorkflowOptions extends DevelopmentGenerationConfig {
|
|
38
|
+
interface DevelopmentWorkflowOptions extends DevelopmentGenerationConfig, DevelopmentCap {
|
|
25
39
|
workflowId: string;
|
|
26
|
-
maxCoins: number;
|
|
27
40
|
request: {
|
|
28
41
|
offeringId: string;
|
|
29
42
|
input: RuntimeWorkflowInput;
|
|
@@ -32,10 +45,7 @@ interface DevelopmentWorkflowOptions extends DevelopmentGenerationConfig {
|
|
|
32
45
|
}
|
|
33
46
|
/** Create a generic benchmark and wait for execution and its actual-usage receipt. */
|
|
34
47
|
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;
|
|
48
|
+
interface DevelopmentJudgeOptions extends DevelopmentGenerationConfig, DevelopmentCap {
|
|
39
49
|
request: {
|
|
40
50
|
state: unknown;
|
|
41
51
|
questions: Record<string, RuntimeJudgeQuestion>;
|
|
@@ -45,10 +55,10 @@ interface DevelopmentJudgeOptions extends DevelopmentGenerationConfig {
|
|
|
45
55
|
};
|
|
46
56
|
}
|
|
47
57
|
/**
|
|
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.
|
|
58
|
+
* The judge on the creator's OWN credits, answered in the same response. Unlike
|
|
59
|
+
* a player's budget — which meters judge calls and moves a whole credit only as
|
|
60
|
+
* they add up to one — a development call is rounded up to a whole credit on
|
|
61
|
+
* its own, so a bench here overstates what a budget would spend on the same calls.
|
|
52
62
|
*/
|
|
53
63
|
declare function developmentJudge(options: DevelopmentJudgeOptions): Promise<RuntimeGenerationView>;
|
|
54
64
|
/** Returns the accepted workflow so its trusted executor can enqueue before waiting. */
|
package/dist/development.js
CHANGED
|
@@ -4,6 +4,7 @@ import {
|
|
|
4
4
|
} from "./chunk-MJPLBT3T.js";
|
|
5
5
|
|
|
6
6
|
// src/development.ts
|
|
7
|
+
var DEVELOPMENT_WAIT_MS = 12e5;
|
|
7
8
|
function assertIdentifier(value) {
|
|
8
9
|
if (!/^[A-Za-z0-9_.:-]{1,120}$/.test(value) || value === "." || value === "..") throw new Error("invalid_development_identifier");
|
|
9
10
|
}
|
|
@@ -17,8 +18,17 @@ function baseUrl(config) {
|
|
|
17
18
|
}
|
|
18
19
|
return url.origin + "/api/runtime/development/projects/" + encodeURIComponent(config.projectId);
|
|
19
20
|
}
|
|
20
|
-
function
|
|
21
|
-
|
|
21
|
+
function maximum(options) {
|
|
22
|
+
const valid = (value) => Number.isSafeInteger(value) && value > 0 && value <= 1e6;
|
|
23
|
+
if (options.maxCredits !== void 0) {
|
|
24
|
+
if (!valid(options.maxCredits) || options.maxCoins !== void 0 && options.maxCoins !== options.maxCredits) throw new Error("invalid_max_credits");
|
|
25
|
+
return { maxCredits: options.maxCredits };
|
|
26
|
+
}
|
|
27
|
+
if (!valid(options.maxCoins)) throw new Error(options.maxCoins === void 0 ? "invalid_max_credits" : "invalid_max_coins");
|
|
28
|
+
return { maxCoins: options.maxCoins };
|
|
29
|
+
}
|
|
30
|
+
function developmentTerms(view) {
|
|
31
|
+
return view.quote?.billingPolicy === "metered-credits-v1" && view.funding === "credits" || view.quote?.billingPolicy === "consumed-v1" && view.funding === "coins";
|
|
22
32
|
}
|
|
23
33
|
async function request(config, path, body) {
|
|
24
34
|
const response = await fetch(baseUrl(config) + path, {
|
|
@@ -32,27 +42,29 @@ async function request(config, path, body) {
|
|
|
32
42
|
const result = await response.json().catch(() => ({}));
|
|
33
43
|
if (!response.ok) throw new Error(typeof result.error === "string" ? result.error : "development_generation_unavailable");
|
|
34
44
|
const view = result;
|
|
35
|
-
if (!isGenerationId(view.id) || view.projectId !== config.projectId || view.development !== true || view
|
|
45
|
+
if (!isGenerationId(view.id) || view.projectId !== config.projectId || view.development !== true || !developmentTerms(view)) throw new Error("invalid_development_response");
|
|
36
46
|
return view;
|
|
37
47
|
}
|
|
38
48
|
async function developmentGenerate(options) {
|
|
39
|
-
|
|
49
|
+
const cap = maximum(options);
|
|
40
50
|
if (options.timeoutMs !== void 0 && (!Number.isFinite(options.timeoutMs) || options.timeoutMs < 0)) throw new Error("invalid_timeout");
|
|
41
51
|
const input = options.request;
|
|
42
|
-
|
|
52
|
+
if (input.maxOutputTokens !== void 0 && (!Number.isSafeInteger(input.maxOutputTokens) || input.maxOutputTokens < 1)) throw new Error("invalid_max_output_tokens");
|
|
53
|
+
const view = await request(options, "/generations", { ...cap, request: {
|
|
43
54
|
modelId: input.modelId,
|
|
44
55
|
prompt: input.prompt,
|
|
45
56
|
outputFormat: input.outputFormat,
|
|
46
57
|
...input.schema === void 0 ? {} : { schema: input.schema },
|
|
58
|
+
...input.maxOutputTokens === void 0 ? {} : { maxOutputTokens: input.maxOutputTokens },
|
|
47
59
|
idempotencyKey: input.idempotencyKey ?? crypto.randomUUID()
|
|
48
60
|
} });
|
|
49
|
-
return wait(options, view, options.timeoutMs ??
|
|
61
|
+
return wait(options, view, options.timeoutMs ?? DEVELOPMENT_WAIT_MS);
|
|
50
62
|
}
|
|
51
63
|
async function developmentJudge(options) {
|
|
52
|
-
|
|
64
|
+
const cap = maximum(options);
|
|
53
65
|
const input = options.request;
|
|
54
66
|
if (!input || input.state === void 0 || !input.questions || typeof input.questions !== "object") throw new Error("invalid_request");
|
|
55
|
-
const view = await request(options, "/judgments", {
|
|
67
|
+
const view = await request(options, "/judgments", { ...cap, request: {
|
|
56
68
|
state: input.state,
|
|
57
69
|
questions: input.questions,
|
|
58
70
|
...input.timeoutMs === void 0 ? {} : { timeoutMs: input.timeoutMs },
|
|
@@ -62,11 +74,11 @@ async function developmentJudge(options) {
|
|
|
62
74
|
return view;
|
|
63
75
|
}
|
|
64
76
|
async function developmentRequestWorkflow(options) {
|
|
65
|
-
|
|
77
|
+
const cap = maximum(options);
|
|
66
78
|
assertIdentifier(options.workflowId);
|
|
67
79
|
assertIdentifier(options.request.offeringId);
|
|
68
80
|
const view = await request(options, "/workflows/" + encodeURIComponent(options.workflowId) + "/requests", {
|
|
69
|
-
|
|
81
|
+
...cap,
|
|
70
82
|
request: {
|
|
71
83
|
offeringId: options.request.offeringId,
|
|
72
84
|
input: options.request.input,
|
|
@@ -100,7 +112,7 @@ async function wait(config, initial, timeoutMs) {
|
|
|
100
112
|
}
|
|
101
113
|
return view;
|
|
102
114
|
}
|
|
103
|
-
async function waitForDevelopmentGeneration(config, generationId, timeoutMs =
|
|
115
|
+
async function waitForDevelopmentGeneration(config, generationId, timeoutMs = DEVELOPMENT_WAIT_MS) {
|
|
104
116
|
return wait(config, await getDevelopmentGeneration(config, generationId), timeoutMs);
|
|
105
117
|
}
|
|
106
118
|
export {
|
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, RuntimeGenerationStreamEvent, 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,17 +122,40 @@ 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';
|
|
130
139
|
schema?: Record<string, unknown>;
|
|
140
|
+
/**
|
|
141
|
+
* The most output tokens this call may write. Omit it for the stand's modest
|
|
142
|
+
* default; ask for more when the answer is long (generated code, a whole
|
|
143
|
+
* scene). Bounded by the stand's cap — `getGenerationModels().limits` serves
|
|
144
|
+
* both numbers, above the cap is `output_tokens_too_large` — and by what
|
|
145
|
+
* the ceiling (`maxCredits`) funds: the ceiling also buys the answer's
|
|
146
|
+
* length, so a long answer needs a ceiling that pays for it (benchmark it).
|
|
147
|
+
*/
|
|
148
|
+
maxOutputTokens?: number;
|
|
131
149
|
/** Allow player-supplied results through their own configured Claude or ChatGPT account. Defaults off. */
|
|
132
150
|
allowExternal?: boolean;
|
|
133
151
|
/** Reuse for retries of the same operation, including after a game reload. */
|
|
134
152
|
idempotencyKey?: string;
|
|
135
|
-
/**
|
|
153
|
+
/**
|
|
154
|
+
* Waiting time only. Reaching it does not cancel an accepted generation:
|
|
155
|
+
* the result is `pending` with `wait_timeout`, and waitForGeneration(id)
|
|
156
|
+
* resumes. Defaults to 20 minutes — longer than the lane's longest dispatch
|
|
157
|
+
* (a 10-minute provider cap on the longest answers) behind a queue wait.
|
|
158
|
+
*/
|
|
136
159
|
timeoutMs?: number;
|
|
137
160
|
/**
|
|
138
161
|
* A standing budget from requestSpendGrant(). With one, the call is admitted
|
|
@@ -153,8 +176,15 @@ interface RuntimeGenerationResult extends RuntimeGenerationBilling {
|
|
|
153
176
|
error?: string;
|
|
154
177
|
}
|
|
155
178
|
interface RequestWorkflowOptions {
|
|
156
|
-
/**
|
|
157
|
-
|
|
179
|
+
/**
|
|
180
|
+
* The operation's ceiling. A workflow whose executor bills coin (the default
|
|
181
|
+
* for every executor registered before credits) reads it as its fixed coin
|
|
182
|
+
* price of a started attempt; one whose executor bills credits reads it as the
|
|
183
|
+
* credit ceiling of a request billed as used. Pass this or `maxCredits`.
|
|
184
|
+
*/
|
|
185
|
+
estimateCoins?: number;
|
|
186
|
+
/** The credit ceiling, for a workflow whose executor bills credits (SDK 0.27+). */
|
|
187
|
+
maxCredits?: number;
|
|
158
188
|
/** Offer configured personal Claude/ChatGPT funding on the same quote. Defaults off. */
|
|
159
189
|
allowExternal?: boolean;
|
|
160
190
|
workflowId: string;
|
|
@@ -205,16 +235,30 @@ interface SpendGrantDisclosure {
|
|
|
205
235
|
periodLabel: 'minute' | 'hour' | 'session';
|
|
206
236
|
/** Honest expected calls per period. The sheet shows the player a worst case beside it. */
|
|
207
237
|
estimatedCallsPerPeriod: number;
|
|
208
|
-
/** Honest expected
|
|
209
|
-
|
|
238
|
+
/** Honest expected credits per period, attributed to the game, never as a
|
|
239
|
+
* Genex figure (SDK 0.27+). Pass this or `estimatedCoinsPerPeriod`. */
|
|
240
|
+
estimatedCreditsPerPeriod?: number;
|
|
241
|
+
/** @deprecated Since 0.27: the same number as `estimatedCreditsPerPeriod`. */
|
|
242
|
+
estimatedCoinsPerPeriod?: number;
|
|
210
243
|
}
|
|
211
244
|
interface SpendGrantOptions {
|
|
212
245
|
/** Models this budget may spend on, from getGenerationModels(). One to eight. */
|
|
213
246
|
models: string[];
|
|
214
|
-
/**
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
247
|
+
/**
|
|
248
|
+
* Hard per-call CEILING in credits (SDK 0.27+): the server refuses a call
|
|
249
|
+
* whose `maxCredits` is higher. Calls are billed as used on the budget, so
|
|
250
|
+
* this bounds what one call may reach, not what it costs. Pass this or
|
|
251
|
+
* `perCallMaxCoins`.
|
|
252
|
+
*/
|
|
253
|
+
perCallMaxCredits?: number;
|
|
254
|
+
/** The honest per-call estimate, in credits, the disclosure and a personal
|
|
255
|
+
* plan's request count are built on — never a price. At most the ceiling;
|
|
256
|
+
* defaults to it. */
|
|
257
|
+
perCallEstimateCredits?: number;
|
|
258
|
+
/** @deprecated Since 0.27: the same number as `perCallMaxCredits`. */
|
|
259
|
+
perCallMaxCoins?: number;
|
|
260
|
+
/** @deprecated Since 0.27: the same number as `perCallEstimateCredits`. */
|
|
261
|
+
perCallEstimateCoins?: number;
|
|
218
262
|
disclosure: SpendGrantDisclosure;
|
|
219
263
|
/** Calls this budget may have in flight at once. Server default applies when omitted. */
|
|
220
264
|
maxConcurrent?: number;
|
|
@@ -222,14 +266,14 @@ interface SpendGrantOptions {
|
|
|
222
266
|
maxCallsPerMinute?: number;
|
|
223
267
|
/** Personal-plan jobs that may be queued at once. Server default applies when omitted. */
|
|
224
268
|
maxPendingExternal?: number;
|
|
225
|
-
/** Offer the player's own Claude/ChatGPT plan beside
|
|
269
|
+
/** Offer the player's own Claude/ChatGPT plan beside credits. Defaults off. */
|
|
226
270
|
allowExternal?: boolean;
|
|
227
271
|
/**
|
|
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.
|
|
272
|
+
* The game also calls judge() — a fast classifier billed as used, like every
|
|
273
|
+
* call on the budget. The sheet tells the player so, beside the server's own
|
|
274
|
+
* worst case for `estimatedCallsPerPeriod` calls per `disclosure.periodLabel`.
|
|
275
|
+
* A budget with the judge is paid in credits: `allowExternal` offers nothing
|
|
276
|
+
* on it. With `enabled: true`, `models` may be empty for a judge-only budget.
|
|
233
277
|
*/
|
|
234
278
|
judge?: {
|
|
235
279
|
enabled: boolean;
|
|
@@ -318,7 +362,7 @@ interface JudgeResult {
|
|
|
318
362
|
/** One typed answer per question; present only on `succeeded`. */
|
|
319
363
|
answers?: Record<string, RuntimeJudgeAnswer>;
|
|
320
364
|
error?: string;
|
|
321
|
-
/** Where the call's money went: never a
|
|
365
|
+
/** Where the call's money went: never a credit of its own, always the budget's meter. */
|
|
322
366
|
billing?: RuntimeJudgmentView['billing'];
|
|
323
367
|
}
|
|
324
368
|
/**
|
package/dist/index.js
CHANGED
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.28.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",
|