@xybrid/react-native 0.10.0-rc1

package/lib/module/errors.js

@@ -0,0 +1,56 @@
+// 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',
+];
+const CODES = new Set(XybridErrorCodes);
+/** Narrow an unknown rejection to a {@link XybridError}. */
+export function isXybridError(error) {
+    if (!(error instanceof Error))
+        return false;
+    const { code } = error;
+    return typeof code === 'string' && CODES.has(code);
+}
+// Mirrors `RetryableError::is_retryable` on the Rust `SdkError`.
+const RETRYABLE = new Set([
+    '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) {
+    return isXybridError(error) && RETRYABLE.has(error.code);
+}

package/lib/module/index.js

@@ -0,0 +1,36 @@
+// @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 } from './xybrid';
+export { Model, ModelDownload, ModelLoader, } 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, } from './errors';
+export { bytesToBase64, float32ToBase64 } from './base64';
+/**
+ * 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) {
+    return NativeXybrid.jsonSchemaToGbnf(typeof schema === 'string' ? schema : JSON.stringify(schema));
+}

package/lib/module/model.js

@@ -0,0 +1,298 @@
+import NativeXybrid from './NativeXybrid';
+import { bindCancel } from './cancel';
+import { StreamingSession } from './session';
+import { fromWireDownloadStatus, fromWireGenerationConfig, fromWireResult, fromWireStreamToken, toWireEnvelope, toWireRunOptions, } from './wire';
+function toWireSource(source) {
+    switch (source.kind) {
+        case 'registry':
+        case 'registrySpeculative':
+            return { kind: source.kind, value: source.id };
+        case 'bundle':
+        case 'directory':
+        case 'modelFile':
+            return { kind: source.kind, value: source.path };
+        case 'huggingFace':
+            return {
+                kind: source.kind,
+                value: source.repo,
+                ...(source.revision ? { revision: source.revision } : {}),
+            };
+    }
+}
+/**
+ * A cheap description of a model. Creating one does no I/O; {@link load}
+ * resolves, downloads if needed, and loads it.
+ */
+export class ModelLoader {
+    constructor(source) {
+        this.source = source;
+    }
+    /** Describe any source. */
+    static from(source) {
+        return new ModelLoader(source);
+    }
+    /** A model from the Xybrid registry. The recommended path. */
+    static fromRegistry(id) {
+        return new ModelLoader({ kind: 'registry', id });
+    }
+    /**
+     * Serve from the cloud gateway while the registry weights download in the
+     * background, instead of blocking on the download. `load()` then resolves
+     * almost immediately with a model that switches to on-device by itself.
+     * Needs an API key and an uncached model — {@link willSpeculate} tells you
+     * up front — otherwise it behaves like {@link fromRegistry}. LLM/chat only.
+     */
+    static fromRegistrySpeculative(id) {
+        return new ModelLoader({ kind: 'registrySpeculative', id });
+    }
+    /** A local `.xyb` bundle. */
+    static fromBundle(path) {
+        return new ModelLoader({ kind: 'bundle', path });
+    }
+    /** A local directory containing `model_metadata.json`. */
+    static fromDirectory(path) {
+        return new ModelLoader({ kind: 'directory', path });
+    }
+    /** A Hugging Face repository (`org/repo` or `org/repo:variant`), optionally pinned. */
+    static fromHuggingFace(repo, options = {}) {
+        return new ModelLoader({ kind: 'huggingFace', repo, ...options });
+    }
+    /** A raw GGUF file; `model_metadata.json` is generated next to it if absent. */
+    static fromModelFile(path) {
+        return new ModelLoader({ kind: 'modelFile', path });
+    }
+    /** Resolve, download if needed, and load. Rejects with a typed `xybrid_*` code. */
+    async load() {
+        return new Model(await NativeXybrid.loadModel(toWireSource(this.source)));
+    }
+    /**
+     * Whether {@link load} would actually speculate: a speculative source, an
+     * API key, and a model not yet cached. Never touches the network.
+     */
+    async willSpeculate() {
+        if (this.source.kind !== 'registrySpeculative')
+            return false;
+        return NativeXybrid.willSpeculate(this.source.id);
+    }
+    /**
+     * Start downloading the weights in the background without loading them —
+     * the object to drive a progress bar from. The download fills the cache, so
+     * the {@link load} afterwards returns at once. Resolves `null` for sources
+     * with nothing to fetch (bundle, directory, Hugging Face, model file).
+     */
+    async download(options = {}) {
+        const { source } = this;
+        if (source.kind !== 'registry' && source.kind !== 'registrySpeculative')
+            return null;
+        return new ModelDownload(await NativeXybrid.startDownload(source.id, options.platform ?? null));
+    }
+}
+/** A model loaded in native memory. Call {@link release} when done with it. */
+export class Model {
+    /** @internal Use {@link ModelLoader.load}. */
+    constructor(
+    /** Opaque native handle — not the model id; see {@link info}. */
+    handle) {
+        this.handle = handle;
+    }
+    /** Identity and capabilities, in one native call. */
+    async info() {
+        const raw = (await NativeXybrid.modelInfo(this.handle));
+        return {
+            ...raw,
+            defaultGenerationConfig: fromWireGenerationConfig(raw.defaultGenerationConfig),
+        };
+    }
+    /** Whether the weights are resident (false after {@link unload} until the next run). */
+    isLoaded() {
+        return NativeXybrid.isLoaded(this.handle);
+    }
+    /**
+     * Run one inference. Pass sampling parameters under `generationConfig`,
+     * a conversation under `context`, and an `AbortSignal` under `signal`.
+     */
+    async run(envelope, options = {}) {
+        const wireEnvelope = toWireEnvelope(envelope);
+        const cancel = await bindCancel(options.signal);
+        try {
+            const wire = await NativeXybrid.run(this.handle, wireEnvelope, toWireRunOptions(options, { context: options.context?.handle, cancel: cancel.token }));
+            return fromWireResult(wire);
+        }
+        finally {
+            await cancel.release();
+        }
+    }
+    /**
+     * Stream inference token by token. Yields each {@link StreamToken}; the
+     * final {@link InferenceResult} is the generator's return value.
+     *
+     * ```ts
+     * for await (const token of model.runStreaming(Envelope.text('Hi'))) {
+     *   setText((prev) => prev + token.token);
+     * }
+     * ```
+     *
+     * Generation stops natively when iteration ends — completion, `break`, a
+     * thrown error, or an aborted `signal`. A generator that is merely
+     * abandoned is never cleaned up (JS runs no `finally` on GC), so on
+     * unmount abort the signal or call `gen.return()`.
+     *
+     * When the turn ends on tool calls, the terminal token carries `toolCalls`
+     * and `rawText` (pass it to `Envelope.toolResults`).
+     */
+    async *runStreaming(envelope, options = {}) {
+        const wireEnvelope = toWireEnvelope(envelope);
+        const cancel = await bindCancel(options.signal);
+        let stream = null;
+        try {
+            stream = await NativeXybrid.streamStart(this.handle, wireEnvelope, toWireRunOptions(options, { context: options.context?.handle, cancel: cancel.token }));
+            for (;;) {
+                const event = (await NativeXybrid.streamNext(stream));
+                // `null`: the stream was disposed underneath us (model released).
+                if (event == null)
+                    return undefined;
+                switch (event.kind) {
+                    case 'token':
+                        yield fromWireStreamToken(event.token);
+                        break;
+                    case 'complete':
+                        return fromWireResult(event.result);
+                    default:
+                        throw new Error(`Unexpected stream event: ${String(event.kind)}`);
+                }
+            }
+        }
+        finally {
+            // Disposing aborts native generation; idempotent after completion.
+            if (stream !== null)
+                await NativeXybrid.dispose(stream).catch(() => { });
+            await cancel.release();
+        }
+    }
+    /**
+     * Open a live ASR session: feed microphone PCM in, read partial transcripts
+     * out. Audio must be Float32, mono, 16 kHz. Rejects with
+     * `xybrid_streaming_unsupported` for a model that cannot stream.
+     */
+    async stream(config = {}) {
+        return new StreamingSession(await NativeXybrid.openStreamingSession(this.handle, config));
+    }
+    /** Prime the model so first-token latency measures inference, not cold start. */
+    warmup() {
+        return NativeXybrid.warmup(this.handle);
+    }
+    /**
+     * Free the weights while keeping this handle valid — the next run reloads
+     * them. Contrast with {@link release}, which frees the handle.
+     */
+    unload() {
+        return NativeXybrid.unload(this.handle);
+    }
+    /**
+     * Whether runs are currently answered by the cloud because the local
+     * weights aren't ready (speculative loads). Predicts the next run;
+     * `InferenceResult.executionTarget` reports what a finished run did.
+     */
+    isCloudServing() {
+        return NativeXybrid.isCloudServing(this.handle);
+    }
+    /** Download progress of a speculative load; `ready` at 1.0 for local models. */
+    async downloadStatus() {
+        return fromWireDownloadStatus((await NativeXybrid.downloadStatus(this.handle)));
+    }
+    /**
+     * Yield the speculative download's status whenever it changes, ending
+     * after a terminal state. A local model yields one `ready` frame.
+     */
+    downloadProgress(options = {}) {
+        return pollDownload(() => this.downloadStatus(), options.intervalMs);
+    }
+    /**
+     * Wait natively until the download settles or `timeoutMs` elapses, then
+     * report it. `0` makes it a non-blocking read.
+     */
+    async awaitDownload(timeoutMs) {
+        return fromWireDownloadStatus((await NativeXybrid.awaitDownload(this.handle, timeoutMs)));
+    }
+    /** TTS voices; empty for models without voices. */
+    async voices() {
+        return (await NativeXybrid.voices(this.handle));
+    }
+    /** The default TTS voice, if the model has voices. */
+    async defaultVoice() {
+        return (await NativeXybrid.defaultVoice(this.handle));
+    }
+    /** One TTS voice by id. */
+    async voice(voiceId) {
+        return (await NativeXybrid.voice(this.handle, voiceId));
+    }
+    /**
+     * Free the native model — weights live in the native heap, so release
+     * models you no longer need. Also stops token streams started from it.
+     * Later calls on this instance reject with `xybrid_handle`.
+     */
+    release() {
+        return NativeXybrid.dispose(this.handle);
+    }
+}
+const TERMINAL_STATES = new Set(['ready', 'failed', 'cancelled']);
+/**
+ * Poll `read` and yield each changed status, ending after a terminal state.
+ * The native side throttles its own updates (~10/s), so a 200 ms default
+ * loses nothing a progress bar can show.
+ */
+async function* pollDownload(read, intervalMs = 200) {
+    const delay = Math.max(16, intervalMs);
+    let previous = null;
+    for (;;) {
+        const status = await read();
+        if (previous === null ||
+            status.state !== previous.state ||
+            status.downloadedBytes !== previous.downloadedBytes ||
+            status.progress !== previous.progress) {
+            yield status;
+            previous = status;
+        }
+        if (TERMINAL_STATES.has(status.state))
+            return;
+        await new Promise((resolve) => setTimeout(resolve, delay));
+    }
+}
+/**
+ * A model download running in the background, separate from loading. Start
+ * one with {@link ModelLoader.download}. Releasing the handle does not stop
+ * the transfer — call {@link cancel}.
+ */
+export class ModelDownload {
+    /** @internal */
+    constructor(handle) {
+        this.handle = handle;
+    }
+    /** Progress, bytes and state in one consistent read. */
+    async status() {
+        return fromWireDownloadStatus((await NativeXybrid.downloadHandleStatus(this.handle)));
+    }
+    /** The failure message once the download failed, else `null`. */
+    error() {
+        return NativeXybrid.downloadHandleError(this.handle);
+    }
+    /** Stop the transfer. The status then settles on `cancelled`. */
+    cancel() {
+        return NativeXybrid.cancelDownload(this.handle);
+    }
+    /**
+     * Yield the status whenever it changes, ending after a terminal state
+     * (`ready`, `failed`, `cancelled`). Polls natively every `intervalMs`.
+     *
+     * ```ts
+     * for await (const s of download.progress()) setProgress(s.progress);
+     * ```
+     */
+    progress(options = {}) {
+        return pollDownload(() => this.status(), options.intervalMs);
+    }
+    /** Free the handle (the transfer keeps going unless cancelled). */
+    release() {
+        return NativeXybrid.dispose(this.handle);
+    }
+}

package/lib/module/pipeline.js

@@ -0,0 +1,48 @@
+import NativeXybrid from './NativeXybrid';
+import { fromWirePipelineResult, toWireEnvelope, } from './wire';
+/**
+ * A multi-stage pipeline (e.g. ASR → LLM → TTS) defined in YAML. A run
+ * returns every stage's output, so a voice assistant can show what it heard
+ * and what it answered while it plays the audio:
+ *
+ * ```ts
+ * const pipeline = await Pipeline.fromFile(path);
+ * const result = await pipeline.run(Envelope.audio(pcmBase64));
+ * const heard = result.stages.find((s) => s.stageId === 'asr')?.text;
+ * ```
+ */
+export class Pipeline {
+    constructor(
+    /** Opaque native handle. */
+    handle) {
+        this.handle = handle;
+    }
+    /** Parse and load a pipeline from YAML content. */
+    static async fromYaml(yaml) {
+        return new Pipeline(await NativeXybrid.loadPipeline({ kind: 'yaml', value: yaml }));
+    }
+    /** Read, parse and load a pipeline YAML file. */
+    static async fromFile(path) {
+        return new Pipeline(await NativeXybrid.loadPipeline({ kind: 'file', value: path }));
+    }
+    /** Load a pipeline bundle. */
+    static async fromBundle(path) {
+        return new Pipeline(await NativeXybrid.loadPipeline({ kind: 'bundle', value: path }));
+    }
+    /** Name and stage ids, in execution order. */
+    async info() {
+        return (await NativeXybrid.pipelineInfo(this.handle));
+    }
+    /**
+     * Run every stage, downloading any missing model first. Per-stage
+     * generation settings belong in the YAML; only `correlationId` applies here.
+     */
+    async run(envelope, options = {}) {
+        const wire = await NativeXybrid.runPipeline(this.handle, toWireEnvelope(envelope), options.correlationId !== undefined ? { correlationId: options.correlationId } : null);
+        return fromWirePipelineResult(wire);
+    }
+    /** Free the native pipeline. */
+    release() {
+        return NativeXybrid.dispose(this.handle);
+    }
+}

package/lib/module/presets.js

@@ -0,0 +1,27 @@
+// Generation-config presets with the same values as the Swift and Kotlin
+// `GenerationConfigs`. Pure TS — no native call.
+/**
+ * Greedy decoding (deterministic, temperature 0): the usual choice for
+ * extraction and tool calling.
+ */
+export function greedy(options = {}) {
+    return {
+        temperature: 0.0,
+        topP: 1.0,
+        topK: 0,
+        stopSequences: [],
+        ...options,
+    };
+}
+/** Higher temperature, for more varied output. */
+export function creative(options = {}) {
+    return {
+        temperature: 0.9,
+        topP: 0.95,
+        topK: 50,
+        stopSequences: [],
+        ...options,
+    };
+}
+/** Preset factories for {@link GenerationConfig}. */
+export const GenerationConfigs = { greedy, creative };

package/lib/module/session.js

@@ -0,0 +1,69 @@
+import NativeXybrid from './NativeXybrid';
+import { float32ToBase64 } from './base64';
+/**
+ * A live ASR session: feed microphone PCM in, read partial transcripts out.
+ * Open one with `model.stream()`.
+ *
+ * ```ts
+ * const session = await model.stream();
+ * (async () => {
+ *   for await (const partial of session.partials()) setCaption(partial.text);
+ * })();
+ * // from your audio callback (Float32, mono, 16 kHz):
+ * await session.feed(samples);
+ * // when the user stops talking:
+ * const transcript = await session.flush();
+ * await session.release();
+ * ```
+ */
+export class StreamingSession {
+    /** @internal Use `model.stream()`. */
+    constructor(
+    /** Opaque native handle. */
+    handle) {
+        this.handle = handle;
+    }
+    /**
+     * Queue PCM samples (Float32, mono, 16 kHz). Transcription happens off the
+     * JS thread; this only waits when the native queue is full.
+     */
+    feed(samples) {
+        return NativeXybrid.sessionFeed(this.handle, float32ToBase64(samples));
+    }
+    /**
+     * Partial transcripts as they arrive, ending when the session finishes
+     * (after {@link flush} or {@link cancel}). Each partial is cumulative:
+     * render it in place of the previous one. Use one iterator per session.
+     */
+    async *partials() {
+        for (;;) {
+            const partial = (await NativeXybrid.sessionNextPartial(this.handle));
+            if (partial == null)
+                return;
+            yield partial;
+        }
+    }
+    /**
+     * Drain the buffered audio and return the complete transcript. The session
+     * is over afterwards.
+     */
+    flush() {
+        return NativeXybrid.sessionFlush(this.handle);
+    }
+    /** Start over on fresh audio without reloading the model. */
+    reset() {
+        return NativeXybrid.sessionReset(this.handle);
+    }
+    /** Stop and discard buffered audio — the "user walked away" path. */
+    cancel() {
+        return NativeXybrid.sessionCancel(this.handle);
+    }
+    /** Whether the session still accepts audio. */
+    isRunning() {
+        return NativeXybrid.sessionIsRunning(this.handle);
+    }
+    /** Free the native session (cancelling it if still running). */
+    release() {
+        return NativeXybrid.dispose(this.handle);
+    }
+}

package/lib/module/types.js

@@ -0,0 +1,9 @@
+// Public types. They mirror the bolt `#[data]` records in
+// crates/xybrid-bolt/src/lib.rs field for field (camelCase), so a value means
+// the same thing here as in the Swift and Kotlin SDKs. tests/parity.test.mjs
+// fails when bolt gains a field or export that is neither mapped here nor
+// listed as intentionally excluded in parity.json.
+//
+// Binary payloads (audio, images) cross as base64 strings: TurboModules have
+// no ArrayBuffer type. See README "Binary payloads".
+export {};