@genex-ai/embed-sdk 0.35.0 → 0.37.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 +213 -4
- package/dist/{chunk-KEW6LYT2.js → chunk-5VDV25LF.js} +214 -15
- package/dist/{chunk-QBCWKMVQ.js → chunk-WQJM5MJL.js} +69 -1
- package/dist/development.d.ts +10 -3
- package/dist/development.js +4 -2
- package/dist/index.d.ts +107 -10
- package/dist/index.js +10 -2
- package/dist/{runtime-generation-B3oFDmCp.d.ts → runtime-generation-D4RMgsvn.d.ts} +138 -6
- package/dist/sentry.js +2 -2
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -138,6 +138,9 @@ fresh at each join (`auth: () => getColyseusAuth()`; tokens rotate) and never lo
|
|
|
138
138
|
- `getAuthorityRegions()`: the same servers by region (`{ region, urls }`), for `connectAuthority()`'s
|
|
139
139
|
`regions`: the nearest region is joined, and each region is its own matchmaking pool. Empty when the
|
|
140
140
|
stand names no regions, and in local test mode.
|
|
141
|
+
- `getAuthorityHome()` (SDK **0.36.0+**): the region of those nearest the player by geography (from the country the player
|
|
142
|
+
connects from), for `connectAuthority()`'s `home`: it is joined and created in first. `undefined` when
|
|
143
|
+
the stand names none or the country is unknown, and in local test mode.
|
|
141
144
|
|
|
142
145
|
In local test mode both lists are empty and `getColyseusAuth()` is `undefined`, except for a
|
|
143
146
|
local authority server: a loopback page opened with `?genex_authority_url=ws://127.0.0.1:<port>`
|
|
@@ -456,13 +459,43 @@ generateButton.addEventListener('click', async () => {
|
|
|
456
459
|
|
|
457
460
|
Call `generate()` directly inside the click handler: a standalone game must
|
|
458
461
|
reserve a confirmation popup before asynchronous work. Embedded games ask the
|
|
459
|
-
trusted Genex parent to show its modal. Native WebViews
|
|
460
|
-
|
|
461
|
-
|
|
462
|
+
trusted Genex parent to show its modal. Native WebViews return
|
|
463
|
+
`native_unsupported`; a dev server (local test mode) returns
|
|
464
|
+
`local_test_unsupported` unless you practise there, below.
|
|
465
|
+
|
|
466
|
+
### Practise on your dev server
|
|
467
|
+
|
|
468
|
+
On `localhost` there is no player, no wallet and no Genex sheet, so model calls
|
|
469
|
+
answer `local_test_unsupported`. To watch them work before you publish, run the
|
|
470
|
+
practice helper beside your dev server and open the game with the key it prints:
|
|
471
|
+
|
|
472
|
+
```bash
|
|
473
|
+
npx genex llm practice
|
|
474
|
+
# genex llm practice listening on 127.0.0.1:41234 — open your game on its dev server with ?genex_llm_practice=41234.<token>
|
|
475
|
+
```
|
|
476
|
+
|
|
477
|
+
With that key in the page's URL, `getGenerationModels()`, `generate()`,
|
|
478
|
+
`generateStream()`, `judge()`, `requestSpendGrant()` and the budget helpers are
|
|
479
|
+
answered by the helper on your machine, in the same shapes, statuses and error
|
|
480
|
+
codes the published lane returns, so the code you write against it runs
|
|
481
|
+
unchanged when published. Answers are made up and free: text starts with
|
|
482
|
+
`[practice]`, JSON is generated from your `schema`, a stream arrives in pieces,
|
|
483
|
+
and a budget is approved by the helper and counts a pretend credit a call.
|
|
484
|
+
Flags stage the hard cases: `--decline`, `--limit-credits <n>`,
|
|
485
|
+
`--fail <code>`, `--latency <ms>`, `--calls-per-minute <n>`, and
|
|
486
|
+
`--answers <file>` for exact answers (`npx genex llm --help`).
|
|
487
|
+
|
|
488
|
+
Every practice result is marked — `source: 'practice'` on a generation (with
|
|
489
|
+
`modelProvenance: 'unverified'`), a budget, a judge answer and the model list —
|
|
490
|
+
and **authorizes nothing**: never grant a reward, a purchase or a score on it,
|
|
491
|
+
and never read it as what a real model would say or cost. The key works only on
|
|
492
|
+
a page served from `localhost`, `127.0.0.1` or `[::1]`; on a published or test
|
|
493
|
+
build it does nothing. Workflows are not practised.
|
|
462
494
|
|
|
463
495
|
`GenerateOptions` requires `maxCredits` (SDK **0.27.0+**; an integer from 1 to
|
|
464
496
|
1,000,000 — the call's ceiling in the player's credits; `estimateCoins`, its old
|
|
465
|
-
name, is still accepted as the same number), `modelId`, `prompt
|
|
497
|
+
name, is still accepted as the same number), `modelId`, `prompt` (or a `messages` conversation, see
|
|
498
|
+
*A system instruction, a conversation and controls*), `outputFormat: 'text' | 'json'`,
|
|
466
499
|
optional bounded `schema`, `maxOutputTokens` (SDK **0.28.0+**, see *How long a
|
|
467
500
|
call may be*), `allowExternal` (default false), `idempotencyKey`,
|
|
468
501
|
`timeoutMs` (default twenty minutes since 0.28.0; ten before) and `grantId` — a standing budget the player
|
|
@@ -502,6 +535,52 @@ gives a call time in proportion to the output it may write (minutes for the
|
|
|
502
535
|
longest answers), so the default wait is twenty minutes; answers that take
|
|
503
536
|
minutes are best streamed (`generateStream()`).
|
|
504
537
|
|
|
538
|
+
### A system instruction, a conversation and controls
|
|
539
|
+
|
|
540
|
+
A call may be more than one prompt: your game's own `system` instruction, a
|
|
541
|
+
`messages` conversation, and controls for the model.
|
|
542
|
+
|
|
543
|
+
```ts
|
|
544
|
+
const reply = await generate({
|
|
545
|
+
modelId, outputFormat: 'text', maxCredits: benchmarkedCeiling, grantId,
|
|
546
|
+
system: 'You are Marn, the gate guard. Short, wary answers.',
|
|
547
|
+
messages: history, // [{ role: 'user' | 'assistant', content }, …]
|
|
548
|
+
prompt: playerLine, // the last user turn
|
|
549
|
+
temperature: 0.8,
|
|
550
|
+
reasoningEffort: 'low',
|
|
551
|
+
cacheSystem: true,
|
|
552
|
+
});
|
|
553
|
+
```
|
|
554
|
+
|
|
555
|
+
- `messages` are `user` / `assistant` turns of plain text, alternating from
|
|
556
|
+
`user`. With a `prompt` they end on an assistant turn (the prompt is the last
|
|
557
|
+
user turn); without one they end on a user turn. Anything else — another
|
|
558
|
+
role, a content part, an extra key — is `invalid_messages`, refused before
|
|
559
|
+
the popup and the network.
|
|
560
|
+
- `temperature` (0–2), `topP` (0–1), `stop` (a few short strings), `seed` and
|
|
561
|
+
`reasoningEffort` (`'none' | 'low' | 'medium' | 'high'`) each need a model
|
|
562
|
+
that takes them: `getGenerationModels().models[i].controls` lists them (and
|
|
563
|
+
`reasoningEfforts` the values), and one the model does not list is
|
|
564
|
+
`unsupported_parameter` — nothing is charged. Reasoning tokens count against
|
|
565
|
+
the answer's length: if a thinking model is cut off (`provider_token_limit`),
|
|
566
|
+
ask for `'low'` or `'none'`, or a larger ceiling.
|
|
567
|
+
- `cacheSystem: true` marks a long, unchanging `system` as a cacheable prefix
|
|
568
|
+
where the vendor needs to be told; it does nothing elsewhere. Calls are billed
|
|
569
|
+
as used, so a cached read simply costs less.
|
|
570
|
+
- Everything you send — prompt, system and every turn — fits
|
|
571
|
+
`limits.maxPromptBytes` together, and is part of what the call costs:
|
|
572
|
+
benchmark the real call (`genex llm bench --system … --messages …`).
|
|
573
|
+
|
|
574
|
+
**It works on every stand.** A stand accepts these fields when
|
|
575
|
+
`getGenerationModels().features?.messages` is `true`. Where it is not — an
|
|
576
|
+
older stand, or one with the feature off — the SDK still runs the call: it
|
|
577
|
+
folds `system`, `messages` and `prompt` into one prompt and drops the controls.
|
|
578
|
+
`foldGenerationRequest({ system, messages, prompt })` returns that exact text
|
|
579
|
+
(`Instructions:` … `Conversation:` … `Answer the last User message as the
|
|
580
|
+
Assistant.`); it is also what a player's own Claude or ChatGPT plan is handed,
|
|
581
|
+
where the controls are likewise not used (`ignoredControls` on the view says
|
|
582
|
+
which). Do not reuse an idempotency key across the two shapes.
|
|
583
|
+
|
|
505
584
|
SDK **0.21.0+** returns the execution `status`, optional `generationId`, and
|
|
506
585
|
`output` plus `source` on success. Cancellation is a normal `canceled` result,
|
|
507
586
|
but it does not imply that consumed work was free. `pending` with
|
|
@@ -692,6 +771,29 @@ sentence for every one of these and for every one-time code as well; show it, or
|
|
|
692
771
|
write your own in-fiction line keyed off the same code. Never show the raw code,
|
|
693
772
|
and never treat `unknown` as failure — it means the outcome is not settled yet.
|
|
694
773
|
|
|
774
|
+
**When what was said isn't allowed.** A stand can check what a game sends to a
|
|
775
|
+
model and what the model answers (`(await getGenerationModels()).features?.moderation`
|
|
776
|
+
is `'enforce'` where it blocks; absent or `'off'`/`'log'` where it does not). A
|
|
777
|
+
blocked call resolves `failed` with `error: 'content_blocked'` and
|
|
778
|
+
`contentBlocked: 'input' | 'output'` — one-time, budget and streamed calls
|
|
779
|
+
alike:
|
|
780
|
+
|
|
781
|
+
```ts
|
|
782
|
+
const reply = await generate({ ...request, grantId });
|
|
783
|
+
if (reply.error === 'content_blocked') {
|
|
784
|
+
// 'input': what the player (or the game) sent was refused before the model
|
|
785
|
+
// ran, at no charge. 'output': the model's answer was withheld; the attempt
|
|
786
|
+
// is charged like any failed one.
|
|
787
|
+
showNotice(generationErrorMessage(reply.error)); // or your own in-fiction line
|
|
788
|
+
if (reply.contentBlocked === 'input') clearTheTextBox();
|
|
789
|
+
}
|
|
790
|
+
```
|
|
791
|
+
|
|
792
|
+
Do not resend the same text: it will be refused again. Violence and dark themes
|
|
793
|
+
inside a game's fiction are not blocked. In a stream, pieces may stop arriving
|
|
794
|
+
before the result says so — as always, the resolved result decides what the
|
|
795
|
+
game keeps, never the pieces.
|
|
796
|
+
|
|
695
797
|
**The receiver pattern.** Persistence is the game's job, and it is what decides
|
|
696
798
|
whether a generated thing survives a reload:
|
|
697
799
|
|
|
@@ -707,6 +809,110 @@ and something that survives a reload. Validate `result.output` against the shape
|
|
|
707
809
|
your game expects before using it, always. It is data, never authority for
|
|
708
810
|
Nex, rewards or items.
|
|
709
811
|
|
|
812
|
+
## Budgets the game's creator pays for
|
|
813
|
+
|
|
814
|
+
A standing budget is normally the player's money, so the player approves it.
|
|
815
|
+
A game whose **creator** has set an allowance aside (`genex llm sponsor set`,
|
|
816
|
+
their own credits, for this one game) can ask for a budget the creator pays
|
|
817
|
+
instead — and then nobody is asked anything:
|
|
818
|
+
|
|
819
|
+
```ts
|
|
820
|
+
import { requestSpendGrant, generate } from '@genex-ai/embed-sdk';
|
|
821
|
+
|
|
822
|
+
// No click needed and no Genex sheet: nobody playing is paying.
|
|
823
|
+
const sponsored = await requestSpendGrant({
|
|
824
|
+
sponsored: true,
|
|
825
|
+
models: ['google/gemini-2.5-flash-lite'],
|
|
826
|
+
perCallMaxCredits: 3,
|
|
827
|
+
});
|
|
828
|
+
if (sponsored.status === 'active') {
|
|
829
|
+
const line = await generate({ grantId: sponsored.grantId, maxCredits: 3, modelId: 'google/gemini-2.5-flash-lite', prompt, outputFormat: 'text' });
|
|
830
|
+
} else if (sponsored.status === 'unavailable') {
|
|
831
|
+
// The creator's allowance cannot serve this player right now. Nothing was
|
|
832
|
+
// asked of the player and nothing is charged. Fall back — your choice:
|
|
833
|
+
// authored content, or the player-paid request above (from a click).
|
|
834
|
+
}
|
|
835
|
+
```
|
|
836
|
+
|
|
837
|
+
- The answer is **`active`** or **`unavailable`** (`failed` only for a
|
|
838
|
+
malformed request). `unavailable` carries `error`, a code:
|
|
839
|
+
`sponsor_not_available` (this game has no live allowance, or the stand does
|
|
840
|
+
not serve them), `sponsor_terms_mismatch` (you asked for a model or a
|
|
841
|
+
ceiling the creator did not allow), `sponsor_player_limit_reached` (this
|
|
842
|
+
player's allowance for today is used; it resets at 00:00 UTC),
|
|
843
|
+
`sponsor_exhausted`, `sponsor_rate_limited`, `sponsor_sign_in_required` (a
|
|
844
|
+
guest, where guests are not served), `sponsor_email_unverified`. A player is
|
|
845
|
+
**never** switched to paying: falling back to a player-paid budget is a
|
|
846
|
+
decision your game makes, in the open, from a click.
|
|
847
|
+
- It works on an older stand too: the SDK reads the stand's `features` (served
|
|
848
|
+
by `getGenerationModels()`) and answers `unavailable` itself, without a
|
|
849
|
+
network error, where sponsored budgets are not served.
|
|
850
|
+
- Ask for only what the game needs: `models` and `perCallMaxCredits` (and
|
|
851
|
+
`judge: { enabled: true, … }`, `maxCallsPerMinute`). The limit is the
|
|
852
|
+
server's — what is left of this player's day — and the pace is at most the
|
|
853
|
+
creator's. The other budget options are accepted and ignored, so the same
|
|
854
|
+
options object can serve the fallback.
|
|
855
|
+
- Asking again returns the budget already running, so ask on every load; there
|
|
856
|
+
is nothing to store. `getActiveSpendGrant()` is the player's OWN budget and
|
|
857
|
+
never returns a sponsored one.
|
|
858
|
+
- Calls then run exactly like any budget's — `generate({ grantId })`,
|
|
859
|
+
`generateStream()`, `judge()` — and can still be refused: by the budget's
|
|
860
|
+
own limits (`grant_limit_reached` is this player's day used up), and when
|
|
861
|
+
the allowance ends (`sponsor_exhausted`, `sponsor_stopped`,
|
|
862
|
+
`sponsor_expired`). Treat any of them as "fall back".
|
|
863
|
+
- Credits only: a sponsored budget is never offered the player's own Claude or
|
|
864
|
+
ChatGPT plan, and never falls back to the player's credits.
|
|
865
|
+
- Guests (no account) are served only where the stand allows it
|
|
866
|
+
(`features.sponsorGuests`) and the creator opted in; elsewhere the answer is
|
|
867
|
+
`unavailable` with `sponsor_sign_in_required`.
|
|
868
|
+
## Shared AI in a multiplayer room
|
|
869
|
+
|
|
870
|
+
A server-authoritative room module can ask a model itself (`ctx.models` in
|
|
871
|
+
`@genex-ai/multiplayer/authority/module`): an AI referee, an NPC's decision, a
|
|
872
|
+
storyteller the whole room hears. It runs on the server, so no player's tab
|
|
873
|
+
has to stay open and no client can forge the answer. The server carries no key
|
|
874
|
+
and no wallet. Its calls are paid from the budgets the players in the room
|
|
875
|
+
**lend** it (SDK **0.37.0+**):
|
|
876
|
+
|
|
877
|
+
```ts
|
|
878
|
+
import { getGenerationModels, requestSpendGrant, lendSpendGrantToRoom, returnSpendGrantFromRoom } from '@genex-ai/embed-sdk';
|
|
879
|
+
import { connectAuthority } from '@genex-ai/multiplayer/authority';
|
|
880
|
+
|
|
881
|
+
// Only where this stand has it: ask, never assume.
|
|
882
|
+
const { features } = await getGenerationModels();
|
|
883
|
+
const shared = features?.roomCalls === true;
|
|
884
|
+
|
|
885
|
+
// From a click, as always. `shareWithRooms` adds one sentence to the sheet.
|
|
886
|
+
const budget = await requestSpendGrant({
|
|
887
|
+
models: ['your-configured-model-id'],
|
|
888
|
+
perCallMaxCredits: 3,
|
|
889
|
+
disclosure: { periodLabel: 'hour', estimatedCallsPerPeriod: 60, estimatedCreditsPerPeriod: 120 },
|
|
890
|
+
...(shared ? { shareWithRooms: true } : {}),
|
|
891
|
+
});
|
|
892
|
+
|
|
893
|
+
const session = await connectAuthority({ room: 'my-game', name: 'Blue' });
|
|
894
|
+
if (shared && budget.status === 'active' && budget.grantId) {
|
|
895
|
+
await lendSpendGrantToRoom(budget.grantId, session.code); // this room, this player's budget
|
|
896
|
+
}
|
|
897
|
+
```
|
|
898
|
+
|
|
899
|
+
- A budget approved **without** `shareWithRooms` can never be spent by a
|
|
900
|
+
server: `lendSpendGrantToRoom()` rejects with `grant_not_shareable`. On a
|
|
901
|
+
stand without room calls, `requestSpendGrant({ shareWithRooms: true })`
|
|
902
|
+
resolves `failed` with `room_calls_unavailable` and shows the player nothing.
|
|
903
|
+
- Every call the room makes is an ordinary call of that budget: the same
|
|
904
|
+
per-call ceiling, limit and pace the player approved, billed as used, on
|
|
905
|
+
their receipts, marked there as asked for by the game's server.
|
|
906
|
+
- The room spreads its calls across the players who lent a budget. A player
|
|
907
|
+
who lends nothing pays nothing, and a room nobody lends to reads `no_budget`
|
|
908
|
+
in the module, which must have a rule of its own for that.
|
|
909
|
+
- A lend ends when the player leaves the room, stops the budget or signs out;
|
|
910
|
+
`returnSpendGrantFromRoom(grantId, session.code)` ends it on a switch of
|
|
911
|
+
yours. A deploy moves a seat to a new room by itself: lend again there,
|
|
912
|
+
`session.on('rejoined', ({ code }) => lendSpendGrantToRoom(grantId, code))`.
|
|
913
|
+
- A budget on the player's own Claude or ChatGPT plan cannot be lent
|
|
914
|
+
(`room_funding_unsupported`).
|
|
915
|
+
|
|
710
916
|
## Streaming replies
|
|
711
917
|
|
|
712
918
|
SDK **0.26.0+**. `generateStream()` is `generate({ grantId })` answered as it is
|
|
@@ -1000,6 +1206,9 @@ const receipt = await developmentGenerate({
|
|
|
1000
1206
|
prompt: 'Invent a friendly creature name.',
|
|
1001
1207
|
outputFormat: 'text',
|
|
1002
1208
|
// maxOutputTokens: 24_000, // 0.28.0+: bench exactly what the game will ask for
|
|
1209
|
+
// system, messages, temperature, reasoningEffort, …: sent as given — a stand
|
|
1210
|
+
// without `features.messages` answers `invalid_request` rather than
|
|
1211
|
+
// measuring a different call.
|
|
1003
1212
|
idempotencyKey: 'calibration-sample-001',
|
|
1004
1213
|
},
|
|
1005
1214
|
});
|