@xybrid/react-native 0.10.0-rc1

package/react-native-xybrid.podspec

@@ -0,0 +1,50 @@
+require "json"
+require_relative "ios/xybrid_natives"
+
+package = JSON.parse(File.read(File.join(__dir__, "package.json")))
+
+Pod::Spec.new do |s|
+  # The npm package is @xybrid/react-native; pod names cannot contain `@` or
+  # `/`, so the pod keeps this name (it only shows up in Podfile.lock).
+  s.name         = "react-native-xybrid"
+  s.version      = package["version"]
+  s.summary      = package["description"]
+  s.homepage     = package["homepage"]
+  s.license      = package["license"]
+  s.authors      = package["author"]
+
+  # Matches the XCFramework's minimum (bindings/apple/BUILD.bazel) and
+  # Package.swift; React Native 0.76+ already needs iOS 15.1.
+  s.platforms    = { :ios => "16.0" }
+  s.source       = { :git => "https://github.com/xybrid-ai/xybrid.git", :tag => "v#{s.version}" }
+
+  # The TurboModule (XybridModule.mm + the Swift implementation) and the
+  # Swift SDK it calls (ios/XybridSwift: Xybrid.swift + xybrid_bolt.swift, the
+  # same sources the standalone Apple SDK ships) compile into this one pod.
+  s.source_files = "ios/*.{mm,swift}", "ios/XybridSwift/*.swift"
+  s.swift_version = "5.0"
+
+  # The Rust core, resolved at `pod install` time — downloaded from the
+  # GitHub Release and checked against package.json's pinned SHA-256, or a
+  # local build. See ios/xybrid_natives.rb for the order and overrides.
+  s.vendored_frameworks = XybridNatives.prepare!(__dir__)
+
+  # System frameworks the Rust core links against (mirrors Package.swift).
+  s.frameworks = "Metal", "MetalPerformanceShaders", "MetalPerformanceShadersGraph",
+                 "CoreML", "Accelerate", "Security"
+  s.libraries  = "c++"
+
+  s.pod_target_xcconfig = {
+    "DEFINES_MODULE" => "YES",
+    # A method missing from the Codegen protocol only warns — and then
+    # crashes at the first JS call, because the TurboModule looks methods up
+    # by the protocol's selectors. Make it a build error instead.
+    "WARNING_CFLAGS" => "$(inherited) -Werror=protocol",
+    # The XCFramework has no x86_64 simulator slice (no prebuilt ONNX Runtime
+    # for Intel simulators), so build simulator targets for arm64 only.
+    "EXCLUDED_ARCHS[sdk=iphonesimulator*]" => "i386 x86_64",
+  }
+
+  # React Native's New Architecture wiring (TurboModule headers + Codegen).
+  install_modules_dependencies(s)
+end

package/src/NativeXybrid.ts

@@ -0,0 +1,131 @@
+// TurboModule spec consumed by React Native Codegen — the one contract both
+// native shims are compiled against: Android extends the generated
+// `NativeXybridSpec` class and iOS conforms to the generated
+// `NativeXybridSpec` protocol (tests/spec-conformance.test.mjs checks the
+// selectors without a Mac).
+//
+// Codegen accepts only `string`, `number`, `boolean`, `Object`, arrays and
+// `Promise`s of those, and `| null`. Structured values therefore cross as
+// plain `Object`s: the TS facade (src/index.ts) builds and narrows them, and
+// the native codecs (ios/XybridCodec.swift, android/.../XybridCodec.kt)
+// translate them to and from the bolt types.
+//
+// Native objects (models, conversation contexts, cancellation tokens, token
+// streams, downloads, pipelines, live-ASR sessions) are opaque string handles
+// held in one registry per platform. `dispose` frees any of them, and freeing
+// a model also disposes the token streams started from it.
+//
+// Nothing here is public API. Keep method names distinct from NSObject /
+// Java `Object` members (hence `dispose`, not `release`; `sdkVersion`, not
+// `version`).
+
+import type { TurboModule } from 'react-native';
+import { TurboModuleRegistry } from 'react-native';
+
+export interface Spec extends TurboModule {
+  // -- SDK configuration --
+  // `options` is `{ apiKey?, gatewayUrl?, ingestUrl?, cacheDir? }`. The SDK
+  // configures itself anonymously on first use; the first `initialize` that
+  // carries options applies them, and later ones reject if they differ.
+  initialize(options: Object | null): Promise<void>;
+  sdkVersion(): Promise<string>;
+  hasApiKey(): Promise<boolean>;
+  setProviderApiKey(provider: string, apiKey: string): Promise<void>;
+  setPlatformUrl(url: string): Promise<void>;
+  setSpeculativeCloud(enabled: boolean): Promise<void>;
+  isSpeculativeCloudEnabled(): Promise<boolean>;
+  willSpeculate(modelId: string): Promise<boolean>;
+  releaseMemory(): Promise<number>;
+  setAutoRelease(enabled: boolean): Promise<void>;
+  isAutoReleaseEnabled(): Promise<boolean>;
+
+  // -- Device state push (both platforms also observe it natively) --
+  setBatteryLevel(percent: number): Promise<void>;
+  clearBatteryLevel(): Promise<void>;
+  setThermalState(state: string): Promise<void>;
+  clearThermalState(): Promise<void>;
+
+  // -- Model cache --
+  cacheStatus(): Promise<Object>;
+  cacheEntries(): Promise<Object[]>;
+  cacheIsModelCached(modelId: string): Promise<boolean>;
+  cacheModelPath(modelId: string): Promise<string | null>;
+  cacheExtractedModelIds(): Promise<string[]>;
+  cacheRemoveModel(modelId: string): Promise<number>;
+  cacheClear(): Promise<number>;
+
+  // -- Stateless helpers --
+  jsonSchemaToGbnf(schemaJson: string): Promise<string>;
+  toolResultsEnvelope(
+    userText: string,
+    priorAssistantText: string,
+    results: Object[],
+  ): Promise<Object>;
+
+  // -- Handles --
+  dispose(handle: string): Promise<void>;
+
+  // -- Models --
+  // `source` is `{ kind, value, revision? }`, kind one of `registry`,
+  // `registrySpeculative`, `bundle`, `directory`, `huggingFace`, `modelFile`.
+  loadModel(source: Object): Promise<string>;
+  modelInfo(model: string): Promise<Object>;
+  isLoaded(model: string): Promise<boolean>;
+  warmup(model: string): Promise<void>;
+  unload(model: string): Promise<void>;
+  isCloudServing(model: string): Promise<boolean>;
+  downloadStatus(model: string): Promise<Object>;
+  awaitDownload(model: string, timeoutMs: number): Promise<Object>;
+  voices(model: string): Promise<Object[]>;
+  defaultVoice(model: string): Promise<Object | null>;
+  voice(model: string, voiceId: string): Promise<Object | null>;
+
+  // -- Inference --
+  // `options` is the wire form of `RunOptions`: sampling config, platform
+  // knobs, plus `context` (a conversation handle) and `cancel` (a
+  // cancellation-token handle) resolved natively.
+  run(model: string, envelope: Object, options: Object | null): Promise<Object>;
+  // Pull-based token streaming. `streamNext` resolves each event
+  // (`{ kind: 'token', token }` or `{ kind: 'complete', result }`) and `null`
+  // once the stream is gone; failures reject with the same codes as `run`.
+  // Disposing a stream aborts its generation.
+  streamStart(model: string, envelope: Object, options: Object | null): Promise<string>;
+  streamNext(stream: string): Promise<Object | null>;
+
+  // -- Cancellation tokens (the stop button behind `RunOptions.signal`) --
+  createCancelToken(): Promise<string>;
+  cancel(token: string): Promise<void>;
+
+  // -- Conversation contexts --
+  createContext(contextId: string | null): Promise<string>;
+  contextPush(context: string, envelope: Object): Promise<void>;
+  contextSetSystem(context: string, envelope: Object): Promise<void>;
+  contextClear(context: string): Promise<void>;
+  contextInfo(context: string): Promise<Object>;
+  contextHistory(context: string): Promise<Object[]>;
+  contextSetMaxHistoryLength(context: string, length: number): Promise<void>;
+
+  // -- Standalone downloads (fill the cache without loading) --
+  startDownload(modelId: string, platform: string | null): Promise<string>;
+  downloadHandleStatus(download: string): Promise<Object>;
+  downloadHandleError(download: string): Promise<string | null>;
+  cancelDownload(download: string): Promise<void>;
+
+  // -- Pipelines --
+  // `source` is `{ kind: 'yaml' | 'file' | 'bundle', value }`.
+  loadPipeline(source: Object): Promise<string>;
+  pipelineInfo(pipeline: string): Promise<Object>;
+  runPipeline(pipeline: string, envelope: Object, options: Object | null): Promise<Object>;
+
+  // -- Live ASR sessions --
+  // `samplesBase64` is little-endian Float32 PCM, mono, 16 kHz.
+  openStreamingSession(model: string, config: Object | null): Promise<string>;
+  sessionFeed(session: string, samplesBase64: string): Promise<void>;
+  sessionNextPartial(session: string): Promise<Object | null>;
+  sessionFlush(session: string): Promise<string>;
+  sessionReset(session: string): Promise<void>;
+  sessionCancel(session: string): Promise<void>;
+  sessionIsRunning(session: string): Promise<boolean>;
+}
+
+export default TurboModuleRegistry.getEnforcing<Spec>('RNXybrid');

package/src/base64.ts

@@ -0,0 +1,43 @@
+// Minimal base64 for the one binary payload JS produces itself: live-ASR PCM.
+// Hermes has no Buffer, and `btoa` only takes binary strings, so encode the
+// bytes directly. Every platform React Native runs on is little-endian, which
+// is the byte order the native shims decode Float32 samples in.
+
+const ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
+
+/** Standard (RFC 4648, padded) base64 of `bytes`. */
+export function bytesToBase64(bytes: Uint8Array): string {
+  const chunks: string[] = [];
+  let chunk = '';
+  let i = 0;
+  for (; i + 2 < bytes.length; i += 3) {
+    const n = (bytes[i] << 16) | (bytes[i + 1] << 8) | bytes[i + 2];
+    chunk +=
+      ALPHABET[(n >> 18) & 63] +
+      ALPHABET[(n >> 12) & 63] +
+      ALPHABET[(n >> 6) & 63] +
+      ALPHABET[n & 63];
+    // Flush periodically so long inputs don't build one enormous rope.
+    if (chunk.length >= 8192) {
+      chunks.push(chunk);
+      chunk = '';
+    }
+  }
+  const rest = bytes.length - i;
+  if (rest === 1) {
+    const n = bytes[i] << 16;
+    chunk += ALPHABET[(n >> 18) & 63] + ALPHABET[(n >> 12) & 63] + '==';
+  } else if (rest === 2) {
+    const n = (bytes[i] << 16) | (bytes[i + 1] << 8);
+    chunk +=
+      ALPHABET[(n >> 18) & 63] + ALPHABET[(n >> 12) & 63] + ALPHABET[(n >> 6) & 63] + '=';
+  }
+  chunks.push(chunk);
+  return chunks.join('');
+}
+
+/** Base64 of Float32 PCM samples as little-endian bytes. */
+export function float32ToBase64(samples: Float32Array | ArrayLike<number>): string {
+  const floats = samples instanceof Float32Array ? samples : Float32Array.from(samples);
+  return bytesToBase64(new Uint8Array(floats.buffer, floats.byteOffset, floats.byteLength));
+}

package/src/cancel.ts

@@ -0,0 +1,47 @@
+import NativeXybrid from './NativeXybrid';
+
+/**
+ * The part of the standard `AbortSignal` this SDK needs, so any
+ * implementation (React Native's `AbortController`, a polyfill) works.
+ */
+export interface AbortSignalLike {
+  readonly aborted: boolean;
+  addEventListener(type: 'abort', listener: () => void): void;
+  removeEventListener(type: 'abort', listener: () => void): void;
+}
+
+/** A native cancellation token bound to an `AbortSignal` for one call. */
+export interface CancelBinding {
+  /** Native token handle, or `null` when the call has no signal. */
+  readonly token: string | null;
+  /** Detach from the signal and free the native token. Never rejects. */
+  release(): Promise<void>;
+}
+
+const NO_SIGNAL: CancelBinding = { token: null, release: () => Promise.resolve() };
+
+/**
+ * Create a native stop button wired to `signal`. Aborting the signal cancels
+ * the token, which stops generation at the next token boundary. A signal
+ * that is already aborted cancels the token before the call starts, so the
+ * call rejects with `xybrid_cancelled` instead of running.
+ */
+export async function bindCancel(signal: AbortSignalLike | undefined): Promise<CancelBinding> {
+  if (!signal) return NO_SIGNAL;
+  const token = await NativeXybrid.createCancelToken();
+  const onAbort = () => {
+    NativeXybrid.cancel(token).catch(() => {});
+  };
+  if (signal.aborted) {
+    await NativeXybrid.cancel(token);
+  } else {
+    signal.addEventListener('abort', onAbort);
+  }
+  return {
+    token,
+    release: async () => {
+      signal.removeEventListener('abort', onAbort);
+      await NativeXybrid.dispose(token).catch(() => {});
+    },
+  };
+}

package/src/context.ts

@@ -0,0 +1,70 @@
+import NativeXybrid from './NativeXybrid';
+import type { ConversationInfo, Envelope } from './types';
+import { fromWireEnvelope, toWireEnvelope, type WireEnvelope } from './wire';
+
+/**
+ * Multi-turn conversation history, held natively. Pass it to
+ * `model.run(envelope, { context })` or `runStreaming`; inference reads the
+ * history but never changes it. The prompt you run is appended to the
+ * history for that run only, so push both turns *after* the run — pushing the
+ * prompt first would send it twice:
+ *
+ * ```ts
+ * const chat = await ConversationContext.create();
+ * await chat.setSystem('You are terse.');
+ *
+ * const question = Envelope.user('What is the capital of France?');
+ * const reply = await model.run(question, { context: chat });
+ * await chat.push(question);
+ * await chat.push(reply.envelope); // already tagged `assistant`
+ * ```
+ */
+export class ConversationContext {
+  private constructor(
+    /** Opaque native handle. */
+    readonly handle: string,
+  ) {}
+
+  /** A new, empty conversation; `id` defaults to a fresh one (telemetry correlation). */
+  static async create(id?: string): Promise<ConversationContext> {
+    return new ConversationContext(await NativeXybrid.createContext(id ?? null));
+  }
+
+  /** Append a turn. Give it a `role` (see `Envelope.user` / `Envelope.assistant`). */
+  push(envelope: Envelope): Promise<void> {
+    return NativeXybrid.contextPush(this.handle, toWireEnvelope(envelope));
+  }
+
+  /** Set the persistent system prompt; it survives {@link clear}. */
+  setSystem(system: Envelope | string): Promise<void> {
+    const envelope: Envelope =
+      typeof system === 'string' ? { kind: 'text', text: system, role: 'system' } : system;
+    return NativeXybrid.contextSetSystem(this.handle, toWireEnvelope(envelope));
+  }
+
+  /** Drop the history; the system prompt is kept. */
+  clear(): Promise<void> {
+    return NativeXybrid.contextClear(this.handle);
+  }
+
+  /** Id, history length and whether a system prompt is set. */
+  async info(): Promise<ConversationInfo> {
+    return (await NativeXybrid.contextInfo(this.handle)) as ConversationInfo;
+  }
+
+  /** History turns in order, excluding the system prompt. */
+  async history(): Promise<Envelope[]> {
+    const wire = (await NativeXybrid.contextHistory(this.handle)) as WireEnvelope[];
+    return wire.map(fromWireEnvelope);
+  }
+
+  /** Cap the history; older turns are pruned first, immediately. */
+  setMaxHistoryLength(length: number): Promise<void> {
+    return NativeXybrid.contextSetMaxHistoryLength(this.handle, length);
+  }
+
+  /** Free the native context. Runs already started keep their snapshot. */
+  release(): Promise<void> {
+    return NativeXybrid.dispose(this.handle);
+  }
+}

package/src/envelope.ts

@@ -0,0 +1,115 @@
+import NativeXybrid from './NativeXybrid';
+import type {
+  AudioEnvelope,
+  EmbeddingEnvelope,
+  Envelope as EnvelopeType,
+  ImageEnvelope,
+  ImageFormat,
+  MessageRole,
+  MultiPartEnvelope,
+  TextEnvelope,
+  ToolResult,
+} from './types';
+import {
+  fromWireEnvelope,
+  normalizeImageFormat,
+  toWireToolResult,
+  type WireEnvelope,
+} from './wire';
+
+/** Input to (and output of) a model. Narrow on `kind`. */
+export type Envelope = EnvelopeType;
+
+/**
+ * Envelope factories, named like the Swift and Kotlin `Envelope` helpers.
+ * Object literals (`{ kind: 'text', text }`) work just as well; these only
+ * save typing and apply the same defaults.
+ */
+export const Envelope = {
+  /** A text prompt, or text to speak with an optional TTS voice and speed. */
+  text(
+    text: string,
+    options: { voiceId?: string; speed?: number; role?: MessageRole } = {},
+  ): TextEnvelope {
+    return { kind: 'text', text, ...options };
+  },
+
+  /** A user turn for a conversation. */
+  user(text: string): TextEnvelope {
+    return { kind: 'text', text, role: 'user' };
+  },
+
+  /** An assistant turn for a conversation (e.g. a model reply you keep). */
+  assistant(text: string): TextEnvelope {
+    return { kind: 'text', text, role: 'assistant' };
+  },
+
+  /** A system prompt. */
+  system(text: string): TextEnvelope {
+    return { kind: 'text', text, role: 'system' };
+  },
+
+  /** PCM/WAV audio, base64-encoded. Defaults to 16 kHz mono. */
+  audio(
+    bytesBase64: string,
+    options: { sampleRate?: number; channels?: number } = {},
+  ): AudioEnvelope {
+    return {
+      kind: 'audio',
+      bytesBase64,
+      sampleRate: options.sampleRate ?? 16000,
+      channels: options.channels ?? 1,
+    };
+  },
+
+  /** An embedding vector. */
+  embedding(data: number[]): EmbeddingEnvelope {
+    return { kind: 'embedding', data };
+  },
+
+  /**
+   * An encoded image for vision-language models. The bytes are validated
+   * natively at run time (`xybrid_invalid_image` on bad input).
+   */
+  image(bytesBase64: string, format: ImageFormat | 'jpg'): ImageEnvelope {
+    return { kind: 'image', bytesBase64, format: normalizeImageFormat(format) };
+  },
+
+  /** A user message with image attachments, for vision-language models. */
+  userMessage(text: string, images: ImageEnvelope[] = []): MultiPartEnvelope {
+    if (!images.every((image) => image?.kind === 'image')) {
+      throw new TypeError('Envelope.userMessage accepts only image envelopes');
+    }
+    return {
+      kind: 'multipart',
+      parts: [{ kind: 'text', text }, ...images],
+      role: 'user',
+    };
+  },
+
+  /**
+   * The continuation envelope for the turn after the model asked for tools.
+   *
+   * One `run` is one model turn, so the tool loop lives in your code: run a
+   * request carrying `generationConfig.tools`, execute every
+   * `result.toolCalls` entry, then run this envelope (with the same tools) to
+   * feed the outcomes back.
+   *
+   * @param userText the original user message of the turn being continued.
+   * @param priorAssistantText that turn's raw output — `result.text` from a
+   *   batch run, or the terminal token's `rawText` when streaming.
+   * @param results tool outcomes, in call order.
+   */
+  async toolResults(
+    userText: string,
+    priorAssistantText: string,
+    results: ToolResult[],
+  ): Promise<Envelope> {
+    const wire = (await NativeXybrid.toolResultsEnvelope(
+      userText,
+      priorAssistantText,
+      results.map(toWireToolResult),
+    )) as WireEnvelope;
+    return fromWireEnvelope(wire);
+  },
+};

package/src/errors.ts

@@ -0,0 +1,67 @@
+// Every native rejection carries one of these codes as `error.code`. The
+// SDK codes map 1:1 onto bolt's `XybridError` variants (same order as
+// crates/xybrid-bolt/src/lib.rs); the last three are raised by the React
+// Native layer itself.
+
+/** Stable error codes for `XybridError.code`. */
+export const XybridErrorCodes = [
+  'xybrid_model_not_found',
+  'xybrid_directory_not_found',
+  'xybrid_metadata_not_found',
+  'xybrid_metadata_invalid',
+  'xybrid_load_error',
+  'xybrid_inference_error',
+  'xybrid_aborted_cloud_fallback',
+  'xybrid_streaming_unsupported',
+  'xybrid_not_loaded',
+  'xybrid_config_error',
+  'xybrid_network_error',
+  'xybrid_offline',
+  'xybrid_io_error',
+  'xybrid_cache_error',
+  'xybrid_pipeline_error',
+  'xybrid_circuit_open',
+  'xybrid_rate_limited',
+  'xybrid_timeout',
+  'xybrid_missing_artifact',
+  'xybrid_unsupported_model_capability',
+  'xybrid_unsupported_backend_capability',
+  'xybrid_invalid_image',
+  'xybrid_cancelled',
+  // React Native layer:
+  /** The handle was never issued, was released, or names another kind of object. */
+  'xybrid_handle',
+  /** A JS argument could not be decoded (bad envelope, options, source, base64…). */
+  'xybrid_invalid_argument',
+  /** Anything unexpected; the message carries the detail. */
+  'xybrid_unknown',
+] as const;
+
+export type XybridErrorCode = (typeof XybridErrorCodes)[number];
+
+/** A rejection raised by the Xybrid native module. */
+export interface XybridError extends Error {
+  code: XybridErrorCode;
+}
+
+const CODES: ReadonlySet<string> = new Set(XybridErrorCodes);
+
+/** Narrow an unknown rejection to a {@link XybridError}. */
+export function isXybridError(error: unknown): error is XybridError {
+  if (!(error instanceof Error)) return false;
+  const { code } = error as Error & { code?: unknown };
+  return typeof code === 'string' && CODES.has(code);
+}
+
+// Mirrors `RetryableError::is_retryable` on the Rust `SdkError`.
+const RETRYABLE: ReadonlySet<XybridErrorCode> = new Set<XybridErrorCode>([
+  'xybrid_network_error',
+  'xybrid_rate_limited',
+  'xybrid_timeout',
+  'xybrid_offline',
+]);
+
+/** Whether retrying the same call later can succeed (network, rate limit, timeout, offline). */
+export function isRetryable(error: unknown): boolean {
+  return isXybridError(error) && RETRYABLE.has(error.code);
+}

package/src/index.ts

@@ -0,0 +1,91 @@
+// @xybrid/react-native — on-device (and optionally cloud) inference for React
+// Native, backed by the same Rust SDK as the Swift, Kotlin, Flutter and Unity
+// bindings.
+//
+//   await Xybrid.initialize({ apiKey });            // optional
+//   const model = await ModelLoader.fromRegistry('qwen3.5-0.8b').load();
+//   const result = await model.run(Envelope.text('Hello'));
+//   await model.release();
+
+import NativeXybrid from './NativeXybrid';
+
+export { Xybrid, type XybridInitOptions } from './xybrid';
+export {
+  Model,
+  ModelDownload,
+  ModelLoader,
+  type ModelSource,
+  type RunOptions,
+} from './model';
+export { ConversationContext } from './context';
+export { Pipeline } from './pipeline';
+export { StreamingSession } from './session';
+export { Envelope } from './envelope';
+export { GenerationConfigs, creative, greedy } from './presets';
+export {
+  XybridErrorCodes,
+  isRetryable,
+  isXybridError,
+  type XybridError,
+  type XybridErrorCode,
+} from './errors';
+export type { AbortSignalLike } from './cancel';
+export { bytesToBase64, float32ToBase64 } from './base64';
+
+export type {
+  AbortSignalKind,
+  AudioEnvelope,
+  CacheEntry,
+  CacheEntryLocation,
+  CacheStatus,
+  ConversationInfo,
+  DownloadState,
+  DownloadStatus,
+  EmbeddingEnvelope,
+  EnvelopeKind,
+  EnvelopeMetadata,
+  ExecutionTarget,
+  GenerationConfig,
+  ImageEnvelope,
+  ImageFormat,
+  InferenceMetrics,
+  InferenceResult,
+  MessageRole,
+  ModelInfo,
+  MultiPartEnvelope,
+  OutputType,
+  PartialResult,
+  PipelineInfo,
+  PipelineResult,
+  StageLatency,
+  StageResult,
+  StreamToken,
+  StreamingConfig,
+  TextEnvelope,
+  ThermalState,
+  ToolCall,
+  ToolDefinition,
+  ToolResult,
+  VoiceInfo,
+} from './types';
+
+/**
+ * Convert a JSON Schema (object or JSON string) into a GBNF grammar for
+ * `generationConfig.grammar`, so a local LLM emits schema-valid JSON. Runs the
+ * same native converter every binding uses; rejects with
+ * `xybrid_config_error` on invalid JSON or an unsupported construct.
+ *
+ * ```ts
+ * const grammar = await jsonSchemaToGbnf({
+ *   type: 'object',
+ *   properties: { name: { type: 'string' } },
+ *   required: ['name'],
+ * });
+ * const result = await model.run(prompt, { generationConfig: { grammar } });
+ * ```
+ */
+export function jsonSchemaToGbnf(schema: object | string): Promise<string> {
+  return NativeXybrid.jsonSchemaToGbnf(
+    typeof schema === 'string' ? schema : JSON.stringify(schema),
+  );
+}