runbios-sdk 0.2.13 → 0.2.14-dev.244

package/README.md

@@ -186,6 +186,35 @@ if (answer) {
 Streaming billing is charged server-side on completed usage; the SDK only needs
 to request `usage` where the endpoint exposes it (no client change).
 
+#### Workspace serverless usage and limits (read-only)
+
+A workspace-bound platform key or hosted OAuth grant with `analytics:read` can
+read workspace RPM/spend settings and usage through the control-plane credential.
+`serverless` alone allows inference but does not grant analytics. Set
+`RUNBIOS_API_KEY` to an analytics:read workspace key (or pass it in the SDK
+config). A dedicated serving key is not a control-plane credential. No
+workspace id is accepted by these methods: the gateway resolves the bound workspace and checks access on
+every call. Key creation/listing, per-key usage, org-wide totals and all RPM or
+spend-cap writes remain in the JWT-authenticated console.
+
+```typescript
+const reporting = new RunBiOS({});
+const limits = await reporting.inference.serverlessLimits();
+const overview = await reporting.inference.serverlessUsageOverview('24h');
+const byModel = await reporting.inference.serverlessUsageByModel('7d');
+const requests = await reporting.inference.serverlessUsageRequests({ window: '7d', outcome: 'failed', limit: 25 });
+const buckets = await reporting.inference.serverlessUsageTimeseries('spend', '7d');
+const daily = await reporting.inference.serverlessUsageDaily(30);
+const savings = await reporting.inference.serverlessUsageSavings('30d');
+```
+
+Windows are `1h`, `24h`, `7d`, `30d` or `90d`. Overview, model breakdown,
+request logs and timeseries come from retained request details (about seven
+days); `daily` uses full-history workspace counters over 1–92 UTC days and
+includes failed admitted requests. The saved workspace RPM cap is a subdivision
+of the org's tier allowance, not a claim about effective remaining RPM.
+An incomplete 200 response is an error, never "zero usage" or "unlimited".
+
 ### Models
 
 The catalog lists only models hosted on Run BiOS (the platform's own verified
@@ -491,7 +520,7 @@ try {
 | `apiKey` | `RUNBIOS_API_KEY` env var (legacy `BIOS_API_KEY`) | Dashboard-issued API key (default `bios-`; custom and provider-shaped prefixes also work; legacy `usf-` keys remain valid) |
 | `accessToken` | — | JWT access token |
 | `orgId` | — | Organization ID (auto-resolved with API keys) |
-| `workspaceId` | — | Workspace ID (auto-resolved with API keys) |
+| `workspaceId` | — | Workspace ID (auto-resolved with workspace-bound API keys). An explicit ID must match the key's bound workspace; a workspace-less key can select a workspace it belongs to within its bound organization. |
 | `baseUrl` | `RUNBIOS_BASE_URL` env var (legacy `BIOS_BASE_URL`), then `https://api.runbios.ai` | Canonical production hostname (release-gated; this documentation does not assert current availability). During prelaunch/dev, pass `https://api-dev.runbios.ai` explicitly. |
 | `timeout` | `30000` | Request timeout in ms |
 | `inferenceKey` | `RUNBIOS_INFERENCE_KEY` env var (legacy `BIOS_INFERENCE_KEY`), then `apiKey` | Key used by `client.inference` for `/v1` calls. A per-deployment `sk-bios-...` key, or the platform `apiKey` itself when it carries the serverless scope — you never pass the same key twice |

package/dist/client.js

@@ -340,7 +340,7 @@ export class HttpClient {
     constructor(config) {
         // Default host stays api.runbios.ai for now; cutover to api.runbios.ai is
         // planned once its DNS exists.
-        this.baseUrl = (config.baseUrl || envBaseUrl() || 'https://api.runbios.ai').replace(/\/+$/, '');
+        this.baseUrl = (config.baseUrl || envBaseUrl() || 'https://api-dev.runbios.ai').replace(/\/+$/, '');
         this.apiKey = config.apiKey ?? envApiKey();
         this.accessToken = config.accessToken;
         this.orgId = config.orgId;

package/dist/index.d.ts

@@ -36,7 +36,7 @@ import { Loop } from './resources/loop.js';
  * SDK version. Sent as part of the User-Agent header.
  * Must match package.json "version" -- enforced by a contract test.
  */
-export declare const VERSION = "0.2.13";
+export declare const VERSION = "0.2.14-dev.244";
 export declare class RunBiOS {
     /** Search models, fetch configs, check adapter compatibility. */
     readonly models: Models;
@@ -74,7 +74,9 @@ export { Integrations, type HuggingFaceIntegration, type IntegrationBrowseParams
 export { Training } from './resources/training.js';
 export { Wallet } from './resources/wallet.js';
 export { GPU, type GPURecommendation } from './resources/gpu.js';
-export { Inference, validateChatRequest, parseSSE, buildInferenceRequest, contextSizingBasis, type ContextSizingBasis, CONTEXT_DEFAULT_CEILING, CONTEXT_EDITABLE_FLOOR, type ChatMessage, type FunctionTool, type ChatCompletionParams, type ChatCompletionResponse, type ChatCompletionChunk, } from './resources/inference.js';
-export type { BiOSConfig, PaginatedResponse, ApiErrorBody, AvailableGpuAlternative, CapacityMinimumRequirement, InferenceBookingAccepted, Model, ModelSearchParams, ModelSearchResponse, ModelDetailResponse, ModelConfig, Dataset, DatasetListParams, DatasetListResponse, DatasetUploadParams, DatasetPreview, DatasetPreviewParams, DatasetImportHFParams, DatasetRegisterHFParams, DatasetHubSearchParams, DatasetHubPreviewParams, DatasetValidation, DatasetFormatVariant, DatasetFormatSpec, DatasetFormatSpecs, DatasetStorageUsage, TrainingMethod, RLHFAlgorithm, AdapterType, TrainingJobStatus, TrainingStatusFilter, TrainingCreateParams, TrainingListParams, TrainingListResponse, TrainingJob, TrainingMetrics, TrainingResourceMetrics, TrainingDeviceMetrics, MetricPoint, MetricGraphConfig, TrainingCheckpoint, TrainingLogs, TrainingLogEntry, TrainingStopResponse, TrainingResumeResponse, CanonicalTrainingRequest, TrainingPreflightDataset, TrainingPreflightWarning, TrainingPreflightResponse, TrainingCapabilityChoice, TrainingConfigFieldCapability, TrainingCapabilities, GPUChoice, WalletBalance, Transaction, TransactionListResponse, TransactionListParams, GPUInfo, GPUPricingResponse, GPUOptionsParams, TrainingRecommendParams, TrainingAdvisorVerdict, TrainingAdvisorRecommendation, TrainingAdvisorUserShape, TrainingAdvisorJustification, TrainingAdvisorBasis, GPUOption, GPUOptionSuggestion, GPUOptionsResponse, InferenceStatus, InferenceCreateParams, InferenceUpdateParams, InferenceDeployment, InferenceDeploymentSummary, InferenceCreateResponse, InferenceListResponse, InferenceUpdateResponse, InferenceLifecycleResponse, InferenceDeleteResponse, InferenceGPUOptionMarket, InferenceGPUOption, InferenceGPUAlternative, InferenceGPUOptionsParams, InferenceGPUOptionsResponse, InferenceCanonicalRequest, InferencePreflightWarning, InferencePreflightResponse, AdapterCompatibility, AdapterCompatibilityResponse, AdapterCompatibilityParams, SupportedArchitecture, ArchitectureScope, SupportedArchitecturesResponse, ApiKey, ApiKeyScope, ApiKeyIntrospection, Organization, OrgMember, OrgInvite, Workspace, Integration, IntegrationCreateParams, StorageUsage, StorageObject, PromptTokensDetails, ChatCompletionUsage, TrainingCadence, TrainingCombinator, ServingKind, TrainingRulePausedReason, LoopTrainingMethod, TrainType, GradersScope, TrainingTrigger, TrainingRunState, TrainingVerdict, TrainingDecision, NotifyState, EvaluationStatus, EvaluationItemStatus, EvaluationWinner, EvaluationWarningCode, ConsentVia, TrainingToolCall, TrainingMessage, TrainingRuleServing, TrainingGPURung, TrainingRule, TrainingRuleConsent, TrainingRulePreflightRefusal, TrainingRuleKeyRef, TrainingRuleKeyCheck, TrainingRulePreflight, TrainingRuleBuildSpec, TrainingRuleTriggerInput, TrainingRuleTrainingInput, TrainingRuleDeployInput, TrainingRuleMoneyInput, TrainingRuleEvaluationInput, TrainingRulePromotionInput, TrainingRuleAcceptTerms, TrainingRulePreflightRequest, TrainingRuleCreateRequest, TrainingRuleUpdateRequest, TrainingRuleConsentRequest, TrainingRuleListParams, TrainingRunPromoteRequest, TrainingRunRejectRequest, TrainingRunRollbackRequest, TrainingRunCancelRequest, TrainingRunListParams, TrainingRun, TrainingRunSummary, TrainingRunEvent, TrainingRunLinks, TrainingRunActions, EvaluationRef, EvaluationDecoding, EvaluationJudgeDimension, EvaluationDimensionScore, EvaluationGraderScore, EvaluationWarning, EvaluationMargin, JudgeAgreementDimension, JudgeAgreement, Evaluation, EvaluationItemSide, EvaluationItem, EvaluationItemListParams, JudgeAgreementParams, AgentSettings, AgentSettingsRequest, BenchmarkStatus, BenchmarkSourceKind, BenchmarkRunStatus, BenchmarkScoring, BenchmarkDimensionScore, Benchmark, BenchmarkItem, BenchmarkRun, BenchmarkHistoryPoint, BenchmarkSource, BenchmarkCreateParams, BenchmarkListParams, BenchmarkItemListParams, BenchmarkHistoryParams, BenchmarkRetireParams, TrainingRuleBenchmarkRequest, InferenceAlias, InferenceAliasRequest, TrainingRuleListResponse, TrainingRuleResponse, TrainingRuleMutationResponse, TrainingRuleDeleteResponse, TrainingRunListResponse, TrainingRunResponse, TrainingRunActionResponse, EvaluationItemsResponse, AgentSettingsResponse, InferenceAliasListResponse, InferenceAliasResponse, InferenceAliasDeleteResponse, BenchmarkListResponse, BenchmarkItemsResponse, BenchmarkHistoryResponse, } from './types.js';
+export { Inference, validateChatRequest, parseSSE, buildInferenceRequest, contextSizingBasis, type ContextSizingBasis, CONTEXT_DEFAULT_CEILING, CONTEXT_EDITABLE_FLOOR, type ChatMessage, type FunctionTool, type ChatCompletionParams, type ChatCompletionResponse, type ChatCompletionChunk, type ServerlessUsageWindow, type ServerlessTimeseriesMetric, type ServerlessWorkspaceLimits, type ServerlessUsageEnvelope, type ServerlessUsageOverviewResponse, type ServerlessUsageRowsResponse, type ServerlessUsageTimeseriesResponse, type ServerlessUsageDailyResponse, type ServerlessSavingsTotals, type ServerlessSavingsPeriod, type ServerlessUsageSavingsResponse, } from './resources/inference.js';
+export type { BiOSConfig, PaginatedResponse, ApiErrorBody, AvailableGpuAlternative, CapacityMinimumRequirement, InferenceBookingAccepted, Model, ModelSearchParams, ModelSearchResponse, ModelDetailResponse, ModelConfig, Dataset, DatasetListParams, DatasetListResponse, DatasetUploadParams, DatasetPreview, DatasetPreviewParams, DatasetImportHFParams, DatasetRegisterHFParams, DatasetHubSearchParams, DatasetHubPreviewParams, DatasetValidation, DatasetFormatVariant, DatasetFormatSpec, DatasetFormatSpecs, DatasetStorageUsage, TrainingMethod, RLHFAlgorithm, AdapterType, TrainingJobStatus, TrainingStatusFilter, TrainingCreateParams, TrainingListParams, TrainingListResponse, TrainingJob, TrainingMetrics, TrainingResourceMetrics, TrainingDeviceMetrics, MetricPoint, MetricGraphConfig, TrainingCheckpoint, TrainingLogs, TrainingLogEntry, TrainingStopResponse, TrainingResumeResponse, CanonicalTrainingRequest, TrainingPreflightDataset, TrainingPreflightWarning, TrainingPreflightResponse, TrainingCapabilityChoice, TrainingConfigFieldCapability, TrainingCapabilities, GPUChoice, WalletBalance, Transaction, TransactionListResponse, TransactionListParams, GPUInfo, GPUPricingResponse, GPUOptionsParams, TrainingRecommendParams, TrainingAdvisorVerdict, TrainingAdvisorRecommendation, TrainingAdvisorUserShape, TrainingAdvisorJustification, TrainingAdvisorBasis, GPUOption, GPUOptionSuggestion, GPUOptionsResponse, InferenceStatus, InferenceCreateParams, InferenceUpdateParams, InferenceDeployment, InferenceDeploymentSummary, InferenceCreateResponse, InferenceListResponse, InferenceUpdateResponse, InferenceLifecycleResponse, InferenceDeleteResponse, InferenceGPUOptionMarket, InferenceGPUOption, InferenceGPUAlternative, InferenceGPUOptionsParams, InferenceGPUOptionsResponse, InferenceCanonicalRequest, InferencePreflightWarning, InferencePreflightResponse, AdapterCompatibility, AdapterCompatibilityResponse, AdapterCompatibilityParams, SupportedArchitecture, ArchitectureScope, SupportedArchitecturesResponse, ApiKey, ApiKeyScope, ApiKeyIntrospection, Organization, OrgMember, OrgInvite, Workspace, Integration, IntegrationCreateParams, StorageUsage, StorageObject, PromptTokensDetails, ChatCompletionUsage, TrainingCadence, TrainingCombinator, ServingKind, TrainingRulePausedReason, LoopTrainingMethod, TrainType, GradersScope, TrainingTrigger, TrainingRecipe, TrainingRunState, TrainingVerdict, TrainingDecision, NotifyState, EvaluationStatus, EvaluationItemStatus, EvaluationWinner, EvaluationWarningCode, ConsentVia, TrainingToolCall, TrainingMessage, TrainingRuleServing, TrainingGPURung, TrainingRule, TrainingRuleConsent, TrainingRulePreflightRefusal, TrainingRuleKeyRef, TrainingRuleKeyCheck, TrainingRulePreflight, TrainingRuleBuildSpec, TrainingRuleTriggerInput, TrainingRuleTrainingInput, TrainingRuleDeployInput, TrainingRuleMoneyInput, TrainingRuleEvaluationInput, TrainingRulePromotionInput, TrainingRuleAcceptTerms, TrainingRulePreflightRequest, TrainingRuleCreateRequest, TrainingRuleUpdateRequest, TrainingRuleConsentRequest, TrainingRuleListParams, TrainingRunPromoteRequest, TrainingRunRejectRequest, TrainingRunRollbackRequest, TrainingRunCancelRequest, TrainingRunListParams, TrainingRun, TrainingRunSummary, TrainingRunEvent, TrainingRunLinks, TrainingRunActions, EvaluationRef, EvaluationDecoding, EvaluationJudgeDimension, EvaluationDimensionScore, EvaluationGraderScore, EvaluationWarning, EvaluationMargin, JudgeAgreementDimension, JudgeAgreement, Evaluation, EvaluationItemSide, EvaluationItem, EvaluationItemListParams, JudgeAgreementParams, AgentSettings, AgentSettingsRequest, BenchmarkStatus, BenchmarkSourceKind, BenchmarkRunStatus, BenchmarkScoring, BenchmarkDimensionScore, Benchmark, BenchmarkItem, BenchmarkRun, BenchmarkHistoryPoint, BenchmarkSource, BenchmarkCreateParams, BenchmarkListParams, BenchmarkItemListParams, BenchmarkHistoryParams, BenchmarkRetireParams, TrainingRuleBenchmarkRequest, InferenceAlias, InferenceAliasRequest, TrainingRuleListResponse, TrainingRuleResponse, TrainingRuleMutationResponse, TrainingRuleDeleteResponse, TrainingRunListResponse, TrainingRunResponse, TrainingRunActionResponse, EvaluationItemsResponse, AgentSettingsResponse, InferenceAliasListResponse, InferenceAliasResponse, InferenceAliasDeleteResponse, BenchmarkListResponse, BenchmarkItemsResponse, BenchmarkHistoryResponse, TrainingRuleRunRefusalCode, TrainingRuleMonthlyLimitRefusal, LoopDatasetDeleteRefusalCode, PipelineStatus, PipelineRecipeExploration, PipelineActiveRun, PipelineVersion, Pipeline, PipelineListResponse, PipelineResponse, } from './types.js';
 /** The closed set of run states a training run never leaves. */
 export { TERMINAL_RUN_STATES } from './types.js';
+/** The most versions a pipeline may be set to make. */
+export { PIPELINE_MAX_VERSIONS_CEILING } from './types.js';

package/dist/index.js

@@ -36,7 +36,7 @@ import { Loop } from './resources/loop.js';
  * SDK version. Sent as part of the User-Agent header.
  * Must match package.json "version" -- enforced by a contract test.
  */
-export const VERSION = '0.2.13';
+export const VERSION = '0.2.14-dev.244';
 export class RunBiOS {
     /** Search models, fetch configs, check adapter compatibility. */
     models;
@@ -105,3 +105,5 @@ export { GPU } from './resources/gpu.js';
 export { Inference, validateChatRequest, parseSSE, buildInferenceRequest, contextSizingBasis, CONTEXT_DEFAULT_CEILING, CONTEXT_EDITABLE_FLOOR, } from './resources/inference.js';
 /** The closed set of run states a training run never leaves. */
 export { TERMINAL_RUN_STATES } from './types.js';
+/** The most versions a pipeline may be set to make. */
+export { PIPELINE_MAX_VERSIONS_CEILING } from './types.js';

package/dist/resources/inference.d.ts

@@ -78,6 +78,75 @@ export interface ChatCompletionParams extends Record<string, unknown> {
 }
 export type ChatCompletionResponse = Record<string, unknown>;
 export type ChatCompletionChunk = Record<string, unknown>;
+export type ServerlessUsageWindow = '1h' | '24h' | '7d' | '30d' | '90d';
+export type ServerlessTimeseriesMetric = 'requests' | 'tokens' | 'spend' | 'ttft_p50' | 'ttft_p95' | 'tps';
+export interface ServerlessWorkspaceLimits {
+    workspace_id: string;
+    workspace_rpm_limit: number | null;
+    is_set: boolean;
+    monthly_spend_cap_cents: number | null;
+    spend_cap_is_set: boolean;
+    updated_at?: string;
+}
+export interface ServerlessUsageEnvelope {
+    window: string;
+    from: string;
+    to: string;
+}
+export interface ServerlessUsageOverviewResponse extends ServerlessUsageEnvelope {
+    overview: {
+        requests: number;
+        input_tokens: number;
+        output_tokens: number;
+        total_tokens: number;
+        spend_microcents: number;
+        [field: string]: unknown;
+    };
+}
+export interface ServerlessUsageRowsResponse extends ServerlessUsageEnvelope {
+    rows: Array<Record<string, unknown>>;
+}
+export interface ServerlessUsageTimeseriesResponse extends ServerlessUsageEnvelope {
+    metric: ServerlessTimeseriesMetric;
+    bucket_secs: number;
+    points: Array<{
+        bucket_ts: string;
+        value: number | null;
+    }>;
+}
+export interface ServerlessUsageDailyResponse {
+    days: number;
+    requests: number;
+    tokens_in: number;
+    tokens_out: number;
+    total_tokens: number;
+    spend_microcents: number;
+    points: Array<Record<string, unknown>>;
+}
+export interface ServerlessSavingsTotals {
+    savings_microcents: number;
+    standard_microcents: number;
+    charged_microcents: number;
+    requests: number;
+}
+export interface ServerlessSavingsPeriod {
+    you: {
+        savings_microcents: number;
+        since?: string | null;
+    };
+    workspace: {
+        savings_microcents: number;
+        since?: string | null;
+    };
+}
+export interface ServerlessUsageSavingsResponse extends ServerlessUsageEnvelope {
+    you: ServerlessSavingsTotals;
+    workspace: ServerlessSavingsTotals;
+    lifetime: ServerlessSavingsPeriod;
+    today: ServerlessSavingsPeriod;
+    by_model: Array<Record<string, unknown>>;
+    by_day: Array<Record<string, unknown>>;
+}
 export declare function validateChatRequest(body: Record<string, unknown>): void;
 export declare function parseSSE(body: ReadableStream<Uint8Array>): AsyncGenerator<string>;
 /**
@@ -98,6 +167,18 @@ export declare class Inference {
     }, http?: HttpClient);
     /** @internal Control-plane transport; present when constructed by the SDK client. */
     private get http();
+    serverlessLimits(): Promise<ServerlessWorkspaceLimits>;
+    serverlessUsageOverview(window?: ServerlessUsageWindow): Promise<ServerlessUsageOverviewResponse>;
+    serverlessUsageByModel(window?: ServerlessUsageWindow): Promise<ServerlessUsageRowsResponse>;
+    serverlessUsageRequests(options?: {
+        window?: ServerlessUsageWindow;
+        outcome?: 'all' | 'ok' | 'failed' | 'rejected';
+        requestId?: string;
+        limit?: number;
+    }): Promise<ServerlessUsageRowsResponse>;
+    serverlessUsageTimeseries(metric: ServerlessTimeseriesMetric, window?: ServerlessUsageWindow): Promise<ServerlessUsageTimeseriesResponse>;
+    serverlessUsageDaily(days?: number): Promise<ServerlessUsageDailyResponse>;
+    serverlessUsageSavings(window?: ServerlessUsageWindow): Promise<ServerlessUsageSavingsResponse>;
     /** Side-effect-free validation with authoritative stock, prices, alternatives, and hold terms. */
     preflight(params: InferenceCreateParams): Promise<InferencePreflightResponse>;
     /**

package/dist/resources/inference.js

@@ -135,6 +135,16 @@ function buildInferenceRequest(params) {
         body.max_price_hour_cents = params.maxPriceHourCents;
     return body;
 }
+function serverlessRead(value, valid) {
+    const body = value && typeof value === 'object' && !Array.isArray(value) ? value : null;
+    if (!body || !valid(body)) {
+        throw new ApiError(0, { error: { code: 'INVALID_SERVERLESS_RESPONSE', message: 'Serverless data was incomplete; do not treat it as empty usage or an unset limit.' } });
+    }
+    return value;
+}
+function hasUsageWindow(body) {
+    return typeof body.window === 'string' && typeof body.from === 'string' && typeof body.to === 'string';
+}
 export function validateChatRequest(body) {
     const messages = body.messages;
     if (!Array.isArray(messages) || messages.length === 0) {
@@ -326,7 +336,7 @@ export class Inference {
         this.key = config.inferenceKey || envInferenceKey() || envApiKey();
         // Same default host as HttpClient (api.runbios.ai); api.runbios.ai cutover
         // is planned once its DNS exists — update both call sites together.
-        this.baseUrl = (config.baseUrl || envBaseUrl() || 'https://api.runbios.ai').replace(/\/+$/, '');
+        this.baseUrl = (config.baseUrl || envBaseUrl() || 'https://api-dev.runbios.ai').replace(/\/+$/, '');
         this.timeout = config.timeout ?? 900_000;
         this._http = http;
     }
@@ -337,6 +347,56 @@ export class Inference {
         }
         return this._http;
     }
+    serverlessLimits() {
+        return this.http.fetchGet('/api/serverless/limits').then(value => serverlessRead(value, body => typeof body.workspace_id === 'string' && body.workspace_id.length > 0 &&
+            typeof body.is_set === 'boolean' && typeof body.spend_cap_is_set === 'boolean' &&
+            (body.workspace_rpm_limit === null || typeof body.workspace_rpm_limit === 'number') &&
+            (body.monthly_spend_cap_cents === null || typeof body.monthly_spend_cap_cents === 'number') &&
+            body.is_set === (body.workspace_rpm_limit !== null) &&
+            body.spend_cap_is_set === (body.monthly_spend_cap_cents !== null)));
+    }
+    serverlessUsageOverview(window = '24h') {
+        return this.http.fetchGet(`/api/serverless/usage/overview?window=${encodeURIComponent(window)}`).then(value => serverlessRead(value, body => hasUsageWindow(body) && body.overview !== null && typeof body.overview === 'object' &&
+            ['requests', 'input_tokens', 'output_tokens', 'total_tokens', 'spend_microcents'].every(field => typeof body.overview[field] === 'number')));
+    }
+    serverlessUsageByModel(window = '24h') {
+        return this.http.fetchGet(`/api/serverless/usage/by-model?window=${encodeURIComponent(window)}`).then(value => serverlessRead(value, body => hasUsageWindow(body) && Array.isArray(body.rows)));
+    }
+    async serverlessUsageRequests(options = {}) {
+        const params = new URLSearchParams({ window: options.window ?? '24h' });
+        if (options.outcome)
+            params.set('outcome', options.outcome);
+        if (options.requestId)
+            params.set('request_id', options.requestId);
+        if (options.limit !== undefined) {
+            if (!Number.isInteger(options.limit) || options.limit < 1 || options.limit > 500)
+                throw new RangeError('limit must be an integer from 1 to 500');
+            params.set('limit', String(options.limit));
+        }
+        return this.http.fetchGet(`/api/serverless/usage/requests?${params}`).then(value => serverlessRead(value, body => hasUsageWindow(body) && Array.isArray(body.rows)));
+    }
+    serverlessUsageTimeseries(metric, window = '24h') {
+        const params = new URLSearchParams({ metric, window });
+        return this.http.fetchGet(`/api/serverless/usage/timeseries?${params}`).then(value => serverlessRead(value, body => hasUsageWindow(body) && body.metric === metric && typeof body.bucket_secs === 'number' && Array.isArray(body.points)));
+    }
+    serverlessUsageDaily(days = 30) {
+        return this.http.fetchGet(`/api/serverless/usage/daily?days=${encodeURIComponent(String(days))}`).then(value => serverlessRead(value, body => typeof body.days === 'number' && Number.isInteger(body.days) && body.days > 0 && Array.isArray(body.points) &&
+            ['requests', 'tokens_in', 'tokens_out', 'total_tokens', 'spend_microcents'].every(field => typeof body[field] === 'number')));
+    }
+    serverlessUsageSavings(window = '30d') {
+        const record = (value) => value && typeof value === 'object' && !Array.isArray(value) ? value : null;
+        const totals = (value) => {
+            const row = record(value);
+            return !!row && ['savings_microcents', 'standard_microcents', 'charged_microcents', 'requests']
+                .every(field => typeof row[field] === 'number');
+        };
+        const period = (value) => {
+            const row = record(value);
+            return !!row && ['you', 'workspace'].every(scope => typeof record(row[scope])?.savings_microcents === 'number');
+        };
+        return this.http.fetchGet(`/api/serverless/usage/savings?window=${encodeURIComponent(window)}`).then(value => serverlessRead(value, body => hasUsageWindow(body) && totals(body.you) && totals(body.workspace) &&
+            period(body.lifetime) && period(body.today) && Array.isArray(body.by_model) && Array.isArray(body.by_day)));
+    }
     // --------------------------------------------------------------------------
     // Control-plane deployment management — `/api/inference*`
     // --------------------------------------------------------------------------

package/dist/resources/loop.d.ts

@@ -1,5 +1,5 @@
 import type { HttpClient } from '../client.js';
-import type { LoopTrace, LoopTraceListResponse, LoopTraceListParams, LoopCaptureParams, LoopCaptureResult, LoopImportParams, LoopImportResult, LoopSignal, LoopSignalParams, LoopCandidate, LoopCandidateParams, LoopGrader, LoopGraderParams, LoopLabel, LoopLabelCount, LoopGradeResult, LoopDataset, LoopDatasetListParams, LoopDatasetItem, LoopDatasetCreateParams, LoopConfig, LoopConfigParams, LoopBuildRule, LoopBuildRuleParams, LoopBuildRuleUpdateParams, LoopStats, LoopJudge, LoopJudgeParams, LoopAgentCredential, LoopAgentStatus, LoopSampleRun, LoopSampleRunParams, LoopJudgeRun, LoopJudgeRunItems, LoopJudgeRunItemStatus, LoopJudgeWork, LoopJudgeVerdict, LoopJudgeVerdictResult, TrainingRule, TrainingRulePreflight, TrainingRulePreflightRequest, TrainingRuleCreateRequest, TrainingRuleUpdateRequest, TrainingRuleConsentRequest, TrainingRuleListParams, TrainingRuleListResponse, TrainingRuleResponse, TrainingRuleMutationResponse, TrainingRuleDeleteResponse, TrainingRun, TrainingRunListParams, TrainingRunListResponse, TrainingRunResponse, TrainingRunActionResponse, TrainingRunPromoteRequest, TrainingRunRejectRequest, TrainingRunRollbackRequest, TrainingRunCancelRequest, Evaluation, EvaluationItemListParams, EvaluationItemsResponse, JudgeAgreement, JudgeAgreementParams, Benchmark, BenchmarkCreateParams, BenchmarkHistoryParams, BenchmarkHistoryResponse, BenchmarkItemListParams, BenchmarkItemsResponse, BenchmarkListParams, BenchmarkListResponse, BenchmarkRetireParams, BenchmarkRun, TrainingRuleBenchmarkRequest, AgentSettings, AgentSettingsRequest } from '../types.js';
+import type { LoopTrace, LoopTraceListResponse, LoopTraceListParams, LoopCaptureParams, LoopCaptureResult, LoopImportParams, LoopImportResult, LoopSignal, LoopSignalParams, LoopCandidate, LoopCandidateParams, LoopGrader, LoopGraderParams, LoopLabel, LoopLabelCount, LoopGradeResult, LoopDataset, LoopDatasetListParams, LoopDatasetItem, LoopDatasetCreateParams, LoopConfig, LoopConfigParams, LoopBuildRule, LoopBuildRuleParams, LoopBuildRuleUpdateParams, LoopStats, LoopJudge, LoopJudgeParams, LoopAgentCredential, LoopAgentStatus, LoopSampleRun, LoopSampleRunParams, LoopJudgeRun, LoopJudgeRunItems, LoopJudgeRunItemStatus, LoopJudgeWork, LoopJudgeVerdict, LoopJudgeVerdictResult, TrainingRule, TrainingRulePreflight, TrainingRulePreflightRequest, TrainingRuleCreateRequest, TrainingRuleUpdateRequest, TrainingRuleConsentRequest, TrainingRuleListParams, TrainingRuleListResponse, TrainingRuleResponse, TrainingRuleMutationResponse, TrainingRuleDeleteResponse, TrainingRun, TrainingRunListParams, TrainingRunListResponse, TrainingRunResponse, TrainingRunActionResponse, TrainingRunPromoteRequest, TrainingRunRejectRequest, TrainingRunRollbackRequest, TrainingRunCancelRequest, Evaluation, EvaluationItemListParams, EvaluationItemsResponse, JudgeAgreement, JudgeAgreementParams, Benchmark, BenchmarkCreateParams, BenchmarkHistoryParams, BenchmarkHistoryResponse, BenchmarkItemListParams, BenchmarkItemsResponse, BenchmarkListParams, BenchmarkListResponse, BenchmarkRetireParams, BenchmarkRun, TrainingRuleBenchmarkRequest, AgentSettings, AgentSettingsRequest, Pipeline, PipelineListResponse } from '../types.js';
 /**
  * The Conscious Loop -- capture what your model was asked and answered, record
  * whether it was right, and turn those judgements into training data.
@@ -335,7 +335,10 @@ export declare class Loop {
      * Delete a training set.
      *
      * The conversations it was built from are untouched -- a set is a selection,
-     * and discarding the selection must not discard the evidence.
+     * and discarding the selection must not discard the evidence. A set a
+     * training run was trained on is refused `409 DATASET_IN_USE` and kept, as
+     * the record of what that run learned from. See
+     * `LoopDatasetDeleteRefusalCode`.
      */
     deleteDataset(id: string): Promise<{
         deleted: boolean;
@@ -614,11 +617,12 @@ export declare class Loop {
      */
     listTrainingRules(params?: TrainingRuleListParams): Promise<TrainingRuleListResponse>;
     /**
-     * Read one rule with its recent runs, what it has spent this month, and how
-     * far its judge agrees with your own reviewers.
+     * Read one rule with its recent runs, what its runs this month have cost at
+     * most, and how far its judge agrees with your own reviewers.
      *
      * Returned whole rather than unwrapped to the rule: `month_spent_cents` is
-     * the number that says whether the monthly ceiling is about to stop it.
+     * the number that says whether the monthly ceiling is about to stop it. It
+     * is an upper bound, not an exact spend: see `Pipeline.month_spent_cents`.
      */
     getTrainingRule(id: string): Promise<TrainingRuleResponse>;
     /**
@@ -626,8 +630,11 @@ export declare class Loop {
      * that can be cleared.
      *
      * A money-bearing change -- a ceiling, a model, a GPU ladder, the promotion
-     * policy -- bumps `revision`, clears the recorded consent and STOPS the rule
-     * firing until someone accepts the new amounts. The reply says so in
+     * policy, or changing `explore_recipes` in EITHER direction -- bumps
+     * `revision`, clears the recorded consent and STOPS the rule firing until
+     * someone accepts the new amounts. Turning recipe variants OFF does this
+     * too: the pipeline then makes no version at all, variant or not, until the
+     * terms are accepted again. The reply says so in
      * `consent_required`, and carries a fresh `preflight` with the new figures.
      * Pass `expected_revision` to be refused with `REVISION_MISMATCH` rather
      * than overwrite an edit somebody else made in the meantime.
@@ -654,8 +661,17 @@ export declare class Loop {
      * Fire a rule now, without waiting for its cadence.
      *
      * Bypasses the schedule and `min_new_rows` only. The row floors, the money
-     * ceilings and the consent all still apply, so this can answer `409
-     * CONSENT_REQUIRED` or `422 NOT_ENOUGH_ROWS` with the counts it needed.
+     * ceilings, the consent, the version limit and the monthly limit all still
+     * apply, so this can answer `409 CONSENT_REQUIRED`, `409 RULE_PAUSED`,
+     * `409 RUN_ACTIVE`, `409 VERSION_LIMIT_REACHED` (the pipeline has made
+     * `max_versions` versions), `409 MONTHLY_LIMIT_REACHED` (the most this
+     * month's runs can have cost plus the most one run may cost would pass the
+     * monthly limit; the error
+     * body carries `month_spent_cents`, `monthly_ceiling_cents`, `run_max_cents`
+     * and `resumes_at`), `409 AGENT_OFF` (the workspace's Conscious Loop agent
+     * is not turned on, so a trained model could not be compared) or
+     * `422 NOT_ENOUGH_ROWS` with the counts it needed. See
+     * `TrainingRuleRunRefusalCode`.
      */
     runTrainingRule(id: string): Promise<TrainingRun>;
     /**
@@ -710,6 +726,34 @@ export declare class Loop {
      * cancelling a training job does not refund the hours it burned.
      */
     cancelTrainingRun(id: string, params?: TrainingRunCancelRequest): Promise<TrainingRunActionResponse>;
+    /**
+     * Every training rule in the workspace, seen as the series of versions it
+     * produced: which exist, which one serves (`champion_version`), how each did
+     * against the champion of its day and on the standing benchmark, the run in
+     * flight and which version it will be, and what the pipeline is waiting for.
+     *
+     * Read-only. Every decision stays on the route that owns it -- promote,
+     * reject and roll back on the run, the version limit and `explore_recipes`
+     * on the rule.
+     *
+     * RETURNED WITH ITS ENVELOPE, because the list is not always all of them:
+     * the service returns the newest 100, `total` is every pipeline in the
+     * workspace and `truncated` is true when more exist than were returned. A
+     * caller that shows `pipelines` alone presents a short list as the whole of
+     * it. The rest are reached through `listTrainingRules`, which pages.
+     */
+    listPipelines(): Promise<PipelineListResponse>;
+    /**
+     * One pipeline, by its training rule's id.
+     *
+     * `status` says whether it is the platform working (`running`), the member
+     * who has to act (`needs_review`, `needs_funds`), or nothing at all until
+     * somebody does (`paused`, with `paused_reason` or `needs_consent` saying
+     * why; `complete` at `max_versions`). `month_spent_cents` is the figure the
+     * monthly limit is enforced against: what runs started this month have cost
+     * at most, not an exact spend.
+     */
+    getPipeline(id: string): Promise<Pipeline>;
     /**
      * The comparison behind a verdict: both models on the same held-out rows,
      * with identical decoding, judge and grader names resolved.

package/dist/resources/loop.js

@@ -440,7 +440,10 @@ export class Loop {
      * Delete a training set.
      *
      * The conversations it was built from are untouched -- a set is a selection,
-     * and discarding the selection must not discard the evidence.
+     * and discarding the selection must not discard the evidence. A set a
+     * training run was trained on is refused `409 DATASET_IN_USE` and kept, as
+     * the record of what that run learned from. See
+     * `LoopDatasetDeleteRefusalCode`.
      */
     async deleteDataset(id) {
         return this._http.fetchDelete(`/api/loop/datasets/${encodeURIComponent(id)}`);
@@ -846,11 +849,12 @@ export class Loop {
         return this._http.fetchGet(`/api/loop/training-rules${qs ? `?${qs}` : ''}`);
     }
     /**
-     * Read one rule with its recent runs, what it has spent this month, and how
-     * far its judge agrees with your own reviewers.
+     * Read one rule with its recent runs, what its runs this month have cost at
+     * most, and how far its judge agrees with your own reviewers.
      *
      * Returned whole rather than unwrapped to the rule: `month_spent_cents` is
-     * the number that says whether the monthly ceiling is about to stop it.
+     * the number that says whether the monthly ceiling is about to stop it. It
+     * is an upper bound, not an exact spend: see `Pipeline.month_spent_cents`.
      */
     async getTrainingRule(id) {
         return this._http.fetchGet(`/api/loop/training-rules/${encodeURIComponent(id)}`);
@@ -860,8 +864,11 @@ export class Loop {
      * that can be cleared.
      *
      * A money-bearing change -- a ceiling, a model, a GPU ladder, the promotion
-     * policy -- bumps `revision`, clears the recorded consent and STOPS the rule
-     * firing until someone accepts the new amounts. The reply says so in
+     * policy, or changing `explore_recipes` in EITHER direction -- bumps
+     * `revision`, clears the recorded consent and STOPS the rule firing until
+     * someone accepts the new amounts. Turning recipe variants OFF does this
+     * too: the pipeline then makes no version at all, variant or not, until the
+     * terms are accepted again. The reply says so in
      * `consent_required`, and carries a fresh `preflight` with the new figures.
      * Pass `expected_revision` to be refused with `REVISION_MISMATCH` rather
      * than overwrite an edit somebody else made in the meantime.
@@ -893,8 +900,17 @@ export class Loop {
      * Fire a rule now, without waiting for its cadence.
      *
      * Bypasses the schedule and `min_new_rows` only. The row floors, the money
-     * ceilings and the consent all still apply, so this can answer `409
-     * CONSENT_REQUIRED` or `422 NOT_ENOUGH_ROWS` with the counts it needed.
+     * ceilings, the consent, the version limit and the monthly limit all still
+     * apply, so this can answer `409 CONSENT_REQUIRED`, `409 RULE_PAUSED`,
+     * `409 RUN_ACTIVE`, `409 VERSION_LIMIT_REACHED` (the pipeline has made
+     * `max_versions` versions), `409 MONTHLY_LIMIT_REACHED` (the most this
+     * month's runs can have cost plus the most one run may cost would pass the
+     * monthly limit; the error
+     * body carries `month_spent_cents`, `monthly_ceiling_cents`, `run_max_cents`
+     * and `resumes_at`), `409 AGENT_OFF` (the workspace's Conscious Loop agent
+     * is not turned on, so a trained model could not be compared) or
+     * `422 NOT_ENOUGH_ROWS` with the counts it needed. See
+     * `TrainingRuleRunRefusalCode`.
      */
     async runTrainingRule(id) {
         const res = await this._http.fetchPost(`/api/loop/training-rules/${encodeURIComponent(id)}/run`, {});
@@ -980,6 +996,47 @@ export class Loop {
     async cancelTrainingRun(id, params = {}) {
         return this._http.fetchPost(`/api/loop/training-runs/${encodeURIComponent(id)}/cancel`, params);
     }
+    // ── pipelines ─────────────────────────────────────────────────────────
+    /**
+     * Every training rule in the workspace, seen as the series of versions it
+     * produced: which exist, which one serves (`champion_version`), how each did
+     * against the champion of its day and on the standing benchmark, the run in
+     * flight and which version it will be, and what the pipeline is waiting for.
+     *
+     * Read-only. Every decision stays on the route that owns it -- promote,
+     * reject and roll back on the run, the version limit and `explore_recipes`
+     * on the rule.
+     *
+     * RETURNED WITH ITS ENVELOPE, because the list is not always all of them:
+     * the service returns the newest 100, `total` is every pipeline in the
+     * workspace and `truncated` is true when more exist than were returned. A
+     * caller that shows `pipelines` alone presents a short list as the whole of
+     * it. The rest are reached through `listTrainingRules`, which pages.
+     */
+    async listPipelines() {
+        const res = await this._http.fetchGet('/api/loop/pipelines');
+        const pipelines = res.pipelines || [];
+        return {
+            pipelines,
+            // An older service sends neither: its list is taken at its word.
+            total: typeof res.total === 'number' ? res.total : pipelines.length,
+            truncated: res.truncated === true,
+        };
+    }
+    /**
+     * One pipeline, by its training rule's id.
+     *
+     * `status` says whether it is the platform working (`running`), the member
+     * who has to act (`needs_review`, `needs_funds`), or nothing at all until
+     * somebody does (`paused`, with `paused_reason` or `needs_consent` saying
+     * why; `complete` at `max_versions`). `month_spent_cents` is the figure the
+     * monthly limit is enforced against: what runs started this month have cost
+     * at most, not an exact spend.
+     */
+    async getPipeline(id) {
+        const res = await this._http.fetchGet(`/api/loop/pipelines/${encodeURIComponent(id)}`);
+        return res.pipeline;
+    }
     // ── the comparison report ─────────────────────────────────────────────
     /**
      * The comparison behind a verdict: both models on the same held-out rows,

package/dist/types.d.ts

@@ -8,13 +8,13 @@ export interface BiOSConfig {
     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.runbios.ai hostname. */
+    /** 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.runbios.ai. */
+    /** 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;
@@ -2533,6 +2533,28 @@ export interface LoopSignalParams {
     reason?: string;
     author?: string;
     metadata?: Record<string, unknown>;
+    /**
+     * Which training pipeline this feedback feeds, named in the SAME call.
+     *
+     * A build rule selects conversations by label and a training rule trains from
+     * that build rule, so a label IS the pipeline a conversation goes down.
+     * Putting one on used to need a second request after this one — and that
+     * second request is the one that gets skipped, by a script that handles the
+     * 201 and moves on, by a retry that succeeds here and fails there, by an
+     * integration whose author never knew labelling was a step.
+     *
+     * What it leaves behind is a reviewed conversation in no pipeline: counted in
+     * every "reviewed" total and selected by nothing.
+     *
+     * Written in one transaction with the verdict: either both land or neither
+     * does. Omit them and nothing changes — the overwhelming majority of feedback
+     * names no pipeline and behaves exactly as it always has.
+     */
+    labels?: string[];
+    /** The same, by dimension: `{ category: 'billing' }`. */
+    attributes?: Record<string, string>;
+    /** The master group the bare labels belong to. */
+    parent?: string;
 }
 export interface LoopTrace {
     id: string;
@@ -3125,9 +3147,46 @@ export type TrainingRulePausedReason = 'consent_invalid' | 'insufficient_funds'
  * republished to keep up with a server-side capability flag.
  */
 export type LoopTrainingMethod = 'sft' | 'rlhf';
+/**
+ * What a rule's stored `train_type` may READ as.
+ *
+ * Still three, and deliberately: the column has always allowed `full`, so a
+ * rule created before standing rules were narrowed to adapters can still come
+ * back carrying it. Narrowing the response type would make this SDK
+ * misrepresent a row that really exists.
+ */
 export type TrainType = 'lora' | 'qlora' | 'full';
+/**
+ * What a rule may be SET to, which is narrower.
+ *
+ * loop-service refuses `full` on preflight, create and update for a standing
+ * rule: a rule trains unattended and on repeat, and a full fine-tune rewrites
+ * every weight instead of adding a small adapter, so it cannot be compared or
+ * rolled back cheaply. Typing the request as the wider set handed callers a
+ * value guaranteed to come back a 400. One-off full fine-tunes are unaffected
+ * — they are a different API.
+ */
+export type RuleTrainType = 'lora' | 'qlora';
 export type GradersScope = 'source' | 'all' | 'none';
-export type TrainingTrigger = 'rows' | 'cadence' | 'both' | 'manual';
+/**
+ * Why a run fired. `variant` is a recipe variant: the pipeline had nothing new
+ * to learn, so it trained the same base model on the same conversations with
+ * one training setting changed (see {@link TrainingRecipe}).
+ */
+export type TrainingTrigger = 'rows' | 'cadence' | 'both' | 'manual' | 'variant';
+/**
+ * The four training settings a recipe variant may change, as the run was
+ * actually trained: the training service's own defaults are filled in where
+ * the rule left a knob unset, so two recipes can be compared value for value.
+ * A knob that does not apply to the run (a LoRA rank on a full fine-tune) is
+ * null, never a guessed number.
+ */
+export interface TrainingRecipe {
+    learning_rate: number | null;
+    num_train_epochs: number | null;
+    lora_rank: number | null;
+    lora_alpha: number | null;
+}
 export type TrainingRunState = 'built' | 'registering' | 'dataset_validating' | 'preflighting' | 'job_creating' | 'training' | 'checkpoint_ready' | 'candidate_booking' | 'candidate_running' | 'evaluating' | 'reported' | 'awaiting_review' | 'promoting' | 'waiting_funds' | 'promoted' | 'rejected' | 'expired' | 'failed' | 'budget_stopped' | 'cancelled' | 'superseded' | 'rolled_back';
 /** The closed set a run never leaves. */
 export declare const TERMINAL_RUN_STATES: readonly TrainingRunState[];
@@ -3218,6 +3277,30 @@ export interface TrainingRule {
     eval_max_rows: number;
     eval_max_tokens: number;
     min_holdout_rows: number;
+    /**
+     * How many versions this pipeline may make, 1 to 10 (five unless changed).
+     * A version is a trained model whose comparison was reported having scored
+     * at least one conversation, or one a member put live; a run that failed,
+     * was cancelled or compared nothing is not one and does not count. At the
+     * limit the pipeline stops, and a manual run is refused with
+     * `409 VERSION_LIMIT_REACHED`, until the limit is raised.
+     */
+    max_versions: number;
+    /**
+     * Try other training recipes when there is nothing new to learn.
+     *
+     * MONEY-BEARING. When on, a pipeline that has made at least one version, and
+     * has nothing reviewed since it that adds anything new to train on (nothing
+     * reviewed at all, or only reviews -- thumbs-down with no correction, say --
+     * that give it no row the last version's set lacked), trains the same base
+     * model on the same conversations with ONE setting changed, and that model
+     * takes over only if it beats what serves the app, like any other version.
+     * Each try is a full paid run inside the rule's per-run ceilings and its
+     * monthly limit, so changing this in EITHER direction changes the terms: the
+     * rule stops firing until the member accepts them again. False unless
+     * somebody turned it on.
+     */
+    explore_recipes: boolean;
     /**
      * The standing benchmark replayed on every run of this rule, beside the
      * per-run comparison and never instead of it. Null is the ordinary state.
@@ -3227,6 +3310,32 @@ export interface TrainingRule {
      * its own. It raises no amount, so it does not invalidate consent.
      */
     benchmark_id: string | null;
+    /**
+     * Whether that benchmark DECIDES the verdict, or only reports a number.
+     *
+     * False for every rule that has not asked, which is the point of it being
+     * separate from `benchmark_id`. Attaching a benchmark means "replay this
+     * fixed set on every run and put the score on the report"; it does not mean
+     * "let that score overrule the comparison this rule was built on".
+     *
+     * When it is on it cuts both ways. A run whose held-out split came up short
+     * can be decided at all -- before this, such a run trained a model, billed a
+     * GPU and could never promote -- and a candidate that wins on fresh
+     * conversations while losing ground on the fixed set is refused.
+     */
+    benchmark_decides: boolean;
+    /**
+     * How many of the benchmark's pinned conversations must have scored before
+     * it may decide anything. A replay that got through four of its forty has
+     * not measured the new model.
+     */
+    benchmark_min_rows: number;
+    /**
+     * The bar on the replay's own candidate-minus-incumbent delta. Like-for-like
+     * WITHIN one replay -- both models, same pinned rows, same frozen judge, one
+     * pass -- and not comparable between runs.
+     */
+    benchmark_min_delta: number;
     auto_promote: boolean;
     promote_margin: number;
     promote_min_win_rate: number;
@@ -3307,6 +3416,14 @@ export interface TrainingRulePreflight {
     key_check: TrainingRuleKeyCheck;
     terms_text: string;
     terms_version: string;
+    /**
+     * The machines the hourly amounts are per hour of: the ladders the platform
+     * chose when the request left them empty, or the caller's own echoed back
+     * unchanged. An amount per hour means nothing without knowing what it is per
+     * hour of, so show these beside the estimate before anyone accepts it.
+     */
+    train_gpu_priorities: TrainingGPURung[];
+    deploy_gpu_priorities: TrainingGPURung[];
 }
 export interface TrainingRuleBuildSpec {
     method: string;
@@ -3340,6 +3457,18 @@ export interface TrainingRuleTriggerInput {
     combinator?: TrainingCombinator;
     /** null removes the row floor, leaving the schedule as the only trigger. */
     min_new_rows?: number | null;
+    /** 1 to 10. Absent leaves it as it is; absent on a create means five. */
+    max_versions?: number;
+    /**
+     * See {@link TrainingRule.explore_recipes}: every variant it allows is a
+     * full paid run, so changing it -- on OR off -- is a money-bearing edit that
+     * pauses the rule, and it makes no version of any kind, until the new terms
+     * are accepted. Turning it off to save money stops the pipeline too, until
+     * somebody accepts again. It sits beside `max_versions`
+     * because both say when the pipeline makes another version. Absent leaves
+     * it as it is; absent on a create means off.
+     */
+    explore_recipes?: boolean;
 }
 export interface TrainingRuleTrainingInput {
     model_id?: string;
@@ -3351,7 +3480,7 @@ export interface TrainingRuleTrainingInput {
      * plain supervised training means.
      */
     rlhf_type?: string | null;
-    train_type?: TrainType;
+    train_type?: RuleTrainType;
     config?: Record<string, unknown>;
     train_gpu_priorities?: TrainingGPURung[];
     train_max_price_hour_cents?: number;
@@ -3434,6 +3563,19 @@ export interface TrainingRuleCreateRequest extends TrainingRulePreflightRequest
      * preflight body and not on the update body.
      */
     benchmark_id?: string;
+    /**
+     * And whether that benchmark decides, for the same reason `benchmark_id` is
+     * here: run 1 reads its gate off the snapshot it freezes, and a gate applied
+     * by a second call lands after run 1 has been decided without it.
+     *
+     * `400 BENCHMARK_GATE_HAS_NO_SET` when it is true with no benchmark,
+     * `400 BENCHMARK_GATE_NEEDS_MIN_ROWS` when it is true with no floor.
+     */
+    benchmark_decides?: boolean;
+    /** Cannot exceed the set's size: `400 BENCHMARK_GATE_UNREACHABLE`. */
+    benchmark_min_rows?: number;
+    /** Zero -- the default -- means "must not lose ground". */
+    benchmark_min_delta?: number;
 }
 export interface TrainingRuleUpdateRequest extends TrainingRulePreflightRequest {
     expected_revision?: number;
@@ -3479,6 +3621,18 @@ export interface TrainingRun {
     authorized_by: string;
     rule_snapshot: Record<string, unknown>;
     trigger: TrainingTrigger;
+    /**
+     * For a recipe variant, what it changed, in plain words ("half the learning
+     * rate"). Null for every run that trained on the ordinary recipe.
+     */
+    recipe_note: string | null;
+    /**
+     * The version whose recipe this run varied. Null when the variant started
+     * from the rule's own settings, and for every run that is not a variant.
+     */
+    recipe_of_version: number | null;
+    /** The four recipe knobs this run trained with, defaults filled in. */
+    recipe: TrainingRecipe;
     fired_reason: string | null;
     state: TrainingRunState;
     state_entered_at: string;
@@ -3487,6 +3641,13 @@ export interface TrainingRun {
     last_reason: string | null;
     error_code: string | null;
     last_error: string | null;
+    /**
+     * What to DO about the failure, in one sentence, derived server-side from
+     * `error_code` -- the same words the failure email carries, so the two
+     * cannot drift. Null when the run has not failed, or when the failure has
+     * no remedy worth printing.
+     */
+    error_next_step: string | null;
     training_ceiling_cents: number;
     candidate_ceiling_cents: number;
     eval_ceiling_cents: number;
@@ -3503,6 +3664,13 @@ export interface TrainingRun {
     queue_deadline_at: string | null;
     checkpoint_id: string | null;
     checkpoint_step: number | null;
+    /**
+     * Which version of the pipeline this run produced. Null for a run that is
+     * not a version: one that failed, was cancelled, or whose comparison scored
+     * nothing, and that nobody put live. `seq` counts attempts; this counts
+     * models that competed, plus any a member promoted without a comparison.
+     */
+    version_no: number | null;
     training_eval_loss: number | null;
     candidate_deployment_id: string | null;
     candidate_name: string | null;
@@ -3546,10 +3714,20 @@ export interface TrainingRunSummary {
     workspace_id: string;
     seq: number;
     trigger: TrainingTrigger;
+    /** See TrainingRun.recipe_note. On the list row too: the Runs table is where a variant is first seen. */
+    recipe_note: string | null;
+    /** See TrainingRun.recipe_of_version. */
+    recipe_of_version: number | null;
+    /** See TrainingRun.recipe. */
+    recipe: TrainingRecipe;
     state: TrainingRunState;
     state_entered_at: string;
     last_reason: string | null;
     error_code: string | null;
+    /** See TrainingRun.error_next_step. On the list row too: the Runs table is where a failure is first seen. */
+    error_next_step: string | null;
+    /** See TrainingRun.version_no. */
+    version_no: number | null;
     verdict: TrainingVerdict | null;
     decision: TrainingDecision | null;
     train_rows: number | null;
@@ -3975,13 +4153,290 @@ export interface BenchmarkRetireParams {
     reason?: string;
 }
 /**
- * Attach a benchmark to a rule, or detach it with a present null.
+ * Attach a benchmark to a rule, detach it with a present null, or move the bar
+ * it decides on.
+ *
+ * ABSENT IS "LEAVE IT", PRESENT IS "MAKE IT THIS", and that applies to every
+ * field here. This is the route that attaches a benchmark AND the route that
+ * moves its bar a month later, so a call naming only `benchmark_id` must not
+ * reset a floor somebody chose, and a call naming only `benchmark_min_delta`
+ * must not detach the set.
  *
- * Not optional, and not omittable: this route sets the field, so an absent key
- * would be a request with nothing in it. Send the id to attach, null to detach.
+ * Detaching is the one exception: a present null `benchmark_id` clears
+ * `benchmark_decides` with it, because a gate with nothing behind it is a
+ * verdict waiting on a measurement that will never come. Asking for both in
+ * one request -- null id and `benchmark_decides: true` -- is refused rather
+ * than resolved, because either resolution is a guess about which half you
+ * meant.
  */
 export interface TrainingRuleBenchmarkRequest {
+    benchmark_id?: string | null;
+    benchmark_decides?: boolean;
+    benchmark_min_rows?: number;
+    benchmark_min_delta?: number;
+}
+/**
+ * The machine codes `runTrainingRule` can be refused with. Each is the
+ * platform declining to start a paid run it would only refuse a minute later,
+ * so each is said in front of the caller rather than left for the rule's
+ * `last_reason` to explain after they have stopped looking.
+ *
+ * - `CONSENT_REQUIRED` (409): the terms changed and nobody accepted them.
+ * - `RULE_PAUSED` (409): the rule is switched off or the platform stopped it.
+ * - `RUN_ACTIVE` (409): one run at a time, so two cannot race to promote.
+ * - `VERSION_LIMIT_REACHED` (409): the pipeline has made `max_versions`
+ *   versions. Raise the limit or start a new pipeline.
+ * - `MONTHLY_LIMIT_REACHED` (409): the most this month's runs can have cost
+ *   plus the most one more run may cost would pass `monthly_ceiling_cents`.
+ *   The body carries the figures:
+ *   see {@link TrainingRuleMonthlyLimitRefusal}.
+ * - `AGENT_OFF` (409): the workspace's Conscious Loop agent is not turned on.
+ *   Every comparison runs under the agent's key, so a run started without one
+ *   would pay for training and could not be compared. Turn it on in Agent
+ *   settings, then run the rule.
+ * - `NOT_ENOUGH_ROWS` (422): too few reviewed or held-out conversations, with
+ *   `train_rows`, `holdout_rows` and the `floor` it needed.
+ */
+export type TrainingRuleRunRefusalCode = 'CONSENT_REQUIRED' | 'RULE_PAUSED' | 'RUN_ACTIVE' | 'VERSION_LIMIT_REACHED' | 'MONTHLY_LIMIT_REACHED' | 'AGENT_OFF' | 'NOT_ENOUGH_ROWS';
+/**
+ * The machine codes `deleteDataset` can be refused with.
+ *
+ * - `DATASET_IN_USE` (409): a training run was trained on this set, so it is
+ *   kept as the record of what that run learned from.
+ */
+export type LoopDatasetDeleteRefusalCode = 'DATASET_IN_USE';
+/**
+ * The body of a manual run refused `409 MONTHLY_LIMIT_REACHED`, as
+ * `ApiError.body` carries it.
+ *
+ * The test is the worst case, not the average: a run may start only if the
+ * most the rule's runs this UTC calendar month can have cost
+ * (`month_spent_cents`), plus the most the run about to start may spend (its
+ * three ceilings added up), fits under the limit.
+ */
+export interface TrainingRuleMonthlyLimitRefusal {
+    error: {
+        code: 'MONTHLY_LIMIT_REACHED';
+        message: string;
+    };
+    /** What this rule's runs have cost at most this UTC calendar month; see {@link Pipeline.month_spent_cents}. */
+    month_spent_cents: number;
+    /** The rule's monthly limit. */
+    monthly_ceiling_cents: number;
+    /** The most one run of this rule may spend: training + candidate + evaluation ceilings. */
+    run_max_cents: number;
+    /**
+     * The first instant of the next UTC month, when the counted spend starts
+     * again from nothing. When `run_max_cents` alone exceeds the limit, no month
+     * will ever fit and only raising the limit helps; `message` says which.
+     */
+    resumes_at: string;
+}
+/** The most versions a pipeline may be set to make (loop-service maxVersionsCeiling). */
+export declare const PIPELINE_MAX_VERSIONS_CEILING = 10;
+/**
+ * What a pipeline is doing. `needs_review` and `needs_funds` are a finished
+ * version waiting on the MEMBER -- a decision, or a top-up -- which is not the
+ * platform working on it.
+ *
+ * `paused` is a rule that is switched off, AND an enabled rule the platform
+ * has stopped firing (`paused_reason`) or whose terms changed and were never
+ * accepted (`needs_consent`). `complete` is a pipeline at its `max_versions`.
+ */
+export type PipelineStatus = 'running' | 'needs_review' | 'needs_funds' | 'waiting' | 'paused' | 'complete';
+/**
+ * The run in flight. It is not a version until its comparison is reported
+ * having scored at least one conversation, or a member puts it live.
+ */
+export interface PipelineActiveRun {
+    run_id: string;
+    state: TrainingRunState;
+    since: string;
+    /**
+     * The version number it will take if it becomes one: if its comparison
+     * scores something, or if a member promotes it anyway.
+     */
+    will_be_version: number;
+    version_no: number | null;
+    last_reason: string | null;
+    last_error: string | null;
+    train_rows: number | null;
+    holdout_rows: number | null;
+    /**
+     * Its comparison scored at least one conversation. False on a reported run
+     * means the held-back set was too small to compare anything: that run is
+     * not a version, and becomes one only if a member promotes it.
+     */
+    competed: boolean;
+    /** What recipe it is trying, when it is a recipe variant. See TrainingRun.recipe_note. */
+    recipe_note: string | null;
+}
+/**
+ * One version: a trained model whose comparison scored at least one
+ * conversation, or one a member put live without one. The second kind has
+ * `rows_scored` 0 and `win_rate` null, and may be the champion.
+ */
+export interface PipelineVersion {
+    version: number;
+    run_id: string;
+    seq: number;
+    state: TrainingRunState;
+    verdict: TrainingVerdict | null;
+    decision: TrainingDecision | null;
+    decided_at: string | null;
+    /** True for the version the app is served by today. */
+    is_champion: boolean;
+    checkpoint_id: string | null;
+    train_rows: number | null;
+    holdout_rows: number | null;
+    /** Head-to-head against the champion of its day, on conversations neither trained on. */
+    rows_scored: number | null;
+    win_rate: number | null;
+    mean_delta: number | null;
+    /**
+     * The standing benchmark's replay of this version, when the rule has one.
+     * Only scores with `benchmark_comparable` sit on one axis.
+     */
+    benchmark_score: number | null;
+    benchmark_rows: number | null;
+    benchmark_rows_total: number | null;
+    benchmark_status: string | null;
+    /**
+     * False for a score that is not on today's yardstick: measured on an earlier
+     * revision of the benchmark's items, or on a different benchmark than the
+     * one attached now. Never draw or subtract those on the same line.
+     */
+    benchmark_comparable: boolean;
+    /**
+     * Everything this version's run cost, in cents: training, the comparison
+     * machine, the judge and the benchmark replay.
+     */
+    cost_cents: number;
+    /**
+     * True when no charge was recorded for the comparison machine (a run made
+     * before the platform recorded one) and `cost_cents` counts it at its
+     * ceiling instead, so the figure is the most the version can have cost,
+     * not what it did.
+     */
+    cost_includes_candidate_ceiling: boolean;
+    created_at: string;
+    /**
+     * When this version's head-to-head started. The champion it faced is the
+     * model that was serving at that moment, which is why a delta against "the
+     * champion before it" is decided by this and not by `created_at`. Null when
+     * no comparison was ever started for it.
+     */
+    compared_at: string | null;
+    /**
+     * Why the run that made it fired. `variant` is a version trained on the same
+     * conversations as the one before it with one setting changed; every other
+     * value is a version that learned from newly reviewed conversations (or a
+     * member's run now).
+     */
+    trigger: TrainingTrigger;
+    /** See TrainingRun.recipe_note. */
+    recipe_note: string | null;
+    /** See TrainingRun.recipe_of_version. */
+    recipe_of_version: number | null;
+    /** See TrainingRun.recipe. */
+    recipe: TrainingRecipe;
+    finished_at: string | null;
+}
+/**
+ * A training rule seen as the series of versions it produces: which exist,
+ * which one serves, whether each beat the one before it, and what happens
+ * next. READ-ONLY: every decision stays on the route that owns it (promote,
+ * reject and roll back on the run; the version limit on the rule).
+ */
+/**
+ * Whether a pipeline can make a recipe variant next, and when it cannot, which
+ * reason -- each is a different next step.
+ *
+ * - `off`: explore_recipes is off.
+ * - `waiting_for_v1`: on, but a variant varies a version and there is none yet.
+ * - `available`: on, with `recipe_variants_left` untried variants that fit.
+ * - `no_slots`: untried variants fit (`recipe_variants_left` > 0), but every
+ *   version slot is made or taken by the run in flight. Raise `max_versions`
+ *   (or, at 10, start a new pipeline) and one can run. Only when variants are
+ *   left: a service that reports `no_slots` with `recipe_variants_left` of 0
+ *   means `all_tried`, and raising the limit starts nothing.
+ * - `all_tried`: every variant that fits has been tried on the conversations
+ *   it has now, whether or not a version slot is free. Raising `max_versions`
+ *   does not start one; new reviews bring the next version.
+ * - `none_fit`: no variant fits this rule's training settings.
+ */
+export type PipelineRecipeExploration = 'off' | 'waiting_for_v1' | 'available' | 'no_slots' | 'all_tried' | 'none_fit';
+export interface Pipeline {
+    rule_id: string;
+    rule_name: string;
+    enabled: boolean;
+    /** The limit the member set, 1 to 10. */
+    max_versions: number;
+    /** Versions made so far. At `max_versions` the pipeline stops. */
+    versions_made: number;
+    /** The pinned base every version is a fresh adapter over, which is what makes their scores comparable. */
+    base_model_id: string;
+    base_model_revision: string;
+    train_type: string;
+    /** Null when what serves is not a version of this pipeline. */
+    champion_version: number | null;
+    /** The name the app calls. It does not change when a version is promoted. */
+    serving_name: string;
+    /**
+     * Another pipeline that has since promoted onto the same serving name. Only
+     * the most recent promotion serves; this pipeline's own champion no longer
+     * does. Null when nothing has taken the name over.
+     */
+    serving_taken_over_by: string | null;
     benchmark_id: string | null;
+    benchmark_name: string | null;
+    benchmark_decides: boolean;
+    benchmark_min_delta: number;
+    status: PipelineStatus;
+    /**
+     * The rule's own sentence about what it is waiting for or why it stopped,
+     * verbatim. Only as fresh as the platform's last visit: when `status` is
+     * `paused`, `paused_reason` and `needs_consent` are what say why.
+     */
+    next_reason: string | null;
+    last_checked_at: string | null;
+    next_due_at: string | null;
+    auto_promote: boolean;
+    /** Why the platform stopped firing this rule, or null. Same codes as the rule's. */
+    paused_reason: TrainingRulePausedReason | null;
+    /**
+     * The rule's terms changed and nobody has accepted them. It makes nothing
+     * until somebody does.
+     */
+    needs_consent: boolean;
+    /** The rule's explore_recipes, as it stands. */
+    explore_recipes: boolean;
+    /**
+     * How many recipe variants that fit this rule's settings have not yet been
+     * tried on the conversations the pipeline has now. Not capped by the free
+     * version slots; 0 while exploration is off or when no variant fits. A count
+     * is not a reason: read `recipe_exploration` for whether one can run next.
+     */
+    recipe_variants_left: number;
+    /** Whether the next recipe variant can be tried, and if not, why. */
+    recipe_exploration: PipelineRecipeExploration;
+    /** The rule's monthly limit. Null means it has none. */
+    monthly_ceiling_cents: number | null;
+    /**
+     * What this rule's runs have cost at most, counted toward the monthly limit
+     * this UTC calendar month -- the figure the limit is enforced against. An
+     * upper bound, not an exact spend. A run counts toward the month it was
+     * created in, and a run still in progress also counts toward the current
+     * month, at its three ceilings or what it has been billed when that is
+     * more. A finished run counts what it was billed, and its comparison
+     * machine is billed at the most it could have cost (the hourly cap for the
+     * time it was up, never more than the candidate ceiling). A run created in
+     * an earlier month that finishes in this one counts here only while it is
+     * still running.
+     */
+    month_spent_cents: number;
+    active_run: PipelineActiveRun | null;
+    versions: PipelineVersion[];
 }
 export interface TrainingRuleListResponse {
     rules: TrainingRule[];
@@ -3990,6 +4445,7 @@ export interface TrainingRuleListResponse {
 export interface TrainingRuleResponse {
     rule: TrainingRule;
     recent_runs: TrainingRunSummary[];
+    /** What this rule's runs have cost at most this UTC calendar month; see {@link Pipeline.month_spent_cents}. */
     month_spent_cents: number;
     judge_agreement: JudgeAgreement | null;
 }
@@ -4062,3 +4518,14 @@ export interface BenchmarkHistoryResponse {
     points: BenchmarkHistoryPoint[];
     total: number;
 }
+export interface PipelineListResponse {
+    /** The newest pipelines first, at most the service's page (100). */
+    pipelines: Pipeline[];
+    /** Every pipeline in the workspace, including any not returned. */
+    total: number;
+    /** More pipelines exist than were returned; the rest are reached through `listTrainingRules`. */
+    truncated: boolean;
+}
+export interface PipelineResponse {
+    pipeline: Pipeline;
+}

package/dist/types.js

@@ -12,3 +12,6 @@ export const TERMINAL_RUN_STATES = [
     'superseded',
     'rolled_back',
 ];
+/* ── Pipelines ────────────────────────────────────────────────────────────── */
+/** The most versions a pipeline may be set to make (loop-service maxVersionsCeiling). */
+export const PIPELINE_MAX_VERSIONS_CEILING = 10;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "runbios-sdk",
-  "version": "0.2.13",
+  "version": "0.2.14-dev.244",
   "description": "Official TypeScript SDK for the Run BiOS training and deployment platform API",
   "type": "module",
   "main": "./dist/index.js",