@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 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 and local-test identity
460
- return `native_unsupported` and `local_test_unsupported` until they have supported
461
- confirmation surfaces.
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`, `outputFormat: 'text' | 'json'`,
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
  });