runbios-sdk 0.2.1-dev.62

package/dist/types.d.ts

@@ -0,0 +1,1916 @@
+/** Configuration for initializing the Run BiOS SDK client. */
+export interface BiOSConfig {
+    /** API key for authentication (prefix: bios-; legacy usf- keys stay valid). Falls back to the RUNBIOS_API_KEY environment variable (legacy: BIOS_API_KEY). Mutually exclusive with accessToken. */
+    apiKey?: string;
+    /** JWT access token for authentication. Mutually exclusive with apiKey. */
+    accessToken?: string;
+    /** Organization ID. Optional when using API keys (resolved from the key). Required for JWT auth. */
+    orgId?: string;
+    /** Workspace ID. Optional when using API keys (resolved from the key). Can override for multi-workspace keys. */
+    workspaceId?: string;
+    /** Base URL for the API. Falls back to the RUNBIOS_BASE_URL environment variable (legacy: BIOS_BASE_URL), then the canonical https://api-dev.runbios.ai hostname. */
+    baseUrl?: string;
+    /** Request timeout in milliseconds. Defaults to 30000. */
+    timeout?: number;
+    /** Default per-deployment inference key. Can be overridden per inference call. */
+    inferenceKey?: string;
+    /** Inference base URL. Defaults to baseUrl, then https://api-dev.runbios.ai. */
+    inferenceBaseUrl?: string;
+    /** End-to-end inference timeout in milliseconds. Defaults to 15 minutes. */
+    inferenceTimeout?: number;
+}
+/** Paginated list response wrapper. */
+export interface PaginatedResponse<T> {
+    items: T[];
+    total: number;
+    offset: number;
+    limit: number;
+    hasMore: boolean;
+}
+/** Standard API error response body. */
+export interface ApiErrorBody {
+    error?: string | {
+        code?: string;
+        message?: string;
+        detail?: string;
+    };
+    detail?: string;
+    message?: string;
+    code?: string;
+    request_id?: string;
+    /**
+     * Bookable-now GPU alternatives, present on availability rejections
+     * (SELECTED_GPU_UNAVAILABLE / CAPACITY_UNAVAILABLE): each entry fits the
+     * requested model's minimum requirements and was in stock at `checked_at`.
+     * Pick one and resubmit — nothing else about the request needs to change.
+     */
+    available_gpus?: AvailableGpuAlternative[];
+    /** Same contract as `available_gpus`; some surfaces use this field name. */
+    available_alternatives?: AvailableGpuAlternative[];
+    /** When the availability snapshot behind the rejection was taken. */
+    checked_at?: string;
+    /**
+     * Rejection class on the standard GPU-rejection contract:
+     * insufficient_stock | below_model_minimum | invalid_gpu_count |
+     * model_too_large | gpu_unsupported. Only insufficient_stock is transient.
+     */
+    reason?: string;
+    /**
+     * Explicit server-computed minimum block on any GPU rejection: the selected
+     * type's minimum + valid counts and the per-type table for the model.
+     * Client-supplied facts can never lower these.
+     */
+    minimum_requirement?: CapacityMinimumRequirement;
+    /** The selection the rejection was about. */
+    selected?: {
+        gpu_type: string;
+        gpu_count: number;
+        tier?: string;
+        availability_status?: 'available' | 'out_of_stock' | 'unknown';
+        available_count?: number;
+    };
+    /**
+     * Whether waiting for capacity is a real option at all. False on every
+     * permanent rejection (the model does not fit that GPU type, the count is
+     * below the minimum or cannot split the model, the engine cannot run the
+     * card): stock will never change the answer. This is the field to branch on,
+     * not the status or the code.
+     */
+    queue_offered?: boolean;
+    /** Whether the capacity queue may be joined for this request. */
+    queue_eligible?: boolean;
+    /**
+     * 1-based rank of the gpu_priorities entry the rejection is about, when the
+     * request carried a ranked ladder.
+     */
+    gpu_priorities_entry?: number;
+}
+/** The explicit minimum-requirement block of the standard capacity contract. */
+export interface CapacityMinimumRequirement {
+    selected_gpu_min: number;
+    selected_valid_counts?: number[];
+    per_type: Array<{
+        gpu_type: string;
+        min_gpus: number;
+        valid_counts: number[];
+    }>;
+}
+/** One bookable-now GPU alternative carried on an availability rejection. */
+export interface AvailableGpuAlternative {
+    gpu_type: string;
+    gpu_count?: number;
+    /** The model's minimum GPU count for this type (never pick below it). */
+    min_gpus?: number;
+    /** Every pickable count for this type (>= min and tensor-parallel-valid). */
+    valid_counts?: number[];
+    available_count?: number;
+    price_per_hour_cents?: number;
+    /** Total hourly price at `gpu_count` on the inference contract. */
+    price_hour_cents?: number;
+    provider?: string;
+    region?: string;
+    tier?: string;
+    recommended?: boolean;
+}
+/**
+ * A model from the Run BiOS model catalog. The catalog is served from the
+ * platform's own registry: every listed model is hosted in Run BiOS storage,
+ * verified end-to-end, and can be trained and deployed. It is never a live
+ * Hugging Face search result — a model that is not listed is not hosted.
+ */
+/**
+ * One row of the Run BiOS model registry (`GET /api/models`).
+ *
+ * The catalog is the platform's own registry: every listed model is hosted in
+ * Run BiOS storage, verified end to end, and can be trained and deployed. It is
+ * never a live Hugging Face search result.
+ *
+ * Field names are the registry's own snake_case, with two long-standing
+ * camelCase exceptions (`maxContext` / `weightBytes`). Everything is optional
+ * because a partner/private model has its weight-revealing fields stripped
+ * before the row leaves the service.
+ */
+export interface Model {
+    /**
+     * Registry UUID -- NOT the model handle. Pass `repo_id` to training and
+     * deployment; `id` is only useful for registry-internal joins.
+     */
+    id?: string;
+    /**
+     * "author/name" -- the handle every other API accepts (hfModelId,
+     * baseModelId, training `model`, gpu-options `model`).
+     */
+    repo_id?: string;
+    author?: string;
+    name?: string;
+    /** Model family slug from the registry (e.g. "gemma", "qwen3"). */
+    family?: string;
+    /** Architecture class from the hosted config.json (e.g. "LlamaForCausalLM"). */
+    architecture?: string;
+    /** Raw model_type from the hosted config.json (e.g. "gemma4"). */
+    model_type?: string;
+    /** Serving surface: "llm" (text) or "vlm" (vision-language). */
+    surface_type?: 'llm' | 'vlm';
+    is_moe?: boolean;
+    /** Total params in billions (all experts resident for MoE). */
+    params_total_b?: number;
+    /** Active params in billions; equals params_total_b for dense models. */
+    params_active_b?: number;
+    precision?: string;
+    license?: string;
+    /**
+     * False once Run BiOS mirrors a weight revision -- which is every catalog model,
+     * so hosted weights never need a Hugging Face account.
+     */
+    gated?: boolean;
+    summary?: string;
+    source?: string;
+    origin_url?: string;
+    /**
+     * "public", or "partner"/"private" (weight-revealing fields, including
+     * maxContext and weightBytes, are stripped for the latter).
+     */
+    visibility?: string;
+    /** Always "verified" on user-facing reads; the registry lists nothing else. */
+    status?: string;
+    downloads?: number;
+    likes?: number;
+    /** Run BiOS-side usage rollups for this model. */
+    train_count?: number;
+    inference_count?: number;
+    verified_at?: string | null;
+    /** Per-surface verification badges plus the image build that passed. */
+    training_verified?: boolean;
+    training_verified_at?: string | null;
+    training_verified_image?: string;
+    inference_verified?: boolean;
+    inference_verified_at?: string | null;
+    inference_verified_image?: string;
+    updated_at?: string;
+    /**
+     * Native max context window in tokens -- the ceiling a deployment's
+     * `contextLength` can never exceed. Omitted when unknown or stripped for a
+     * protected model.
+     */
+    maxContext?: number;
+    /**
+     * On-disk weight size of the primary hosted revision, in bytes. Omitted
+     * when no primary revision is mirrored or stripped for a protected model.
+     */
+    weightBytes?: number;
+}
+/** Response from `GET /api/models/{author}/{name}`. */
+export interface ModelDetailResponse {
+    model: Model;
+    /** Whether the file/config viewer applies -- public models only. */
+    files_viewable?: boolean;
+    /** Cached model card; present only for public models that have one. */
+    readme_md?: string;
+    /**
+     * The revision this card and file list describe -- the one hosted in our
+     * mirror. Public models only, and only once something is mirrored.
+     */
+    primary_revision?: string;
+}
+export interface ModelSearchParams {
+    /**
+     * Search text. Becomes the registry's `q` filter -- the ONLY search
+     * parameter it reads. (`search` / `query` are not recognized on the wire and
+     * are silently ignored, returning every model, which is why the SDK maps the
+     * name for you.)
+     */
+    query?: string;
+    /** Filter by model surface: "all", "llm", or "vlm". */
+    type?: 'all' | 'llm' | 'vlm';
+    /** Pagination offset. Defaults to 0. */
+    offset?: number;
+    /** Number of results to return. Server defaults to 24 and clamps to 60. */
+    limit?: number;
+    /** Minimum parameter count in billions. */
+    minParams?: number;
+    /** Maximum parameter count in billions. */
+    maxParams?: number;
+    /** Sort order accepted by the registry. */
+    sort?: 'downloads' | 'likes' | 'params' | 'name' | 'trending';
+    /**
+     * @deprecated Ignored by the registry-backed catalog. Include the author in
+     * `query` instead — model ids are "author/name" and match as text.
+     */
+    author?: string;
+    /**
+     * @deprecated Ignored by the registry-backed catalog — hosted models are
+     * visible to every workspace (partner models are labeled via `visibility`).
+     */
+    visibility?: 'all' | 'public' | 'private';
+    /**
+     * @deprecated Ignored by the registry-backed catalog — it carries verified
+     * full base models only, so no adapter/quantized filtering is needed.
+     */
+    kind?: 'full' | 'adapter';
+    /**
+     * @deprecated Ignored by the registry-backed catalog — hosted models never
+     * require a Hugging Face integration (legacy from the live-HF era).
+     */
+    integrationId?: string;
+}
+/** Response from a model search. */
+export interface ModelSearchResponse {
+    models: Model[];
+    total: number;
+    offset: number;
+    limit: number;
+    hasMore: boolean;
+    /**
+     * @deprecated Legacy field from the live-Hugging-Face era. The registry-
+     * backed catalog no longer returns it — hosted models need no HF account.
+     */
+    hfUsername?: string;
+}
+/** Model configuration resolved from the registry's hosted copy of the model. */
+export interface ModelConfig {
+    /** Full model id. */
+    modelId: string;
+    /** Model type from config.json (e.g. "llama", "qwen2"). */
+    model_type: string | null;
+    /** Model architecture classes. */
+    architectures: string[];
+    /** Total parameter count in billions. */
+    totalParams: number;
+    /** Active parameter count in billions. */
+    activeParams: number;
+    /** Whether this is a Mixture-of-Experts model. */
+    isMoE: boolean;
+    /** Whether config was successfully resolved. */
+    resolved: boolean;
+}
+/** A dataset in the user's workspace. */
+export interface Dataset {
+    id: string;
+    name: string;
+    description?: string;
+    workspace_id?: string;
+    source?: string;
+    hf_dataset_id?: string | null;
+    hf_subset?: string | null;
+    hf_split?: string | null;
+    dataset_type?: string;
+    detected_format?: string | null;
+    num_samples?: number | null;
+    num_columns?: number | null;
+    column_info?: Array<Record<string, unknown>>;
+    column_mapping?: Record<string, string> | null;
+    compatible_training_methods?: string[];
+    compatible_rlhf_algorithms?: string[];
+    detected_fields?: string[];
+    file_format?: string | null;
+    file_size_bytes?: number;
+    status?: string;
+    max_samples?: number | null;
+    error_message?: string | null;
+    progress_percent?: number;
+    progress_message?: string;
+    storage_mode?: string;
+    num_shards?: number | null;
+    method_usable_counts?: Record<string, number> | null;
+    consistency_info?: Record<string, unknown> | null;
+    validation_warnings?: string[];
+    created_at?: string;
+    /** @deprecated Use file_size_bytes. Populated as a compatibility alias. */
+    file_size?: number;
+    /** @deprecated Use num_samples. Populated as a compatibility alias. */
+    row_count?: number;
+    /** @deprecated Use num_columns. Populated as a compatibility alias. */
+    column_count?: number;
+    /** @deprecated Use file_format or detected_format. Populated as a compatibility alias. */
+    format?: string;
+}
+/** Parameters for listing datasets. */
+export interface DatasetListParams {
+    /** Filter by workspace ID. */
+    workspaceId?: string;
+    /** Filter by dataset type. */
+    datasetType?: string;
+    /** Lifecycle bucket: ready, processing, or failed. */
+    status?: 'ready' | 'processing' | 'failed';
+    /** Case-insensitive name search. */
+    query?: string;
+    /** Server-side ordering. */
+    sort?: 'newest' | 'oldest' | 'name' | 'size';
+    /** Page size (maximum 200). */
+    limit?: number;
+    /** Page offset. */
+    offset?: number;
+}
+/** Server-driven dataset page returned by GET /api/datasets. */
+export interface DatasetListResponse {
+    datasets: Dataset[];
+    total: number;
+    counts: {
+        all: number;
+        ready: number;
+        processing: number;
+        failed: number;
+    };
+    total_samples: number;
+    limit: number;
+    offset: number;
+}
+/** Parameters for uploading a dataset. */
+export interface DatasetUploadParams {
+    /** Path to the file on disk (Node.js only). */
+    filePath: string;
+    /** Display name for the dataset. */
+    name: string;
+    /** Optional description. */
+    description?: string;
+    /** Target workspace ID. */
+    workspaceId?: string;
+    /** Dataset format hint (e.g. "jsonl", "csv", "parquet"). */
+    format?: string;
+    /** Maximum number of samples to retain. */
+    maxSamples?: number;
+    /** Optional source-to-canonical column mapping. */
+    columnMapping?: Record<string, string>;
+}
+/** Parameters for previewing dataset rows. */
+export interface DatasetPreviewParams {
+    /** Page number (1-indexed). Defaults to 1. */
+    page?: number;
+    /** Number of rows per page. Defaults to 10. */
+    pageSize?: number;
+}
+/** Dataset preview response. */
+export interface DatasetPreview {
+    samples: Record<string, unknown>[];
+    total: number;
+    page: number;
+    page_size: number;
+    total_pages: number;
+    /** @deprecated Use samples. Populated as a compatibility alias. */
+    rows?: Record<string, unknown>[];
+    /** @deprecated Use total. Populated as a compatibility alias. */
+    total_rows?: number;
+}
+/** Parameters for importing a dataset from HuggingFace Hub. */
+export interface DatasetImportHFParams {
+    /** HuggingFace dataset repository ID (e.g. "databricks/dolly-15k"). */
+    repoId: string;
+    /** Display name for the imported dataset. */
+    name?: string;
+    /** Dataset subset/config to import. */
+    subset?: string;
+    /** Dataset split to import (e.g. "train", "test"). */
+    split?: string;
+    /** Maximum number of samples to import. */
+    maxSamples?: number;
+    /** HuggingFace integration ID for private datasets. */
+    integrationId?: string;
+    /** Sampling strategy used with maxSamples. */
+    sampleStrategy?: 'first' | 'random';
+    /** Optional source-to-canonical column mapping. */
+    columnMapping?: Record<string, string>;
+    /** Whether to reference or materialize the source dataset. */
+    importMode?: 'auto' | 'reference' | 'materialize';
+}
+/** Parameters for registering a HuggingFace dataset without an integration. */
+export interface DatasetRegisterHFParams {
+    repoId: string;
+    name?: string;
+    workspaceId?: string;
+    description?: string;
+    subset?: string;
+    split?: string;
+    maxSamples?: number;
+    sampleStrategy?: 'first' | 'random';
+    columnMapping?: Record<string, string>;
+    importMode?: 'auto' | 'reference' | 'materialize';
+}
+/** Parameters for searching HuggingFace Hub datasets. */
+export interface DatasetHubSearchParams {
+    /** Search query. */
+    query?: string;
+    /** Page number (1-indexed). Defaults to 1. */
+    page?: number;
+    /** Sort order. Defaults to "downloads". */
+    sort?: 'downloads' | 'likes' | 'trending';
+}
+/** Parameters for previewing a HuggingFace Hub dataset. */
+export interface DatasetHubPreviewParams {
+    /** HuggingFace dataset ID. */
+    datasetId: string;
+    /** Split to preview. Defaults to "train". */
+    split?: string;
+    /** Subset/config name. */
+    subset?: string;
+    /** Number of rows to preview. Defaults to 10. */
+    limit?: number;
+}
+/** Dataset validation result. */
+export interface DatasetValidation {
+    dataset_type: string;
+    detected_format?: string | null;
+    confidence: number;
+    format_valid: boolean;
+    num_samples: number;
+    num_columns: number;
+    detected_fields: string[];
+    column_info: Array<Record<string, unknown>>;
+    compatible_training_methods: string[];
+    compatible_rlhf_algorithms: string[];
+    method_usable_counts?: Record<string, number> | null;
+    validation_errors: string[];
+    validation_warnings: string[];
+    consistency?: Record<string, unknown> | null;
+    preview_samples: Record<string, unknown>[];
+}
+/** One accepted row shape for a dataset type. */
+export interface DatasetFormatVariant {
+    name: string;
+    required_fields: string[];
+    description: string;
+    example: string;
+    needs_conversion?: boolean;
+}
+/** Dataset format specification for one training family. */
+export interface DatasetFormatSpec {
+    label: string;
+    formats: DatasetFormatVariant[];
+}
+/** Mapping keyed by dataset type (sft, rlhf_offline_preference, pt, etc.). */
+export type DatasetFormatSpecs = Record<string, DatasetFormatSpec>;
+/** Dataset storage usage info. */
+export interface DatasetStorageUsage {
+    total_bytes: number;
+    total_mb?: number;
+    total_gb?: number;
+    dataset_count: number;
+    workspace_id?: string | null;
+    pricing?: Record<string, number>;
+    recent_charges?: Array<Record<string, unknown>>;
+}
+/** Supported training methods. */
+export type TrainingMethod = 'sft' | 'rlhf' | 'pt' | 'vlm';
+/** Supported RLHF algorithms. */
+export type RLHFAlgorithm = 'dpo' | 'simpo' | 'cpo' | 'orpo' | 'kto' | 'rm';
+/** Supported adapter types. */
+export type AdapterType = 'lora' | 'qlora' | 'adalora' | 'full' | 'loha' | 'lokr' | 'boft' | 'oft' | 'vera' | 'fourierft' | 'bone' | 'adapter' | 'reft' | 'llamapro' | 'longlora';
+/** Training job status values. */
+export type TrainingJobStatus = 'pending' | 'queued' | 'securing' | 'booked' | 'provisioning' | 'preparing' | 'starting' | 'downloading' | 'running' | 'completed' | 'failed' | 'interrupted' | 'saving' | 'stopped' | 'stopping' | 'resuming' | 'cancelled';
+/** Status values accepted by GET /api/training/jobs?status=. */
+export type TrainingStatusFilter = 'pending' | 'queued' | 'securing' | 'booked' | 'provisioning' | 'preparing' | 'starting' | 'running' | 'interrupted' | 'saving' | 'completed' | 'failed' | 'stopped';
+/** One ranked GPU fallback choice. The first choice is the primary. */
+export interface GPUChoice {
+    gpuType: string;
+    gpuCount: number;
+    /** Neutral USF Cloud placement selector; omit to let the platform choose. */
+    provider?: string;
+    /** Placement region; omit for the default global market. */
+    region?: string;
+    /** Native market tier; training and deployment capacity are secure-only. */
+    tier?: 'secure';
+}
+/** Parameters for creating a training job. */
+export interface TrainingCreateParams {
+    /** Stable retry key. Reuse it after a timeout; a new value creates a new job. Auto-generated when omitted. */
+    idempotencyKey?: string;
+    /**
+     * Model id to fine-tune. Must be hosted on Run BiOS — pick from the platform's
+     * own catalog (client.models.search); arbitrary Hugging Face ids are
+     * rejected. Training FROM a fine-tuned model (adapter stacking) is not
+     * supported; every job starts from a catalog base model.
+     */
+    model: string;
+    /** Optional model branch, tag, or commit; the API canonicalizes it to an exact commit. */
+    modelRevision?: string;
+    /** One dataset ID to train on. Kept for compatibility with single-dataset jobs. */
+    datasetId?: string;
+    /** Ordered dataset IDs for multi-dataset training. */
+    datasetIds?: string[];
+    /**
+     * Optional per-dataset row cap: keep only the first N rows of a dataset
+     * (key = a dataset ID from datasetIds, value = row count). Omit an entry, or
+     * use 0, to train on the whole dataset. Useful for training on a slice of a
+     * large dataset without importing a trimmed copy.
+     */
+    datasetSampleLimits?: Record<string, number>;
+    /** Training method. */
+    method: TrainingMethod;
+    /** Adapter type. */
+    adapter: AdapterType;
+    /** RLHF algorithm (required when method is "rlhf"). */
+    rlhfAlgorithm?: RLHFAlgorithm;
+    /** GPU type identifier. */
+    gpuType?: string;
+    /** Number of GPUs to use. */
+    gpuCount?: number;
+    /** Primary and backup GPU choices, in priority order (maximum five). */
+    gpuPriorities?: GPUChoice[];
+    /** Consent to try 3-5 ranked, distinct GPU types when the primary is unavailable. */
+    queueIfUnavailable?: boolean;
+    /** Optional RFC 3339 queue deadline, from one minute through seven days in the future. */
+    queueDeadline?: string | Date;
+    /** Maximum accepted total hourly price for the complete GPU count, in cents. */
+    maxPriceHourCents?: number;
+    /** Display name for the job. */
+    name?: string;
+    /** Target workspace ID. */
+    workspaceId?: string;
+    /** Number of training epochs. */
+    epochs?: number;
+    /** Training batch size per device. */
+    batchSize?: number;
+    /** Gradient accumulation steps. */
+    gradientAccumulation?: number;
+    /** Learning rate. */
+    learningRate?: number;
+    /** Learning rate scheduler type. */
+    lrScheduler?: string;
+    /** Warmup ratio (0-1). */
+    warmupRatio?: number;
+    /** Warmup steps (overrides warmupRatio). */
+    warmupSteps?: number;
+    /** Weight decay. */
+    weightDecay?: number;
+    /** Maximum gradient norm for clipping. */
+    maxGradNorm?: number;
+    /** Maximum sequence length. */
+    maxSeqLength?: number;
+    /** Enable gradient checkpointing. */
+    gradientCheckpointing?: boolean;
+    /** Enable mixed precision training (bf16/fp16). */
+    mixedPrecision?: 'bf16' | 'fp16' | 'no';
+    /** Random seed. */
+    seed?: number;
+    /** LoRA rank. */
+    loraRank?: number;
+    /** LoRA alpha scaling factor. */
+    loraAlpha?: number;
+    /** LoRA dropout rate. */
+    loraDropout?: number;
+    /** LoRA target modules (comma-separated or array). */
+    loraTargetModules?: string | string[];
+    /** Quantization bit width (4 or 8). */
+    quantizationBit?: 4 | 8;
+    /** DeepSpeed stage ("zero2" or "zero3"). */
+    deepspeed?: 'zero2' | 'zero3';
+    /** Storage size in GB. */
+    storageGb?: number;
+    /** Number of checkpoints to retain at the platform level. */
+    numCheckpoints?: number;
+    /** Model parameter hint in billions; the server resolves and floors it. */
+    modelParamsB?: number;
+    /** Active-parameter hint for MoE models in billions. */
+    modelActiveParamsB?: number;
+    /** Integration used for gated/private model access. */
+    integrationId?: string;
+    /** Existing network volume to attach. */
+    networkVolumeId?: string;
+    /** Cache the composed dataset for retry/resume. Defaults to true server-side. */
+    cacheDataset?: boolean;
+    /** Legacy dataset ordering mode. Prefer mixing for weighted/phased plans. */
+    datasetMixing?: 'shuffle' | 'sequential' | 'interleave' | 'random' | 'curriculum';
+    /** Structured multi-dataset mixing plan. */
+    mixing?: Record<string, unknown>;
+    /** Save checkpoint every N steps. */
+    saveSteps?: number;
+    /** Save checkpoint every N epochs. */
+    saveEpochs?: number;
+    /** Maximum number of checkpoints to keep. */
+    maxCheckpoints?: number;
+    /** Evaluate every N steps. */
+    evalSteps?: number;
+    /** Evaluation dataset split. */
+    evalSplit?: string | number;
+    /** Additional configuration passed directly to the training backend. */
+    extraConfig?: Record<string, unknown>;
+}
+/** Parameters for listing training jobs. */
+export interface TrainingListParams {
+    /** Filter by workspace ID. */
+    workspaceId?: string;
+    /** Filter by status. */
+    status?: TrainingStatusFilter;
+    /** Page size (maximum 100). */
+    limit?: number;
+    /** Page offset. */
+    offset?: number;
+}
+/** One phase of a training job's lifecycle (Progress Frame v2). */
+export interface TrainingJobPhase {
+    /** Canonical phase id, e.g. "dataset_download", "model_load", "training", "checkpoint_upload". */
+    phase: string;
+    state: 'pending' | 'active' | 'done' | 'failed' | 'skipped';
+    /** Percent complete for the active phase, 0-100. */
+    pct?: number;
+    done_bytes?: number;
+    total_bytes?: number;
+    done_units?: number;
+    total_units?: number;
+    /** Unit for done_units/total_units, e.g. "bytes", "shards", "steps", "examples". */
+    units?: string;
+    /** Measured throughput in units per second. */
+    rate?: number;
+    eta_seconds?: number;
+    /** Per-item breakdown for fan-out phases (one entry per dataset in dataset_download). */
+    items?: Array<Record<string, unknown>>;
+    started_at?: string;
+    ended_at?: string;
+    updated_at?: string;
+}
+/** A training job. */
+export interface TrainingJob {
+    id: string;
+    /** Present on create/resume responses; id is always normalized from this value. */
+    job_id?: string;
+    name?: string;
+    model_id?: string;
+    model_revision?: string;
+    training_method?: TrainingMethod;
+    train_type?: AdapterType;
+    rlhf_type?: RLHFAlgorithm | null;
+    dataset_ids?: string[];
+    gpu_type?: string;
+    gpu_count?: number;
+    storage_gb?: number;
+    status: TrainingJobStatus;
+    error_message?: string | null;
+    error_code?: string | null;
+    current_step?: number;
+    total_steps?: number;
+    current_loss?: number | null;
+    best_loss?: number | null;
+    config?: Record<string, unknown>;
+    started_at?: string;
+    completed_at?: string;
+    created_at?: string;
+    billing_started_at?: string;
+    resume_from_job_id?: string | null;
+    resume_count?: number;
+    can_resume?: boolean;
+    has_cached_dataset?: boolean;
+    final_model_s3_key?: string | null;
+    mix_manifest?: Record<string, unknown> | null;
+    preserve_on_stop?: boolean;
+    desired_state?: 'running' | 'stopped';
+    stop_state?: 'idle' | 'requested' | 'signalled' | 'terminating' | 'applied' | 'superseded';
+    stop_requested_at?: string | null;
+    stop_bios_accepted_at?: string | null;
+    stop_last_error?: string | null;
+    s3_upload_status?: string | null;
+    progress?: unknown;
+    stage?: string;
+    stage_detail?: string;
+    attempt?: number;
+    attempts_max?: number;
+    billed_cents?: number;
+    billable_seconds?: number;
+    stage_elapsed_seconds?: number;
+    stage_estimate_seconds?: number;
+    dl_done_bytes?: number;
+    dl_total_bytes?: number;
+    ds_done_bytes?: number;
+    ds_total_bytes?: number;
+    checkpoint_count?: number;
+    /** The current machine attempt's per-phase records, in canonical order. */
+    phases?: TrainingJobPhase[];
+    /** Estimated seconds until the job finishes (absent when unknown). */
+    eta_seconds?: number;
+    /** How the ETA was derived: measured on the machine, or from historical medians. */
+    eta_confidence?: 'measured' | 'historical';
+    /** Most recent per-phase update time. */
+    last_phase_update_at?: string;
+    /**
+     * The current machine attempt id. Quote this when contacting support — it
+     * identifies the exact machine attempt behind a run.
+     */
+    attempt_id?: string;
+    /** Last time the machine reported in. */
+    last_callback_at?: string;
+    /** How the platform is hearing from the machine right now. */
+    push_channel_state?: 'live' | 'delayed' | 'poll_only';
+    /** @deprecated Use model_id. Populated as a compatibility alias when known. */
+    model?: string;
+    /** @deprecated Use training_method. Populated as a compatibility alias when known. */
+    method?: TrainingMethod;
+    /** @deprecated Use train_type. Populated as a compatibility alias when known. */
+    adapter?: AdapterType;
+    /** @deprecated Use rlhf_type. Populated as a compatibility alias when known. */
+    rlhf_algorithm?: RLHFAlgorithm;
+    /** @deprecated Use dataset_ids. Populated from the first dataset when known. */
+    dataset_id?: string;
+    /** @deprecated Use error_message. */
+    error?: string;
+}
+/** Paginated response from GET /api/training/jobs. */
+export interface TrainingListResponse {
+    jobs: TrainingJob[];
+    total: number;
+    limit: number;
+    offset: number;
+}
+/** Training metrics for a job. */
+export interface TrainingMetrics {
+    metrics: MetricPoint[];
+    training_method?: string | null;
+    rlhf_type?: string | null;
+    graph_configs: MetricGraphConfig[];
+    /** @deprecated Use metrics. Populated as a compatibility alias. */
+    steps?: MetricPoint[];
+}
+/** A single metric data point. */
+export interface MetricPoint {
+    step: number;
+    epoch?: number;
+    loss?: number;
+    eval_loss?: number;
+    learning_rate?: number;
+    grad_norm?: number;
+    reward?: number;
+    gpu_memory_mb?: number;
+    gpu_utilization_pct?: number;
+    extra_metrics?: Record<string, unknown>;
+    timestamp: string;
+    [key: string]: unknown;
+}
+/** Metric series configuration returned for the selected training method. */
+export interface MetricGraphConfig {
+    key: string;
+    label: string;
+    color: string;
+}
+/** A training checkpoint. */
+export interface TrainingCheckpoint {
+    id: string;
+    name: string;
+    step: number;
+    epoch?: number | null;
+    size_bytes: number;
+    is_final: boolean;
+    is_best: boolean;
+    base_model_id: string;
+    base_model_revision: string;
+    created_at: string;
+}
+/** Training logs response. */
+export interface TrainingLogs {
+    logs: TrainingLogEntry[];
+    /** Plain-text compatibility view of logs, oldest API clients can migrate to entries. */
+    lines?: string[];
+}
+/** One structured training log entry. */
+export interface TrainingLogEntry {
+    level: string;
+    message: string;
+    timestamp: string;
+}
+/** Response from stopping a training job. */
+export interface TrainingStopResponse {
+    message: string;
+    job_id: string;
+    status: TrainingJobStatus;
+    desired_state: 'stopped';
+    stop_state: 'requested' | 'signalled' | 'terminating' | 'applied';
+    keep_data: boolean;
+    requested_at?: string | null;
+}
+/** Response from resuming a training job into a new job. */
+export interface TrainingResumeResponse {
+    id: string;
+    job_id: string;
+    name: string;
+    status: TrainingJobStatus;
+    resume_from: string;
+    checkpoint: string;
+    resume_count: number;
+    model_id: string;
+    model_revision: string;
+}
+/** Canonical snake_case request echoed by the side-effect-free preflight API. */
+export interface CanonicalTrainingRequest {
+    workspace_id: string;
+    name: string;
+    dataset_id: string;
+    dataset_ids: string[];
+    hf_dataset_ids?: string;
+    dataset_mixing?: string;
+    mixing?: Record<string, unknown>;
+    model_id: string;
+    model_revision?: string;
+    training_method: TrainingMethod;
+    train_type: AdapterType;
+    rlhf_type?: RLHFAlgorithm;
+    gpu_type: string;
+    gpu_count: number;
+    gpu_priorities?: Array<{
+        gpu_type: string;
+        gpu_count: number;
+        provider?: string;
+        region?: string;
+        tier?: 'secure';
+    }>;
+    queue_if_unavailable?: boolean;
+    queue_deadline?: string;
+    max_price_hour_cents?: number;
+    storage_gb: number;
+    num_checkpoints?: number;
+    model_params_b?: number;
+    model_active_params_b?: number;
+    integration_id?: string;
+    network_volume_id?: string;
+    cache_dataset?: boolean;
+    config: Record<string, unknown>;
+}
+export interface TrainingPreflightDataset {
+    id: string;
+    status: string;
+    dataset_type?: string;
+    storage_mode?: string;
+    method_usable_counts?: Record<string, number>;
+    requires_revalidation: boolean;
+}
+export interface TrainingPreflightWarning {
+    code: string;
+    message: string;
+}
+/** Side-effect-free validation/sizing result; this endpoint never creates or bills a job. */
+export interface TrainingPreflightResponse {
+    valid: boolean;
+    contract_version: string;
+    request_hash: string;
+    canonical_request: CanonicalTrainingRequest;
+    datasets: TrainingPreflightDataset[];
+    model_params_b: number;
+    model_active_params_b?: number;
+    minimum_vram_gb: number;
+    minimum_storage_gb: number;
+    gpu_options: GPUOption[];
+    recommended?: GPUOption;
+    suggestions: GPUOptionSuggestion[];
+    availability_known: boolean;
+    availability_checked_at?: string;
+    queue_eligible: boolean;
+    warnings: TrainingPreflightWarning[];
+    checked_at: string;
+}
+/** One method, algorithm, or adapter reported by the pinned training engine. */
+export interface TrainingCapabilityChoice {
+    id: string;
+    name: string;
+    enabled: boolean;
+    engine_supported: boolean;
+    disabled_reason?: string;
+    aliases?: string[];
+    supported_methods?: string[];
+    supported_algorithms?: string[];
+    dependencies?: string[];
+}
+/** JSON-schema-like description of one accepted config field. */
+export interface TrainingConfigFieldCapability {
+    name: string;
+    label: string;
+    type: 'integer' | 'number' | 'boolean' | 'string' | 'string_array' | 'string_or_string_array' | 'object';
+    default: unknown;
+    enabled: boolean;
+    disabled_reason?: string;
+    aliases?: string[];
+    enum?: string[];
+    minimum?: number;
+    maximum?: number;
+    exclusive_minimum?: boolean;
+    methods?: string[];
+    algorithms?: string[];
+    adapters?: string[];
+    description?: string;
+}
+/** Dynamic contract returned by GET /api/training/capabilities. */
+export interface TrainingCapabilities {
+    contract_version: string;
+    schema_version: string;
+    methods: TrainingCapabilityChoice[];
+    algorithms: TrainingCapabilityChoice[];
+    adapters: TrainingCapabilityChoice[];
+    fields: TrainingConfigFieldCapability[];
+    incompatibilities: Array<{
+        code: string;
+        when: Record<string, unknown>;
+        message: string;
+    }>;
+}
+/**
+ * Wallet balance (`GET /api/billing/wallet`).
+ *
+ * Two money figures, and they are NOT interchangeable: `balance_cents` is the
+ * deposited balance, while `available_balance_cents` is what can actually be
+ * spent right now (balance minus `active_holds_cents` and `accruing_cents`).
+ * Spend decisions read the second one.
+ *
+ * Auto top-up is FLAT, not nested, and the threshold/amount fields are in
+ * cents despite carrying no `_cents` suffix.
+ */
+export interface WalletBalance {
+    balance_cents: number;
+    /** Same figure formatted as "12.34"; convenience only. */
+    balance_dollars?: string;
+    available_balance_cents: number;
+    available_balance_dollars?: string;
+    /**
+     * Usage recorded per pod-minute but not yet closed into an hourly ledger
+     * row. `accrued_usage_cents` is the same number under its older name.
+     */
+    accruing_cents?: number;
+    accrued_usage_cents?: number;
+    /** Money reserved by open deposits/authorizations on running work. */
+    active_holds_cents?: number;
+    currency: string;
+    auto_topup_enabled?: boolean;
+    /** Threshold in CENTS, despite the field name. */
+    auto_topup_threshold?: number;
+    /** Top-up amount in CENTS, despite the field name. */
+    auto_topup_amount?: number;
+    low_balance_bar1_cents?: number;
+    low_balance_bar2_cents?: number;
+    low_balance_bar3_cents?: number;
+    has_payment_method?: boolean;
+    has_stripe_customer?: boolean;
+    total_deposited_cents?: number;
+    total_spent_cents?: number;
+    total_tax_cents?: number;
+    transaction_count?: number;
+}
+/** One billing ledger row. */
+export interface Transaction {
+    id: string;
+    wallet_id?: string;
+    /** credit | debit | refund */
+    type: string;
+    amount_cents: number;
+    tax_cents?: number;
+    balance_after_cents?: number;
+    source?: string;
+    source_ref?: string | null;
+    description?: string;
+    /**
+     * Coarse user-facing bucket: top_up, bonus, training_compute,
+     * inference_compute, compute, storage, training_deposit, inference_deposit,
+     * training_deposit_return, inference_deposit_return, deposit,
+     * deposit_return, card_refund, other. Presentation only, never money.
+     */
+    category?: string;
+    /**
+     * The resource this row was attributed to. Use these instead of a `job_id`
+     * field, which the ledger does not return.
+     */
+    resource_type?: string | null;
+    resource_id?: string | null;
+    status: string;
+    metadata?: Record<string, unknown>;
+    created_at: string;
+}
+/**
+ * Response from `GET /api/billing/transactions`.
+ *
+ * The rows are WRAPPED -- read `.transactions`, never the response itself.
+ */
+export interface TransactionListResponse {
+    transactions: Transaction[];
+    total: number;
+    limit: number;
+    offset: number;
+}
+/** Parameters for listing transactions. */
+export interface TransactionListParams {
+    /** Maximum number of transactions. Defaults to 50. */
+    limit?: number;
+    /** Pagination offset. Defaults to 0. */
+    offset?: number;
+}
+/** GPU pricing and availability info. */
+export interface GPUInfo {
+    gpu_type: string;
+    display_name: string;
+    vram_gb: number;
+    tier: string;
+    best_for: string;
+    max_gpu_count: number;
+    default_storage_gb: number;
+    param_range: string;
+    methods: string;
+    available: boolean;
+    available_count: number;
+    price_per_hour_cents: number;
+    price_display: string;
+}
+/** Response from the GPU pricing endpoint. */
+export interface GPUPricingResponse {
+    gpus: GPUInfo[];
+    stale?: boolean;
+    stale_message?: string;
+}
+/** Parameters understood by the authenticated training GPU-options endpoint. */
+export interface GPUOptionsParams {
+    modelId: string;
+    /** Requested model branch, tag, or commit; response returns the exact commit. */
+    modelRevision?: string;
+    /** Stored integration used for gated or private models. */
+    integrationId?: string;
+    /** Canonical adapter/train type. */
+    trainType?: AdapterType | string;
+    /** @deprecated Use trainType. */
+    adapter?: AdapterType | string;
+    method?: TrainingMethod | string;
+    rlhfType?: RLHFAlgorithm | string;
+    modelParamsB?: number;
+    modelActiveParamsB?: number;
+}
+/** One model-aware GPU option with live stock and total-price context. */
+export interface GPUOption {
+    gpu_type: string;
+    display_name: string;
+    vram_gb: number;
+    price_per_hour_cents: number;
+    available: boolean;
+    available_count: number;
+    max_gpu_count: number;
+    min_gpu_count: number;
+    required_count: number;
+    recommended_count: number;
+    total_price_per_hour_cents?: number;
+    default_storage_gb: number;
+    min_storage_gb: number;
+    selectable: boolean;
+    bookable: boolean;
+    reason?: string;
+    checked_at?: string;
+}
+/** Actionable alternative returned when no GPU option is currently bookable. */
+export interface GPUOptionSuggestion {
+    type: 'adapter' | 'smaller_model' | 'wait' | string;
+    adapter?: string;
+    adapter_label?: string;
+    gpu_type?: string;
+    gpu_display_name?: string;
+    gpu_count?: number;
+    price_per_hour_cents?: number;
+    message: string;
+}
+export interface GPUOptionsResponse {
+    options: GPUOption[];
+    /** Canonical owner/model identity. */
+    model_id: string;
+    /** Exact immutable 40-hex model commit used for sizing. */
+    model_revision: string;
+    model_params_b: number;
+    min_vram_gb: number;
+    min_storage_gb: number;
+    availability_known: boolean;
+    checked_at: string;
+    recommended?: {
+        gpu_type: string;
+        gpu_count: number;
+        storage_gb: number;
+        price_per_hour_cents: number;
+        total_price_per_hour_cents: number;
+    };
+    suggestions?: GPUOptionSuggestion[];
+}
+export type InferenceStatus = 'provisioning' | 'queued_capacity' | 'downloading_weights' | 'loading_model' | 'running' | 'degraded' | 'stopped' | 'paused_insufficient_funds' | 'crash_loop' | 'failed' | 'deleting' | 'deleted' | string;
+export type InferenceToolCallParser = 'deepseekv3' | 'deepseekv31' | 'deepseekv32' | 'glm' | 'glm45' | 'glm47' | 'gpt-oss' | 'kimi_k2' | 'lfm2' | 'llama3' | 'mimo' | 'mistral' | 'omega17' | 'omega17_exp' | 'omega17_vl_exp' | 'pythonic' | 'qwen' | 'qwen25' | 'qwen3_coder' | 'step3' | 'step3p5' | 'minimax-m2' | 'trinity' | 'interns1' | 'hermes' | 'gigachat3' | 'usf_omega' | 'usf_milli' | 'usf_mini';
+export type InferenceReasoningParser = 'deepseek-r1' | 'deepseek-v3' | 'glm45' | 'gpt-oss' | 'kimi' | 'kimi_k2' | 'mimo' | 'qwen3' | 'qwen3-thinking' | 'minimax' | 'minimax-append-think' | 'step3' | 'step3p5' | 'mistral' | 'nemotron_3' | 'interns1' | 'usf_omega' | 'usf_milli' | 'usf_mini';
+/** How the tool-call verdict was reached and what callers can expect. */
+export type InferenceToolCallMode = 'native' | 'best_effort' | 'off' | 'unsupported';
+export interface InferenceServingConfig {
+    /**
+     * 'auto' (default) derives the format from the model's own chat template;
+     * 'off' disables tool calling for this deployment; a concrete family name
+     * forces that parser. Unknown names are rejected before GPU allocation.
+     */
+    tool_call_parser?: InferenceToolCallParser | 'auto' | 'off';
+    /** Same semantics as tool_call_parser, for reasoning extraction. */
+    reasoning_parser?: InferenceReasoningParser | 'auto' | 'off';
+    /**
+     * Custom chat template (Jinja text, 64 KB max). Validated at save time and
+     * applied at the next restart. A template with a known tool format enables
+     * full tool support; an unknown format runs tools in best-effort mode.
+     */
+    chat_template?: string;
+    [key: string]: unknown;
+}
+export interface InferenceCreateParams {
+    name: string;
+    /**
+     * Deployment source: a verified training checkpoint, or 'hf_model' — the
+     * legacy wire name for a base model from the Run BiOS catalog (the platform's
+     * own hosted registry, never a live Hugging Face reference).
+     */
+    sourceType: 'checkpoint' | 'hf_model';
+    sourceJobId?: string;
+    sourceCheckpointId?: string;
+    /**
+     * Catalog model id (e.g. "meta-llama/Llama-3.1-8B-Instruct"), required with
+     * sourceType 'hf_model'. Legacy field name: the model must be hosted on
+     * Run BiOS (see client.models.search) — arbitrary Hugging Face ids are rejected.
+     */
+    hfModelId?: string;
+    /** Exact 40-hex commit returned by deployment preflight. */
+    hfModelRevision?: string;
+    /**
+     * @deprecated Legacy field kept for wire compatibility. Catalog models are
+     * pre-mirrored and never gated, so no integration is needed to deploy them.
+     */
+    hfIntegrationId?: string;
+    baseModelId?: string;
+    /** Exact base-model commit returned by deployment preflight. */
+    baseModelRevision?: string;
+    /** Optional assertion; the API derives the authoritative mode from the verified source artifact. */
+    servingMode?: 'full' | 'adapter' | 'merged';
+    /**
+     * SERVER-DERIVED and immutable, exactly like `servingMode` above: the
+     * platform reads the task off the resolved model (chat for chat and vision
+     * models, completion for a base checkpoint with no chat template, embedding,
+     * rerank) and REJECTS a value that disagrees with its own derivation with
+     * 400 "This model's serving mode is configured automatically from the model
+     * itself". Whether a given value is accepted therefore depends on the MODEL,
+     * which only the server can resolve, so the SDK does not pre-judge it: those
+     * four are the canonical spellings, the server also accepts its own variants
+     * (plurals, any case, surrounding space), and the value is forwarded
+     * untouched for the server to rule on. Omit it and read the derived task back
+     * from preflight's `canonical_request.model_task`.
+     */
+    modelTask?: string;
+    /**
+     * SERVER-DERIVED. Accepted on the wire for backward compatibility and then
+     * IGNORED: image-input support comes from the resolved model's own config
+     * (vision_config / image tokens), never from the client. The SDK does not
+     * forward it; read `supports_images` back from the deployment instead.
+     */
+    supportsImages?: boolean;
+    gpuType: string;
+    gpuCount: number;
+    /** Primary plus ranked fallback GPU types; queueing requires 3-5 distinct types. */
+    gpuPriorities?: GPUChoice[];
+    /** Deployment serving currently supports only the secure capacity tier. */
+    gpuTier?: 'secure';
+    /** Explicit consent to wait up to seven days when the selected SKU is unavailable. */
+    allowCapacityQueue?: boolean;
+    /** Maximum accepted total hourly price across all selected GPUs, in cents. */
+    maxPriceHourCents?: number;
+    storageGb?: number;
+    /**
+     * Serving context window in tokens. OMIT IT and the server pre-fills
+     * `min(nativeMax, 262144)`; the window is adjustable only when the model's
+     * native max exceeds the 32,768 floor (which is also the fallback when the
+     * native window is unknown), and it can NEVER exceed the model's own native
+     * max -- a larger value is rejected with 400 `context_length N exceeds the
+     * model's maximum of M`. Read the ceiling from
+     * `client.models.nativeMaxContext(modelId)` before deploying, and read it
+     * back from `native_max_context` on the deployment detail.
+     *
+     * This is a SIZING input: a larger window means a larger KV cache and can
+     * raise the minimum GPU count for the same model.
+     */
+    contextLength?: number;
+    quant?: string;
+    servingConfig?: InferenceServingConfig;
+}
+export interface InferenceUpdateParams {
+    allowCapacityQueue?: boolean;
+    maxPriceHourCents?: number;
+    /**
+     * Raise or lower the serving window. Same policy as on create: never above
+     * the model's native max (read it from `native_max_context` on the
+     * deployment detail, or `client.models.nativeMaxContext(modelId)`), and
+     * adjustable only when that native max exceeds the 32,768 floor. Raising it
+     * enlarges the KV cache and can require more GPUs than the deployment holds.
+     */
+    contextLength?: number;
+    quant?: string;
+    servingConfig?: InferenceServingConfig;
+}
+/**
+ * One row of the deployment LIST (`GET /api/inference`).
+ *
+ * The list is a lean grid projection and is NOT the same shape as the detail:
+ * it carries the model handle as `model_ref` (there is no `model` key -- that
+ * only exists on the detail, where it aliases the name) plus per-deployment
+ * usage counters, and it omits everything the detail resolves per row
+ * (context_length, native_max_context, quantization, serving_config, endpoint
+ * key prefix, queue block, connection, ...). Call `get(id)` for those.
+ */
+export interface InferenceDeploymentSummary {
+    id: string;
+    name: string;
+    status: InferenceStatus;
+    status_reason?: string;
+    /** Compatibility alias of status_reason. */
+    error_code?: string;
+    desired_state: 'running' | 'stopped';
+    source_type: 'checkpoint' | 'hf_model';
+    /**
+     * The deployment's model repo id (hf_model_id, else base_model_id, else "").
+     * The detail exposes the same handle as hf_model_id / base_model_id.
+     */
+    model_ref?: string;
+    architecture?: string;
+    params_total_b?: number;
+    is_moe?: boolean;
+    model_task?: 'chat' | 'completion' | 'embedding' | 'rerank';
+    supports_images?: boolean;
+    gpu_type: string;
+    gpu_count: number;
+    gpu_tier: 'secure';
+    gpu_provider?: string;
+    gpu_region?: string;
+    cost_per_hour_cents?: number;
+    endpoint_url?: string;
+    created_at: string;
+    started_at?: string | null;
+    stopped_at?: string | null;
+    /** Lifetime counters from the deployment's own metering rollup. */
+    requests_total?: number;
+    prompt_tokens_total?: number;
+    generation_tokens_total?: number;
+    gpu_seconds_total?: number;
+    /** Streaming-only mean TTFT; null until a streamed request has landed. */
+    avg_ttft_ms?: number | null;
+    /**
+     * Billed charge from one batched billing lookup; null when billing was
+     * unreachable or slow (a money read never blocks the list).
+     */
+    charged_cents?: number | null;
+    /** History view (`include_terminated`) only: how the lifecycle closed, and when. */
+    disposition?: string;
+    deleted_at?: string | null;
+    ended_at?: string | null;
+}
+/**
+ * One deployment DETAIL (`GET /api/inference/{id}`). See
+ * {@link InferenceDeploymentSummary} for the narrower list row.
+ */
+export interface InferenceDeployment {
+    id: string;
+    /**
+     * The public model handle is the workspace-unique deployment NAME (the detail
+     * aliases `name` here). The MODEL repo id is hf_model_id / base_model_id; the
+     * list row calls it `model_ref`.
+     */
+    name: string;
+    model?: string;
+    workspace_id?: string;
+    status: InferenceStatus;
+    /** Stable machine-readable terminal reason; queue expiry is `queue_expired`. */
+    status_reason?: string | null;
+    /** Compatibility alias for status_reason. */
+    error_code?: string | null;
+    desired_state: 'running' | 'stopped';
+    /** 'hf_model' is the legacy wire name for a Run BiOS-catalog base model. */
+    source_type: 'checkpoint' | 'hf_model';
+    source_job_id?: string;
+    source_checkpoint_id?: string;
+    /** Catalog model id. Legacy field name — hosted on Run BiOS, not live Hugging Face. */
+    hf_model_id?: string;
+    hf_model_revision?: string | null;
+    base_model_id?: string;
+    base_model_revision?: string;
+    immutable_base_model_source?: string;
+    serving_mode?: 'full' | 'adapter' | 'merged';
+    supports_tool_calls?: boolean;
+    tool_call_parser?: InferenceToolCallParser | null;
+    reasoning_parser?: InferenceReasoningParser | null;
+    tool_call_mode?: InferenceToolCallMode;
+    tool_calls_unsupported_reason?: string;
+    tool_calls_note?: string;
+    supports_reasoning?: boolean;
+    tool_call_source?: string;
+    /**
+     * False for a base model with no chat template -- /v1/chat/completions
+     * raises a tokenizer error there; use text completions instead.
+     */
+    chat_capable?: boolean;
+    is_base_model?: boolean;
+    /** SERVER-DERIVED (see {@link InferenceCreateParams}). */
+    model_task?: 'chat' | 'completion' | 'embedding' | 'rerank';
+    architecture?: string;
+    model_type?: string;
+    params_total_b?: number;
+    params_active_b?: number;
+    is_moe?: boolean;
+    quantization?: string;
+    quant_locked?: boolean;
+    weight_bytes?: number;
+    /** The window this deployment runs with. */
+    context_length?: number;
+    /**
+     * The model's native ceiling, which `context_length` can never be raised
+     * past. 0 when the native max is unknown. LIST rows do not carry this.
+     */
+    native_max_context?: number;
+    storage_gb?: number;
+    serving_config?: Record<string, unknown>;
+    /**
+     * True while the requested settings differ from the applied_* values the
+     * engine is actually running.
+     */
+    config_dirty?: boolean;
+    applied_context_length?: number | null;
+    applied_quantization?: string | null;
+    applied_serving_config?: Record<string, unknown> | null;
+    supports_images?: boolean;
+    /** Weight-download progress while status is downloading_weights. */
+    download_progress?: Record<string, unknown>;
+    /** Sanitized pre-agent boot phase, present only while provisioning. */
+    boot_progress?: Record<string, unknown>;
+    boot_elapsed_seconds?: number;
+    failed_phase?: string;
+    restart_count?: number;
+    last_heartbeat_at?: string | null;
+    auto_sleep_minutes?: number | null;
+    /** Segmented two-way connection health (push / pull / tunnel). */
+    connection?: Record<string, unknown>;
+    /**
+     * The AUTHORITATIVE set of lifecycle actions this deployment accepts right
+     * now, computed from the same guards resume/stop/restart/delete enforce.
+     */
+    available_actions?: Record<string, boolean>;
+    eligible_gpu_choice_count?: number;
+    gpu_type: string;
+    gpu_count: number;
+    gpu_tier: 'secure';
+    gpu_provider?: string;
+    gpu_region?: string;
+    cost_per_hour_cents?: number;
+    max_price_hour_cents?: number;
+    allow_capacity_queue?: boolean;
+    queued_since?: string | null;
+    queue_expires_at?: string | null;
+    queue_position?: number | null;
+    gpu_priorities?: Array<{
+        gpu_type: string;
+        gpu_count: number;
+        provider?: string;
+        region?: string;
+        tier?: 'secure';
+    }>;
+    selected_gpu_rank?: number | null;
+    queue?: InferenceQueue | null;
+    provision_generation?: number;
+    restart_generation?: number;
+    restart_state?: 'idle' | 'in_progress' | 'waiting_ready';
+    restart_requested_at?: string | null;
+    restart_completed_at?: string | null;
+    restart_claimed_until?: string | null;
+    restart_last_error?: string | null;
+    wallet_authorization_status?: 'active' | 'captured' | 'released' | 'refunded' | 'expired' | string;
+    billing_contract_version?: number;
+    endpoint_url?: string;
+    inference_key_prefix?: string;
+    last_error?: string;
+    created_at: string;
+    started_at?: string | null;
+    stopped_at?: string | null;
+    notification_delivery?: InferenceNotificationSummary;
+}
+export type InferenceNotificationState = 'pending' | 'sending' | 'delivered' | 'dead_letter';
+export interface InferenceNotification {
+    id: number;
+    deployment_id: string;
+    event_type: string;
+    template: string;
+    template_data: Record<string, string>;
+    idempotency_key: string;
+    state: InferenceNotificationState;
+    attempt_count: number;
+    last_error?: string | null;
+    created_at: string;
+    updated_at: string;
+    delivered_at?: string | null;
+    dead_lettered_at?: string | null;
+}
+export interface InferenceNotificationSummary {
+    pending: number;
+    sending: number;
+    delivered: number;
+    dead_letter: number;
+}
+export interface InferenceNotificationListResponse {
+    notifications: InferenceNotification[];
+}
+/**
+ * 202 body of a book-before-reveal create: no id, no key — only the opaque
+ * handle to poll (`inference.getBooking` / `inference.waitForBooking`).
+ */
+export interface InferenceBookingAccepted {
+    booking: {
+        handle: string;
+        status: 'booking';
+        estimated_seconds: number;
+        poll_url: string;
+    };
+}
+export interface InferenceCreateResponse {
+    id: string;
+    deployment_id: string;
+    model: string;
+    workspace_id: string;
+    endpoint_url: string;
+    status: InferenceStatus;
+    /** Returned exactly once. Store it securely. */
+    inference_key: string;
+    inference_key_prefix: string;
+    hf_model_revision?: string | null;
+    base_model_revision: string;
+    immutable_base_model_source: string;
+    supports_tool_calls: boolean;
+    tool_call_parser?: InferenceToolCallParser | null;
+    reasoning_parser?: InferenceReasoningParser | null;
+    tool_call_mode?: InferenceToolCallMode;
+    tool_calls_unsupported_reason?: string;
+    tool_calls_note?: string;
+    gpu: string;
+    gpu_provider: string;
+    gpu_region: string;
+    gpu_tier: 'secure';
+    estimated_hourly_cents: number;
+    max_price_hour_cents: number;
+    /** Runtime-supported ranked choices whose frozen price is within the accepted cap. */
+    eligible_gpu_choice_count: number;
+    authorized_cents: number;
+    gpu_priorities: Array<{
+        gpu_type: string;
+        gpu_count: number;
+        provider?: string;
+        region?: string;
+        tier?: 'secure';
+    }>;
+}
+export type InferenceListStatusFilter = 'all' | 'running' | 'provisioning' | 'stopped' | 'failed' | 'queued_capacity' | 'degraded' | 'paused_insufficient_funds' | 'crash_loop' | 'downloading_weights' | 'loading_model';
+export interface InferenceListParams {
+    /** Bounded page size. The server defaults to 50 and caps at 200. */
+    limit?: number;
+    /** Opaque nextCursor returned by the preceding page. */
+    cursor?: string;
+    status?: InferenceListStatusFilter;
+    /** Case-insensitive deployment-name prefix, maximum 120 characters. */
+    search?: string;
+}
+/** One bounded keyset page of {@link InferenceDeploymentSummary} rows. */
+export interface InferenceListResponse {
+    deployments: InferenceDeploymentSummary[];
+    has_more: boolean;
+    next_cursor?: string | null;
+    limit: number;
+}
+export interface InferenceQueueChoice {
+    choice_id?: string;
+    rank: number;
+    gpu_type: string;
+    gpu_count: number;
+    provider?: string;
+    region?: string;
+    tier?: 'secure';
+    price_per_gpu_hour_cents?: number;
+    total_price_hour_cents?: number;
+    eligible: boolean;
+    selected: boolean;
+}
+export interface InferenceQueue {
+    request_id?: string | null;
+    state?: string | null;
+    position?: number | null;
+    position_scope?: 'shared_capacity_fair_queue' | 'shared_capacity_position_unavailable';
+    position_estimated?: boolean;
+    position_as_of?: string | null;
+    position_lower_bound?: number | null;
+    position_truncated?: boolean;
+    position_unavailable_reason?: string;
+    priority?: number;
+    enqueue_sequence?: number | null;
+    deadline_at?: string | null;
+    max_price_hour_cents?: number;
+    eligible_gpu_choice_count?: number;
+    all_choices?: InferenceQueueChoice[];
+    selected_choice?: InferenceQueueChoice | null;
+    allocation_claimed_until?: string | null;
+    reservation_expires_at?: string | null;
+    provision_retry_at?: string | null;
+    last_error?: string | null;
+}
+export interface InferenceLifecycleResponse {
+    status: string;
+    action: 'stop' | 'resume' | 'restart';
+    in_place?: boolean;
+    restart_generation?: number;
+}
+export interface InferenceDeleteResponse {
+    status: 'deleted' | 'deleting';
+    detail?: string;
+}
+export interface InferenceUpdateResponse {
+    status: 'updated' | string;
+    restart_required: boolean;
+}
+export interface InferenceGPUOptionMarket {
+    availability_status: 'available' | 'out_of_stock' | 'unknown';
+    /** Null/omitted when live stock could not be verified. */
+    available_count?: number | null;
+    price_per_gpu_hour_cents: number;
+    minimum_configuration_hour_cents: number;
+    recommended_configuration_hour_cents: number;
+}
+export interface InferenceGPUOption {
+    gpu_type: string;
+    vram_gb: number;
+    min_gpus: number;
+    recommended_gpus: number;
+    valid_counts?: number[];
+    /**
+     * valid_counts filtered to counts live stock can fill RIGHT NOW in a single
+     * placement (book-first contract). Absent when availability is unknown — never
+     * fabricated. Offer/submit only these when present.
+     */
+    bookable_counts?: number[];
+    selectable: boolean;
+    reason?: string;
+    /**
+     * Machine discriminator for an unselectable option: `gpu_unsupported` when
+     * the serving engine cannot run this card at all (size and count are both
+     * irrelevant), otherwise the memory verdict (`model_too_large`).
+     */
+    reason_code?: string;
+    market?: InferenceGPUOptionMarket;
+}
+export interface InferenceGPUPlacementOption extends InferenceGPUOption {
+    provider: string;
+    region: string;
+    tier: 'secure';
+    market: InferenceGPUOptionMarket;
+}
+export interface InferenceGPUAlternative {
+    gpu_type: string;
+    gpu_count: number;
+    vram_gb: number;
+    price_hour_cents: number;
+    availability_status: 'available' | 'out_of_stock' | 'unknown';
+}
+export interface InferenceGPUOptionsParams {
+    /**
+     * MODEL-ADDRESSED sizing (recommended): the SERVER resolves the model facts
+     * from this model id (optionally with `revision`) and computes
+     * min_gpus/valid_counts/bookable_counts — the same single implementation the
+     * create gate enforces. When set, the deprecated client-fact params below
+     * are unnecessary.
+     */
+    model?: string;
+    revision?: string;
+    /** Size from an existing deployment's pinned facts instead of a model id. */
+    inferenceId?: string;
+    /**
+     * @deprecated Legacy field kept for wire compatibility — catalog models are
+     * pre-mirrored and never gated, so no integration is needed with `model`.
+     */
+    hfIntegrationId?: string;
+    /** DEPRECATED client-fact path; required only when `model`/`inferenceId` are absent. */
+    paramsB?: number;
+    activeParamsB?: number;
+    isMoe?: boolean;
+    quant?: string;
+    /**
+     * SIZING INPUT, not a validated field: this endpoint sizes whatever window
+     * you pass and never checks it against the model's native max. Omit it to
+     * size the window a deployment would actually get (`min(nativeMax, 262144)`,
+     * falling back to the 32,768 floor when the native window is unknown).
+     * Passing a value ABOVE the native max returns honest sizing for an
+     * IMPOSSIBLE window -- a larger `min_gpus` for a deployment the create gate
+     * will reject with 400 `context_length N exceeds the model's maximum of M`.
+     * Read the ceiling from `client.models.nativeMaxContext(modelId)` before
+     * trusting a `min_gpus` computed at a custom window.
+     */
+    contextLength?: number;
+    kvHeads?: number;
+    numLayers?: number;
+    kvLayers?: number;
+    headDim?: number;
+    attention?: 'gqa' | 'mla';
+    numAttentionHeads?: number;
+    kvLoraRank?: number;
+    qkRopeHeadDim?: number;
+    gpuTier?: 'secure';
+}
+export interface InferenceGPUOptionsResponse {
+    options: InferenceGPUOption[];
+    /** Exact provider/region/tier markets; clients must select from this list. */
+    placements: InferenceGPUPlacementOption[];
+    cheapest_recommended?: InferenceGPUOption | null;
+    best_available?: InferenceGPUAlternative | null;
+    alternatives?: InferenceGPUAlternative[];
+    availability_known: boolean;
+    availability_checked_at?: string;
+}
+export interface InferencePreflightWarning {
+    code: string;
+    message: string;
+}
+export interface InferenceCanonicalRequest {
+    name: string;
+    /** 'hf_model' is the legacy wire name for a Run BiOS-catalog base model. */
+    source_type: 'checkpoint' | 'hf_model';
+    source_job_id?: string;
+    source_checkpoint_id?: string;
+    /** Catalog model id. Legacy field name — hosted on Run BiOS, not live Hugging Face. */
+    hf_model_id?: string;
+    hf_model_revision?: string;
+    /** Legacy field — catalog models never need an integration. */
+    hf_integration_id?: string;
+    base_model_id: string;
+    base_model_revision: string;
+    serving_mode?: 'full' | 'adapter' | 'merged';
+    model_task?: 'chat' | 'completion' | 'embedding' | 'rerank';
+    supports_images?: boolean;
+    gpu_type: string;
+    gpu_count: number;
+    gpu_priorities?: Array<{
+        gpu_type: string;
+        gpu_count: number;
+        provider?: string;
+        region?: string;
+        tier?: 'secure';
+    }>;
+    allow_capacity_queue: boolean;
+    max_price_hour_cents: number;
+    [key: string]: unknown;
+}
+export interface InferencePreflightResponse {
+    valid: boolean;
+    contract_version: 'deployment.v3' | string;
+    request_hash: string;
+    workspace_id: string;
+    canonical_request: InferenceCanonicalRequest;
+    model: {
+        repo_id: string;
+        revision: string;
+        immutable_source: string;
+        architecture: string;
+        model_type: string;
+        params_total_b: number;
+        params_active_b: number;
+        is_moe: boolean;
+        native_max_context: number;
+        quant_locked: boolean;
+        supports_tool_calls: boolean;
+        tool_call_parser?: InferenceToolCallParser | null;
+        reasoning_parser?: InferenceReasoningParser | null;
+        tool_call_mode?: InferenceToolCallMode;
+        tool_calls_unsupported_reason?: string;
+        tool_calls_note?: string;
+    };
+    selected_gpu: {
+        gpu_type: string;
+        gpu_count: number;
+        provider: string;
+        region: string;
+        tier: 'secure';
+        availability_status: 'available' | 'out_of_stock' | 'unknown';
+        available_count: number;
+        price_per_gpu_hour_cents: number;
+        total_price_hour_cents: number;
+    };
+    gpu_options: InferenceGPUOption[];
+    gpu_placements: InferenceGPUPlacementOption[];
+    alternatives: InferenceGPUAlternative[];
+    best_available?: InferenceGPUAlternative | null;
+    availability_known: boolean;
+    availability_checked_at: string;
+    eligible_gpu_choice_count: number;
+    supports_tool_calls: boolean;
+    tool_call_parser?: InferenceToolCallParser | null;
+    reasoning_parser?: InferenceReasoningParser | null;
+    tool_call_mode?: InferenceToolCallMode;
+    tool_calls_unsupported_reason?: string;
+    tool_calls_note?: string;
+    queue_eligible: boolean;
+    queue_required: boolean;
+    billing: {
+        max_price_hour_cents: number;
+        authorization_amount_cents: number;
+        capture_amount_cents: number;
+        authorization_ttl_seconds: number;
+        authorization_mutates_balance: false;
+    };
+    warnings: InferencePreflightWarning[];
+}
+/** Adapter compatibility info. */
+export interface AdapterCompatibility {
+    id: string;
+    name: string;
+    fullName: string;
+    category: 'popular' | 'advanced' | 'specialized';
+    description: string;
+    compatible: boolean;
+    reason: string | null;
+    defaultConfig: Record<string, unknown>;
+    rlhfAlgorithms: string[];
+}
+/** Response from the adapter compatibility endpoint. */
+export interface AdapterCompatibilityResponse {
+    architecture: string;
+    architectureName: string;
+    type: 'llm' | 'vlm';
+    trainingMethod: string;
+    rlhfAlgorithm: string | null;
+    unsupported: string | null;
+    gated: boolean;
+    adapters: AdapterCompatibility[];
+    compatibleCount: number;
+    incompatibleCount: number;
+}
+/** One entry in the supported-architecture registry. */
+export interface SupportedArchitecture {
+    /** For inference: the architecture class (e.g. "LlamaForCausalLM"). For training: the arch key (e.g. "llama"). */
+    architecture: string;
+    display_name: string;
+    /** Comma-separated model_type aliases this entry covers. */
+    model_types: string;
+    enabled: boolean;
+    notes: string;
+}
+/** Which registry to read. */
+export type ArchitectureScope = 'inference' | 'training';
+/** Response from getSupportedArchitectures. When `count` is 0 the registry is empty (nothing is explicitly gated). */
+export interface SupportedArchitecturesResponse {
+    scope: ArchitectureScope;
+    architectures: SupportedArchitecture[];
+    count: number;
+}
+/** Parameters for checking adapter compatibility. */
+export interface AdapterCompatibilityParams {
+    /** Architecture key (e.g. "llama", "qwen2"). */
+    architecture?: string;
+    /** The model's model_type for automatic architecture detection. */
+    modelType?: string;
+    /** Training method. Defaults to "sft". */
+    trainingMethod?: TrainingMethod;
+    /** RLHF algorithm (relevant when trainingMethod is "rlhf"). */
+    rlhfAlgorithm?: RLHFAlgorithm;
+}
+/** An API key. */
+export interface ApiKey {
+    id: string;
+    name: string;
+    prefix: string;
+    /** The full key value — only present on creation. */
+    key?: string;
+    scopes: ApiKeyScope[];
+    scope_preset: string;
+    created_at: string;
+    last_used_at?: string | null;
+    expires_at?: string | null;
+    status: 'active' | 'revoked' | 'expired';
+}
+/** Valid API key permission scope. */
+export type ApiKeyScope = 'models:read' | 'datasets:read' | 'datasets:write' | 'training:read' | 'training:write' | 'billing:read' | 'deployments:read' | 'deployments:write' | 'analytics:read' | 'integrations:read' | 'integrations:write' | 'serverless';
+/** Result of introspecting an API key — shows what it can do. */
+export interface ApiKeyIntrospection {
+    auth_type: 'api_key' | 'jwt';
+    key_id: string | null;
+    key_name: string | null;
+    key_prefix: string | null;
+    status: string;
+    org: {
+        id: string;
+        name: string;
+    };
+    workspace: {
+        id: string;
+        name: string;
+    };
+    user: {
+        id: string;
+        name: string;
+        email: string;
+        role: string;
+    };
+    scopes: ApiKeyScope[];
+    scope_preset: string;
+    scope_details: Array<{
+        scope: ApiKeyScope;
+        description: string;
+        tools: string[];
+        sdk_methods: string[];
+    }>;
+    allowed_mcp_tools: string[];
+    allowed_sdk_methods: string[];
+    rate_limit: {
+        requests_per_minute: number;
+        requests_per_hour: number;
+    };
+    expires_at: string | null;
+    created_at: string;
+    last_used_at: string | null;
+}
+/** An organization. */
+export interface Organization {
+    id: string;
+    name: string;
+    avatar_url?: string;
+    created_at?: string;
+}
+/** An organization member. */
+export interface OrgMember {
+    user_id: string;
+    name: string;
+    email: string;
+    role: string;
+    avatar_url?: string;
+    joined_at?: string;
+}
+/** An organization invite. */
+export interface OrgInvite {
+    id: string;
+    email: string;
+    role: string;
+    status: string;
+    created_at: string;
+    expires_at?: string;
+}
+/** A workspace within an organization. */
+export interface Workspace {
+    id: string;
+    name: string;
+    description?: string;
+    org_id: string;
+    created_at?: string;
+    updated_at?: string;
+}
+/** A HuggingFace integration connection. */
+export interface Integration {
+    id: string;
+    provider: string;
+    label: string;
+    hf_username: string;
+    key_last4: string;
+    scope: string;
+    status: string;
+    created_at?: string;
+}
+/** Parameters for creating an integration. */
+export interface IntegrationCreateParams {
+    /** Display label for this integration. */
+    label: string;
+    /** HuggingFace API key. */
+    apiKey: string;
+    /** Provider name. Defaults to "huggingface". */
+    provider?: string;
+}
+/** Storage usage info. */
+export interface StorageUsage {
+    total_bytes: number;
+    object_count: number;
+    by_type?: Record<string, number>;
+}
+/** A storage object. */
+export interface StorageObject {
+    id: string;
+    type: string;
+    name: string;
+    size_bytes: number;
+    created_at: string;
+}