roborama 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,822 @@
+/**
+ * Types for every documented request/response shape.
+ *
+ * Field names stay snake_case on both sides of the wire (`max_budget_usd`,
+ * `success_rate`, `ci95`), so examples translate between the docs tabs one
+ * field at a time.
+ */
+/** `auto(ci=0.95, moe=0.03)` sizes n for a target margin of error (Wilson). */
+type AutoEpisodesSpec = `auto(${string})`;
+/** A positive episode count, or an `auto(ci=..., moe=...)` sizing spec. */
+type EpisodesSpec = number | AutoEpisodesSpec;
+type Priority = "burst" | "standard" | "soak";
+type Interventions = "none" | "on_stall" | "scripted";
+type RunKind = "run" | "eval" | "verify" | "matrix" | "threshold" | "compare" | "transfer";
+type RunStatus = "queued" | "scheduling" | "running" | "completed" | "failed" | "stopped";
+type ExportFormat = "lerobot" | "rlds" | "mcap-bundle";
+/** A container image we run in-facility, GPU-adjacent. */
+interface ContainerPolicy {
+    type: "container";
+    image: string;
+    action_space: string;
+    observation_contract: string;
+}
+/** A checkpoint on a known runtime (`openpi`, `lerobot`). */
+interface CheckpointPolicy {
+    type: "checkpoint";
+    hf: string;
+    runtime: "openpi" | "lerobot" | (string & {});
+    /** Inference/decoding parameters, pinned and recorded. */
+    inference?: {
+        action_horizon?: number;
+        chunk_size?: number;
+        temp?: number;
+    };
+    action_space?: string;
+    observation_contract?: string;
+}
+/** Customer-hosted inference; measured RTT is logged per step. */
+interface EndpointPolicy {
+    type: "endpoint";
+    url: string;
+    latency_budget_ms?: number;
+    fallback?: "halt" | "teleop";
+}
+type Policy$1 = ContainerPolicy | CheckpointPolicy | EndpointPolicy;
+/** Accepts SDK-built and hand-written (including `as const`) policy objects. */
+type PolicyInput = Policy$1 | (Readonly<ContainerPolicy> & {
+    readonly type: "container";
+}) | (Readonly<CheckpointPolicy> & {
+    readonly type: "checkpoint";
+}) | (Readonly<EndpointPolicy> & {
+    readonly type: "endpoint";
+});
+/** For `threshold`: a webhook that receives checkpoint pushes. */
+interface PolicyStream {
+    webhook: string;
+}
+/** Seeded, versioned, replayable perturbation schedule. */
+interface Perturbation {
+    layout_jitter_mm?: number;
+    lighting?: readonly string[];
+    distractors?: string;
+    seed?: number;
+}
+/** Customer IP posture, explicit per run. */
+interface DataPosture {
+    retention?: string;
+    train_on_failures?: boolean;
+}
+interface RunCreateBase {
+    priority?: Priority;
+    max_budget_usd?: number;
+    perturbation?: Perturbation;
+    data?: DataPosture;
+    interventions?: Interventions;
+    /** Test-mode pacing control (e.g. `{ speed: 100 }`); ignored outside sandbox. */
+    sandbox?: {
+        speed?: number;
+    };
+}
+/** `kind: "run"` (the default): one policy, one robot, one task. */
+interface CreateRunParams extends RunCreateBase {
+    kind?: "run";
+    robot: string;
+    environment: string;
+    task: string;
+    policy?: PolicyInput;
+    episodes?: EpisodesSpec;
+}
+/** `kind: "eval"`: a frozen, versioned suite with a citable attestation. */
+interface CreateEvalParams extends RunCreateBase {
+    kind: "eval";
+    policy: PolicyInput;
+    suite: string;
+    robots: readonly string[];
+    publish?: "private" | "leaderboard";
+}
+/** `kind: "verify"`: physically verify sim-flagged scenarios. */
+interface CreateVerifyParams extends RunCreateBase {
+    kind: "verify";
+    policy: PolicyInput;
+    scenarios: unknown;
+    robots: readonly string[];
+    task?: string;
+    audit_sample?: number;
+    return_ground_truth?: boolean;
+}
+/** `kind: "matrix"`: the embodiment × environment sweep. */
+interface CreateMatrixParams extends RunCreateBase {
+    kind: "matrix";
+    policy: PolicyInput;
+    robots: readonly string[];
+    environments: readonly string[];
+    task: string;
+    episodes_per_cell?: EpisodesSpec;
+}
+/** `kind: "threshold"`: an outcome contract — push checkpoints, get verdicts. */
+interface CreateThresholdParams extends RunCreateBase {
+    kind: "threshold";
+    policy_stream: PolicyStream;
+    target: {
+        success_rate: number;
+        ci: number;
+        task: string;
+    };
+    iterate_on: string;
+    escalate_to: string;
+    monthly_cap_usd?: number;
+    on_verified?: {
+        webhook: string;
+    };
+}
+/** `kind: "compare"`: paired A/B on the same initial conditions. */
+interface CreateCompareParams extends RunCreateBase {
+    kind: "compare";
+    policies: Record<string, PolicyInput>;
+    paired?: boolean;
+    robot: string;
+    task: string;
+}
+/** `kind: "transfer"`: quantify the embodiment transfer gap. */
+interface CreateTransferParams extends RunCreateBase {
+    kind: "transfer";
+    policy: PolicyInput;
+    source: string;
+    target: string;
+    task: string;
+}
+type RunCreateParams = CreateRunParams | CreateEvalParams | CreateVerifyParams | CreateMatrixParams | CreateThresholdParams | CreateCompareParams | CreateTransferParams;
+interface StageRate {
+    stage: string;
+    n: number;
+    success_rate: number;
+    ci95: [number, number];
+}
+interface InstructionRate {
+    instruction: string;
+    held_out: boolean;
+    n: number;
+    success_rate: number;
+    ci95: [number, number];
+}
+/** Every result carries `n` and a Wilson confidence interval, by construction. */
+interface Result {
+    n: number;
+    success_rate: number;
+    ci95: [number, number];
+    interval_method?: "wilson";
+    failure_clusters?: Record<string, number>;
+    robot_hours?: number;
+    environment_hours?: number;
+    cost_usd?: number;
+    artifacts?: {
+        mcap?: string;
+        video?: string;
+        ground_truth?: string;
+        report_pdf?: string;
+    };
+    stage_rates?: StageRate[];
+    instruction_breakdown?: InstructionRate[];
+    interventions?: {
+        declared?: Interventions;
+        count?: number;
+        timestamps?: string[];
+    };
+}
+/** The wire form of a run object (`GET /v1/runs/{id}`), plus kind extras. */
+interface RunData {
+    id: string;
+    object: "run";
+    kind: RunKind;
+    status: RunStatus;
+    created?: string;
+    completed?: string;
+    robot?: string;
+    robots?: string[];
+    environment?: string;
+    environments?: string[];
+    task?: string;
+    suite?: string;
+    policy?: Policy$1;
+    policies?: Record<string, Policy$1>;
+    episodes?: EpisodesSpec;
+    episodes_per_cell?: EpisodesSpec;
+    priority?: Priority;
+    perturbation?: Perturbation;
+    data?: DataPosture;
+    max_budget_usd?: number;
+    resolved_pins?: Record<string, string>;
+    result?: Result;
+    [extra: string]: unknown;
+}
+interface Episode {
+    id: string;
+    object?: "episode";
+    index: number;
+    outcome: "success" | "failure" | "estop";
+    cluster?: string;
+    duration_s?: number;
+    video_url?: string;
+    mcap_url?: string;
+    replay_spec?: Record<string, unknown>;
+}
+/** The deployment verification report — conformance evidence, citable. */
+interface Report {
+    object?: "report";
+    run_id: string;
+    kind?: "verification";
+    result?: Result;
+    resolved_pins?: Record<string, string>;
+    citation?: string;
+    pdf_url?: string;
+    /** Alias of `pdf_url` — the downloadable report. */
+    url?: string;
+}
+interface Export {
+    object?: "export";
+    id: string;
+    run_id?: string;
+    format?: ExportFormat | string;
+    status: "preparing" | "ready" | "expired";
+    download_url?: string | null;
+}
+/** A live run event: episode ticker or status transition. */
+interface WatchEvent {
+    status: string;
+    episode?: number;
+    of?: number;
+    outcome?: string;
+    duration_s?: number;
+    cell?: string;
+    webrtc?: string;
+}
+interface Robot {
+    id: string;
+    class?: string;
+    dof?: number;
+    hands?: string;
+    firmwares?: string[];
+    cells?: number;
+    duty_cycle_pct?: number;
+    tier?: "soak" | "verify";
+}
+interface Environment {
+    id: string;
+    rev?: string;
+    class?: string;
+    instrumentation?: string[];
+    objects?: number;
+    reset?: "scripted" | "teleop-assisted";
+    adder_tier?: "bare" | "standard" | "replica" | "instrumented-replica";
+}
+interface Suite {
+    id: string;
+    rev?: string;
+    frozen?: string;
+    scoring?: string;
+    episodes_per_task?: number;
+    tasks?: string[];
+    environments?: string[];
+    [extra: string]: unknown;
+}
+interface QuoteParams {
+    robot: string;
+    environment: string;
+    episodes: EpisodesSpec;
+    priority?: Priority;
+}
+interface Quote {
+    object?: "quote";
+    robot?: string;
+    environment?: string;
+    episodes?: EpisodesSpec;
+    priority?: string;
+    robot_hours: number;
+    env_hours: number;
+    usd: number;
+    queue_eta: string;
+    breakdown?: {
+        minutes_per_episode_est?: number;
+        robot_usd_per_hour?: number;
+        env_usd_per_hour?: number;
+        robot_usd?: number;
+        env_usd?: number;
+    };
+    expires?: string;
+}
+interface GateCreateParams {
+    on: string;
+    suite: string;
+    robots: readonly string[];
+    fail_if: {
+        success_rate_drop_pts?: number;
+        new_collision?: boolean;
+    };
+}
+interface Gate extends GateCreateParams {
+    object?: "gate";
+    id: string;
+    status: "active" | "paused";
+    robots: string[];
+}
+interface Stream {
+    object?: "stream";
+    cell: string;
+    run?: string;
+    episode?: number;
+    of?: number;
+    webrtc?: string;
+    mjpeg?: string;
+    viewer_token?: string;
+    expires?: string;
+}
+interface Budget {
+    monthly_usd: number;
+    hard?: boolean;
+    remaining_usd?: number;
+}
+interface Usage {
+    object?: "usage";
+    period: string;
+    robot_hours: Record<string, number>;
+    env_hours: Record<string, number>;
+    usd_total?: number;
+    budget?: Budget;
+}
+type KeyScope = "runs:read" | "runs:write" | "streams:read" | "data:purge" | "keys:admin" | "calibration:export";
+interface Key {
+    object?: "key";
+    id: string;
+    scope: KeyScope[];
+    /** `rbr_live_` prefix; shown once at creation, never again. */
+    secret?: string;
+    created?: string;
+}
+interface PurgeReceipt {
+    object?: "purge_receipt";
+    id: string;
+    run_id: string;
+    status: "completed";
+    purged_at?: string;
+}
+interface CalibrationExportParams {
+    embodiment: string;
+    scenes: readonly string[];
+    channels: readonly ("gt/object_poses" | "commanded_vs_executed" | "contact_events")[];
+    /** Scoped: validation use, no policy training. */
+    license: "sim-calibration-v1";
+}
+interface TaskCreateParams {
+    name: string;
+    visibility?: "private" | "published";
+    initial_conditions: Record<string, unknown>;
+    success_predicates: readonly Record<string, string>[];
+    instructions?: {
+        sampled_per_episode?: readonly string[];
+        held_out?: readonly string[];
+    };
+    stages?: readonly Record<string, string>[];
+    envelope?: Record<string, unknown>;
+    baseline?: {
+        internal_trials?: number;
+        internal_rate?: number;
+    };
+}
+interface TaskData {
+    id: string;
+    object?: "task";
+    name: string;
+    rev: string | null;
+    status: "draft" | "piloting" | "frozen";
+    visibility: "private" | "published";
+    created?: string;
+    frozen?: string | null;
+    signatures?: string[];
+    initial_conditions?: Record<string, unknown>;
+    success_predicates?: Record<string, string>[];
+    instructions?: Record<string, unknown>;
+    stages?: Record<string, string>[];
+    envelope?: Record<string, unknown>;
+    pilot?: Record<string, unknown> | null;
+    [extra: string]: unknown;
+}
+interface Pilot {
+    run_id: string;
+    robot?: string;
+    episodes?: number;
+    /** Live WebRTC stream — watch the calibration session. */
+    stream_url: string;
+}
+interface KitCreateParams {
+    name: string;
+    items: readonly {
+        desc: string;
+        qty: number;
+    }[];
+}
+interface KitData {
+    id: string;
+    object?: "kit";
+    name: string;
+    /** `registered → received → tracked → available` (as `kit/<name>`). */
+    status: "registered" | "received" | "tracked" | "available";
+    status_history?: {
+        status: string;
+        at: string;
+    }[];
+    items?: {
+        desc: string;
+        qty: number;
+    }[];
+    tracking?: {
+        mocap_markers?: number;
+        mass_g?: number;
+        mesh_scan?: boolean;
+    } | null;
+    environment_ref?: string | null;
+    shipping_label_url?: string;
+}
+interface TransferSide {
+    robot: string;
+    n: number;
+    success_rate: number;
+    ci95: [number, number];
+}
+interface TransferReport {
+    object?: "transfer";
+    task: string;
+    interval_method?: "wilson";
+    source: TransferSide;
+    target: TransferSide;
+    delta_pts: number;
+    new_failure_clusters: string[];
+}
+interface MatrixCell {
+    robot: string;
+    environment: string;
+    n: number;
+    success_rate: number;
+    ci95: [number, number];
+    status: "pass" | "fail";
+}
+/** Embodiment × environment grid of rate ± CI per cell. */
+type Heatmap = Record<string, Record<string, {
+    n: number;
+    success_rate: number;
+    ci95: [number, number];
+    status: string;
+}>>;
+interface MatrixRegression {
+    robot: string;
+    environment: string;
+    delta_pts: number;
+    note?: string;
+}
+/** A matrix result: overall stats plus the grid and per-stage breakdowns. */
+interface MatrixResult extends Result {
+    heatmap: Heatmap;
+    cells: MatrixCell[];
+}
+/** The documented error envelope (`{"error": {code, message, ...}}`). */
+type ErrorCode = "invalid_api_key" | "insufficient_scope" | "not_found" | "contract_validation_failed" | "firmware_pin_unavailable" | "environment_unavailable" | "task_unknown" | "scenario_format_invalid" | "episodes_invalid" | "budget_exceeded" | "monthly_budget_exceeded" | "quote_expired" | "queue_timeout" | "policy_endpoint_timeout" | "estop_triggered" | "retention_expired" | "publish_forbidden" | "rate_limited" | (string & {});
+interface ErrorEnvelope {
+    error: {
+        code: ErrorCode;
+        message: string;
+        run_id?: string;
+        doc_url?: string;
+        partial_result?: Result;
+    };
+}
+/** Options for the client constructor. */
+interface RoboramaOptions {
+    /** Overrides `ROBORAMA_API_KEY`. Keys carry the `rbr_live_` prefix. */
+    apiKey?: string;
+    /** Overrides `ROBORAMA_BASE_URL` / the documented default. */
+    baseUrl?: string;
+    /** Force mock mode on/off; default follows `ROBORAMA_MOCK`. */
+    mock?: boolean;
+    /** Custom fetch implementation (defaults to `globalThis.fetch`). */
+    fetch?: typeof globalThis.fetch;
+}
+
+/**
+ * The Roborama client: bearer auth, idempotency keys, typed errors, and a
+ * deterministic mock mode.
+ *
+ * `new Roborama()` reads `ROBORAMA_API_KEY` from the environment; every
+ * method returns a promise; field names stay snake_case on both sides of
+ * the wire. Set `ROBORAMA_MOCK=1` (or `new Roborama({ mock: true })`) to
+ * integrate offline against fixture-shaped results while hosted execution
+ * is in private preview.
+ */
+
+declare const DEFAULT_BASE_URL = "https://api.roborama.com";
+type Json = Record<string, any>;
+declare class Transport {
+    private mockOpt?;
+    private mockBackend?;
+    private apiKey?;
+    readonly baseUrl: string;
+    private fetchImpl?;
+    constructor(opts?: RoboramaOptions);
+    get mock(): boolean;
+    private engine;
+    private key;
+    request(method: string, path: string, opts?: {
+        body?: Json;
+        params?: Json;
+    }): Promise<any>;
+    events(runId: string): AsyncGenerator<WatchEvent>;
+}
+/** Three constructors, each with a declared contract, validated before any motor moves. */
+declare const Policy: {
+    /** A container image we run in-facility, GPU-adjacent. */
+    readonly container: (opts: Omit<ContainerPolicy, "type">) => ContainerPolicy;
+    /** A checkpoint on a known runtime (`openpi`, `lerobot`). */
+    readonly checkpoint: (opts: Omit<CheckpointPolicy, "type">) => CheckpointPolicy;
+    /** Customer-hosted inference; measured RTT is logged per step. */
+    readonly endpoint: (opts: Omit<EndpointPolicy, "type">) => EndpointPolicy;
+};
+declare class BaseRunHandle {
+    protected transport: Transport;
+    protected data: RunData;
+    constructor(transport: Transport, data: RunData);
+    get id(): string;
+    get kind(): RunKind;
+    get status(): RunStatus;
+    get resolved_pins(): Record<string, string>;
+    /** The full wire payload, for forward compatibility. */
+    get raw(): RunData;
+    refresh(): Promise<this>;
+    protected raiseIfStopped(): void;
+}
+/** A created or fetched run. `result()` resolves once the run completes. */
+declare class RunHandle extends BaseRunHandle {
+    /** `n`, `success_rate`, `ci95`, clusters, both meters, `cost_usd`. */
+    result(): Promise<Result>;
+    /** Per-episode artifacts: `video_url`, `mcap_url`, `replay_spec`. */
+    episodes(): Promise<Episode[]>;
+    /** Live events: episode ticker plus WebRTC stream URLs. No polling. */
+    watch(): AsyncGenerator<WatchEvent>;
+    /** Dataset export: `lerobot`, `rlds`, or `mcap-bundle`. */
+    export(opts: {
+        format: ExportFormat;
+    }): Promise<Export>;
+    /** The deployment verification report, citable. */
+    report(opts?: {
+        format?: "json" | "pdf";
+    }): Promise<Report>;
+}
+/** A versioned suite evaluation (`kind: "eval"`) with a citable attestation. */
+declare class EvalRunHandle extends RunHandle {
+    get citation(): string | undefined;
+    get attestation(): string | undefined;
+    get attestation_url(): string | undefined;
+    get per_task(): Json[];
+}
+/** A paired A/B comparison (`kind: "compare"`). */
+declare class CompareRunHandle extends RunHandle {
+    get winner(): string | undefined;
+    get p_value(): number | undefined;
+    get effect_pts(): number | undefined;
+    get results(): Record<string, Result>;
+}
+/** Physical verification of sim-flagged scenarios (`kind: "verify"`). */
+declare class VerifyRunHandle extends RunHandle {
+    /** Where reality matched sim predictions. */
+    get sim_agreement(): number | undefined;
+    /** Scenario ids where reality diverged. */
+    get disagreements(): string[];
+    get ground_truth_url(): string | undefined;
+}
+/** An outcome contract (`kind: "threshold"`). The hardware calls you. */
+declare class ThresholdContractHandle extends RunHandle {
+    /** Register the webhook fired after verification-tier confirmation. */
+    onVerified(opts: {
+        webhook: string;
+    }): Promise<this>;
+}
+/** A transfer-gap measurement (`kind: "transfer"`). */
+declare class TransferRunHandle extends BaseRunHandle {
+    /** Source vs. target statistics and the failure clusters transfer opened. */
+    report(): Promise<TransferReport>;
+}
+/** An embodiment × environment sweep (`kind: "matrix"`). */
+declare class MatrixRunHandle extends RunHandle {
+    get cells(): MatrixCell[];
+    /** Embodiment × environment grid of rate ± CI per cell. */
+    heatmap(): Promise<Heatmap>;
+    /** Cells that degraded vs. a prior release run. */
+    regressions(opts: {
+        vs: string;
+    }): Promise<MatrixRegression[]>;
+    /** The release-gate deliverable (PDF). */
+    verificationReport(opts?: {
+        format?: "json" | "pdf";
+    }): Promise<Report>;
+    /** Overall stats plus the grid and per-stage/per-instruction breakdowns. */
+    result(): Promise<MatrixResult>;
+}
+/**
+ * A Task Spec: declarative, versioned, instrument-bound.
+ * Lifecycle: `draft` → `pilot()` → `amend()` → `freeze()` → immutable `name@vN`.
+ */
+declare class TaskHandle {
+    private transport;
+    private data;
+    constructor(transport: Transport, data: TaskData);
+    get id(): string;
+    get name(): string;
+    get status(): "draft" | "piloting" | "frozen";
+    /** Frozen revision id (`espresso@v1`); null until frozen. */
+    get rev(): string | null;
+    get visibility(): "private" | "published";
+    get raw(): TaskData;
+    /** Run the calibration session; the returned `stream_url` is live. */
+    pilot(opts: {
+        robot: string;
+        episodes?: number;
+    }): Promise<Pilot>;
+    /** Iterate on the method while piloting. Omitted fields are unchanged. */
+    amend(fields: Partial<TaskCreateParams>): Promise<this>;
+    /** Freeze to an immutable, co-signed revision (`name@vN`). */
+    freeze(): Promise<this>;
+}
+/** A kit of customer hardware, with live follow-ups. */
+declare class KitHandle {
+    private transport;
+    private data;
+    constructor(transport: Transport, data: KitData);
+    get id(): string;
+    get name(): string;
+    /** `registered → received → tracked → available` (as `kit/<name>`). */
+    get status(): KitData["status"];
+    get environment_ref(): string | null | undefined;
+    get raw(): KitData;
+    /** The inbound shipping label to the facility (URL). */
+    shippingLabel(): Promise<string>;
+}
+/**
+ * The Roborama client. Reads `ROBORAMA_API_KEY` from the environment;
+ * mirrors the Python surface method for method.
+ */
+declare class Roborama {
+    /** Policy constructors: `Roborama.Policy.checkpoint({...})`, etc. */
+    static readonly Policy: {
+        /** A container image we run in-facility, GPU-adjacent. */
+        readonly container: (opts: Omit<ContainerPolicy, "type">) => ContainerPolicy;
+        /** A checkpoint on a known runtime (`openpi`, `lerobot`). */
+        readonly checkpoint: (opts: Omit<CheckpointPolicy, "type">) => CheckpointPolicy;
+        /** Customer-hosted inference; measured RTT is logged per step. */
+        readonly endpoint: (opts: Omit<EndpointPolicy, "type">) => EndpointPolicy;
+    };
+    private transport;
+    readonly runs: {
+        /** `POST /v1/runs`; `kind` selects the primitive (default `run`). */
+        create(params: CreateRunParams): Promise<RunHandle>;
+        create(params: CreateEvalParams): Promise<EvalRunHandle>;
+        create(params: CreateVerifyParams): Promise<VerifyRunHandle>;
+        create(params: CreateMatrixParams): Promise<MatrixRunHandle>;
+        create(params: CreateThresholdParams): Promise<ThresholdContractHandle>;
+        create(params: CreateCompareParams): Promise<CompareRunHandle>;
+        create(params: CreateTransferParams): Promise<TransferRunHandle>;
+        create(params: RunCreateParams): Promise<RunHandle>;
+        get(runId: string): Promise<RunHandle>;
+        list(params?: {
+            kind?: RunKind;
+            status?: RunStatus;
+            limit?: number;
+        }): Promise<RunHandle[]>;
+    };
+    /** Physical verification of sim-flagged scenarios (`runs.create` with `kind: "verify"`). */
+    readonly verifications: {
+        create(params: Omit<CreateVerifyParams, "kind">): Promise<VerifyRunHandle>;
+    };
+    /** Embodiment × environment sweeps (`runs.create` with `kind: "matrix"`). */
+    readonly matrices: {
+        create(params: Omit<CreateMatrixParams, "kind">): Promise<MatrixRunHandle>;
+    };
+    readonly robots: {
+        list(): Promise<Robot[]>;
+    };
+    readonly environments: {
+        list(params?: {
+            cls?: string;
+        }): Promise<Environment[]>;
+    };
+    readonly suites: {
+        list(): Promise<Suite[]>;
+    };
+    readonly gates: {
+        create(params: GateCreateParams): Promise<Gate>;
+    };
+    readonly streams: {
+        get(cell: string): Promise<Stream>;
+    };
+    readonly keys: {
+        create(params: {
+            scope: readonly KeyScope[];
+        }): Promise<Key>;
+        list(): Promise<Key[]>;
+    };
+    readonly budgets: {
+        set(params: {
+            monthly_usd: number;
+            hard?: boolean;
+        }): Promise<Budget>;
+    };
+    readonly data: {
+        purge(runId: string): Promise<PurgeReceipt>;
+    };
+    readonly calibration: {
+        export(params: CalibrationExportParams): Promise<Export>;
+    };
+    readonly tasks: {
+        create(params: TaskCreateParams): Promise<TaskHandle>;
+        get(taskId: string): Promise<TaskHandle>;
+        list(): Promise<TaskHandle[]>;
+    };
+    readonly kits: {
+        register(params: KitCreateParams): Promise<KitHandle>;
+        get(kitId: string): Promise<KitHandle>;
+    };
+    readonly scenarios: {
+        /** Load PolaRiS / Isaac / world-model exports or layout-replay specs. */
+        fromFile(path: string): Promise<Record<string, unknown>>;
+    };
+    constructor(options?: RoboramaOptions);
+    /** Whether this client is in mock mode. */
+    get mock(): boolean;
+    get baseUrl(): string;
+    /** Both meters, dollars, and a queue ETA — before you commit. */
+    quote(params: QuoteParams): Promise<Quote>;
+    /** Metered usage for a period (`YYYY-MM`): hours by tier, dollars, budget. */
+    usage(params?: {
+        period?: string;
+    }): Promise<Usage>;
+}
+
+/**
+ * One error class, `RoboramaError`, with a `.code` matching the fixed set at
+ * https://roborama.com/docs/errors/. Switch on the code, not the message —
+ * messages are for humans and may improve without notice.
+ */
+
+declare class RoboramaError extends Error {
+    /** Machine-readable code from the documented fixed set. */
+    readonly code: ErrorCode;
+    /** HTTP status, when the error came off the wire. */
+    readonly status?: number;
+    /** Present when the error concerns a specific run. */
+    readonly run_id?: string;
+    /** Link to the matching entry in the error reference. */
+    readonly doc_url?: string;
+    /**
+     * For `budget_exceeded`: honest statistics for the episodes that ran
+     * before the hard stop (`n`, `success_rate`, `ci95`).
+     */
+    readonly partial_result?: Result;
+    constructor(message: string, opts: {
+        code: ErrorCode;
+        status?: number;
+        run_id?: string;
+        doc_url?: string;
+        partial_result?: Result;
+    });
+}
+
+declare function zForCi(ci: number): number;
+/** Wilson score interval, rounded to 3 decimals (the API's display precision). */
+declare function wilsonCi(successes: number, n: number, ci?: number): [number, number];
+/** Parse `auto(ci=0.95, moe=0.03)` → `{ci, moe}`; null when not auto-form. */
+declare function parseAuto(spec: string): {
+    ci: number;
+    moe: number;
+} | null;
+/** Conservative pre-run sizing (p=0.5) for a target margin of error. */
+declare function planningN(ci: number, moe: number): number;
+
+/**
+ * roborama — real robots as an API.
+ *
+ * ```ts
+ * import Roborama from "roborama"; // reads ROBORAMA_API_KEY
+ *
+ * const roborama = new Roborama();
+ * const run = await roborama.runs.create({
+ *   robot: "g1-edu-pro@fw2.3",
+ *   environment: "kitchen-std@v1.2",
+ *   task: "pick_place@v1",
+ *   episodes: "auto(ci=0.95, moe=0.03)",
+ * });
+ * console.log(await run.result()); // n=612  rate=0.874  ci95=(0.846, 0.898)
+ * ```
+ *
+ * Hosted execution is in private preview. Set `ROBORAMA_MOCK=1` (or
+ * `new Roborama({ mock: true })`) to integrate today against a
+ * deterministic, fixture-shaped mock backend.
+ */
+
+export { type AutoEpisodesSpec, type Budget, type CalibrationExportParams, type CheckpointPolicy, CompareRunHandle, type ContainerPolicy, type CreateCompareParams, type CreateEvalParams, type CreateMatrixParams, type CreateRunParams, type CreateThresholdParams, type CreateTransferParams, type CreateVerifyParams, DEFAULT_BASE_URL, type DataPosture, type EndpointPolicy, type Environment, type Episode, type EpisodesSpec, type ErrorCode, type ErrorEnvelope, EvalRunHandle, type Export, type ExportFormat, type Gate, type GateCreateParams, type Heatmap, type InstructionRate, type Interventions, type Key, type KeyScope, type KitCreateParams, type KitData, KitHandle, type MatrixCell, type MatrixRegression, type MatrixResult, MatrixRunHandle, type Perturbation, type Pilot, Policy, type PolicyInput, type PolicyStream, type Priority, type PurgeReceipt, type Quote, type QuoteParams, type Report, type Result, Roborama, RoboramaError, type RoboramaOptions, type Robot, type RunCreateParams, type RunData, RunHandle, type RunKind, type RunStatus, type StageRate, type Stream, type Suite, type TaskCreateParams, type TaskData, TaskHandle, ThresholdContractHandle, type TransferReport, TransferRunHandle, type TransferSide, type Usage, VerifyRunHandle, type WatchEvent, Roborama as default, parseAuto, planningN, wilsonCi, zForCi };