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

package/README.md

@@ -171,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,6 +1,6 @@
-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 NexraModelSpecFilter } from './media-geometry-BoxkWQlj.js';
-export { M as MediaGeometryField, j as MediaGeometryProjection, k as NexraBillingCurrency, l as NexraCatalogModelIdentity, m as NexraModelEndpointSpec, 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-BoxkWQlj.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;
 
@@ -20,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, NexraCatalogChangePage, NexraCatalogChangeParams, NexraCatalogModelState, NexraCatalogRevision, NexraDisplayQuoteBatch, NexraModelSpec, NexraModelSpecFilter, NexraQuote, NexraSalePriceList, formatModelDisplayName, 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

@@ -4,10 +4,12 @@ import {
   decodeMediaGeometry,
   encodeMediaGeometry,
   formatModelDisplayName,
+  getLanguageModelBinding,
   getModelSpec,
   listModelSpecs,
-  projectMediaGeometry
-} from "./chunk-ECF5MLSM.js";
+  projectMediaGeometry,
+  resolveNexraLanguageReasoning
+} from "./chunk-ESV6ODRA.js";
 import "./chunk-IEBCNRT4.js";
 export {
   CatalogClient,
@@ -15,7 +17,9 @@ export {
   decodeMediaGeometry,
   encodeMediaGeometry,
   formatModelDisplayName,
+  getLanguageModelBinding,
   getModelSpec,
   listModelSpecs,
-  projectMediaGeometry
+  projectMediaGeometry,
+  resolveNexraLanguageReasoning
 };