@genex-ai/embed-sdk 0.27.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 +39 -4
- package/dist/{chunk-7SWNXF5V.js → chunk-WSJ5XPEF.js} +17 -6
- package/dist/development.d.ts +5 -1
- package/dist/development.js +5 -2
- package/dist/index.d.ts +15 -1
- package/dist/index.js +1 -1
- package/dist/sentry.js +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -53,13 +53,45 @@ confirmation surfaces.
|
|
|
53
53
|
`GenerateOptions` requires `maxCredits` (SDK **0.27.0+**; an integer from 1 to
|
|
54
54
|
1,000,000 — the call's ceiling in the player's credits; `estimateCoins`, its old
|
|
55
55
|
name, is still accepted as the same number), `modelId`, `prompt`, `outputFormat: 'text' | 'json'`,
|
|
56
|
-
optional bounded `schema`, `
|
|
57
|
-
`
|
|
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
|
|
58
59
|
already approved, which removes the popup entirely (see *Standing budgets*). Reuse an idempotency key only for the same
|
|
59
60
|
operation; store it if you need retries to survive a reload. Only models returned
|
|
60
61
|
by Genex are accepted. This first adapter generates text and JSON, including
|
|
61
62
|
creature descriptions, dialogue, rules and other structured game data.
|
|
62
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
|
+
|
|
63
95
|
SDK **0.21.0+** returns the execution `status`, optional `generationId`, and
|
|
64
96
|
`output` plus `source` on success. Cancellation is a normal `canceled` result,
|
|
65
97
|
but it does not imply that consumed work was free. `pending` with
|
|
@@ -524,6 +556,7 @@ const receipt = await developmentGenerate({
|
|
|
524
556
|
modelId: 'your-configured-model-id',
|
|
525
557
|
prompt: 'Invent a friendly creature name.',
|
|
526
558
|
outputFormat: 'text',
|
|
559
|
+
// maxOutputTokens: 24_000, // 0.28.0+: bench exactly what the game will ask for
|
|
527
560
|
idempotencyKey: 'calibration-sample-001',
|
|
528
561
|
},
|
|
529
562
|
});
|
|
@@ -545,8 +578,10 @@ funded output allowance holds that answer plus the stand's headroom. The
|
|
|
545
578
|
ceiling also decides how long the answer may be, so declare at least the p95
|
|
546
579
|
`fitCredits` of your settled samples, not the charged credits alone.
|
|
547
580
|
`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
|
|
549
|
-
|
|
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
|
|
550
585
|
refused the request before running it (a rejected key, an unknown model, a rate
|
|
551
586
|
limit — `error: 'provider_http_<status>'`), nothing is charged, the hold is
|
|
552
587
|
released, and SDK 0.24.2+ types `providerMessage`: the provider's own words,
|
|
@@ -276,6 +276,10 @@ function ceilingField(options) {
|
|
|
276
276
|
if (credits !== void 0 && coins !== void 0 && credits !== coins) return { error: "invalid_max_credits" };
|
|
277
277
|
return { field: credits !== void 0 ? { maxCredits: credits } : { estimateCoins: coins } };
|
|
278
278
|
}
|
|
279
|
+
function validMaxOutputTokens(value) {
|
|
280
|
+
return value === void 0 || Number.isSafeInteger(value) && value >= 1;
|
|
281
|
+
}
|
|
282
|
+
var GENERATION_WAIT_MS = 12e5;
|
|
279
283
|
function getGenerationModels() {
|
|
280
284
|
return request("/models");
|
|
281
285
|
}
|
|
@@ -347,20 +351,21 @@ async function poll(generationId, timeoutMs, readOutcome, popup) {
|
|
|
347
351
|
}
|
|
348
352
|
return { status: "pending", generationId, error: "wait_timeout" };
|
|
349
353
|
}
|
|
350
|
-
function waitForGeneration(generationId, timeoutMs =
|
|
354
|
+
function waitForGeneration(generationId, timeoutMs = GENERATION_WAIT_MS) {
|
|
351
355
|
if (!isGenerationId(generationId)) return Promise.resolve({ status: "failed", error: "invalid_generation_id" });
|
|
352
356
|
return poll(generationId, timeoutMs, outcome);
|
|
353
357
|
}
|
|
354
358
|
async function generate(options) {
|
|
355
359
|
const ceiling = ceilingField(options);
|
|
356
360
|
if ("error" in ceiling) return { status: "failed", error: ceiling.error };
|
|
361
|
+
if (!validMaxOutputTokens(options.maxOutputTokens)) return { status: "failed", error: "invalid_max_output_tokens" };
|
|
357
362
|
const { timeoutMs, idempotencyKey, grantId, maxCredits: _credits, estimateCoins: _coins, ...rest } = options;
|
|
358
363
|
const input = { ...rest, ...ceiling.field };
|
|
359
|
-
if (grantId !== void 0) return generateUnderGrant(grantId, input, idempotencyKey, timeoutMs ??
|
|
364
|
+
if (grantId !== void 0) return generateUnderGrant(grantId, input, idempotencyKey, timeoutMs ?? GENERATION_WAIT_MS);
|
|
360
365
|
return startGeneration(
|
|
361
366
|
"/generations",
|
|
362
367
|
{ ...input, idempotencyKey },
|
|
363
|
-
timeoutMs ??
|
|
368
|
+
timeoutMs ?? GENERATION_WAIT_MS,
|
|
364
369
|
outcome
|
|
365
370
|
);
|
|
366
371
|
}
|
|
@@ -569,6 +574,7 @@ async function generateUnderGrant(grantId, input, idempotencyKey, timeoutMs) {
|
|
|
569
574
|
async function generateStream(options) {
|
|
570
575
|
const ceiling = ceilingField(options);
|
|
571
576
|
if ("error" in ceiling) return { status: "failed", error: ceiling.error };
|
|
577
|
+
if (!validMaxOutputTokens(options.maxOutputTokens)) return { status: "failed", error: "invalid_max_output_tokens" };
|
|
572
578
|
const { timeoutMs, idempotencyKey, grantId, onDelta, onPartialField, signal, allowExternal: _unused, maxCredits: _credits, estimateCoins: _coins, ...rest } = options;
|
|
573
579
|
const body = { ...rest, ...ceiling.field };
|
|
574
580
|
if (grantId === void 0 || grantId === null) return { status: "failed", error: "stream_requires_grant" };
|
|
@@ -656,9 +662,9 @@ async function generateStream(options) {
|
|
|
656
662
|
if (done) {
|
|
657
663
|
const view = done;
|
|
658
664
|
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 ??
|
|
665
|
+
return finish(outcome(view) ?? await poll(view.id, timeoutMs ?? GENERATION_WAIT_MS, outcome));
|
|
660
666
|
}
|
|
661
|
-
if (generationId) return finish(await poll(generationId, timeoutMs ??
|
|
667
|
+
if (generationId) return finish(await poll(generationId, timeoutMs ?? GENERATION_WAIT_MS, outcome));
|
|
662
668
|
return { status: "failed", error: "generation_unavailable" };
|
|
663
669
|
} catch (error) {
|
|
664
670
|
if (signal?.aborted) return aborted();
|
|
@@ -853,9 +859,14 @@ function generationErrorMessage(code) {
|
|
|
853
859
|
case "provider_token_limit":
|
|
854
860
|
return "The model ran out of room before a usable answer was ready. The attempt is still charged.";
|
|
855
861
|
case "request_too_large":
|
|
862
|
+
case "prompt_too_large":
|
|
863
|
+
case "schema_too_large":
|
|
856
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.";
|
|
857
867
|
case "invalid_request":
|
|
858
868
|
case "invalid_schema":
|
|
869
|
+
case "invalid_max_output_tokens":
|
|
859
870
|
return "This request wasn\u2019t something Genex could accept.";
|
|
860
871
|
case "generation_limit":
|
|
861
872
|
return "As many requests are running as Genex allows at once. Wait for one to finish.";
|
|
@@ -903,7 +914,7 @@ var RETRY_FLAG = "genex:embed:retry";
|
|
|
903
914
|
var POPOVER_DISMISSED_FLAG = "genex:guest:popover-dismissed";
|
|
904
915
|
var LOCAL_AUTH_FLAG = "genex:embed:local-auth";
|
|
905
916
|
var PLAYER_ID_KEY = "genex:player";
|
|
906
|
-
var SDK_VERSION = "0.
|
|
917
|
+
var SDK_VERSION = "0.28.0";
|
|
907
918
|
var config2 = null;
|
|
908
919
|
var state = "pending";
|
|
909
920
|
var user = null;
|
package/dist/development.d.ts
CHANGED
|
@@ -26,9 +26,13 @@ interface DevelopmentGenerationOptions extends DevelopmentGenerationConfig, Deve
|
|
|
26
26
|
prompt: string;
|
|
27
27
|
outputFormat: 'text' | 'json';
|
|
28
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;
|
|
29
32
|
idempotencyKey?: string;
|
|
30
33
|
};
|
|
31
|
-
/** 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. */
|
|
32
36
|
timeoutMs?: number;
|
|
33
37
|
}
|
|
34
38
|
interface DevelopmentWorkflowOptions extends DevelopmentGenerationConfig, DevelopmentCap {
|
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
|
}
|
|
@@ -48,14 +49,16 @@ async function developmentGenerate(options) {
|
|
|
48
49
|
const cap = maximum(options);
|
|
49
50
|
if (options.timeoutMs !== void 0 && (!Number.isFinite(options.timeoutMs) || options.timeoutMs < 0)) throw new Error("invalid_timeout");
|
|
50
51
|
const input = options.request;
|
|
52
|
+
if (input.maxOutputTokens !== void 0 && (!Number.isSafeInteger(input.maxOutputTokens) || input.maxOutputTokens < 1)) throw new Error("invalid_max_output_tokens");
|
|
51
53
|
const view = await request(options, "/generations", { ...cap, request: {
|
|
52
54
|
modelId: input.modelId,
|
|
53
55
|
prompt: input.prompt,
|
|
54
56
|
outputFormat: input.outputFormat,
|
|
55
57
|
...input.schema === void 0 ? {} : { schema: input.schema },
|
|
58
|
+
...input.maxOutputTokens === void 0 ? {} : { maxOutputTokens: input.maxOutputTokens },
|
|
56
59
|
idempotencyKey: input.idempotencyKey ?? crypto.randomUUID()
|
|
57
60
|
} });
|
|
58
|
-
return wait(options, view, options.timeoutMs ??
|
|
61
|
+
return wait(options, view, options.timeoutMs ?? DEVELOPMENT_WAIT_MS);
|
|
59
62
|
}
|
|
60
63
|
async function developmentJudge(options) {
|
|
61
64
|
const cap = maximum(options);
|
|
@@ -109,7 +112,7 @@ async function wait(config, initial, timeoutMs) {
|
|
|
109
112
|
}
|
|
110
113
|
return view;
|
|
111
114
|
}
|
|
112
|
-
async function waitForDevelopmentGeneration(config, generationId, timeoutMs =
|
|
115
|
+
async function waitForDevelopmentGeneration(config, generationId, timeoutMs = DEVELOPMENT_WAIT_MS) {
|
|
113
116
|
return wait(config, await getDevelopmentGeneration(config, generationId), timeoutMs);
|
|
114
117
|
}
|
|
115
118
|
export {
|
package/dist/index.d.ts
CHANGED
|
@@ -137,11 +137,25 @@ interface GenerateOptions {
|
|
|
137
137
|
prompt: string;
|
|
138
138
|
outputFormat: 'text' | 'json';
|
|
139
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;
|
|
140
149
|
/** Allow player-supplied results through their own configured Claude or ChatGPT account. Defaults off. */
|
|
141
150
|
allowExternal?: boolean;
|
|
142
151
|
/** Reuse for retries of the same operation, including after a game reload. */
|
|
143
152
|
idempotencyKey?: string;
|
|
144
|
-
/**
|
|
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
|
+
*/
|
|
145
159
|
timeoutMs?: number;
|
|
146
160
|
/**
|
|
147
161
|
* A standing budget from requestSpendGrant(). With one, the call is admitted
|
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",
|