@xybrid/react-native 0.10.0-rc1

package/lib/commonjs/model.js

@@ -0,0 +1,307 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ModelDownload = exports.Model = exports.ModelLoader = void 0;
+const NativeXybrid_1 = __importDefault(require("./NativeXybrid"));
+const cancel_1 = require("./cancel");
+const session_1 = require("./session");
+const wire_1 = require("./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.
+ */
+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_1.default.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_1.default.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_1.default.startDownload(source.id, options.platform ?? null));
+    }
+}
+exports.ModelLoader = ModelLoader;
+/** A model loaded in native memory. Call {@link release} when done with it. */
+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_1.default.modelInfo(this.handle));
+        return {
+            ...raw,
+            defaultGenerationConfig: (0, wire_1.fromWireGenerationConfig)(raw.defaultGenerationConfig),
+        };
+    }
+    /** Whether the weights are resident (false after {@link unload} until the next run). */
+    isLoaded() {
+        return NativeXybrid_1.default.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 = (0, wire_1.toWireEnvelope)(envelope);
+        const cancel = await (0, cancel_1.bindCancel)(options.signal);
+        try {
+            const wire = await NativeXybrid_1.default.run(this.handle, wireEnvelope, (0, wire_1.toWireRunOptions)(options, { context: options.context?.handle, cancel: cancel.token }));
+            return (0, wire_1.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 = (0, wire_1.toWireEnvelope)(envelope);
+        const cancel = await (0, cancel_1.bindCancel)(options.signal);
+        let stream = null;
+        try {
+            stream = await NativeXybrid_1.default.streamStart(this.handle, wireEnvelope, (0, wire_1.toWireRunOptions)(options, { context: options.context?.handle, cancel: cancel.token }));
+            for (;;) {
+                const event = (await NativeXybrid_1.default.streamNext(stream));
+                // `null`: the stream was disposed underneath us (model released).
+                if (event == null)
+                    return undefined;
+                switch (event.kind) {
+                    case 'token':
+                        yield (0, wire_1.fromWireStreamToken)(event.token);
+                        break;
+                    case 'complete':
+                        return (0, wire_1.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_1.default.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 session_1.StreamingSession(await NativeXybrid_1.default.openStreamingSession(this.handle, config));
+    }
+    /** Prime the model so first-token latency measures inference, not cold start. */
+    warmup() {
+        return NativeXybrid_1.default.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_1.default.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_1.default.isCloudServing(this.handle);
+    }
+    /** Download progress of a speculative load; `ready` at 1.0 for local models. */
+    async downloadStatus() {
+        return (0, wire_1.fromWireDownloadStatus)((await NativeXybrid_1.default.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 (0, wire_1.fromWireDownloadStatus)((await NativeXybrid_1.default.awaitDownload(this.handle, timeoutMs)));
+    }
+    /** TTS voices; empty for models without voices. */
+    async voices() {
+        return (await NativeXybrid_1.default.voices(this.handle));
+    }
+    /** The default TTS voice, if the model has voices. */
+    async defaultVoice() {
+        return (await NativeXybrid_1.default.defaultVoice(this.handle));
+    }
+    /** One TTS voice by id. */
+    async voice(voiceId) {
+        return (await NativeXybrid_1.default.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_1.default.dispose(this.handle);
+    }
+}
+exports.Model = Model;
+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}.
+ */
+class ModelDownload {
+    /** @internal */
+    constructor(handle) {
+        this.handle = handle;
+    }
+    /** Progress, bytes and state in one consistent read. */
+    async status() {
+        return (0, wire_1.fromWireDownloadStatus)((await NativeXybrid_1.default.downloadHandleStatus(this.handle)));
+    }
+    /** The failure message once the download failed, else `null`. */
+    error() {
+        return NativeXybrid_1.default.downloadHandleError(this.handle);
+    }
+    /** Stop the transfer. The status then settles on `cancelled`. */
+    cancel() {
+        return NativeXybrid_1.default.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_1.default.dispose(this.handle);
+    }
+}
+exports.ModelDownload = ModelDownload;

package/lib/commonjs/pipeline.js

@@ -0,0 +1,55 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Pipeline = void 0;
+const NativeXybrid_1 = __importDefault(require("./NativeXybrid"));
+const wire_1 = require("./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;
+ * ```
+ */
+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_1.default.loadPipeline({ kind: 'yaml', value: yaml }));
+    }
+    /** Read, parse and load a pipeline YAML file. */
+    static async fromFile(path) {
+        return new Pipeline(await NativeXybrid_1.default.loadPipeline({ kind: 'file', value: path }));
+    }
+    /** Load a pipeline bundle. */
+    static async fromBundle(path) {
+        return new Pipeline(await NativeXybrid_1.default.loadPipeline({ kind: 'bundle', value: path }));
+    }
+    /** Name and stage ids, in execution order. */
+    async info() {
+        return (await NativeXybrid_1.default.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_1.default.runPipeline(this.handle, (0, wire_1.toWireEnvelope)(envelope), options.correlationId !== undefined ? { correlationId: options.correlationId } : null);
+        return (0, wire_1.fromWirePipelineResult)(wire);
+    }
+    /** Free the native pipeline. */
+    release() {
+        return NativeXybrid_1.default.dispose(this.handle);
+    }
+}
+exports.Pipeline = Pipeline;

package/lib/commonjs/presets.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GenerationConfigs = void 0;
+exports.greedy = greedy;
+exports.creative = creative;
+// 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.
+ */
+function greedy(options = {}) {
+    return {
+        temperature: 0.0,
+        topP: 1.0,
+        topK: 0,
+        stopSequences: [],
+        ...options,
+    };
+}
+/** Higher temperature, for more varied output. */
+function creative(options = {}) {
+    return {
+        temperature: 0.9,
+        topP: 0.95,
+        topK: 50,
+        stopSequences: [],
+        ...options,
+    };
+}
+/** Preset factories for {@link GenerationConfig}. */
+exports.GenerationConfigs = { greedy, creative };

package/lib/commonjs/session.js

@@ -0,0 +1,76 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StreamingSession = void 0;
+const NativeXybrid_1 = __importDefault(require("./NativeXybrid"));
+const base64_1 = require("./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();
+ * ```
+ */
+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_1.default.sessionFeed(this.handle, (0, base64_1.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_1.default.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_1.default.sessionFlush(this.handle);
+    }
+    /** Start over on fresh audio without reloading the model. */
+    reset() {
+        return NativeXybrid_1.default.sessionReset(this.handle);
+    }
+    /** Stop and discard buffered audio — the "user walked away" path. */
+    cancel() {
+        return NativeXybrid_1.default.sessionCancel(this.handle);
+    }
+    /** Whether the session still accepts audio. */
+    isRunning() {
+        return NativeXybrid_1.default.sessionIsRunning(this.handle);
+    }
+    /** Free the native session (cancelling it if still running). */
+    release() {
+        return NativeXybrid_1.default.dispose(this.handle);
+    }
+}
+exports.StreamingSession = StreamingSession;

package/lib/commonjs/types.js

@@ -0,0 +1,10 @@
+"use strict";
+// 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".
+Object.defineProperty(exports, "__esModule", { value: true });