@genex-ai/embed-sdk 0.36.0 → 0.38.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
@@ -459,13 +459,46 @@ generateButton.addEventListener('click', async () => {
459
459
 
460
460
  Call `generate()` directly inside the click handler: a standalone game must
461
461
  reserve a confirmation popup before asynchronous work. Embedded games ask the
462
- trusted Genex parent to show its modal. Native WebViews and local-test identity
463
- return `native_unsupported` and `local_test_unsupported` until they have supported
464
- 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()`, the budget helpers and the
479
+ voice calls (`getVoiceCatalog()`, `transcribe()`, `speak()`) are
480
+ answered by the helper on your machine, in the same shapes, statuses and error
481
+ codes the published lane returns, so the code you write against it runs
482
+ unchanged when published. Answers are made up and free: text starts with
483
+ `[practice]`, JSON is generated from your `schema`, a stream arrives in pieces,
484
+ a spoken line is a babble about as long as the real one, a recording is heard
485
+ as a stock line, and a budget is approved by the helper and counts a pretend
486
+ credit a call.
487
+ Flags stage the hard cases: `--decline`, `--limit-credits <n>`,
488
+ `--fail <code>`, `--latency <ms>`, `--calls-per-minute <n>`, and
489
+ `--answers <file>` for exact answers (`npx genex llm --help`).
490
+
491
+ Every practice result is marked — `source: 'practice'` on a generation (with
492
+ `modelProvenance: 'unverified'`), a budget, a judge answer and the model list —
493
+ and **authorizes nothing**: never grant a reward, a purchase or a score on it,
494
+ and never read it as what a real model would say or cost. The key works only on
495
+ a page served from `localhost`, `127.0.0.1` or `[::1]`; on a published or test
496
+ build it does nothing. Workflows are not practised.
465
497
 
466
498
  `GenerateOptions` requires `maxCredits` (SDK **0.27.0+**; an integer from 1 to
467
499
  1,000,000 — the call's ceiling in the player's credits; `estimateCoins`, its old
468
- name, is still accepted as the same number), `modelId`, `prompt`, `outputFormat: 'text' | 'json'`,
500
+ name, is still accepted as the same number), `modelId`, `prompt` (or a `messages` conversation, see
501
+ *A system instruction, a conversation and controls*), `outputFormat: 'text' | 'json'`,
469
502
  optional bounded `schema`, `maxOutputTokens` (SDK **0.28.0+**, see *How long a
470
503
  call may be*), `allowExternal` (default false), `idempotencyKey`,
471
504
  `timeoutMs` (default twenty minutes since 0.28.0; ten before) and `grantId` — a standing budget the player
@@ -505,6 +538,52 @@ gives a call time in proportion to the output it may write (minutes for the
505
538
  longest answers), so the default wait is twenty minutes; answers that take
506
539
  minutes are best streamed (`generateStream()`).
507
540
 
541
+ ### A system instruction, a conversation and controls
542
+
543
+ A call may be more than one prompt: your game's own `system` instruction, a
544
+ `messages` conversation, and controls for the model.
545
+
546
+ ```ts
547
+ const reply = await generate({
548
+ modelId, outputFormat: 'text', maxCredits: benchmarkedCeiling, grantId,
549
+ system: 'You are Marn, the gate guard. Short, wary answers.',
550
+ messages: history, // [{ role: 'user' | 'assistant', content }, …]
551
+ prompt: playerLine, // the last user turn
552
+ temperature: 0.8,
553
+ reasoningEffort: 'low',
554
+ cacheSystem: true,
555
+ });
556
+ ```
557
+
558
+ - `messages` are `user` / `assistant` turns of plain text, alternating from
559
+ `user`. With a `prompt` they end on an assistant turn (the prompt is the last
560
+ user turn); without one they end on a user turn. Anything else — another
561
+ role, a content part, an extra key — is `invalid_messages`, refused before
562
+ the popup and the network.
563
+ - `temperature` (0–2), `topP` (0–1), `stop` (a few short strings), `seed` and
564
+ `reasoningEffort` (`'none' | 'low' | 'medium' | 'high'`) each need a model
565
+ that takes them: `getGenerationModels().models[i].controls` lists them (and
566
+ `reasoningEfforts` the values), and one the model does not list is
567
+ `unsupported_parameter` — nothing is charged. Reasoning tokens count against
568
+ the answer's length: if a thinking model is cut off (`provider_token_limit`),
569
+ ask for `'low'` or `'none'`, or a larger ceiling.
570
+ - `cacheSystem: true` marks a long, unchanging `system` as a cacheable prefix
571
+ where the vendor needs to be told; it does nothing elsewhere. Calls are billed
572
+ as used, so a cached read simply costs less.
573
+ - Everything you send — prompt, system and every turn — fits
574
+ `limits.maxPromptBytes` together, and is part of what the call costs:
575
+ benchmark the real call (`genex llm bench --system … --messages …`).
576
+
577
+ **It works on every stand.** A stand accepts these fields when
578
+ `getGenerationModels().features?.messages` is `true`. Where it is not — an
579
+ older stand, or one with the feature off — the SDK still runs the call: it
580
+ folds `system`, `messages` and `prompt` into one prompt and drops the controls.
581
+ `foldGenerationRequest({ system, messages, prompt })` returns that exact text
582
+ (`Instructions:` … `Conversation:` … `Answer the last User message as the
583
+ Assistant.`); it is also what a player's own Claude or ChatGPT plan is handed,
584
+ where the controls are likewise not used (`ignoredControls` on the view says
585
+ which). Do not reuse an idempotency key across the two shapes.
586
+
508
587
  SDK **0.21.0+** returns the execution `status`, optional `generationId`, and
509
588
  `output` plus `source` on success. Cancellation is a normal `canceled` result,
510
589
  but it does not imply that consumed work was free. `pending` with
@@ -695,6 +774,29 @@ sentence for every one of these and for every one-time code as well; show it, or
695
774
  write your own in-fiction line keyed off the same code. Never show the raw code,
696
775
  and never treat `unknown` as failure — it means the outcome is not settled yet.
697
776
 
777
+ **When what was said isn't allowed.** A stand can check what a game sends to a
778
+ model and what the model answers (`(await getGenerationModels()).features?.moderation`
779
+ is `'enforce'` where it blocks; absent or `'off'`/`'log'` where it does not). A
780
+ blocked call resolves `failed` with `error: 'content_blocked'` and
781
+ `contentBlocked: 'input' | 'output'` — one-time, budget and streamed calls
782
+ alike:
783
+
784
+ ```ts
785
+ const reply = await generate({ ...request, grantId });
786
+ if (reply.error === 'content_blocked') {
787
+ // 'input': what the player (or the game) sent was refused before the model
788
+ // ran, at no charge. 'output': the model's answer was withheld; the attempt
789
+ // is charged like any failed one.
790
+ showNotice(generationErrorMessage(reply.error)); // or your own in-fiction line
791
+ if (reply.contentBlocked === 'input') clearTheTextBox();
792
+ }
793
+ ```
794
+
795
+ Do not resend the same text: it will be refused again. Violence and dark themes
796
+ inside a game's fiction are not blocked. In a stream, pieces may stop arriving
797
+ before the result says so — as always, the resolved result decides what the
798
+ game keeps, never the pieces.
799
+
698
800
  **The receiver pattern.** Persistence is the game's job, and it is what decides
699
801
  whether a generated thing survives a reload:
700
802
 
@@ -710,6 +812,110 @@ and something that survives a reload. Validate `result.output` against the shape
710
812
  your game expects before using it, always. It is data, never authority for
711
813
  Nex, rewards or items.
712
814
 
815
+ ## Budgets the game's creator pays for
816
+
817
+ A standing budget is normally the player's money, so the player approves it.
818
+ A game whose **creator** has set an allowance aside (`genex llm sponsor set`,
819
+ their own credits, for this one game) can ask for a budget the creator pays
820
+ instead — and then nobody is asked anything:
821
+
822
+ ```ts
823
+ import { requestSpendGrant, generate } from '@genex-ai/embed-sdk';
824
+
825
+ // No click needed and no Genex sheet: nobody playing is paying.
826
+ const sponsored = await requestSpendGrant({
827
+ sponsored: true,
828
+ models: ['google/gemini-2.5-flash-lite'],
829
+ perCallMaxCredits: 3,
830
+ });
831
+ if (sponsored.status === 'active') {
832
+ const line = await generate({ grantId: sponsored.grantId, maxCredits: 3, modelId: 'google/gemini-2.5-flash-lite', prompt, outputFormat: 'text' });
833
+ } else if (sponsored.status === 'unavailable') {
834
+ // The creator's allowance cannot serve this player right now. Nothing was
835
+ // asked of the player and nothing is charged. Fall back — your choice:
836
+ // authored content, or the player-paid request above (from a click).
837
+ }
838
+ ```
839
+
840
+ - The answer is **`active`** or **`unavailable`** (`failed` only for a
841
+ malformed request). `unavailable` carries `error`, a code:
842
+ `sponsor_not_available` (this game has no live allowance, or the stand does
843
+ not serve them), `sponsor_terms_mismatch` (you asked for a model or a
844
+ ceiling the creator did not allow), `sponsor_player_limit_reached` (this
845
+ player's allowance for today is used; it resets at 00:00 UTC),
846
+ `sponsor_exhausted`, `sponsor_rate_limited`, `sponsor_sign_in_required` (a
847
+ guest, where guests are not served), `sponsor_email_unverified`. A player is
848
+ **never** switched to paying: falling back to a player-paid budget is a
849
+ decision your game makes, in the open, from a click.
850
+ - It works on an older stand too: the SDK reads the stand's `features` (served
851
+ by `getGenerationModels()`) and answers `unavailable` itself, without a
852
+ network error, where sponsored budgets are not served.
853
+ - Ask for only what the game needs: `models` and `perCallMaxCredits` (and
854
+ `judge: { enabled: true, … }`, `maxCallsPerMinute`). The limit is the
855
+ server's — what is left of this player's day — and the pace is at most the
856
+ creator's. The other budget options are accepted and ignored, so the same
857
+ options object can serve the fallback.
858
+ - Asking again returns the budget already running, so ask on every load; there
859
+ is nothing to store. `getActiveSpendGrant()` is the player's OWN budget and
860
+ never returns a sponsored one.
861
+ - Calls then run exactly like any budget's — `generate({ grantId })`,
862
+ `generateStream()`, `judge()` — and can still be refused: by the budget's
863
+ own limits (`grant_limit_reached` is this player's day used up), and when
864
+ the allowance ends (`sponsor_exhausted`, `sponsor_stopped`,
865
+ `sponsor_expired`). Treat any of them as "fall back".
866
+ - Credits only: a sponsored budget is never offered the player's own Claude or
867
+ ChatGPT plan, and never falls back to the player's credits.
868
+ - Guests (no account) are served only where the stand allows it
869
+ (`features.sponsorGuests`) and the creator opted in; elsewhere the answer is
870
+ `unavailable` with `sponsor_sign_in_required`.
871
+ ## Shared AI in a multiplayer room
872
+
873
+ A server-authoritative room module can ask a model itself (`ctx.models` in
874
+ `@genex-ai/multiplayer/authority/module`): an AI referee, an NPC's decision, a
875
+ storyteller the whole room hears. It runs on the server, so no player's tab
876
+ has to stay open and no client can forge the answer. The server carries no key
877
+ and no wallet. Its calls are paid from the budgets the players in the room
878
+ **lend** it (SDK **0.37.0+**):
879
+
880
+ ```ts
881
+ import { getGenerationModels, requestSpendGrant, lendSpendGrantToRoom, returnSpendGrantFromRoom } from '@genex-ai/embed-sdk';
882
+ import { connectAuthority } from '@genex-ai/multiplayer/authority';
883
+
884
+ // Only where this stand has it: ask, never assume.
885
+ const { features } = await getGenerationModels();
886
+ const shared = features?.roomCalls === true;
887
+
888
+ // From a click, as always. `shareWithRooms` adds one sentence to the sheet.
889
+ const budget = await requestSpendGrant({
890
+ models: ['your-configured-model-id'],
891
+ perCallMaxCredits: 3,
892
+ disclosure: { periodLabel: 'hour', estimatedCallsPerPeriod: 60, estimatedCreditsPerPeriod: 120 },
893
+ ...(shared ? { shareWithRooms: true } : {}),
894
+ });
895
+
896
+ const session = await connectAuthority({ room: 'my-game', name: 'Blue' });
897
+ if (shared && budget.status === 'active' && budget.grantId) {
898
+ await lendSpendGrantToRoom(budget.grantId, session.code); // this room, this player's budget
899
+ }
900
+ ```
901
+
902
+ - A budget approved **without** `shareWithRooms` can never be spent by a
903
+ server: `lendSpendGrantToRoom()` rejects with `grant_not_shareable`. On a
904
+ stand without room calls, `requestSpendGrant({ shareWithRooms: true })`
905
+ resolves `failed` with `room_calls_unavailable` and shows the player nothing.
906
+ - Every call the room makes is an ordinary call of that budget: the same
907
+ per-call ceiling, limit and pace the player approved, billed as used, on
908
+ their receipts, marked there as asked for by the game's server.
909
+ - The room spreads its calls across the players who lent a budget. A player
910
+ who lends nothing pays nothing, and a room nobody lends to reads `no_budget`
911
+ in the module, which must have a rule of its own for that.
912
+ - A lend ends when the player leaves the room, stops the budget or signs out;
913
+ `returnSpendGrantFromRoom(grantId, session.code)` ends it on a switch of
914
+ yours. A deploy moves a seat to a new room by itself: lend again there,
915
+ `session.on('rejoined', ({ code }) => lendSpendGrantToRoom(grantId, code))`.
916
+ - A budget on the player's own Claude or ChatGPT plan cannot be lent
917
+ (`room_funding_unsupported`).
918
+
713
919
  ## Streaming replies
714
920
 
715
921
  SDK **0.26.0+**. `generateStream()` is `generate({ grantId })` answered as it is
@@ -839,6 +1045,119 @@ Benchmark on your own credits with `developmentJudge()` from
839
1045
  billed one whole credit a call — a player's budget, which meters, spends far
840
1046
  less for the same calls.
841
1047
 
1048
+ ## Voice
1049
+
1050
+ SDK **0.38.0+**. The game can **hear the player** and **talk back**. `transcribe()` turns a
1051
+ recording into words; `speak()` says a line in one of Genex's voices, streamed
1052
+ while it is made; `createSpeaker()` plays lines back to back, and can speak a
1053
+ model's reply while `generateStream()` is still writing it. Each is a call
1054
+ under a standing budget, billed as used on its meter like `judge()` (never a
1055
+ credit of its own), so voice is **grant-only**: ask for it when you request the
1056
+ budget. A voice budget is paid from the player's Genex credits, and the sheet
1057
+ names every company the player's voice or the game's lines are sent to.
1058
+ **Genex stores no audio**: a recording is passed to the transcription provider
1059
+ and dropped, and a spoken line is streamed and never kept.
1060
+
1061
+ ```ts
1062
+ import { getVoiceCatalog, requestSpendGrant, createVoiceRecorder, transcribe, generateStream, createSpeaker,
1063
+ generationErrorMessage } from '@genex-ai/embed-sdk';
1064
+
1065
+ const catalog = await getVoiceCatalog();
1066
+ if (!catalog.enabled) return useTypedInput(); // no voice here: typing still works
1067
+
1068
+ // From the player's click, as every budget request.
1069
+ const tier = catalog.speech.models[0]!.tier; // tiers and voices come from the catalog
1070
+ const voice = catalog.speech.voices.find((v) => v.tiers.includes(tier))!.id;
1071
+ const budget = await requestSpendGrant({
1072
+ models: [model.id],
1073
+ perCallMaxCredits: 8, perCallEstimateCredits: 2,
1074
+ disclosure: { periodLabel: 'minute', estimatedCallsPerPeriod: 4, estimatedCreditsPerPeriod: 8 },
1075
+ voice: {
1076
+ speech: { tiers: [tier], estimatedCharactersPerPeriod: 1200 }, // the game speaks
1077
+ transcription: { estimatedSecondsPerPeriod: 60 }, // the game listens
1078
+ },
1079
+ });
1080
+ const grantId = budget.grantId!;
1081
+
1082
+ const recorder = createVoiceRecorder({ onLevel: (level) => micMeter.set(level) });
1083
+ const speaker = createSpeaker({ grantId, voice, maxCharacters: catalog.limits.speech.maxCharacters,
1084
+ onLineStart: (line) => subtitle.show(line.text),
1085
+ onLineEnd: (line) => { if (line.error) showNotice(generationErrorMessage(line.error)); } });
1086
+
1087
+ talk.onpointerdown = () => recorder.start().catch((error) => showNotice(generationErrorMessage(error.code)));
1088
+ talk.onpointerup = async () => {
1089
+ const audio = await recorder.stop().catch(() => null); // `not_recording`: the start was refused
1090
+ if (!audio) return;
1091
+ const heard = await transcribe({ grantId, audio });
1092
+ if (heard.status !== 'succeeded') return showNotice(generationErrorMessage(heard.error));
1093
+ if (!heard.text) return; // nobody spoke
1094
+ await generateStream({ grantId, modelId: model.id, prompt: heard.text, outputFormat: 'text', maxCredits: 8,
1095
+ onDelta: (piece) => speaker.feed(piece) }); // each sentence is spoken as it closes
1096
+ await speaker.end(); // the rest, then wait until it has played
1097
+ };
1098
+ ```
1099
+
1100
+ - **Cast from the catalog.** `getVoiceCatalog()` lists the voices (a one-line
1101
+ description to cast from, a gender, and the tiers that can speak each), one
1102
+ speech model per tier (`premium`, `standard`, `economy`: a game names a
1103
+ tier, never a vendor), the transcription models, the limits (characters per
1104
+ line, seconds per recording) and estimated prices. Never type a voice id or a
1105
+ tier from memory. It answers `{ enabled: false }` wherever voice cannot run (a
1106
+ stand without it, local test mode without the practice helper, the app, an
1107
+ untrusted frame, no player) and never throws. Keep typed input as the
1108
+ fallback: a player may refuse the microphone, have none, or play where voice
1109
+ is off.
1110
+ - **Push to talk.** `createVoiceRecorder({ maxSeconds?, onLevel?, deviceId? })`:
1111
+ `start()` on the press asks for the microphone, `stop()` on the release
1112
+ resolves a 16 kHz mono WAV `Blob`, `cancel()` throws it away. It stops itself
1113
+ at `maxSeconds` (default 30, at most 60) and the next `stop()` returns that
1114
+ recording. A failure rejects with `error.code` `microphone_denied`,
1115
+ `microphone_unavailable` or `not_recording`. The microphone and the audio
1116
+ graph are let go on stop, cancel and the cut-off. On its Genex page a game is
1117
+ given the microphone only when its build declares it: add
1118
+ `"genex": { "capabilities": ["microphone"] }` to `package.json`.
1119
+ - **`transcribe({ grantId, audio, language?, model?, idempotencyKey?, signal? })`**
1120
+ takes one 16-bit PCM WAV (anything else is `audio_invalid`, before the
1121
+ network) and resolves `text` (`''` when nobody spoke), `language`,
1122
+ `durationMs` and `billing`. Reuse `idempotencyKey` to retry the same recording
1123
+ without paying twice; `pending` with `wait_timeout` means that call is still
1124
+ running: send it again with the same key to read its answer.
1125
+ - **`speak({ grantId, text, voice, tier?, style?, language?, onStart?, onAudio?, signal? })`**
1126
+ streams 16-bit PCM (24 kHz mono; `onStart` names the format) and resolves the
1127
+ line's receipt with all of its audio (`audio`, `wav()`). A spoken line is
1128
+ never replayed: its key is used once, and a reused one is
1129
+ `idempotency_conflict`. A stream that is cut resolves `unknown` with
1130
+ `provider_outcome_unknown` and the audio that arrived; `signal` stops the
1131
+ reading (`request_aborted`), and the line is still made and charged.
1132
+ - **`createSpeaker({ grantId, voice, tier?, style?, language?, onLineStart?, onLineEnd?, maxCharacters? })`**
1133
+ queues lines (`say(text)`) or a streamed reply (`feed(delta)` then `end()`),
1134
+ one request at a time and in order, each made while the one before it plays,
1135
+ so speech has no gaps. A line past `maxCharacters` is split at sentence ends,
1136
+ then at spaces. A line that fails (`grant_limit_reached`, `voice_busy`, …) is
1137
+ reported through `onLineEnd` and the queue moves on; `stop()` silences at once
1138
+ and drops the queue, and each dropped line ends `canceled` with
1139
+ `game_stopped`. **Browsers play audio only after the player has interacted
1140
+ with the page**: create the speaker, or call `say()`, from a click or a key
1141
+ press.
1142
+
1143
+ The refusals to handle as game states: `voice_requires_grant` (no budget),
1144
+ `voice_not_enabled` (the budget was approved without voice, or without the half
1145
+ this call needs: request a new one), `voice_requires_credits`,
1146
+ `voice_not_found` (a voice that is not in the catalog or not on that tier),
1147
+ `voice_busy` and `voice_paused` (the platform's, retry later), `text_too_long`,
1148
+ `audio_invalid`, `audio_too_long`, `audio_too_short`, and every budget code
1149
+ above. `generationErrorMessage()` has a sentence for each.
1150
+
1151
+ The wire, for other clients: `GET /api/runtime/voice` is the catalog (404 where
1152
+ the stand has no voice). `POST /api/runtime/grants/:id/transcriptions` takes the
1153
+ WAV bytes as its body (`Content-Type: audio/wav`), an `Idempotency-Key` header
1154
+ and optional `language` and `model` query parameters, and answers JSON.
1155
+ `POST /api/runtime/grants/:id/speech` takes
1156
+ `{ idempotencyKey, text, voice, tier?, style?, language? }` and answers
1157
+ `text/event-stream`: one `start` `{ generationId, encoding, sampleRate, channels }`,
1158
+ `audio` `{ data }` events (base64 PCM, whole samples, in order) and one `done`
1159
+ carrying the receipt. Both take the embed token as a bearer.
1160
+
842
1161
  ## Your subscription and the Genex player watcher
843
1162
 
844
1163
  Both approval sheets can offer the player their own Claude or ChatGPT plan
@@ -1003,6 +1322,9 @@ const receipt = await developmentGenerate({
1003
1322
  prompt: 'Invent a friendly creature name.',
1004
1323
  outputFormat: 'text',
1005
1324
  // maxOutputTokens: 24_000, // 0.28.0+: bench exactly what the game will ask for
1325
+ // system, messages, temperature, reasoningEffort, …: sent as given — a stand
1326
+ // without `features.messages` answers `invalid_request` rather than
1327
+ // measuring a different call.
1006
1328
  idempotencyKey: 'calibration-sample-001',
1007
1329
  },
1008
1330
  });