/**
 * @octomil/browser — Browser attempt runner
 *
 * A lightweight, tree-shakeable attempt runner for the browser SDK.
 * Evaluates candidate plans and selects a route for inference.
 *
 * Browser execution modes:
 * - `sdk_runtime`       — TRUE in-browser execution via WebGPU or WASM
 *                         (ONNX Runtime Web / Transformers.js)
 * - `external_endpoint` — Explicitly configured outside-the-browser local server
 *                         (e.g. user's `octomil serve` on localhost)
 * - `hosted_gateway`    — Cloud execution via Octomil server
 *
 * Local fallback chain:
 *   WebGPU candidate → WASM candidate (both sdk_runtime, both local)
 *   → cloud (only when policy allows)
 *
 * Attempt stages: policy, prepare, download, verify, load, benchmark, gate, inference
 * Attempt statuses: skipped, failed, selected
 * Gate result statuses: passed, failed, unknown, not_required
 */
export type Locality = "local" | "cloud";
export type Mode = "sdk_runtime" | "hosted_gateway" | "external_endpoint";
export type AttemptStage = "policy" | "prepare" | "download" | "verify" | "load" | "benchmark" | "gate" | "inference" | "output_quality";
export type AttemptStatus = "skipped" | "failed" | "selected";
export type GateStatus = "passed" | "failed" | "unknown" | "not_required";
export type GateCode = "artifact_verified" | "runtime_available" | "model_loads" | "context_fits" | "modality_supported" | "tool_support" | "min_tokens_per_second" | "max_ttft_ms" | "max_error_rate" | "min_free_memory_bytes" | "min_free_storage_bytes" | "benchmark_fresh" | "min_battery_pct" | "max_thermal_state" | "require_charging" | "require_wifi" | "schema_valid" | "tool_call_valid" | "safety_passed" | "evaluator_score_min" | "json_parseable" | "max_refusal_rate";
export type GateClass = "readiness" | "performance" | "output_quality";
export type EvaluationPhase = "pre_inference" | "during_inference" | "post_inference";
export interface GateResult {
    code: string;
    status: GateStatus;
    observed_number?: number;
    threshold_number?: number;
    reason_code?: string | null;
    gate_class: GateClass;
    evaluation_phase: EvaluationPhase;
    required?: boolean;
    fallback_eligible?: boolean;
    observed_string?: string;
    safe_metadata?: Record<string, unknown>;
}
export interface RouteAttempt {
    index: number;
    locality: Locality;
    mode: Mode;
    engine: string | null;
    artifact: AttemptArtifact | null;
    status: AttemptStatus;
    stage: AttemptStage;
    gate_results: GateResult[];
    reason: {
        code: string;
        message: string;
    };
}
export interface AttemptArtifact {
    id: string | null;
    digest: string | null;
    cache: {
        status: ArtifactCacheStatus;
        managed_by: string;
    };
}
export type ArtifactCacheStatus = "hit" | "miss" | "downloaded" | "not_applicable" | "unavailable";
export interface FallbackTrigger {
    code: string;
    stage: string;
    message: string;
    gate_code?: string;
    gate_class?: GateClass;
    evaluation_phase?: EvaluationPhase;
    candidate_index?: number;
    output_visible_before_failure?: boolean;
}
export interface AttemptLoopResult<T = unknown> {
    selectedAttempt: RouteAttempt | null;
    attempts: RouteAttempt[];
    fallbackUsed: boolean;
    fallbackTrigger: FallbackTrigger | null;
    fromAttempt: number | null;
    toAttempt: number | null;
    value?: T;
    error?: unknown;
}
export interface CandidateGate {
    code: string;
    required: boolean;
    threshold_number?: number;
    threshold_string?: string;
    window_seconds?: number;
    source: "server" | "sdk" | "runtime";
    gate_class?: GateClass;
    evaluation_phase?: EvaluationPhase;
    fallback_eligible?: boolean;
    blocking_default?: boolean;
}
export interface CandidatePlan {
    locality: Locality;
    engine?: string;
    /** For sdk_runtime: preferred execution provider ("webgpu" | "wasm") */
    executionProvider?: "webgpu" | "wasm";
    /** Artifact info from planner for local candidates */
    artifact?: {
        artifact_id?: string;
        digest?: string;
        download_url?: string;
        size_bytes?: number;
        format?: string;
    };
    gates?: CandidateGate[];
    priority: number;
}
/**
 * Maps gate codes to their default class, evaluation phase, and blocking default.
 * Used to infer gate_class and evaluation_phase when not provided by the server.
 */
export declare const GATE_CLASSIFICATION: Record<string, {
    gate_class: GateClass;
    evaluation_phase: EvaluationPhase;
    blocking_default: boolean;
}>;
/**
 * Classify a gate code. Returns default classification for unknown codes.
 */
export declare function classifyGate(code: string): {
    gate_class: GateClass;
    evaluation_phase: EvaluationPhase;
    blocking_default: boolean;
};
export declare function completeGateResult(result: Omit<GateResult, "gate_class" | "evaluation_phase"> & Partial<Pick<GateResult, "gate_class" | "evaluation_phase">>): GateResult;
/**
 * Pluggable interface for post-inference output quality evaluation.
 * Evaluators run in the browser process — no content is uploaded.
 */
export interface OutputQualityEvaluator {
    name: string;
    evaluate(input: {
        request: unknown;
        response: unknown;
        gate: CandidateGate;
    }): Promise<{
        passed: boolean;
        score?: number;
        reason_code?: string;
        safe_metadata?: Record<string, unknown>;
    }>;
}
/**
 * Pluggable interface for checking whether an in-browser runtime is available.
 * Implementations probe WebGPU/WASM capabilities and report availability.
 */
export interface RuntimeChecker {
    /**
     * Check if a specific execution provider is available in this browser.
     * @param provider - "webgpu" or "wasm"
     * @returns availability + reason code on failure
     */
    checkProvider(provider: "webgpu" | "wasm"): Promise<{
        available: boolean;
        reasonCode?: string;
    }>;
    /**
     * Check if the runtime engine (e.g. onnxruntime-web) can be loaded.
     */
    checkEngineAvailable(engine?: string): Promise<{
        available: boolean;
        reasonCode?: string;
    }>;
}
/**
 * Pluggable interface for checking artifact cache state.
 * Implementations must not silently download artifacts as part of the check.
 */
export interface ArtifactChecker {
    /**
     * Check if the artifact is cached and ready for use.
     */
    check(artifact: CandidatePlan["artifact"]): Promise<{
        available: boolean;
        cacheStatus: ArtifactCacheStatus;
        reasonCode?: string;
    }>;
}
/**
 * Pluggable interface for checking whether an external endpoint is reachable.
 * Inject a custom implementation to customize health-check behaviour
 * (e.g. timeout, retry, custom path).
 */
export interface EndpointChecker {
    /** Check if an external endpoint is reachable. */
    check(endpoint: string): Promise<{
        available: boolean;
        reasonCode?: string;
    }>;
}
/**
 * Evaluates a list of candidate plans and selects the first viable route.
 *
 * The browser attempt runner supports three execution modes:
 *
 * 1. `sdk_runtime` — True in-browser execution via WebGPU or WASM.
 *    The runner probes the execution provider, checks artifact availability,
 *    and evaluates gates before selecting. Falls back from WebGPU to WASM
 *    locally before considering cloud.
 *
 * 2. `external_endpoint` — An explicitly configured outside-the-browser
 *    local server (e.g. `octomil serve` on localhost). Only used when a
 *    `localEndpoint` URL is provided.
 *
 * 3. `hosted_gateway` — Cloud inference via Octomil's hosted API.
 *
 * When a candidate fails and `fallbackAllowed` is true, the runner moves to
 * the next candidate and records a fallback trigger.
 */
export declare class BrowserAttemptRunner {
    private readonly fallbackAllowed;
    private readonly streaming;
    private readonly localEndpoint;
    private readonly endpointChecker;
    private readonly runtimeChecker;
    private readonly artifactChecker;
    private readonly outputQualityEvaluator;
    constructor(opts?: {
        fallbackAllowed?: boolean;
        streaming?: boolean;
        localEndpoint?: string | null;
        endpointChecker?: EndpointChecker | null;
        runtimeChecker?: RuntimeChecker | null;
        artifactChecker?: ArtifactChecker | null;
        outputQualityEvaluator?: OutputQualityEvaluator | null;
    });
    shouldFallbackAfterInferenceError(firstOutputEmitted?: boolean): boolean;
    /**
     * Run the attempt loop over the given candidates in priority order.
     *
     * Returns the first selected attempt (if any), all attempted candidates,
     * and fallback metadata.
     */
    run(candidates: CandidatePlan[]): Promise<AttemptLoopResult>;
    runWithInference<T>(candidates: CandidatePlan[], executeCandidate: (candidate: CandidatePlan, attempt: RouteAttempt) => Promise<T> | T, opts?: {
        firstOutputEmitted?: () => boolean;
    }): Promise<AttemptLoopResult<T>>;
    /** Engines that run IN the browser (WebGPU/WASM). */
    private static readonly BROWSER_ENGINES;
    /**
     * Artifact formats that CAN run in the browser.
     *
     * CAVEAT: "safetensors" is ambiguous — it is used by both Transformers.js
     * (browser-safe) and PyTorch/HuggingFace server-side checkpoints (NOT
     * browser-safe). A safetensors artifact is only trusted when paired with
     * a known browser engine (BROWSER_ENGINES). Gate 0 in evaluateSdkRuntime
     * enforces this: if the engine is not in BROWSER_ENGINES, the candidate
     * is rejected regardless of artifact format.
     */
    private static readonly BROWSER_ARTIFACT_FORMATS;
    /**
     * A candidate is an sdk_runtime candidate when:
     * - It has an explicit `executionProvider` ("webgpu" | "wasm"), OR
     * - It has a browser-native engine name (onnx-web, transformers.js), OR
     * - It has no engine but declares a browser-safe artifact format, AND
     *   does NOT have a `localEndpoint` (those are external_endpoint).
     *
     * Server-side engines (mlx-lm, llama.cpp, coreml, etc.) are NOT sdk_runtime —
     * they should fail with a clear error in evaluateSdkRuntime's Gate 0.
     *
     * A candidate with an unknown engine that is NOT in BROWSER_ENGINES is
     * classified as sdk_runtime so it enters evaluateSdkRuntime where Gate 0
     * rejects it with a clear `unsupported_artifact_target` error.
     */
    private isSdkRuntimeCandidate;
    /**
     * Build a failed RouteAttempt for use in gate rejection helpers.
     */
    private failAttempt;
    private evaluateSdkRuntime;
    private evaluateDeviceEnvironmentGate;
    private evaluateOutputQualityGates;
    private evaluateExternalEndpoint;
}
//# sourceMappingURL=attempt-runner.d.ts.map