bios-sdk 0.1.0-dev.1

package/dist/types.d.ts

@@ -0,0 +1,1466 @@
+/** Configuration for initializing the BIOS SDK client. */
+export interface BiOSConfig {
+    /** API key for authentication (prefix: usf-). 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. Defaults to the canonical https://api-dev.usbios.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.usbios.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;
+}
+/** A model returned from the HuggingFace-backed model search. */
+export interface Model {
+    /** Full HuggingFace model ID (e.g. "meta-llama/Llama-3.1-8B"). */
+    id: string;
+    /** Model author / organization. */
+    author: string;
+    /** Human-readable model name. */
+    name: string;
+    /** Total parameter count in billions. */
+    totalParams: number;
+    /** Active parameter count in billions (differs from total for MoE models). */
+    activeParams: number;
+    /** Architecture type: "dense" or "moe". */
+    architecture: 'dense' | 'moe';
+    /** Model type: "llm" or "vlm". */
+    modelType: 'llm' | 'vlm';
+    /** HuggingFace model_type from config.json. */
+    hfModelType: string | null;
+    /** Download count on HuggingFace. */
+    downloads: number;
+    /** Like count on HuggingFace. */
+    likes: number;
+    /** Whether this is a private model. */
+    isPrivate: boolean;
+    /** Whether this is an adapter/LoRA model. */
+    isAdapter: boolean;
+}
+/** Parameters for searching models. */
+export interface ModelSearchParams {
+    /** Search query string. */
+    query?: string;
+    /** Filter by model type: "all", "llm", or "vlm". */
+    type?: 'all' | 'llm' | 'vlm';
+    /** Pagination offset. Defaults to 0. */
+    offset?: number;
+    /** Number of results to return. Max 50, defaults to 20. */
+    limit?: number;
+    /** Minimum parameter count in billions. */
+    minParams?: number;
+    /** Maximum parameter count in billions. */
+    maxParams?: number;
+    /** Sort order: "downloads", "likes", or "trending". */
+    sort?: 'downloads' | 'likes' | 'trending';
+    /** Filter by author/organization. */
+    author?: string;
+    /** Visibility filter: "all", "public", or "private". */
+    visibility?: 'all' | 'public' | 'private';
+    /** Model kind: "full" (base models only) or "adapter". */
+    kind?: 'full' | 'adapter';
+    /** HuggingFace integration ID for accessing private models. */
+    integrationId?: string;
+}
+/** Response from a model search. */
+export interface ModelSearchResponse {
+    models: Model[];
+    total: number;
+    offset: number;
+    limit: number;
+    hasMore: boolean;
+    hfUsername: string;
+}
+/** Model configuration from HuggingFace config.json. */
+export interface ModelConfig {
+    /** Full HuggingFace 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' | 'provisioning' | 'preparing' | 'starting' | 'downloading' | 'running' | 'completed' | 'failed' | 'saving' | 'stopped' | 'stopping' | 'resuming' | 'cancelled';
+/** Status values accepted by GET /api/training/jobs?status=. */
+export type TrainingStatusFilter = 'pending' | 'queued' | 'provisioning' | 'preparing' | 'starting' | 'running' | '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;
+    /** HuggingFace model ID to fine-tune. */
+    model: string;
+    /** Optional Hugging Face 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;
+    /** HuggingFace 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 from the pod, or from historical medians. */
+    eta_confidence?: 'measured' | 'historical';
+    /** Most recent per-phase update time. */
+    last_phase_update_at?: string;
+    /** The current machine attempt id. */
+    attempt_id?: string;
+    /** The provisioned pod id for the current attempt. */
+    pod_id?: string;
+    /** Last time the pod pushed a callback. */
+    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;
+    image_compatibility: {
+        minimum: string;
+        maximum_exclusive: string;
+    };
+    methods: TrainingCapabilityChoice[];
+    algorithms: TrainingCapabilityChoice[];
+    adapters: TrainingCapabilityChoice[];
+    fields: TrainingConfigFieldCapability[];
+    incompatibilities: Array<{
+        code: string;
+        when: Record<string, unknown>;
+        message: string;
+    }>;
+}
+/** Wallet balance information. */
+export interface WalletBalance {
+    balance_cents: number;
+    available_cents: number;
+    pending_charges_cents: number;
+    currency: string;
+    auto_topup?: {
+        enabled: boolean;
+        threshold_cents: number;
+        amount_cents: number;
+    };
+}
+/** A billing transaction record. */
+export interface Transaction {
+    id: string;
+    type: string;
+    amount_cents: number;
+    description?: string;
+    status: string;
+    created_at: string;
+    job_id?: string;
+}
+/** 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 Hugging Face branch, tag, or commit; response returns the exact commit. */
+    modelRevision?: string;
+    /** Stored Hugging Face integration used for gated or private repositories. */
+    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 Hugging Face owner/repository identity. */
+    model_id: string;
+    /** Exact immutable 40-hex Hugging Face 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;
+    sourceType: 'checkpoint' | 'hf_model';
+    sourceJobId?: string;
+    sourceCheckpointId?: string;
+    hfModelId?: string;
+    /** Exact 40-hex commit returned by deployment preflight. */
+    hfModelRevision?: string;
+    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';
+    modelTask?: 'chat' | 'completion' | 'embedding' | 'rerank';
+    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;
+    contextLength?: number;
+    quant?: string;
+    servingConfig?: InferenceServingConfig;
+}
+export interface InferenceUpdateParams {
+    allowCapacityQueue?: boolean;
+    maxPriceHourCents?: number;
+    contextLength?: number;
+    quant?: string;
+    servingConfig?: InferenceServingConfig;
+}
+export interface InferenceDeployment {
+    id: string;
+    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';
+    source_type: 'checkpoint' | 'hf_model';
+    source_job_id?: string;
+    source_checkpoint_id?: string;
+    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;
+    model_task?: 'chat' | 'completion' | 'embedding' | 'rerank';
+    architecture?: string;
+    params_total_b?: number;
+    is_moe?: boolean;
+    quantization?: string;
+    context_length?: 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[];
+}
+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;
+}
+export interface InferenceListResponse {
+    deployments: InferenceDeployment[];
+    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 provider inventory 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[];
+    selectable: boolean;
+    reason?: 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 {
+    paramsB: number;
+    activeParamsB?: number;
+    isMoe?: boolean;
+    quant?: string;
+    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;
+    source_type: 'checkpoint' | 'hf_model';
+    source_job_id?: string;
+    source_checkpoint_id?: string;
+    hf_model_id?: string;
+    hf_model_revision?: string;
+    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 HF architecture class (e.g. "LlamaForCausalLM"). For training: the arch key (e.g. "llama"). */
+    architecture: string;
+    display_name: string;
+    /** Comma-separated HF 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;
+    /** HuggingFace 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';
+/** 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;
+}