@byte_fluffy/nexra-sdk 0.1.0-alpha.27 → 0.1.0-alpha.29

package/README.md

@@ -37,6 +37,71 @@ available from `@byte_fluffy/nexra-sdk/media`.
 The default API base URL is `https://api.nexra-ai.com/v1`. When overriding
 `baseUrl`, include the `/v1` API prefix.
 
+## Model display names
+
+`getModelSpec`, `listModelSpecs`, `nexra.models.search`, `nexra.models.get`, and
+`nexra.catalog.model` return display names with spaces between words and
+capitalized initials, such as
+`Grok Imagine Image`, `GPT 5.4`, and `Wan 2.7 Image Pro`. Brand spelling, acronyms,
+and decimal versions are preserved. Model detail family versions follow the same
+format.
+
+Use `formatModelDisplayName(name)` to apply this format to other display labels.
+It is available from the package root and `/catalog`. Formatting affects only
+`displayName`: use the static catalog's `id`, model discovery's `slug`, or the
+live catalog's `modelId` for requests, never the formatted display name.
+
+## Live model catalog
+
+`getModelSpec` and `listModelSpecs` read the catalog bundled with this SDK release.
+Use `catalog.model(publicId, operation)` to read the currently published database
+input schema, display name, sale prices and actual model revision. A successful
+`available: false` response authoritatively confirms an unavailable or retired
+public identity; HTTP failures throw and must preserve the last successful value.
+An unknown identity returns 404. Model IDs are URL-encoded by the SDK.
+
+`catalog.changes` lists lightweight public model/operation identities and their
+latest revisions. Start with `after: "0"` for initial alignment. Keep the first
+page's `revision` as `upper` for every remaining page and pass its opaque
+`nextCursor`. The cursor is bound to that `after`/`upper` window. Revisions are
+64-bit decimal strings; compare them with `BigInt`, not JavaScript numbers.
+
+```ts
+let after = "0";
+let cursor: string | undefined;
+let upper: string | undefined;
+do {
+  const page = await nexra.catalog.changes({ after, upper, cursor });
+  upper ??= page.revision;
+  // Record changed identities for independent background model reads.
+  enqueueChanges(page.data);
+  cursor = page.nextCursor;
+} while (cursor);
+after = upper!;
+
+for await (const event of nexra.catalog.events({ after, signal })) {
+  enqueueChanges(event.data);
+  after = event.revision;
+}
+```
+
+`enqueueChanges` is application code that records the affected identities before
+advancing the receiving cursor; it does not block on all model reads. Each model
+response carries its own actual revision. Do not label an older response with the
+requested target revision or let it overwrite newer state. An identity updated
+beyond a page window's fixed upper bound appears in the next window, including
+when its index row was replaced during pagination.
+
+`catalog.events` opens one authenticated SSE stream, ignores heartbeats, and
+emits complete `catalog.quote-context.changed` windows with `{ revision,
+changedAt, data }`. Notifications wake the API instance immediately; a per-instance
+60-second revision check recovers silent notification loss. When a stream ends or
+throws, the application reconnects using its retained `after` cursor; the SDK
+does not reconnect automatically. Abort the supplied signal to stop an active
+read. Leaving the iterator cancels and releases the response stream. Keep cached
+values and cursors separate for different API sources and authorization identities.
+No credentials, channel costs or user discounts are included in the public events.
+
 ## Private ElevenLabs voices
 
 Voice design uses `elevenlabs/eleven_multilingual_ttv_v2`, with exactly one prompt
@@ -106,6 +171,77 @@ const flashResult = await nexra.run("agnes/agnes-video-2-5-flash", flashInput, {
 });
 ```
 
+## Native language models
+
+The optional `@byte_fluffy/nexra-sdk/language` entrypoint returns AI SDK
+`LanguageModelV4` models. Install its optional provider peers when using this
+entrypoint; the core SDK and media entrypoints do not load them. These provider
+versions require Node.js 22 or a supported Bun runtime:
+
+```sh
+npm install @ai-sdk/provider@^4.0.2 @ai-sdk/provider-utils@^5.0.21 \
+  @ai-sdk/openai@^4.0.11 @ai-sdk/anthropic@^4.0.30 @ai-sdk/google@^4.0.12 ai@^7
+```
+
+```ts
+import { generateText, streamText } from "ai";
+import { getLanguageModelBinding } from "@byte_fluffy/nexra-sdk/catalog";
+import { createNexraLanguageModel } from "@byte_fluffy/nexra-sdk/language";
+
+const modelId = "openai/gpt-6-sol";
+const binding = getLanguageModelBinding(modelId);
+const model = createNexraLanguageModel(modelId, {
+  apiKey: process.env.NEXRA_API_KEY!,
+});
+
+if (binding.supportsStreaming) {
+  const result = streamText({ model, prompt: "Explain a paper boat", maxRetries: 0 });
+  for await (const text of result.textStream) process.stdout.write(text);
+} else {
+  const result = await generateText({ model, prompt: "Explain a paper boat", maxRetries: 0 });
+  console.log(result.text);
+}
+```
+
+The binding selects a declared native endpoint, preferring Gemini, Responses,
+Chat Completions, then Messages. Pass `protocol` to choose another endpoint
+declared by that model. Native endpoint `inputSchema` and `outputSchema` describe
+wire parameters; language operation schemas may describe Playground inputs.
+`binding.maxOutputTokens` is the lower of the model capability and selected
+native endpoint limit. Messages requests validate the combined visible and
+thinking token budget before sending; explicit budgets are never clamped.
+The SDK does not wrap text requests in media Tasks or retry generations.
+
+Messages, tool history and ordered content parts use the AI SDK prompt contract.
+Chat Completions supports declared image/video/audio URLs and inline MP3, WAV,
+AAC and M4A audio without downloading URLs or changing codecs. Native model results and stream finish events retain `usage.raw`, including
+cache and modality details. With AI SDK 7, read `result.finalStep.usage.raw`
+or each step callback's usage. Aggregate `result.usage` and `totalUsage` do not
+retain raw records.
+
+Chat native extension fields are passed under `providerOptions.nexra`;
+Responses uses `openai`, Messages uses `anthropic`, and Gemini uses `google`.
+Explicit provider options are preserved. Model identity and prompt/stream
+fields stay owned by the SDK. Kimi K2.5 currently declares synchronous Chat
+Completions only, so use `generateText` for that model.
+
+Responses defaults to `store: false` in this SDK so each request replays the full
+conversation and encrypted reasoning instead of relying on stored item IDs.
+Pass `providerOptions.openai.store: true` explicitly for a stored conversation.
+The current Responses provider cannot preserve sampling parameters alongside
+reasoning for canonical Nexra IDs. Explicit `temperature` or `topP` therefore
+fails before sending instead of being silently discarded. A caller may select
+`forceReasoning: false` for sampling without explicit reasoning controls.
+The documented provider version floors are tested; Anthropic budget validation
+uses its exported capability helper and the shared provider budget mapper.
+
+Use `resolveNexraLanguageReasoning(modelId, { enabled: false })` from `/catalog`
+for a quiet generation policy. Its `providerOptions` select a declared off mode
+or the model's minimum reasoning effort; `canDisable` distinguishes those cases.
+An explicit AI SDK `reasoning: "none"` is rejected when the native model requires
+reasoning, rather than being changed silently. Explicit provider options take
+precedence over shared reasoning defaults.
+
 GPT-6 Sol and GPT-6 Luna are included in the language model catalog. Sale prices
 are not bundled into the SDK; use the current prices published by the selected
 Nexra environment:

package/dist/catalog.d.ts

@@ -1,10 +1,18 @@
-import { H as HttpTransport, N as NexraSalePriceList, C as CreateNexraQuoteRequest, a as NexraQuote, b as CreateNexraDisplayQuoteBatchRequest, c as NexraDisplayQuoteBatch, d as NexraCatalogRevision, e as NexraModelSpec, f as NexraModelSpecFilter } from './media-geometry-B7ip-nrA.js';
-export { M as MediaGeometryField, g as MediaGeometryProjection, h as NexraBillingCurrency, i as NexraModelEndpointSpec, j as NexraModelOperation, k as NexraSalePrice, l as NexraSettlement, U as UnifiedMediaGeometry, m as applyMediaGeometry, n as decodeMediaGeometry, o as encodeMediaGeometry, p as projectMediaGeometry } from './media-geometry-B7ip-nrA.js';
-import './json-Drjj1OKl.js';
+import { J as JsonObject } from './json-Drjj1OKl.js';
+import { H as HttpTransport, N as NexraCatalogChangeParams, a as NexraCatalogChangePage, b as NexraCatalogModelState, c as NexraSalePriceList, C as CreateNexraQuoteRequest, d as NexraQuote, e as CreateNexraDisplayQuoteBatchRequest, f as NexraDisplayQuoteBatch, g as NexraCatalogRevision, h as NexraModelSpec, i as NexraModelEndpointSpec, j as NexraModelSpecFilter } from './media-geometry-nJ7I7ohO.js';
+export { M as MediaGeometryField, k as MediaGeometryProjection, l as NexraBillingCurrency, m as NexraCatalogModelIdentity, n as NexraModelOperation, o as NexraSalePrice, p as NexraSettlement, U as UnifiedMediaGeometry, q as applyMediaGeometry, r as decodeMediaGeometry, s as encodeMediaGeometry, t as projectMediaGeometry } from './media-geometry-nJ7I7ohO.js';
+
+declare function formatModelDisplayName(displayName: string): string;
 
 declare class CatalogClient {
     private readonly transport;
     constructor(transport: HttpTransport);
+    changes(params?: NexraCatalogChangeParams, signal?: AbortSignal): Promise<NexraCatalogChangePage>;
+    model(modelId: string, operation: string, signal?: AbortSignal): Promise<NexraCatalogModelState>;
+    events(options?: {
+        after?: string;
+        signal?: AbortSignal;
+    }): AsyncGenerator<NexraCatalogChangePage>;
     listPrices(signal?: AbortSignal): Promise<NexraSalePriceList>;
     quote(request: CreateNexraQuoteRequest, signal?: AbortSignal): Promise<NexraQuote>;
     quoteBatch(request: CreateNexraDisplayQuoteBatchRequest, signal?: AbortSignal): Promise<NexraDisplayQuoteBatch>;
@@ -12,5 +20,25 @@ declare class CatalogClient {
 }
 declare function getModelSpec(modelId: string): NexraModelSpec | undefined;
 declare function listModelSpecs(filter?: NexraModelSpecFilter): readonly NexraModelSpec[];
+type NexraLanguageProtocol = "gemini-generate-content" | "openai-responses" | "openai-chat-completions" | "anthropic-messages";
+type NexraLanguageModelBinding = Readonly<{
+    spec: NexraModelSpec;
+    endpoint: NexraModelEndpointSpec & {
+        protocol: NexraLanguageProtocol;
+    };
+    supportsStreaming: boolean;
+    maxOutputTokens?: number;
+}>;
+declare function getLanguageModelBinding(modelId: string, options?: {
+    protocol?: NexraLanguageProtocol;
+}): NexraLanguageModelBinding;
+type NexraLanguageReasoning = Readonly<{
+    providerOptions: Record<string, JsonObject>;
+    canDisable: boolean;
+}>;
+declare function resolveNexraLanguageReasoning(modelId: string, options: {
+    enabled: boolean;
+    protocol?: NexraLanguageProtocol;
+}): NexraLanguageReasoning;
 
-export { CatalogClient, CreateNexraDisplayQuoteBatchRequest, CreateNexraQuoteRequest, NexraCatalogRevision, NexraDisplayQuoteBatch, NexraModelSpec, NexraModelSpecFilter, NexraQuote, NexraSalePriceList, getModelSpec, listModelSpecs };
+export { CatalogClient, CreateNexraDisplayQuoteBatchRequest, CreateNexraQuoteRequest, NexraCatalogChangePage, NexraCatalogChangeParams, NexraCatalogModelState, NexraCatalogRevision, NexraDisplayQuoteBatch, type NexraLanguageModelBinding, type NexraLanguageProtocol, type NexraLanguageReasoning, NexraModelEndpointSpec, NexraModelSpec, NexraModelSpecFilter, NexraQuote, NexraSalePriceList, formatModelDisplayName, getLanguageModelBinding, getModelSpec, listModelSpecs, resolveNexraLanguageReasoning };

package/dist/catalog.js

@@ -3,17 +3,23 @@ import {
   applyMediaGeometry,
   decodeMediaGeometry,
   encodeMediaGeometry,
+  formatModelDisplayName,
+  getLanguageModelBinding,
   getModelSpec,
   listModelSpecs,
-  projectMediaGeometry
-} from "./chunk-N622DGTD.js";
-import "./chunk-YQXMWTSV.js";
+  projectMediaGeometry,
+  resolveNexraLanguageReasoning
+} from "./chunk-ESV6ODRA.js";
+import "./chunk-IEBCNRT4.js";
 export {
   CatalogClient,
   applyMediaGeometry,
   decodeMediaGeometry,
   encodeMediaGeometry,
+  formatModelDisplayName,
+  getLanguageModelBinding,
   getModelSpec,
   listModelSpecs,
-  projectMediaGeometry
+  projectMediaGeometry,
+  resolveNexraLanguageReasoning
 };