@octomil/browser 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OctoMil
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,75 @@
+# @octomil/browser
+
+In-browser ML inference via ONNX Runtime Web + WebGPU.
+
+[![npm](https://img.shields.io/npm/v/@octomil/browser)](https://www.npmjs.com/package/@octomil/browser)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+## Install
+
+```bash
+npm install @octomil/browser
+```
+
+## Quick Start
+
+```typescript
+import { Octomil } from '@octomil/browser';
+
+const ml = new Octomil({
+  model: 'https://models.octomil.com/sentiment-v1.onnx',
+  backend: 'webgpu',
+});
+
+await ml.load();
+const result = await ml.predict({ text: 'This is amazing!' });
+console.log(result.label, result.score);
+ml.dispose();
+```
+
+## Script Tag
+
+```html
+<script src="https://unpkg.com/@octomil/browser/dist/octomil.min.js"></script>
+<script>
+  const ml = new Octomil({ model: 'model.onnx' });
+  ml.load().then(() => ml.predict({ text: 'hello' })).then(console.log);
+</script>
+```
+
+## API
+
+### `new Octomil(options)`
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `model` | `string` | required | Model URL or registry name |
+| `backend` | `'webgpu' \| 'wasm'` | auto | Inference backend |
+| `cacheStrategy` | `'cache-api' \| 'indexeddb' \| 'none'` | `'cache-api'` | Model caching |
+| `serverUrl` | `string` | - | Server for registry resolution |
+| `apiKey` | `string` | - | API key for authenticated downloads |
+
+### Methods
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `load()` | `Promise<void>` | Download and initialize model |
+| `predict(input)` | `Promise<PredictOutput>` | Run inference |
+| `chat(messages)` | `Promise<ChatResponse>` | Chat completions |
+| `dispose()` | `void` | Release resources |
+
+### Input Formats
+
+```typescript
+await ml.predict({ raw: new Float32Array([...]), dims: [1, 3, 224, 224] });
+await ml.predict({ text: 'classify this' });
+await ml.predict({ image: document.querySelector('canvas') });
+```
+
+## Documentation
+
+[docs.octomil.com](https://docs.octomil.com)
+
+## License
+
+MIT

package/dist/cache.d.ts

@@ -0,0 +1,25 @@
+/**
+ * @octomil/browser — Model cache manager
+ *
+ * Caches downloaded ONNX model binaries using the Cache API (preferred)
+ * or IndexedDB as a fallback.  Cache entries are keyed by model URL so
+ * that different model versions naturally invalidate stale entries.
+ */
+import type { CacheInfo, CacheStrategy } from "./types.js";
+export interface ModelCache {
+    get(key: string): Promise<ArrayBuffer | null>;
+    put(key: string, data: ArrayBuffer): Promise<void>;
+    has(key: string): Promise<boolean>;
+    remove(key: string): Promise<void>;
+    info(key: string): Promise<CacheInfo>;
+}
+/**
+ * Create a {@link ModelCache} instance for the given strategy.
+ *
+ * Falls back gracefully:
+ *  - `"cache-api"` — uses Cache API if available, else IndexedDB, else no-op.
+ *  - `"indexeddb"` — uses IndexedDB if available, else no-op.
+ *  - `"none"` — always no-op.
+ */
+export declare function createModelCache(strategy: CacheStrategy): ModelCache;
+//# sourceMappingURL=cache.d.ts.map

package/dist/cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../src/cache.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAgB3D,MAAM,WAAW,UAAU;IACzB,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;IAC9C,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnD,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACnC,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnC,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;CACvC;AA8LD;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,aAAa,GAAG,UAAU,CA2BpE"}

package/dist/cache.js

@@ -0,0 +1,202 @@
+/**
+ * @octomil/browser — Model cache manager
+ *
+ * Caches downloaded ONNX model binaries using the Cache API (preferred)
+ * or IndexedDB as a fallback.  Cache entries are keyed by model URL so
+ * that different model versions naturally invalidate stale entries.
+ */
+import { OctomilError } from "./types.js";
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+const CACHE_NAME = "octomil-models-v1";
+const IDB_DB_NAME = "octomil-models";
+const IDB_STORE_NAME = "blobs";
+const IDB_VERSION = 1;
+// ---------------------------------------------------------------------------
+// Cache API implementation
+// ---------------------------------------------------------------------------
+class CacheApiModelCache {
+    async open() {
+        return caches.open(CACHE_NAME);
+    }
+    async get(key) {
+        const cache = await this.open();
+        const response = await cache.match(key);
+        if (!response)
+            return null;
+        return response.arrayBuffer();
+    }
+    async put(key, data) {
+        const cache = await this.open();
+        const response = new Response(data, {
+            headers: {
+                "x-octomil-cached-at": new Date().toISOString(),
+                "x-octomil-size": String(data.byteLength),
+            },
+        });
+        await cache.put(key, response);
+    }
+    async has(key) {
+        const cache = await this.open();
+        const match = await cache.match(key);
+        return match !== undefined;
+    }
+    async remove(key) {
+        const cache = await this.open();
+        await cache.delete(key);
+    }
+    async info(key) {
+        const cache = await this.open();
+        const response = await cache.match(key);
+        if (!response) {
+            return { cached: false, sizeBytes: 0 };
+        }
+        const sizeHeader = response.headers.get("x-octomil-size");
+        const cachedAtHeader = response.headers.get("x-octomil-cached-at");
+        return {
+            cached: true,
+            sizeBytes: sizeHeader ? parseInt(sizeHeader, 10) : 0,
+            cachedAt: cachedAtHeader ?? undefined,
+        };
+    }
+}
+class IndexedDBModelCache {
+    dbPromise = null;
+    openDB() {
+        if (this.dbPromise)
+            return this.dbPromise;
+        this.dbPromise = new Promise((resolve, reject) => {
+            const request = indexedDB.open(IDB_DB_NAME, IDB_VERSION);
+            request.onupgradeneeded = () => {
+                const db = request.result;
+                if (!db.objectStoreNames.contains(IDB_STORE_NAME)) {
+                    db.createObjectStore(IDB_STORE_NAME, { keyPath: "key" });
+                }
+            };
+            request.onsuccess = () => resolve(request.result);
+            request.onerror = () => reject(request.error);
+        });
+        return this.dbPromise;
+    }
+    async tx(mode) {
+        const db = await this.openDB();
+        const transaction = db.transaction(IDB_STORE_NAME, mode);
+        return transaction.objectStore(IDB_STORE_NAME);
+    }
+    async get(key) {
+        const store = await this.tx("readonly");
+        return new Promise((resolve, reject) => {
+            const request = store.get(key);
+            request.onsuccess = () => {
+                const entry = request.result;
+                resolve(entry?.data ?? null);
+            };
+            request.onerror = () => reject(request.error);
+        });
+    }
+    async put(key, data) {
+        const store = await this.tx("readwrite");
+        const entry = {
+            key,
+            data,
+            sizeBytes: data.byteLength,
+            cachedAt: new Date().toISOString(),
+        };
+        return new Promise((resolve, reject) => {
+            const request = store.put(entry);
+            request.onsuccess = () => resolve();
+            request.onerror = () => reject(request.error);
+        });
+    }
+    async has(key) {
+        const store = await this.tx("readonly");
+        return new Promise((resolve, reject) => {
+            const request = store.count(key);
+            request.onsuccess = () => resolve(request.result > 0);
+            request.onerror = () => reject(request.error);
+        });
+    }
+    async remove(key) {
+        const store = await this.tx("readwrite");
+        return new Promise((resolve, reject) => {
+            const request = store.delete(key);
+            request.onsuccess = () => resolve();
+            request.onerror = () => reject(request.error);
+        });
+    }
+    async info(key) {
+        const store = await this.tx("readonly");
+        return new Promise((resolve, reject) => {
+            const request = store.get(key);
+            request.onsuccess = () => {
+                const entry = request.result;
+                if (!entry) {
+                    resolve({ cached: false, sizeBytes: 0 });
+                }
+                else {
+                    resolve({
+                        cached: true,
+                        sizeBytes: entry.sizeBytes,
+                        cachedAt: entry.cachedAt,
+                    });
+                }
+            };
+            request.onerror = () => reject(request.error);
+        });
+    }
+}
+// ---------------------------------------------------------------------------
+// No-op implementation
+// ---------------------------------------------------------------------------
+class NoopModelCache {
+    async get(_key) {
+        return null;
+    }
+    async put(_key, _data) {
+        /* no-op */
+    }
+    async has(_key) {
+        return false;
+    }
+    async remove(_key) {
+        /* no-op */
+    }
+    async info(_key) {
+        return { cached: false, sizeBytes: 0 };
+    }
+}
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+/**
+ * Create a {@link ModelCache} instance for the given strategy.
+ *
+ * Falls back gracefully:
+ *  - `"cache-api"` — uses Cache API if available, else IndexedDB, else no-op.
+ *  - `"indexeddb"` — uses IndexedDB if available, else no-op.
+ *  - `"none"` — always no-op.
+ */
+export function createModelCache(strategy) {
+    if (strategy === "none") {
+        return new NoopModelCache();
+    }
+    if (strategy === "cache-api") {
+        if (typeof caches !== "undefined") {
+            return new CacheApiModelCache();
+        }
+        // Fallback to IndexedDB when Cache API is unavailable.
+        if (typeof indexedDB !== "undefined") {
+            return new IndexedDBModelCache();
+        }
+        return new NoopModelCache();
+    }
+    if (strategy === "indexeddb") {
+        if (typeof indexedDB !== "undefined") {
+            return new IndexedDBModelCache();
+        }
+        return new NoopModelCache();
+    }
+    throw new OctomilError("CACHE_ERROR", `Unknown cache strategy: ${strategy}`);
+}
+//# sourceMappingURL=cache.js.map

package/dist/cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.js","sourceRoot":"","sources":["../src/cache.ts"],"names":[],"mappings":"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"}

package/dist/device-auth.d.ts

@@ -0,0 +1,41 @@
+/**
+ * @octomil/browser — Device authentication manager
+ *
+ * Handles device registration, token bootstrap/refresh/revoke for
+ * authenticated model downloads and training round participation.
+ */
+import type { DeviceAuthConfig } from "./types.js";
+export declare class DeviceAuthManager {
+    private readonly serverUrl;
+    private readonly apiKey;
+    private token;
+    private deviceId;
+    private refreshTimer;
+    private disposed;
+    constructor(config: DeviceAuthConfig);
+    /** Register this device and obtain an initial auth token. */
+    bootstrap(orgId: string): Promise<void>;
+    /** Get a valid access token, refreshing if needed. */
+    getToken(): Promise<string>;
+    /** Refresh the current token. */
+    refreshToken(): Promise<void>;
+    /** Revoke the current token and clear local state. */
+    revokeToken(): Promise<void>;
+    /** Whether we currently hold a valid token. */
+    get isAuthenticated(): boolean;
+    /** Current device identifier. */
+    get currentDeviceId(): string | null;
+    /** Release timers. */
+    dispose(): void;
+    private request;
+    private isTokenExpired;
+    private isTokenExpiringSoon;
+    private scheduleRefresh;
+    private clearRefreshTimer;
+    private clearState;
+    /** Generate a stable device ID by hashing browser fingerprint data. */
+    generateDeviceId(): Promise<string>;
+    private collectDeviceInfo;
+    private ensureNotDisposed;
+}
+//# sourceMappingURL=device-auth.d.ts.map

package/dist/device-auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"device-auth.d.ts","sourceRoot":"","sources":["../src/device-auth.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EACV,gBAAgB,EAGjB,MAAM,YAAY,CAAC;AAYpB,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,KAAK,CAAgC;IAC7C,OAAO,CAAC,QAAQ,CAAuB;IACvC,OAAO,CAAC,YAAY,CAA8C;IAClE,OAAO,CAAC,QAAQ,CAAS;gBAEb,MAAM,EAAE,gBAAgB;IASpC,6DAA6D;IACvD,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAsC7C,sDAAsD;IAChD,QAAQ,IAAI,OAAO,CAAC,MAAM,CAAC;IAiBjC,iCAAiC;IAC3B,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC;IA0CnC,sDAAsD;IAChD,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC;IAkBlC,+CAA+C;IAC/C,IAAI,eAAe,IAAI,OAAO,CAE7B;IAED,iCAAiC;IACjC,IAAI,eAAe,IAAI,MAAM,GAAG,IAAI,CAEnC;IAED,sBAAsB;IACtB,OAAO,IAAI,IAAI;YAUD,OAAO;IAYrB,OAAO,CAAC,cAAc;IAKtB,OAAO,CAAC,mBAAmB;IAK3B,OAAO,CAAC,eAAe;IAavB,OAAO,CAAC,iBAAiB;IAOzB,OAAO,CAAC,UAAU;IAKlB,uEAAuE;IACjE,gBAAgB,IAAI,OAAO,CAAC,MAAM,CAAC;IAkBzC,OAAO,CAAC,iBAAiB;IAczB,OAAO,CAAC,iBAAiB;CAQ1B"}

package/dist/device-auth.js

@@ -0,0 +1,203 @@
+/**
+ * @octomil/browser — Device authentication manager
+ *
+ * Handles device registration, token bootstrap/refresh/revoke for
+ * authenticated model downloads and training round participation.
+ */
+import { OctomilError } from "./types.js";
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+const REFRESH_BUFFER_MS = 30_000; // refresh 30s before expiry
+// ---------------------------------------------------------------------------
+// DeviceAuthManager
+// ---------------------------------------------------------------------------
+export class DeviceAuthManager {
+    serverUrl;
+    apiKey;
+    token = null;
+    deviceId = null;
+    refreshTimer = null;
+    disposed = false;
+    constructor(config) {
+        this.serverUrl = config.serverUrl;
+        this.apiKey = config.apiKey;
+    }
+    // -----------------------------------------------------------------------
+    // Public
+    // -----------------------------------------------------------------------
+    /** Register this device and obtain an initial auth token. */
+    async bootstrap(orgId) {
+        this.ensureNotDisposed();
+        this.deviceId = await this.generateDeviceId();
+        const deviceInfo = this.collectDeviceInfo();
+        const response = await this.request("/api/v1/devices/register", {
+            method: "POST",
+            body: JSON.stringify({
+                org_id: orgId,
+                device_id: this.deviceId,
+                platform: "browser",
+                info: deviceInfo,
+            }),
+        });
+        if (!response.ok) {
+            throw new OctomilError("NETWORK_ERROR", `Device registration failed: HTTP ${response.status}`);
+        }
+        const data = (await response.json());
+        this.token = {
+            accessToken: data.token,
+            refreshToken: data.refresh_token,
+            expiresAt: new Date(data.expires_at).getTime(),
+        };
+        this.scheduleRefresh();
+    }
+    /** Get a valid access token, refreshing if needed. */
+    async getToken() {
+        this.ensureNotDisposed();
+        if (!this.token) {
+            throw new OctomilError("NETWORK_ERROR", "Not authenticated. Call bootstrap() first.");
+        }
+        if (this.isTokenExpiringSoon()) {
+            await this.refreshToken();
+        }
+        return this.token.accessToken;
+    }
+    /** Refresh the current token. */
+    async refreshToken() {
+        this.ensureNotDisposed();
+        if (!this.token) {
+            throw new OctomilError("NETWORK_ERROR", "No token to refresh. Call bootstrap() first.");
+        }
+        const response = await this.request("/api/v1/auth/refresh", {
+            method: "POST",
+            body: JSON.stringify({
+                refresh_token: this.token.refreshToken,
+                device_id: this.deviceId,
+            }),
+        });
+        if (!response.ok) {
+            // Token expired beyond repair — clear state
+            this.token = null;
+            throw new OctomilError("NETWORK_ERROR", `Token refresh failed: HTTP ${response.status}`);
+        }
+        const data = (await response.json());
+        this.token = {
+            accessToken: data.token,
+            refreshToken: data.refresh_token,
+            expiresAt: new Date(data.expires_at).getTime(),
+        };
+        this.scheduleRefresh();
+    }
+    /** Revoke the current token and clear local state. */
+    async revokeToken() {
+        this.ensureNotDisposed();
+        if (!this.token)
+            return;
+        try {
+            await this.request("/api/v1/auth/revoke", {
+                method: "POST",
+                body: JSON.stringify({
+                    token: this.token.accessToken,
+                    device_id: this.deviceId,
+                }),
+            });
+        }
+        finally {
+            this.clearState();
+        }
+    }
+    /** Whether we currently hold a valid token. */
+    get isAuthenticated() {
+        return this.token !== null && !this.isTokenExpired();
+    }
+    /** Current device identifier. */
+    get currentDeviceId() {
+        return this.deviceId;
+    }
+    /** Release timers. */
+    dispose() {
+        if (this.disposed)
+            return;
+        this.disposed = true;
+        this.clearRefreshTimer();
+    }
+    // -----------------------------------------------------------------------
+    // Internal
+    // -----------------------------------------------------------------------
+    async request(path, init) {
+        const headers = {
+            "Content-Type": "application/json",
+            Authorization: `Bearer ${this.apiKey}`,
+        };
+        return fetch(`${this.serverUrl}${path}`, {
+            ...init,
+            headers: { ...headers, ...init.headers },
+        });
+    }
+    isTokenExpired() {
+        if (!this.token)
+            return true;
+        return Date.now() >= this.token.expiresAt;
+    }
+    isTokenExpiringSoon() {
+        if (!this.token)
+            return true;
+        return Date.now() >= this.token.expiresAt - REFRESH_BUFFER_MS;
+    }
+    scheduleRefresh() {
+        this.clearRefreshTimer();
+        if (!this.token)
+            return;
+        const delay = Math.max(0, this.token.expiresAt - Date.now() - REFRESH_BUFFER_MS);
+        this.refreshTimer = setTimeout(() => {
+            void this.refreshToken().catch(() => {
+                // Best-effort auto-refresh; next getToken() call will retry.
+            });
+        }, delay);
+    }
+    clearRefreshTimer() {
+        if (this.refreshTimer !== null) {
+            clearTimeout(this.refreshTimer);
+            this.refreshTimer = null;
+        }
+    }
+    clearState() {
+        this.token = null;
+        this.clearRefreshTimer();
+    }
+    /** Generate a stable device ID by hashing browser fingerprint data. */
+    async generateDeviceId() {
+        const raw = [
+            typeof navigator !== "undefined" ? navigator.userAgent : "unknown",
+            typeof screen !== "undefined" ? `${screen.width}x${screen.height}` : "0x0",
+            typeof Intl !== "undefined"
+                ? Intl.DateTimeFormat().resolvedOptions().timeZone
+                : "UTC",
+            typeof navigator !== "undefined" ? navigator.language : "en",
+        ].join("|");
+        const data = new TextEncoder().encode(raw);
+        const hashBuffer = await crypto.subtle.digest("SHA-256", data);
+        const hashArray = new Uint8Array(hashBuffer);
+        return Array.from(hashArray)
+            .map((b) => b.toString(16).padStart(2, "0"))
+            .join("");
+    }
+    collectDeviceInfo() {
+        return {
+            userAgent: typeof navigator !== "undefined" ? navigator.userAgent : "unknown",
+            language: typeof navigator !== "undefined" ? navigator.language : "en",
+            screenWidth: typeof screen !== "undefined" ? screen.width : 0,
+            screenHeight: typeof screen !== "undefined" ? screen.height : 0,
+            timezone: typeof Intl !== "undefined"
+                ? Intl.DateTimeFormat().resolvedOptions().timeZone
+                : "UTC",
+            webgpu: typeof navigator !== "undefined" && "gpu" in navigator,
+        };
+    }
+    ensureNotDisposed() {
+        if (this.disposed) {
+            throw new OctomilError("SESSION_DISPOSED", "DeviceAuthManager has been disposed.");
+        }
+    }
+}
+//# sourceMappingURL=device-auth.js.map

package/dist/device-auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"device-auth.js","sourceRoot":"","sources":["../src/device-auth.ts"],"names":[],"mappings":"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"}

package/dist/experiments.d.ts

@@ -0,0 +1,44 @@
+/**
+ * @octomil/browser — A/B testing and experiments client
+ *
+ * Deterministic variant assignment, experiment config caching,
+ * and metric reporting for model experiments.
+ */
+import type { Experiment, ExperimentVariant, TelemetryEvent } from "./types.js";
+export declare class ExperimentsClient {
+    private readonly serverUrl;
+    private readonly apiKey?;
+    private readonly cacheTtlMs;
+    private readonly onTelemetry?;
+    private experimentsCache;
+    constructor(options: {
+        serverUrl: string;
+        apiKey?: string;
+        cacheTtlMs?: number;
+        onTelemetry?: (event: TelemetryEvent) => void;
+    });
+    /** Fetch all active experiments (cached). */
+    getActiveExperiments(): Promise<Experiment[]>;
+    /** Get full experiment config by ID. */
+    getExperimentConfig(experimentId: string): Promise<Experiment>;
+    /**
+     * Deterministic variant assignment.
+     * Hash(deviceId + experimentId) → bucket → variant by cumulative traffic %.
+     */
+    getVariant(experiment: Experiment, deviceId: string): ExperimentVariant | null;
+    /** Check if a device is enrolled in a specific experiment. */
+    isEnrolled(experiment: Experiment, deviceId: string): boolean;
+    /**
+     * Find which experiment (if any) affects a given model, and return
+     * the variant this device should use.
+     */
+    resolveModelExperiment(modelId: string, deviceId: string): Promise<{
+        experiment: Experiment;
+        variant: ExperimentVariant;
+    } | null>;
+    /** Report a metric for an experiment. */
+    trackMetric(experimentId: string, metricName: string, value: number, deviceId?: string): Promise<void>;
+    /** Clear the experiment cache. */
+    clearCache(): void;
+}
+//# sourceMappingURL=experiments.d.ts.map

package/dist/experiments.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"experiments.d.ts","sourceRoot":"","sources":["../src/experiments.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EACV,UAAU,EACV,iBAAiB,EACjB,cAAc,EACf,MAAM,YAAY,CAAC;AAOpB,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAkC;IAE/D,OAAO,CAAC,gBAAgB,CAGR;gBAEJ,OAAO,EAAE;QACnB,SAAS,EAAE,MAAM,CAAC;QAClB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,cAAc,KAAK,IAAI,CAAC;KAC/C;IAOD,6CAA6C;IACvC,oBAAoB,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC;IA4BnD,wCAAwC;IAClC,mBAAmB,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAgBpE;;;OAGG;IACH,UAAU,CAAC,UAAU,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,GAAG,iBAAiB,GAAG,IAAI;IAiB9E,8DAA8D;IAC9D,UAAU,CAAC,UAAU,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO;IAI7D;;;OAGG;IACG,sBAAsB,CAC1B,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC;QAAE,UAAU,EAAE,UAAU,CAAC;QAAC,OAAO,EAAE,iBAAiB,CAAA;KAAE,GAAG,IAAI,CAAC;IAczE,yCAAyC;IACnC,WAAW,CACf,YAAY,EAAE,MAAM,EACpB,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE,MAAM,EACb,QAAQ,CAAC,EAAE,MAAM,GAChB,OAAO,CAAC,IAAI,CAAC;IA0BhB,kCAAkC;IAClC,UAAU,IAAI,IAAI;CAGnB"}