/**
 * @octomil/browser — TypeScript type definitions
 *
 * All public interfaces and types for the browser inference SDK.
 */
import type { LocalResponsesRuntime, LocalResponsesRuntimeResolver } from "./responses-runtime.js";
export { AuthType } from "./_generated/auth_type.js";
export { PrincipalType } from "./_generated/principal_type.js";
export { Scope } from "./_generated/scope.js";
/**
 * Organization-scoped API key authentication.
 * Used by server-side SDKs, CLI tools, and CI/CD pipelines.
 */
export interface OrgApiKeyAuth {
    type: "org_api_key";
    apiKey: string;
    orgId: string;
    serverUrl?: string;
}
/**
 * Short-lived device token authentication.
 * Used by edge devices that go through a bootstrap/registration flow.
 */
export interface DeviceTokenAuth {
    type: "device_token";
    deviceId: string;
    bootstrapToken: string;
    serverUrl?: string;
}
/**
 * Discriminated union of supported authentication configurations.
 */
export type AuthConfig = OrgApiKeyAuth | DeviceTokenAuth;
/** Result returned by `control.refresh()`. */
export interface ControlSyncResult {
    updated: boolean;
    configVersion: string;
    assignmentsChanged: boolean;
    /** ISO-8601 timestamp of when the data was fetched. */
    fetchedAt: string;
}
/** Inference backend. `"webgpu"` is preferred; `"wasm"` is the universal fallback. */
export type Backend = "webgpu" | "wasm";
/** Model caching strategy. */
export type CacheStrategy = "cache-api" | "indexeddb" | "none";
/** Options for initialising an {@link OctomilClient} instance. */
export interface OctomilOptions {
    /**
     * Model identifier — either a full URL to an `.onnx` file or
     * a name resolvable via the Octomil model registry.
     */
    model: string;
    /**
     * Authentication configuration. Use `{ type: "org_api_key", ... }` for
     * API key auth or `{ type: "device_token", ... }` for device token auth.
     */
    auth?: AuthConfig;
    /**
     * Server URL derived from auth config. Set internally by the constructor.
     * @internal
     */
    serverUrl?: string;
    /**
     * API key or bootstrap token derived from auth config. Set internally.
     * @internal
     */
    apiKey?: string;
    /**
     * Inference backend.
     * - `"webgpu"` — uses WebGPU when available (fastest).
     * - `"wasm"`   — WASM SIMD fallback (universal).
     * - `undefined` — auto-detect (try WebGPU first, then WASM).
     */
    backend?: Backend;
    /**
     * Whether to report anonymous telemetry (latency, cache hits) to the
     * Octomil dashboard. Opt-in only.
     * @default false
     */
    telemetry?: boolean;
    /** Telemetry endpoint override. Only used when `telemetry` is `true`. */
    telemetryUrl?: string;
    /**
     * Model caching strategy.
     * @default "cache-api"
     */
    cacheStrategy?: CacheStrategy;
    /** Called during model download with progress information. */
    onProgress?: (progress: DownloadProgress) => void;
    /**
     * Routing configuration. When set, the SDK calls the routing API
     * before each inference to decide between on-device and cloud execution.
     * If omitted, all inference runs locally (current default behavior).
     */
    routing?: {
        /** Routing preference. @default "fastest" */
        prefer?: RoutingPreference;
        /** Cache TTL in milliseconds. @default 300_000 (5 minutes) */
        cacheTtlMs?: number;
        /** Number of model parameters (used by routing heuristics). */
        modelParams?: number;
        /** Model size in MB (used by routing heuristics). */
        modelSizeMb?: number;
    };
    /**
     * Optional local runtime used by `responses.create()` / `responses.stream()`.
     *
     * When provided, the browser SDK can execute the structured responses API
     * locally instead of requiring a server-backed chat completions endpoint.
     */
    responsesRuntime?: LocalResponsesRuntime | LocalResponsesRuntimeResolver;
}
/** Progress information emitted during model download. */
export interface DownloadProgress {
    /** Bytes received so far. */
    loaded: number;
    /** Total bytes (may be 0 if the server omits Content-Length). */
    total: number;
    /** Percentage 0–100 (NaN when total is unknown). */
    percent: number;
}
/**
 * Named tensor map. Keys are input tensor names, values are the data.
 * When a model has a single input you can pass the data directly.
 */
export type TensorData = Float32Array | Int32Array | BigInt64Array | Uint8Array;
export interface NamedTensors {
    [name: string]: {
        data: TensorData;
        dims: number[];
    };
}
/**
 * Predict input — either a named tensor map for explicit control,
 * or a convenience payload that the model adapter will pre-process.
 */
export type PredictInput = NamedTensors | {
    text: string;
} | {
    image: ImageData | HTMLCanvasElement | HTMLImageElement;
} | {
    raw: TensorData;
    dims: number[];
};
/** Result of a single inference call. */
export interface PredictOutput {
    /** Raw output tensors keyed by name. */
    tensors: NamedTensors;
    /** Top-level convenience fields (model-dependent). */
    label?: string;
    score?: number;
    scores?: number[];
    /** Inference wall-clock time in milliseconds. */
    latencyMs: number;
}
/** Role for a chat message. */
export type ChatRole = "system" | "user" | "assistant";
/** A single message in a chat conversation. */
export interface ChatMessage {
    role: ChatRole;
    content: string;
}
/** Response from the chat API. */
export interface ChatResponse {
    message: ChatMessage;
    /** Token-generation latency in milliseconds. */
    latencyMs: number;
    /** Usage stats when available. */
    usage?: {
        promptTokens: number;
        completionTokens: number;
        totalTokens: number;
    };
}
/** Information about the cached model. */
export interface CacheInfo {
    /** Whether the model is currently cached. */
    cached: boolean;
    /** Size in bytes (0 if not cached). */
    sizeBytes: number;
    /** ISO-8601 timestamp of when the model was cached. */
    cachedAt?: string;
}
/** A single telemetry event queued for delivery. */
export interface TelemetryEvent {
    name: string;
    timestamp: string;
    traceId?: string;
    spanId?: string;
    attributes: Record<string, string | number | boolean>;
}
/** Metadata returned by the Octomil model registry. */
export interface ModelMetadata {
    name?: string;
    version?: string;
    format?: "onnx";
    sizeBytes?: number;
    url?: string;
    download_url?: string;
    checksum?: string;
}
export interface DeviceAuthConfig {
    serverUrl: string;
    apiKey: string;
}
export interface DeviceAuthToken {
    accessToken: string;
    refreshToken: string;
    /** Epoch ms when the access token expires. */
    expiresAt: number;
}
export interface DeviceInfo {
    userAgent: string;
    language: string;
    screenWidth: number;
    screenHeight: number;
    timezone: string;
    webgpu: boolean;
}
export type StreamingModality = "text" | "image" | "audio" | "video";
export interface StreamingOptions {
    modality?: StreamingModality;
    signal?: AbortSignal;
    params?: Record<string, unknown>;
}
export interface StreamingChunk {
    index: number;
    data: unknown;
    modality: StreamingModality;
    done: boolean;
}
export interface StreamingResult {
    totalChunks: number;
    totalBytes: number;
    durationMs: number;
    ttfcMs: number;
    metrics?: InferenceMetrics;
}
export interface ChatOptions {
    temperature?: number;
    maxTokens?: number;
    topP?: number;
    stream?: boolean;
    signal?: AbortSignal;
}
export interface ChatChunk {
    index: number;
    content: string;
    done: boolean;
    role?: ChatRole;
}
/** A single token from the cloud streaming inference endpoint. */
export interface StreamToken {
    token: string;
    done: boolean;
    provider?: string;
    latencyMs?: number;
    sessionId?: string;
}
export type WeightMap = Record<string, Float32Array>;
export interface TrainingConfig {
    modelId?: string;
    epochs: number;
    batchSize: number;
    learningRate: number;
    /** User-provided training step — browser ONNX doesn't support training natively. */
    onTrainStep: (weights: WeightMap, params: {
        epoch: number;
        batchSize: number;
        learningRate: number;
    }) => Promise<TrainStepResult>;
}
export interface TrainStepResult {
    weights: WeightMap;
    loss?: number;
}
export interface FederatedRound {
    id: string;
    federationId: string;
    roundNumber: number;
    status: "pending" | "selecting" | "in_progress" | "aggregating" | "complete";
    modelVersion: string;
    config: Record<string, unknown>;
}
/** Cached gradient entry for offline/retry submission. */
export interface GradientCacheEntry {
    roundId: string;
    federationId: string;
    delta: Record<string, {
        data: number[];
        shape: number[];
    }>;
    metrics?: Record<string, number>;
    timestamp: number;
    submitted: boolean;
}
export interface ExperimentVariant {
    id: string;
    name: string;
    modelId: string;
    modelVersion: string;
    trafficPercentage: number;
}
export interface Experiment {
    id: string;
    name: string;
    status: "draft" | "active" | "paused" | "completed";
    variants: ExperimentVariant[];
    createdAt: string;
}
/** Device capability info sent to the routing API. */
export interface DeviceCapabilities {
    platform: "web";
    model: string;
    total_memory_mb: number;
    gpu_available: boolean;
    npu_available: boolean;
    supported_runtimes: string[];
}
/** Routing preference for execution target. */
export type RoutingPreference = "device" | "cloud" | "cheapest" | "fastest";
/** Request body for POST /api/v1/route. */
export interface RoutingRequest {
    model_id: string;
    model_params: number;
    model_size_mb: number;
    device_capabilities: DeviceCapabilities;
    prefer: RoutingPreference;
}
/** Fallback target returned by routing when cloud is primary. */
export interface RoutingFallbackTarget {
    endpoint: string;
    [key: string]: unknown;
}
/** Response from POST /api/v1/route. */
export interface RoutingDecision {
    id: string;
    target: "device" | "cloud";
    format: string;
    engine: string;
    fallback_target: RoutingFallbackTarget | null;
    /** `true` when loaded from persistent cache (server was unreachable). */
    cached?: boolean;
    /** `true` when this is a synthetic offline-default decision. */
    offline?: boolean;
}
/** Request body for POST /api/v1/inference. */
export interface CloudInferenceRequest {
    model_id: string;
    input_data: unknown;
    parameters: Record<string, unknown>;
}
/** Response from POST /api/v1/inference. */
export interface CloudInferenceResponse {
    output: unknown;
    latency_ms: number;
    provider: string;
}
/** Configuration for the routing client. */
export interface RoutingConfig {
    serverUrl: string;
    apiKey: string;
    /** Cache TTL in milliseconds. @default 300_000 (5 minutes) */
    cacheTtlMs?: number;
    /** Routing preference. @default "fastest" */
    prefer?: RoutingPreference;
}
/** Raw response from POST /api/v1/embeddings. */
export interface EmbeddingResponse {
    data: Array<{
        embedding: number[];
        index: number;
    }>;
    model: string;
    usage: {
        prompt_tokens: number;
        total_tokens: number;
    };
}
/** Parsed result returned by `embed()`. */
export interface EmbeddingResult {
    embeddings: number[][];
    model: string;
    usage: EmbeddingUsage;
}
/** Token usage statistics from the embeddings endpoint. */
export interface EmbeddingUsage {
    promptTokens: number;
    totalTokens: number;
}
import { ErrorCode, type ErrorCategory, type RetryClass, type SuggestedAction } from "./_generated/error_code.js";
export type { ErrorCategory, RetryClass, SuggestedAction, ErrorClassification, } from "./_generated/error_code.js";
/**
 * Canonical error codes — 36 codes from octomil-contracts.
 */
export type OctomilErrorCode = "INVALID_API_KEY" | "AUTHENTICATION_FAILED" | "FORBIDDEN" | "DEVICE_NOT_REGISTERED" | "TOKEN_EXPIRED" | "DEVICE_REVOKED" | "CLOUD_CREDENTIALS_MISSING" | "CLOUD_CREDENTIALS_REVOKED" | "CLOUD_PROVIDER_AUTH_FAILED" | "NETWORK_UNAVAILABLE" | "REQUEST_TIMEOUT" | "SERVER_ERROR" | "RATE_LIMITED" | "INVALID_INPUT" | "UNSUPPORTED_MODALITY" | "CONTEXT_TOO_LARGE" | "MODEL_NOT_FOUND" | "MODEL_LOAD_FAILED" | "MODEL_DISABLED" | "VERSION_NOT_FOUND" | "DOWNLOAD_FAILED" | "CHECKSUM_MISMATCH" | "INSUFFICIENT_STORAGE" | "INSUFFICIENT_MEMORY" | "RUNTIME_UNAVAILABLE" | "ACCELERATOR_UNAVAILABLE" | "INFERENCE_FAILED" | "STREAM_INTERRUPTED" | "POLICY_DENIED" | "CLOUD_FALLBACK_DISALLOWED" | "MAX_TOOL_ROUNDS_EXCEEDED" | "TRAINING_FAILED" | "TRAINING_NOT_SUPPORTED" | "WEIGHT_UPLOAD_FAILED" | "CONTROL_SYNC_FAILED" | "ASSIGNMENT_NOT_FOUND" | "CANCELLED" | "APP_BACKGROUNDED" | "UNKNOWN";
/**
 * Map from contract `ErrorCode` enum values (snake_case) to the SDK's
 * `OctomilErrorCode` string union (UPPER_SNAKE_CASE).
 *
 * Every canonical code defined in octomil-contracts is explicitly referenced
 * here to ensure contract parity.
 */
export declare const ERROR_CODE_MAP: Readonly<Record<ErrorCode, OctomilErrorCode>>;
/** Structured error thrown by the SDK. */
export declare class OctomilError extends Error {
    readonly code: OctomilErrorCode;
    readonly cause?: unknown;
    constructor(code: OctomilErrorCode, message: string, cause?: unknown);
    /** Whether this error represents a transient failure that can be retried. */
    get retryable(): boolean;
    /** The error category from the contract taxonomy. */
    get category(): ErrorCategory | undefined;
    /** The retry classification from the contract taxonomy. */
    get retryClass(): RetryClass | undefined;
    /** Whether this error is eligible for cloud fallback. */
    get fallbackEligible(): boolean;
    /** The suggested remediation action. */
    get suggestedAction(): SuggestedAction | undefined;
    /**
     * Create an `OctomilError` from a contract `ErrorCode` enum value.
     *
     * Maps the snake_case canonical code to the SDK's UPPER_SNAKE_CASE code.
     */
    static fromErrorCode(errorCode: ErrorCode, message: string, cause?: unknown): OctomilError;
    /**
     * Create an `OctomilError` from an HTTP status code.
     *
     * Maps common HTTP statuses to the appropriate canonical error code.
     */
    static fromHttpStatus(status: number, message?: string): OctomilError;
    /**
     * Create an `OctomilError` from a server error response body.
     *
     * Extracts the `code` field from the JSON body and maps it to the SDK's
     * error code enum. Falls back to HTTP status mapping when the `code` field
     * is absent or unrecognized.
     */
    static fromServerResponse(status: number, body: Record<string, unknown> | null): OctomilError;
}
export interface BenchmarkResult {
    engine_name: string;
    tokens_per_second: number;
    ttft_ms: number;
    memory_mb: number;
    error?: string;
    metadata?: Record<string, string>;
}
export interface DetectionResult {
    engine: string;
    available: boolean;
    info: string;
}
export interface RankedEngine {
    engine: string;
    result: BenchmarkResult;
}
export interface InferenceMetrics {
    ttfc_ms: number;
    prompt_tokens: number;
    total_tokens: number;
    tokens_per_second: number;
    total_duration_ms: number;
    cache_hit: boolean;
    attention_backend?: string;
}
export interface GenerationChunk {
    text: string;
    token_count: number;
    tokens_per_second: number;
    finish_reason?: string;
}
export interface CacheStats {
    hits: number;
    misses: number;
    hit_rate: number;
    entries: number;
    memory_mb: number;
}
/** Filter criteria for analytics queries. */
export interface AnalyticsFilter {
    startTime?: string;
    endTime?: string;
    devicePlatform?: string;
    minSampleCount?: number;
}
/** Descriptive statistics for a single group. */
export interface GroupStats {
    groupId: string;
    count: number;
    mean: number;
    median?: number;
    stdDev?: number;
    min?: number;
    max?: number;
    percentiles?: Record<string, number>;
}
/** Result of a descriptive statistics query. */
export interface DescriptiveResult {
    variable: string;
    groupBy: string;
    groups: GroupStats[];
}
/** Confidence interval for a statistical test. */
export interface ConfidenceInterval {
    lower: number;
    upper: number;
    level: number;
}
/** Result of a two-sample t-test. */
export interface TTestResult {
    variable: string;
    groupA: string;
    groupB: string;
    tStatistic: number;
    pValue: number;
    degreesOfFreedom: number;
    confidenceInterval?: ConfidenceInterval;
    significant: boolean;
}
/** Result of a chi-square test of independence. */
export interface ChiSquareResult {
    variable1: string;
    variable2: string;
    chiSquareStatistic: number;
    pValue: number;
    degreesOfFreedom: number;
    significant: boolean;
    cramersV?: number;
}
/** Post-hoc pairwise comparison result. */
export interface PostHocPair {
    groupA: string;
    groupB: string;
    pValue: number;
    significant: boolean;
}
/** Result of a one-way ANOVA test. */
export interface AnovaResult {
    variable: string;
    groupBy: string;
    fStatistic: number;
    pValue: number;
    degreesOfFreedomBetween: number;
    degreesOfFreedomWithin: number;
    significant: boolean;
    postHocPairs?: PostHocPair[];
}
/** A saved analytics query with its result. */
export interface AnalyticsQuery {
    id: string;
    federationId: string;
    queryType: string;
    variable: string;
    groupBy: string;
    status: string;
    result?: Record<string, unknown>;
    errorMessage?: string;
    createdAt: string;
    updatedAt: string;
}
/** Response for listing analytics queries. */
export interface AnalyticsQueryListResponse {
    queries: AnalyticsQuery[];
    total: number;
}
//# sourceMappingURL=types.d.ts.map