runbios-sdk 0.2.22-dev.313 → 0.2.22-dev.319

package/README.md

@@ -100,7 +100,7 @@ without an explicit replay acknowledgement from the endpoint.
 
 **Parameter naming on `/v1` calls.** Only the parameters this SDK names are
 camelCase: `model`, `messages`, `tools`, `toolChoice`, `reasoningEffort`,
-`inferenceKey`, `idempotencyKey`, `requestId`, `signal`. Every other key is
+`inferenceKey`, `idempotencyKey`, `requestId`, `signal`, `loop`. Every other key is
 forwarded to the OpenAI-compatible endpoint **verbatim**, so it must use
 OpenAI's own snake_case spelling — `max_tokens`, `top_p`, `stop`,
 `frequency_penalty`, `presence_penalty`. The endpoint rejects an unknown key
@@ -217,6 +217,53 @@ for await (const event of dedicated.streamCompletions({ model: 'completion-deplo
 methods close the upstream reader when iteration ends. None of the inference
 POSTs are retried automatically, and `idempotencyKey` is sent only if supplied.
 
+#### Record conversations into a Conscious Loop pipeline (one header)
+
+Add `loop: { pipeline: '<tag>' }` to `chatCompletions`, `streamChatCompletions`,
+`messages` or `streamMessages` and the call is sent exactly as before with one
+more header, `X-Loop-Pipeline: <tag>` (several tags: `pipeline: ['a', 'b']`).
+The gateway records the exchange -- what was asked, what the model answered and
+its tool calls -- as a sample of the pipelines those tags feed (a pipeline's
+`own_tag`), even where recording is off for that model: the header is your
+consent for that one exchange. It works for serverless models and dedicated
+deployments, including the pipeline's own `loop-<tag>` model.
+
+The gateway answers with the sample's id in `X-Loop-Sample-Id`. A non-streaming
+result carries it as `loop_sample_id` (non-enumerable: it is never part of the
+answer's JSON), and `loop.onSampleId` hears it as soon as the headers arrive,
+before the first streamed chunk. It is `null` when the gateway recorded nothing.
+Send feedback on that id; it is the trace id the feedback calls take.
+
+```typescript
+const reply = await client.inference.chatCompletions({
+  model: 'loop-support-replies',
+  messages: [{ role: 'user', content: 'Where is my order?' }],
+  loop: { pipeline: 'support-replies' },
+});
+const sampleId = reply.loop_sample_id;
+if (sampleId) {
+  await client.loop.upvote(sampleId);                  // a good answer
+  // await client.loop.downvote(sampleId);             // a bad one
+  // await client.loop.correct(sampleId, 'The right answer.');
+}
+
+for await (const chunk of client.inference.streamChatCompletions({
+  model: 'loop-support-replies',
+  messages: [{ role: 'user', content: 'Where is my order?' }],
+  loop: { pipeline: 'support-replies', onSampleId: (id) => console.log('sample', id) },
+})) {
+  process.stdout.write(String((chunk.choices as any)?.[0]?.delta?.content ?? ''));
+}
+```
+
+Feedback sent before the sample is recorded is refused `409
+SAMPLE_NOT_YET_RECORDED`, and nothing is stored. `upvote`, `downvote`,
+`correct`, `gold` and `signal` send it again after the `Retry-After` seconds (2
+when none is given), at most 6 times in all, then throw that error. A stream
+that was cut short is never recorded, so its id stays unknown. If you send
+`X-Request-ID`, keep it unique per call: a repeated one is recorded once.
+`completions`, `embeddings` and `rerank` are not recorded and refuse the option.
+
 #### Workspace serverless usage and limits (read-only)
 
 A workspace-bound platform key or hosted OAuth grant with `analytics:read` can

package/dist/client.d.ts

@@ -50,8 +50,19 @@ export declare class ApiError extends Error {
     readonly availableGpus: AvailableGpuAlternative[] | undefined;
     /** Availability snapshot time behind an availability rejection. */
     readonly checkedAt: string | undefined;
+    /**
+     * How many seconds the service asked you to wait before trying again: its
+     * `Retry-After` header, as seconds or as a date. Undefined when it sent none.
+     */
+    retryAfter: number | undefined;
     constructor(status: number, body: ApiErrorBody);
 }
+/**
+ * Seconds to wait from a `Retry-After` header: a number of seconds, or an HTTP
+ * date (seconds until then, never negative). Undefined when absent or
+ * unreadable. @internal
+ */
+export declare function retryAfterSeconds(value: string | null | undefined, now?: number): number | undefined;
 /**
  * The one transient GPU-rejection code: the GPU is not in stock right now, so
  * waiting or joining the capacity queue can still succeed.

package/dist/client.js

@@ -53,6 +53,11 @@ export class ApiError extends Error {
     availableGpus;
     /** Availability snapshot time behind an availability rejection. */
     checkedAt;
+    /**
+     * How many seconds the service asked you to wait before trying again: its
+     * `Retry-After` header, as seconds or as a date. Undefined when it sent none.
+     */
+    retryAfter;
     constructor(status, body) {
         const err = body.error;
         const nested = typeof err === 'object' && err !== null ? err : null;
@@ -71,8 +76,29 @@ export class ApiError extends Error {
         const alts = flat.available_gpus ?? flat.available_alternatives;
         this.availableGpus = Array.isArray(alts) && alts.length > 0 ? alts : undefined;
         this.checkedAt = flat.checked_at;
+        this.retryAfter = undefined;
     }
 }
+/**
+ * Seconds to wait from a `Retry-After` header: a number of seconds, or an HTTP
+ * date (seconds until then, never negative). Undefined when absent or
+ * unreadable. @internal
+ */
+export function retryAfterSeconds(value, now = Date.now()) {
+    const raw = (value ?? '').trim();
+    if (!raw)
+        return undefined;
+    if (/^\d+(\.\d+)?$/.test(raw))
+        return Number(raw);
+    const at = Date.parse(raw);
+    return Number.isNaN(at) ? undefined : Math.max(0, (at - now) / 1000);
+}
+/** The error a non-2xx response stands for, with its `Retry-After`. @internal */
+function errorFromResponse(res, data) {
+    const err = buildApiError(res.status, data);
+    err.retryAfter = retryAfterSeconds(res.headers.get('retry-after'));
+    return err;
+}
 /**
  * Flatten the standard `{ error: { ... } }` envelope over the legacy top-level
  * fields so structured capacity data is found in either shape. @internal
@@ -431,7 +457,7 @@ export class HttpClient {
         }
         const data = await res.json().catch(() => ({}));
         if (!res.ok) {
-            throw buildApiError(res.status, data);
+            throw errorFromResponse(res, data);
         }
         return data;
     }
@@ -486,7 +512,7 @@ export class HttpClient {
         }
         const data = await res.json().catch(() => ({}));
         if (!res.ok) {
-            throw buildApiError(res.status, data);
+            throw errorFromResponse(res, data);
         }
         return data;
     }

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.22-dev.313";
+export declare const VERSION = "0.2.22-dev.319";
 export declare class RunBiOS {
     /** Search models, fetch configs, check adapter compatibility. */
     readonly models: Models;
@@ -74,8 +74,8 @@ 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, type InferenceVerbParams, type CompletionParams, type EmbeddingParams, type RerankParams, type AnthropicMessageParams, 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, InferenceModel, InferenceModelListResponse, ModelConfig, Dataset, DatasetListParams, DatasetListResponse, DatasetUploadParams, DatasetPreview, DatasetPreviewParams, DatasetImportHFParams, DatasetRegisterHFParams, DatasetHubSearchParams, DatasetHubPreviewParams, DatasetValidation, DatasetFormatVariant, DatasetFormatSpec, DatasetFormatSpecs, DatasetStorageUsage, TrainingMethod, RLHFAlgorithm, AdapterType, TrainingJobStatus, TrainingStatusFilter, TrainingCreateParams, TrainingStartFromParams, TrainingStartFrom, TrainingListParams, TrainingListResponse, TrainingJob, TrainingMetrics, TrainingResourceMetrics, TrainingDeviceMetrics, MetricPoint, MetricGraphConfig, TrainingCheckpoint, TrainingLogs, TrainingLogEntry, TrainingStopResponse, TrainingResumeResponse, CanonicalTrainingRequest, TrainingPreflightDataset, TrainingPreflightWarning, TrainingPreflightResponse, TrainingCapabilityChoice, TrainingConfigFieldCapability, TrainingCapabilities, TrainingFeature, 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, ServingKind, TrainingRulePausedReason, TrainingTrigger, TrainingRecipe, TrainingRunState, TrainingVerdict, TrainingDecision, EvaluationStatus, EvaluationItemStatus, ItemErrorCode, EvaluationWinner, EvaluationItemWinnerFilter, ReportStatusFilter, ReportSort, EvaluationWarningCode, TrainingToolCall, TrainingMessage, TrainingRuleServing, TrainingRunPromoteRequest, TrainingRunRejectRequest, TrainingRunRollbackRequest, TrainingRunCancelRequest, TrainingRunListParams, TrainingRun, TrainingRunSummary, TrainingRunEvent, TrainingRunLinks, TrainingRunActions, EvaluationRef, EvaluationDecoding, EvaluationJudgeDimension, EvaluationDimensionScore, EvaluationWarning, EvaluationMargin, Evaluation, EvaluationItemJudge, EvaluationReferenceKind, EvaluationReference, EvaluationPairwiseOrder, EvaluationItemPairwise, EvaluationItemSide, EvaluationItem, EvaluationItemListParams, BenchmarkStatus, BenchmarkSourceKind, BenchmarkRunStatus, BenchmarkScoring, BenchmarkCheck, BenchmarkDimensionScore, Benchmark, BenchmarkItem, BenchmarkRun, BenchmarkRunItemSide, BenchmarkRunItem, BenchmarkRunItemListParams, BenchmarkHistoryPoint, BenchmarkSource, BenchmarkCreateParams, BenchmarkListParams, BenchmarkItemListParams, BenchmarkHistoryParams, BenchmarkRetireParams, InferenceAlias, InferenceAliasRequest, TrainingRuleDeleteResponse, TrainingRunListResponse, TrainingRunBenchmarkRun, TrainingRunResponse, TrainingRunActionResponse, EvaluationItemsResponse, BenchmarkRunItemsResponse, InferenceAliasListResponse, InferenceAliasResponse, InferenceAliasDeleteResponse, BenchmarkListResponse, BenchmarkItemsResponse, BenchmarkHistoryResponse, TrainingRuleRunRefusalCode, TrainingRuleSaveRefusalCode, TrainingRuleMonthlyLimitRefusal, PipelineStatus, PipelineActiveRun, PipelineVersion, PipelineAttempt, PipelineAttemptTrigger, Lineage, PipelineChain, PipelineChainRebuild, TrainingRunRollbackRefusalCode, LoopTraceRebuild, LoopTraceDeleteResponse, PipelineAttemptOutcome, PipelineLiveDeploymentStatus, PipelineLiveDeployment, LoopStorageWhere, LoopStorage, Pipeline, PipelineListParams, PipelineListResponse, PipelineResponse, PipelineTrainWhen, PipelineSchedule, PipelineWriteRequest, PipelineMutationResponse, PipelineImportParams, PipelineFloors, HeldBackFloors, LoopModel, LoopModelsResponse, LoopTracePipeline, LoopTracePipelinesResponse, LoopMetricsHistoryParams, LoopMetricPoint, LoopSignalDay, LoopMetricsHistory, PromotionPolicyState, RuleBenchmark, PipelineBenchmarksResponse, PipelineBenchmarkAttachParams, PipelineBenchmarkMoveParams, CompareBenchmark, VersionBenchmarkScore, PromotionMeasurement, PromotionOutcome, VersionHoldout, VersionScores, VersionScoreDifference, VersionCompareResponse, VersionCompareParams, TrainingRunPromotion, VerdictCheck, VerdictCheckKey, VerdictChecksWithheld, TrainingRunCost, AttemptDirection, AttemptHoldout, AttemptCompareSide, AttemptSharedSample, AttemptSharedFigures, AttemptBenchmarkSide, AttemptCompareBenchmark, AttemptCompareItemSide, AttemptCompareItem, AttemptCompareResponse, AttemptCompareParams, } 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 InferenceVerbParams, type CompletionParams, type EmbeddingParams, type RerankParams, type AnthropicMessageParams, type AnthropicMessageResponse, type LoopCaptureOption, type LoopSampleIdOnResult, LOOP_PIPELINE_HEADER, LOOP_SAMPLE_ID_HEADER, 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, InferenceModel, InferenceModelListResponse, ModelConfig, Dataset, DatasetListParams, DatasetListResponse, DatasetUploadParams, DatasetPreview, DatasetPreviewParams, DatasetImportHFParams, DatasetRegisterHFParams, DatasetHubSearchParams, DatasetHubPreviewParams, DatasetValidation, DatasetFormatVariant, DatasetFormatSpec, DatasetFormatSpecs, DatasetStorageUsage, TrainingMethod, RLHFAlgorithm, AdapterType, TrainingJobStatus, TrainingStatusFilter, TrainingCreateParams, TrainingStartFromParams, TrainingStartFrom, TrainingListParams, TrainingListResponse, TrainingJob, TrainingMetrics, TrainingResourceMetrics, TrainingDeviceMetrics, MetricPoint, MetricGraphConfig, TrainingCheckpoint, TrainingLogs, TrainingLogEntry, TrainingStopResponse, TrainingResumeResponse, CanonicalTrainingRequest, TrainingPreflightDataset, TrainingPreflightWarning, TrainingPreflightResponse, TrainingCapabilityChoice, TrainingConfigFieldCapability, TrainingCapabilities, TrainingFeature, 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, ServingKind, TrainingRulePausedReason, TrainingTrigger, TrainingRecipe, TrainingRunState, TrainingVerdict, TrainingDecision, EvaluationStatus, EvaluationItemStatus, ItemErrorCode, EvaluationWinner, EvaluationItemWinnerFilter, ReportStatusFilter, ReportSort, EvaluationWarningCode, TrainingToolCall, TrainingMessage, TrainingRuleServing, TrainingRunPromoteRequest, TrainingRunRejectRequest, TrainingRunRollbackRequest, TrainingRunCancelRequest, TrainingRunListParams, TrainingRun, TrainingRunSummary, TrainingRunEvent, TrainingRunLinks, TrainingRunActions, EvaluationRef, EvaluationDecoding, EvaluationJudgeDimension, EvaluationDimensionScore, EvaluationWarning, EvaluationMargin, Evaluation, EvaluationItemJudge, EvaluationReferenceKind, EvaluationReference, EvaluationPairwiseOrder, EvaluationItemPairwise, EvaluationItemSide, EvaluationItem, EvaluationItemListParams, BenchmarkStatus, BenchmarkSourceKind, BenchmarkRunStatus, BenchmarkScoring, BenchmarkCheck, BenchmarkDimensionScore, Benchmark, BenchmarkItem, BenchmarkRun, BenchmarkRunItemSide, BenchmarkRunItem, BenchmarkRunItemListParams, BenchmarkHistoryPoint, BenchmarkSource, BenchmarkCreateParams, BenchmarkListParams, BenchmarkItemListParams, BenchmarkHistoryParams, BenchmarkRetireParams, InferenceAlias, InferenceAliasRequest, TrainingRuleDeleteResponse, TrainingRunListResponse, TrainingRunBenchmarkRun, TrainingRunResponse, TrainingRunActionResponse, EvaluationItemsResponse, BenchmarkRunItemsResponse, InferenceAliasListResponse, InferenceAliasResponse, InferenceAliasDeleteResponse, BenchmarkListResponse, BenchmarkItemsResponse, BenchmarkHistoryResponse, TrainingRuleRunRefusalCode, TrainingRuleSaveRefusalCode, TrainingRuleMonthlyLimitRefusal, PipelineStatus, PipelineActiveRun, PipelineVersion, PipelineAttempt, AttemptExplanation, PipelineAttemptListParams, PipelineAttemptListResponse, PipelineAttemptModelFilter, PipelineAttemptResultFilter, PipelineAttemptTrigger, Lineage, PipelineChain, PipelineChainRebuild, TrainingRunRollbackRefusalCode, LoopTraceRebuild, LoopTraceDeleteResponse, PipelineAttemptOutcome, PipelineLiveDeploymentStatus, PipelineLiveDeployment, LoopStorageWhere, LoopStorage, Pipeline, PipelineListParams, PipelineListStatus, PipelineListResponse, PipelineTrainingSettings, PipelineTrainingDefaults, PipelineTrainingRequest, PipelineResponse, PipelineTrainWhen, PipelineSchedule, PipelineWriteRequest, PipelineMutationResponse, PipelineImportParams, PipelineFloors, HeldBackFloors, LoopModel, LoopModelsResponse, LoopUnavailableModel, LoopUnavailableReasonCode, LoopTracePipeline, LoopTracePipelinesResponse, LoopMetricsHistoryParams, LoopMetricPoint, LoopSignalDay, LoopMetricsHistory, PromotionPolicyState, RuleBenchmark, PipelineBenchmarksResponse, PipelineBenchmarkAttachParams, PipelineBenchmarkMoveParams, CompareBenchmark, VersionBenchmarkScore, PromotionMeasurement, PromotionOutcome, VersionHoldout, VersionScores, VersionScoreDifference, VersionCompareResponse, VersionCompareParams, TrainingRunPromotion, VerdictCheck, VerdictCheckKey, VerdictChecksWithheld, TrainingRunCost, AttemptDirection, AttemptHoldout, AttemptCompareSide, AttemptSharedSample, AttemptSharedFigures, AttemptBenchmarkSide, AttemptCompareBenchmark, AttemptCompareItemSide, AttemptCompareItem, AttemptCompareResponse, AttemptCompareParams, } 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. */

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.22-dev.313';
+export const VERSION = '0.2.22-dev.319';
 export class RunBiOS {
     /** Search models, fetch configs, check adapter compatibility. */
     models;
@@ -102,7 +102,7 @@ export { Integrations } from './resources/integrations.js';
 export { Training } from './resources/training.js';
 export { Wallet } from './resources/wallet.js';
 export { GPU } from './resources/gpu.js';
-export { Inference, validateChatRequest, parseSSE, buildInferenceRequest, contextSizingBasis, CONTEXT_DEFAULT_CEILING, CONTEXT_EDITABLE_FLOOR, } from './resources/inference.js';
+export { Inference, validateChatRequest, parseSSE, buildInferenceRequest, contextSizingBasis, CONTEXT_DEFAULT_CEILING, CONTEXT_EDITABLE_FLOOR, LOOP_PIPELINE_HEADER, LOOP_SAMPLE_ID_HEADER, } 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. */

package/dist/resources/inference.d.ts

@@ -49,6 +49,50 @@ export interface FunctionTool extends Record<string, unknown> {
         strict?: boolean;
     };
 }
+/**
+ * Record one exchange into Conscious Loop pipelines with one header (the
+ * `loop` option of `chatCompletions`, `streamChatCompletions`, `messages` and
+ * `streamMessages`).
+ *
+ * The call goes to your model exactly as it would without it, with
+ * `X-Loop-Pipeline: <tag>[, <tag>...]` added: the gateway records the
+ * exchange (what was asked, what the model answered, its tool calls) as a
+ * sample of the pipelines those tags feed -- a pipeline's `own_tag` -- even
+ * where recording is off for that model, because the header is your consent
+ * for this one exchange. It answers with the sample's id in
+ * `X-Loop-Sample-Id`, before the body when streaming. Send feedback on that id
+ * with `client.loop.upvote`, `downvote` or `correct`: the sample id is the
+ * `traceId` they take. Feedback sent before the sample is recorded can be
+ * refused 409 `SAMPLE_NOT_YET_RECORDED`; send it again after the
+ * `Retry-After` seconds.
+ *
+ * Works for serverless models and dedicated deployments, on
+ * `/v1/chat/completions` and `/v1/messages` only.
+ */
+export interface LoopCaptureOption {
+    /** One pipeline tag, or several; each a non-empty tag with no comma. */
+    pipeline: string | string[];
+    /**
+     * Called once with the sample id as soon as the response headers arrive
+     * (before the first streamed chunk), or with null when the gateway recorded
+     * nothing for this exchange (no `X-Loop-Sample-Id` came back). A
+     * non-streaming result also carries it as `loop_sample_id`.
+     */
+    onSampleId?: (sampleId: string | null) => void;
+}
+/** The request header the `loop` option sends. */
+export declare const LOOP_PIPELINE_HEADER = "X-Loop-Pipeline";
+/** The response header the gateway answers a recorded exchange with: the sample's id. */
+export declare const LOOP_SAMPLE_ID_HEADER = "X-Loop-Sample-Id";
+/**
+ * A non-streaming `/v1` answer, as the endpoint sent it, plus
+ * `loop_sample_id`: the `X-Loop-Sample-Id` the gateway answered with, or null
+ * when it sent none. It is NON-ENUMERABLE, so it is never part of the
+ * object's JSON or its keys; read it by name.
+ */
+export interface LoopSampleIdOnResult {
+    readonly loop_sample_id?: string | null;
+}
 export interface ChatCompletionParams extends Record<string, unknown> {
     messages: ChatMessage[];
     model?: string;
@@ -75,8 +119,10 @@ export interface ChatCompletionParams extends Record<string, unknown> {
     idempotencyKey?: string;
     requestId?: string;
     signal?: AbortSignal;
+    /** Record this exchange into Conscious Loop pipelines. See {@link LoopCaptureOption}. */
+    loop?: LoopCaptureOption;
 }
-export type ChatCompletionResponse = Record<string, unknown>;
+export type ChatCompletionResponse = Record<string, unknown> & LoopSampleIdOnResult;
 export type ChatCompletionChunk = Record<string, unknown>;
 export interface InferenceVerbParams extends Record<string, unknown> {
     model?: string;
@@ -99,7 +145,11 @@ export interface AnthropicMessageParams extends InferenceVerbParams {
     messages: Array<Record<string, unknown>>;
     max_tokens: number;
     anthropicVersion?: string;
+    /** Record this exchange into Conscious Loop pipelines. See {@link LoopCaptureOption}. */
+    loop?: LoopCaptureOption;
 }
+/** A non-streaming `/v1/messages` answer, with `loop_sample_id` (see {@link LoopSampleIdOnResult}). */
+export type AnthropicMessageResponse = Record<string, unknown> & LoopSampleIdOnResult;
 export type ServerlessUsageWindow = '1h' | '24h' | '7d' | '30d' | '90d';
 export type ServerlessTimeseriesMetric = 'requests' | 'tokens' | 'spend' | 'ttft_p50' | 'ttft_p95' | 'tps';
 export interface ServerlessWorkspaceLimits {
@@ -359,12 +409,28 @@ export declare class Inference {
     completions(params: CompletionParams): Promise<Record<string, unknown>>;
     embeddings(params: EmbeddingParams): Promise<Record<string, unknown>>;
     rerank(params: RerankParams): Promise<Record<string, unknown>>;
-    messages(params: AnthropicMessageParams): Promise<Record<string, unknown>>;
+    /**
+     * Anthropic Messages (`/v1/messages`). With `loop: { pipeline }` the
+     * exchange is recorded into those pipelines and the result carries
+     * `loop_sample_id` (see {@link LoopCaptureOption}).
+     */
+    messages(params: AnthropicMessageParams): Promise<AnthropicMessageResponse>;
     streamCompletions(params: CompletionParams): AsyncGenerator<Record<string, unknown>>;
+    /** Anthropic Messages, streamed. With `loop`, `loop.onSampleId` hears the sample id before the first event. */
     streamMessages(params: AnthropicMessageParams): AsyncGenerator<Record<string, unknown>>;
     listModels(inferenceKey?: string): Promise<InferenceModelListResponse>;
     retrieveModel(modelId: string, inferenceKey?: string): Promise<InferenceModel>;
+    /**
+     * OpenAI chat completions (`/v1/chat/completions`). With
+     * `loop: { pipeline: 'support-replies' }` the exchange is recorded into
+     * that pipeline and the result carries `loop_sample_id`, the id to send
+     * feedback on (see {@link LoopCaptureOption}).
+     */
     chatCompletions(params: ChatCompletionParams): Promise<ChatCompletionResponse>;
+    /**
+     * OpenAI chat completions, streamed. With `loop`, `loop.onSampleId` hears
+     * the sample id as soon as the headers arrive, before the first chunk.
+     */
     streamChatCompletions(params: ChatCompletionParams): AsyncGenerator<ChatCompletionChunk>;
 }
 export { buildInferenceRequest };

package/dist/resources/inference.js

@@ -135,6 +135,43 @@ function buildInferenceRequest(params) {
         body.max_price_hour_cents = params.maxPriceHourCents;
     return body;
 }
+/** The request header the `loop` option sends. */
+export const LOOP_PIPELINE_HEADER = 'X-Loop-Pipeline';
+/** The response header the gateway answers a recorded exchange with: the sample's id. */
+export const LOOP_SAMPLE_ID_HEADER = 'X-Loop-Sample-Id';
+/** `X-Loop-Pipeline`'s value for a `loop` option, or a thrown Error before any request. */
+function loopPipelineHeader(loop) {
+    if (!loop || typeof loop !== 'object')
+        throw new Error('loop must be an object: { pipeline }');
+    const tags = Array.isArray(loop.pipeline) ? loop.pipeline : [loop.pipeline];
+    if (tags.length === 0)
+        throw new Error('loop.pipeline must name at least one pipeline tag');
+    return tags.map((tag) => {
+        const value = typeof tag === 'string' ? tag.trim() : '';
+        // A comma would split one tag into two, and a control character would end
+        // the header: both are refused here rather than sent.
+        if (!value || /[,\u0000-\u001f\u007f]/.test(value)) {
+            throw new Error(`loop.pipeline: ${JSON.stringify(tag)} is not a pipeline tag`);
+        }
+        return value;
+    }).join(', ');
+}
+/** The sample id a response carries (null when none), told to the caller's onSampleId once. */
+function takeLoopSampleId(response, loop) {
+    const id = response.headers.get(LOOP_SAMPLE_ID_HEADER)?.trim() || null;
+    if (loop?.onSampleId)
+        loop.onSampleId(id);
+    return id;
+}
+/** `loop_sample_id` on a non-streaming result, non-enumerable. */
+function withLoopSampleId(payload, id) {
+    if (payload && typeof payload === 'object' && !Array.isArray(payload)) {
+        Object.defineProperty(payload, 'loop_sample_id', {
+            value: id, enumerable: false, writable: false, configurable: true,
+        });
+    }
+    return payload;
+}
 function serverlessRead(value, valid) {
     const body = value && typeof value === 'object' && !Array.isArray(value) ? value : null;
     if (!body || !valid(body)) {
@@ -792,7 +829,7 @@ export class Inference {
     // OpenAI-compatible key-scoped inference — `/v1/chat/completions`
     // --------------------------------------------------------------------------
     prepare(params, stream) {
-        const { messages, model, tools, toolChoice, reasoningEffort, inferenceKey, idempotencyKey, requestId, signal, ...extra } = params;
+        const { messages, model, tools, toolChoice, reasoningEffort, inferenceKey, idempotencyKey, requestId, signal, loop, ...extra } = params;
         const key = inferenceKey || this.key;
         if (!key)
             throw new Error('an inferenceKey is required');
@@ -814,6 +851,8 @@ export class Inference {
         };
         if (idempotencyKey)
             headers['Idempotency-Key'] = idempotencyKey;
+        if (loop !== undefined)
+            headers[LOOP_PIPELINE_HEADER] = loopPipelineHeader(loop);
         return { body, key, headers, signal };
     }
     abortContext(signal) {
@@ -831,7 +870,10 @@ export class Inference {
         };
     }
     prepareVerb(params, stream, anthropic) {
-        const { inferenceKey, idempotencyKey, requestId, signal, anthropicVersion, stream: requestedStream, ...payload } = params;
+        const { inferenceKey, idempotencyKey, requestId, signal, anthropicVersion, stream: requestedStream, loop, ...payload } = params;
+        if (loop !== undefined && !anthropic) {
+            throw new Error('loop capture is offered on chatCompletions and messages only');
+        }
         if (requestedStream !== undefined)
             throw new Error('Choose the streaming method instead of setting stream in a request body');
         const key = inferenceKey || this.key;
@@ -851,6 +893,8 @@ export class Inference {
             }
             headers['Anthropic-Version'] = anthropicVersion || '2023-06-01';
         }
+        if (loop !== undefined)
+            headers[LOOP_PIPELINE_HEADER] = loopPipelineHeader(loop);
         return { body: stream ? { ...payload, stream: true } : payload, headers, signal };
     }
     async sendVerb(path, params, anthropic = false) {
@@ -862,6 +906,8 @@ export class Inference {
             });
             if (!response.ok)
                 throw await apiError(response);
+            const loop = anthropic ? params.loop : undefined;
+            const sampleId = anthropic ? takeLoopSampleId(response, loop) : null;
             let payload;
             try {
                 payload = await response.json();
@@ -872,7 +918,7 @@ export class Inference {
             if (!payload || typeof payload !== 'object' || Array.isArray(payload)) {
                 throw new ApiError(response.status, { error: 'Inference endpoint returned no response object' });
             }
-            return payload;
+            return anthropic ? withLoopSampleId(payload, sampleId) : payload;
         }
         catch (error) {
             if (abort.controller.signal.aborted && !(error instanceof ApiError)) {
@@ -929,6 +975,8 @@ export class Inference {
             if (!contentType.includes('text/event-stream')) {
                 throw new ApiError(response.status, { error: `Expected text/event-stream, received ${contentType || 'no content type'}` });
             }
+            if (anthropic)
+                takeLoopSampleId(response, params.loop);
             if (!response.body)
                 throw new ApiError(0, { error: 'Inference stream returned no body' });
             for await (const data of parseSSE(response.body)) {
@@ -976,12 +1024,18 @@ export class Inference {
     rerank(params) {
         return this.sendVerb('/v1/rerank', params);
     }
+    /**
+     * Anthropic Messages (`/v1/messages`). With `loop: { pipeline }` the
+     * exchange is recorded into those pipelines and the result carries
+     * `loop_sample_id` (see {@link LoopCaptureOption}).
+     */
     messages(params) {
         return this.sendVerb('/v1/messages', params, true);
     }
     async *streamCompletions(params) {
         yield* this.streamVerb('/v1/completions', params);
     }
+    /** Anthropic Messages, streamed. With `loop`, `loop.onSampleId` hears the sample id before the first event. */
     async *streamMessages(params) {
         yield* this.streamVerb('/v1/messages', params, true);
     }
@@ -994,6 +1048,12 @@ export class Inference {
             throw new Error('RunBiOS: modelId is required to retrieve an inference model');
         return asInferenceModel(await this.modelRead(`/v1/models/${encodeURIComponent(id)}`, inferenceKey));
     }
+    /**
+     * OpenAI chat completions (`/v1/chat/completions`). With
+     * `loop: { pipeline: 'support-replies' }` the exchange is recorded into
+     * that pipeline and the result carries `loop_sample_id`, the id to send
+     * feedback on (see {@link LoopCaptureOption}).
+     */
     async chatCompletions(params) {
         const prepared = this.prepare(params, false);
         const abort = this.abortContext(prepared.signal);
@@ -1003,7 +1063,8 @@ export class Inference {
             });
             if (!response.ok)
                 throw await apiError(response);
-            return await response.json();
+            const sampleId = takeLoopSampleId(response, params.loop);
+            return withLoopSampleId(await response.json(), sampleId);
         }
         catch (error) {
             if (abort.controller.signal.aborted && !(error instanceof ApiError)) {
@@ -1016,6 +1077,10 @@ export class Inference {
             abort.remove();
         }
     }
+    /**
+     * OpenAI chat completions, streamed. With `loop`, `loop.onSampleId` hears
+     * the sample id as soon as the headers arrive, before the first chunk.
+     */
     async *streamChatCompletions(params) {
         const prepared = this.prepare(params, true);
         const abort = this.abortContext(prepared.signal);
@@ -1029,6 +1094,7 @@ export class Inference {
             if (!contentType.includes('text/event-stream')) {
                 throw new ApiError(response.status, { error: `Expected text/event-stream, received ${contentType || 'no content type'}` });
             }
+            takeLoopSampleId(response, params.loop);
             if (!response.body)
                 throw new ApiError(0, { error: 'Inference response has no body' });
             for await (const data of parseSSE(response.body)) {

package/dist/resources/loop.d.ts

@@ -1,63 +1,11 @@
-import type { HttpClient } from '../client.js';
-import type { LoopTrace, LoopTraceDeleteResponse, LoopTraceListResponse, LoopTraceListParams, LoopCaptureParams, LoopCaptureResult, LoopImportParams, LoopImportResult, LoopSignal, LoopSignalParams, LoopLabel, LoopLabelCount, LoopConfig, LoopConfigParams, LoopStats, LoopTracePipelinesResponse, LoopMetricsHistory, LoopMetricsHistoryParams, TrainingRuleDeleteResponse, TrainingRunListParams, TrainingRunListResponse, TrainingRunResponse, TrainingRunActionResponse, TrainingRunPromoteRequest, TrainingRunRejectRequest, TrainingRunRollbackRequest, TrainingRunCancelRequest, Evaluation, EvaluationItemListParams, EvaluationItemsResponse, Benchmark, BenchmarkCreateParams, BenchmarkHistoryParams, BenchmarkHistoryResponse, BenchmarkItemListParams, BenchmarkItemsResponse, BenchmarkListParams, BenchmarkListResponse, BenchmarkRetireParams, BenchmarkRun, BenchmarkRunItemListParams, BenchmarkRunItemsResponse, Pipeline, PipelineListParams, PipelineListResponse, PipelineWriteRequest, PipelineMutationResponse, LoopModelsResponse, PipelineImportParams, PipelineBenchmarksResponse, PipelineBenchmarkAttachParams, PipelineBenchmarkMoveParams, VersionCompareResponse, VersionCompareParams, AttemptCompareResponse, AttemptCompareParams } from '../types.js';
-/**
- * The Conscious Loop -- pipelines that keep improving a model from the
- * conversations you send them.
- *
- * A pipeline is one use case: a model, the tags whose samples train it, when
- * to train, and how a new version is promoted. Every time it trains it makes
- * an attempt; an attempt that goes live becomes the next version: one that
- * beats the live model, one a member approves, or, after a deleted
- * conversation, a rebuild without it that is not clearly worse (a `manual`
- * pipeline waits for a member even then).
- *
- * Nothing is captured until a source is switched on, and you can switch it
- * off again at any time. Creating a pipeline switches on the source named by
- * its own tag (`own_tag`), stamping that tag, and deleting it switches that
- * source off again. Anything that looks like a credential or a personal detail
- * is removed before the record is written, never afterwards.
- *
- * Requires an API key carrying `loop:read` and/or `loop:write`. Those scopes are
- * deliberately absent from the Read Only preset, because what they return is
- * your raw prompts and completions rather than catalog metadata.
- *
- * Offered on the development environment only for now. Anywhere else every
- * method here, reads included, rejects with a `ComingSoonError` whose
- * `code` is `LOOP_COMING_SOON` (HTTP 403): a deliberate product state, not an
- * outage, so retrying cannot succeed there.
- *
- * @example
- * ```ts
- * // 1. A pipeline: a model it can train, and its own tag.
- * const { models } = await client.loop.listModels();
- * const { pipeline } = await client.loop.createPipeline({
- *   name: 'Support replies',
- *   model: { id: models[0].id },
- * });
- *
- * // 2. Send samples from your app to the pipeline's own source: its create
- * //    switched that source on, and it tags everything it records.
- * const sent = await client.loop.capture({
- *   deployment_id: pipeline.own_tag!,
- *   model: 'gpt-4o',
- *   messages: [{ role: 'user', content: 'what is our refund window' }],
- *   completion: 'thirty days',
- * });
- *
- * // 3. Say whether it was right, on the trace_id the capture answered with.
- * //    A correction is the most valuable answer.
- * if (sent.trace_id) {
- *   await client.loop.correct(sent.trace_id, 'Thirty days from delivery, no questions asked.');
- * }
- *
- * // 4. Once it has its minimum, it trains; versions appear on the pipeline.
- * const p = await client.loop.getPipeline(pipeline.rule_id);
- * ```
- */
+import { type HttpClient } from '../client.js';
+import type { LoopTrace, LoopTraceDeleteResponse, LoopTraceListResponse, LoopTraceListParams, LoopCaptureParams, LoopCaptureResult, LoopImportParams, LoopImportResult, LoopSignal, LoopSignalParams, LoopLabel, LoopLabelCount, LoopConfig, LoopConfigParams, LoopStats, LoopTracePipelinesResponse, LoopMetricsHistory, LoopMetricsHistoryParams, TrainingRuleDeleteResponse, TrainingRunListParams, TrainingRunListResponse, TrainingRunResponse, TrainingRunActionResponse, TrainingRunPromoteRequest, TrainingRunRejectRequest, TrainingRunRollbackRequest, TrainingRunCancelRequest, Evaluation, EvaluationItemListParams, EvaluationItemsResponse, Benchmark, BenchmarkCreateParams, BenchmarkHistoryParams, BenchmarkHistoryResponse, BenchmarkItemListParams, BenchmarkItemsResponse, BenchmarkListParams, BenchmarkListResponse, BenchmarkRetireParams, BenchmarkRun, BenchmarkRunItemListParams, BenchmarkRunItemsResponse, Pipeline, PipelineAttemptListParams, PipelineAttemptListResponse, PipelineListParams, PipelineListResponse, PipelineWriteRequest, PipelineMutationResponse, LoopModelsResponse, PipelineImportParams, PipelineBenchmarksResponse, PipelineBenchmarkAttachParams, PipelineBenchmarkMoveParams, VersionCompareResponse, VersionCompareParams, AttemptCompareResponse, AttemptCompareParams } from '../types.js';
 export declare class Loop {
     private readonly _http;
     /** @internal */
     constructor(_http: HttpClient);
+    /** @internal How feedback waits between tries; tests replace it so nothing sleeps. */
+    _sleep: (ms: number) => Promise<void>;
     /**
      * Send one exchange to be captured.
      *
@@ -139,7 +87,14 @@ export declare class Loop {
      * a shorter list moves every row after the gap and imports it again.
      */
     importRows(params: LoopImportParams): Promise<LoopImportResult>;
-    /** List captured conversations, newest first. */
+    /**
+     * List captured conversations, newest first.
+     *
+     * `q` searches the text: 2 to 200 characters, any case, matched as written
+     * in every message, the answer and its tool calls. Samples kept in your own
+     * storage cannot be searched; a search answers how many were left out as
+     * `unsearched`.
+     */
     listTraces(params?: LoopTraceListParams): Promise<LoopTraceListResponse>;
     /**
      * Read one conversation, with every verdict and tag recorded on it.
@@ -176,6 +131,13 @@ export declare class Loop {
      * `edited` or `gold` verdict is the example, in place of the model's answer;
      * a `rejected` answer is left out. Nothing is learned from an answer that was
      * rejected or replaced. `source` defaults to `human`.
+     *
+     * Feedback on an `X-Loop-Sample-Id` sent right after the answer can reach
+     * the service before the sample does, which answers 409
+     * `SAMPLE_NOT_YET_RECORDED` and stores nothing. This method, and so `upvote`,
+     * `downvote`, `correct` and `gold`, sends it again after the `Retry-After`
+     * seconds (2 when none is given), at most 6 times in all, and then throws
+     * that error. No other error is retried.
      */
     signal(traceId: string, params: LoopSignalParams): Promise<LoopSignal>;
     /**
@@ -356,15 +318,21 @@ export declare class Loop {
      */
     cancelTrainingRun(id: string, params?: TrainingRunCancelRequest): Promise<TrainingRunActionResponse>;
     /**
-     * Every pipeline in the workspace: its versions (the attempts that became
-     * the live model), every attempt, which version is live, the attempt in
-     * flight, and what the pipeline is waiting for.
+     * The workspace's pipelines, a page at a time: its versions (the attempts
+     * that became the live model), its latest 5 attempts (`attempts_total` says
+     * how many; {@link listPipelineAttempts} pages through every one), which
+     * version is live, the attempt in flight, and what the pipeline is waiting
+     * for.
+     *
+     * `limit` is 100 when absent and at most 100; `q` matches the name, the tag
+     * or the model (case-insensitive); `status` keeps the pipelines `training`,
+     * waiting on you (`needs_you`), `serving` or `paused`.
      *
      * RETURNED WITH ITS ENVELOPE, because the list is not always all of them:
-     * the service returns a page of 100, newest first, `total` is every
-     * pipeline in the workspace and `truncated` is true when more exist after
-     * this page. A caller that shows `pipelines` alone presents a short list as
-     * the whole of it; the next page is `{ offset: offset + pipelines.length }`.
+     * the service returns one page, newest first, `total` is every pipeline
+     * that matches and `truncated` is true when more exist after this page. A
+     * caller that shows `pipelines` alone presents a short list as the whole of
+     * it; the next page is `{ offset: offset + pipelines.length }`.
      */
     listPipelines(params?: PipelineListParams): Promise<PipelineListResponse>;
     /**
@@ -378,6 +346,17 @@ export declare class Loop {
      * at most, not an exact spend.
      */
     getPipeline(id: string): Promise<Pipeline>;
+    /**
+     * A pipeline's attempts, newest first, a page at a time: every training run
+     * it made, winner or not, each the shape `attempts` has on the pipeline
+     * (with its `explanation` in plain words). `limit` is 50 when absent and at
+     * most 200. Narrow by `result` (`became_version`, `not_better`,
+     * `inconclusive`, `failed`, `stopped`, `running` -- which includes one
+     * waiting for a decision -- or `waiting_for_review`) and by `model` (`main`,
+     * or `second` for the second model's attempts); `total` follows the
+     * filters.
+     */
+    listPipelineAttempts(id: string, params?: PipelineAttemptListParams): Promise<PipelineAttemptListResponse>;
     /**
      * The base models a pipeline can train: only those the engine trains with
      * LoRA SFT and the platform can serve for the comparison, recommended first.
@@ -394,6 +373,9 @@ export declare class Loop {
      * not learned yet plus a replay of what it already learned (about half
      * of what it trains on, picked at random, so it is not forgotten), and a
      * winner is merged in and served as one model.
+     * `unavailable` lists every other model the platform knows, each with
+     * why it is not offered here (`reason_code`, and `reason`, one plain
+     * sentence); `[]` from a service from before it was sent.
      * When the list cannot be read it throws `ApiError` 503
      * `MODELS_UNAVAILABLE`, whose `body.floors` still carries the floors.
      */
@@ -413,7 +395,9 @@ export declare class Loop {
      * What is charged is the GPU time the runs actually use; the platform's own
      * per-run and monthly limits stop a run that goes wrong. `holdout.percent`
      * (5 to 20, default 5) is the share of its samples held back to judge each
-     * attempt and never trained on.
+     * attempt and never trained on. `training` sets any of its training
+     * settings (`epochs`, `learning_rate`, `lora_rank`, `lora_alpha`,
+     * `replay_percent`); left out, or null, every one is automatic.
      */
     createPipeline(params: PipelineWriteRequest): Promise<PipelineMutationResponse>;
     /**
@@ -421,7 +405,13 @@ export declare class Loop {
      * the limit and `challenger_model: null` removes the challenger. `promotion`
      * is how the promotion policy is set. A new `holdout.percent` is a new
      * revision: lowering it keeps every sample already held back, and raising it
-     * holds back only new samples. Saving is the authorization, as on a create.
+     * holds back only new samples. `training` changes only the settings it
+     * carries -- `{ epochs: 8 }` sets the passes and keeps the rest,
+     * `{ epochs: null }` puts the passes back to automatic -- and
+     * `training: null` puts every one back to automatic; the next attempt
+     * trains with them, and earlier attempts keep the settings they trained
+     * with. Out of range is 422 `TRAINING_SETTING_OUT_OF_RANGE`, naming the
+     * field. Saving is the authorization, as on a create.
      */
     updatePipeline(id: string, params: PipelineWriteRequest): Promise<PipelineMutationResponse>;
     /**
@@ -585,6 +575,9 @@ export declare class Loop {
      * series that silently dropped the runs where the benchmark could not be
      * scored would read as an unbroken line and not be one, so those points come
      * back with `candidate_score` null and `status_reason` saying why.
+     *
+     * `pipeline` (a pipeline's id) keeps only the points of that pipeline's
+     * attempts, so the trend is one pipeline's attempts by attempt number.
      */
     getBenchmarkHistory(id: string, params?: BenchmarkHistoryParams): Promise<BenchmarkHistoryResponse>;
     /**

package/dist/resources/loop.js

@@ -1,3 +1,4 @@
+import { ApiError } from '../client.js';
 /**
  * The Conscious Loop -- pipelines that keep improving a model from the
  * conversations you send them.
@@ -52,12 +53,25 @@
  * const p = await client.loop.getPipeline(pipeline.rule_id);
  * ```
  */
+/**
+ * The code feedback is refused with (409, `Retry-After`) when it names a sample
+ * id the gateway issued moments ago (`X-Loop-Sample-Id`) and the sample is not
+ * recorded yet. Nothing was stored, so sending the same feedback again is safe.
+ */
+const SAMPLE_NOT_YET_RECORDED = 'SAMPLE_NOT_YET_RECORDED';
+/** Feedback is sent at most this many times while its sample is on its way. */
+const FEEDBACK_TRIES = 6;
+/** The wait when the 409 names none, and the longest wait honoured. */
+const FEEDBACK_RETRY_DEFAULT_SECONDS = 2;
+const FEEDBACK_RETRY_MAX_SECONDS = 30;
 export class Loop {
     _http;
     /** @internal */
     constructor(_http) {
         this._http = _http;
     }
+    /** @internal How feedback waits between tries; tests replace it so nothing sleeps. */
+    _sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
     // ── capture ───────────────────────────────────────────────────────────
     /**
      * Send one exchange to be captured.
@@ -145,9 +159,18 @@ export class Loop {
         return this._http.fetchPost('/api/loop/import', params);
     }
     // ── traces ────────────────────────────────────────────────────────────
-    /** List captured conversations, newest first. */
+    /**
+     * List captured conversations, newest first.
+     *
+     * `q` searches the text: 2 to 200 characters, any case, matched as written
+     * in every message, the answer and its tool calls. Samples kept in your own
+     * storage cannot be searched; a search answers how many were left out as
+     * `unsearched`.
+     */
     async listTraces(params = {}) {
         const q = new URLSearchParams();
+        if (params.q)
+            q.set('q', params.q);
         if (params.deployment_id)
             q.set('deployment_id', params.deployment_id);
         if (params.conversation_id)
@@ -226,10 +249,29 @@ export class Loop {
      * `edited` or `gold` verdict is the example, in place of the model's answer;
      * a `rejected` answer is left out. Nothing is learned from an answer that was
      * rejected or replaced. `source` defaults to `human`.
+     *
+     * Feedback on an `X-Loop-Sample-Id` sent right after the answer can reach
+     * the service before the sample does, which answers 409
+     * `SAMPLE_NOT_YET_RECORDED` and stores nothing. This method, and so `upvote`,
+     * `downvote`, `correct` and `gold`, sends it again after the `Retry-After`
+     * seconds (2 when none is given), at most 6 times in all, and then throws
+     * that error. No other error is retried.
      */
     async signal(traceId, params) {
-        const res = await this._http.fetchPost(`/api/loop/traces/${encodeURIComponent(traceId)}/signals`, params);
-        return res.signal;
+        const path = `/api/loop/traces/${encodeURIComponent(traceId)}/signals`;
+        for (let tries = 1;; tries++) {
+            try {
+                const res = await this._http.fetchPost(path, params);
+                return res.signal;
+            }
+            catch (err) {
+                const onItsWay = err instanceof ApiError && err.status === 409 && err.code === SAMPLE_NOT_YET_RECORDED;
+                if (!onItsWay || tries >= FEEDBACK_TRIES)
+                    throw err;
+                const seconds = Math.min(err.retryAfter ?? FEEDBACK_RETRY_DEFAULT_SECONDS, FEEDBACK_RETRY_MAX_SECONDS);
+                await this._sleep(seconds * 1000);
+            }
+        }
     }
     /**
      * Thumbs up: this answer was good. Shorthand for `signal(id, { verdict:
@@ -481,20 +523,32 @@ export class Loop {
     }
     // ── pipelines ─────────────────────────────────────────────────────────
     /**
-     * Every pipeline in the workspace: its versions (the attempts that became
-     * the live model), every attempt, which version is live, the attempt in
-     * flight, and what the pipeline is waiting for.
+     * The workspace's pipelines, a page at a time: its versions (the attempts
+     * that became the live model), its latest 5 attempts (`attempts_total` says
+     * how many; {@link listPipelineAttempts} pages through every one), which
+     * version is live, the attempt in flight, and what the pipeline is waiting
+     * for.
+     *
+     * `limit` is 100 when absent and at most 100; `q` matches the name, the tag
+     * or the model (case-insensitive); `status` keeps the pipelines `training`,
+     * waiting on you (`needs_you`), `serving` or `paused`.
      *
      * RETURNED WITH ITS ENVELOPE, because the list is not always all of them:
-     * the service returns a page of 100, newest first, `total` is every
-     * pipeline in the workspace and `truncated` is true when more exist after
-     * this page. A caller that shows `pipelines` alone presents a short list as
-     * the whole of it; the next page is `{ offset: offset + pipelines.length }`.
+     * the service returns one page, newest first, `total` is every pipeline
+     * that matches and `truncated` is true when more exist after this page. A
+     * caller that shows `pipelines` alone presents a short list as the whole of
+     * it; the next page is `{ offset: offset + pipelines.length }`.
      */
     async listPipelines(params = {}) {
         const q = new URLSearchParams();
+        if (params.limit != null)
+            q.set('limit', String(params.limit));
         if (params.offset)
             q.set('offset', String(params.offset));
+        if (params.q)
+            q.set('q', params.q);
+        if (params.status)
+            q.set('status', params.status);
         const qs = q.toString();
         const res = await this._http.fetchGet(`/api/loop/pipelines${qs ? `?${qs}` : ''}`);
         const pipelines = res.pipelines || [];
@@ -519,6 +573,31 @@ export class Loop {
         const res = await this._http.fetchGet(`/api/loop/pipelines/${encodeURIComponent(id)}`);
         return res.pipeline;
     }
+    /**
+     * A pipeline's attempts, newest first, a page at a time: every training run
+     * it made, winner or not, each the shape `attempts` has on the pipeline
+     * (with its `explanation` in plain words). `limit` is 50 when absent and at
+     * most 200. Narrow by `result` (`became_version`, `not_better`,
+     * `inconclusive`, `failed`, `stopped`, `running` -- which includes one
+     * waiting for a decision -- or `waiting_for_review`) and by `model` (`main`,
+     * or `second` for the second model's attempts); `total` follows the
+     * filters.
+     */
+    async listPipelineAttempts(id, params = {}) {
+        const q = new URLSearchParams();
+        if (params.limit != null)
+            q.set('limit', String(params.limit));
+        if (params.offset)
+            q.set('offset', String(params.offset));
+        if (params.result)
+            q.set('result', params.result);
+        if (params.model)
+            q.set('model', params.model);
+        const qs = q.toString();
+        const res = await this._http.fetchGet(`/api/loop/pipelines/${encodeURIComponent(id)}/attempts${qs ? `?${qs}` : ''}`);
+        const attempts = res.attempts || [];
+        return { attempts, total: typeof res.total === 'number' ? res.total : attempts.length };
+    }
     // ── creating and changing pipelines ───────────────────────────────────
     //
     // One body -- a name, a model, tags, when to train, how to promote -- and
@@ -541,12 +620,15 @@ export class Loop {
      * not learned yet plus a replay of what it already learned (about half
      * of what it trains on, picked at random, so it is not forgotten), and a
      * winner is merged in and served as one model.
+     * `unavailable` lists every other model the platform knows, each with
+     * why it is not offered here (`reason_code`, and `reason`, one plain
+     * sentence); `[]` from a service from before it was sent.
      * When the list cannot be read it throws `ApiError` 503
      * `MODELS_UNAVAILABLE`, whose `body.floors` still carries the floors.
      */
     async listModels() {
         const res = await this._http.fetchGet('/api/loop/models');
-        return { ...res, models: res.models || [] };
+        return { ...res, models: res.models || [], unavailable: res.unavailable || [] };
     }
     /**
      * Create a pipeline -- one use case.
@@ -563,7 +645,9 @@ export class Loop {
      * What is charged is the GPU time the runs actually use; the platform's own
      * per-run and monthly limits stop a run that goes wrong. `holdout.percent`
      * (5 to 20, default 5) is the share of its samples held back to judge each
-     * attempt and never trained on.
+     * attempt and never trained on. `training` sets any of its training
+     * settings (`epochs`, `learning_rate`, `lora_rank`, `lora_alpha`,
+     * `replay_percent`); left out, or null, every one is automatic.
      */
     async createPipeline(params) {
         return this._http.fetchPost('/api/loop/pipelines', params);
@@ -573,7 +657,13 @@ export class Loop {
      * the limit and `challenger_model: null` removes the challenger. `promotion`
      * is how the promotion policy is set. A new `holdout.percent` is a new
      * revision: lowering it keeps every sample already held back, and raising it
-     * holds back only new samples. Saving is the authorization, as on a create.
+     * holds back only new samples. `training` changes only the settings it
+     * carries -- `{ epochs: 8 }` sets the passes and keeps the rest,
+     * `{ epochs: null }` puts the passes back to automatic -- and
+     * `training: null` puts every one back to automatic; the next attempt
+     * trains with them, and earlier attempts keep the settings they trained
+     * with. Out of range is 422 `TRAINING_SETTING_OUT_OF_RANGE`, naming the
+     * field. Saving is the authorization, as on a create.
      */
     async updatePipeline(id, params) {
         return this._http.fetchPut(`/api/loop/pipelines/${encodeURIComponent(id)}`, params);
@@ -811,9 +901,14 @@ export class Loop {
      * series that silently dropped the runs where the benchmark could not be
      * scored would read as an unbroken line and not be one, so those points come
      * back with `candidate_score` null and `status_reason` saying why.
+     *
+     * `pipeline` (a pipeline's id) keeps only the points of that pipeline's
+     * attempts, so the trend is one pipeline's attempts by attempt number.
      */
     async getBenchmarkHistory(id, params = {}) {
         const q = new URLSearchParams();
+        if (params.pipeline)
+            q.set('pipeline', params.pipeline);
         if (params.limit != null)
             q.set('limit', String(params.limit));
         if (params.offset != null)

package/dist/types.d.ts

@@ -2771,12 +2771,23 @@ export interface LoopTraceListParams {
     signal?: 'good' | 'bad' | 'corrected';
     /** Only the conversations nobody has given feedback on yet. */
     unsignalled?: boolean;
+    /**
+     * Text search: 2 to 200 characters, case-insensitive, matched as written
+     * (`%` and `_` are plain characters) in every message, the answer and the
+     * answer's tool calls. Combines with every other filter.
+     */
+    q?: string;
 }
 export interface LoopTraceListResponse {
     traces: LoopTrace[];
     total: number;
     limit: number;
     offset: number;
+    /**
+     * Present only when `q` was sent: how many of the samples the other filters
+     * select keep their text in your own storage and so were not searched.
+     */
+    unsearched?: number;
 }
 export interface LoopConfig {
     deployment_id: string;
@@ -2995,8 +3006,9 @@ export type TrainingTrigger = 'rows' | 'cadence' | 'both' | 'manual' | 'variant'
  * `served_as` is `adapter` for an attempt from the base and `merged` for one
  * built on versions (one model with every version merged in). A winner is
  * merged in and served as one model. `learned_deleted_conversation` is true
- * when a conversation it trained on has since been deleted: a rebuild
- * without it is on its way, and it can no longer be rolled back to.
+ * when it -- or a version it was built on, whose model is merged into it --
+ * learned a conversation that has since been deleted: a rebuild without it is
+ * on its way, and it can no longer be rolled back to.
  */
 export interface Lineage {
     trained_from: 'base' | 'versions';
@@ -3023,6 +3035,12 @@ export interface TrainingRecipe {
     num_train_epochs: number | null;
     lora_rank: number | null;
     lora_alpha: number | null;
+    /**
+     * True when one of the pipeline's own training settings ({@link Pipeline.training})
+     * was applied over the automatic recipe for this run, frozen when it started;
+     * false when it trained on automatic settings throughout.
+     */
+    custom: boolean;
 }
 export type TrainingRunState = 'built' | 'registering' | 'dataset_validating' | 'preflighting' | 'job_creating' | 'training' | 'checkpoint_ready' | 'candidate_booking' | 'candidate_running' | 'evaluating' | 'reported' | 'awaiting_review' | 'promoting' | 'waiting_funds'
 /**
@@ -3926,6 +3944,8 @@ export interface BenchmarkItemListParams {
     offset?: number;
 }
 export interface BenchmarkHistoryParams {
+    /** Only the points of this pipeline's attempts (its id, `rule_id`). */
+    pipeline?: string;
     /** 50 when absent; at most 200. */
     limit?: number;
     offset?: number;
@@ -4012,6 +4032,8 @@ export type TrainingRuleRunRefusalCode = 'NOT_ENOUGH_SAMPLES' | 'PIPELINE_NEEDS_
  *   pipeline's current one (ignoring case) is kept, and whether it can still
  *   be trained is checked when an attempt starts.
  * - `NO_GPU_FITS` (422): no machines can train or serve the model right now.
+ * - `TRAINING_SETTING_OUT_OF_RANGE` (422): a `training` setting is outside its
+ *   range; the message names the field and the range. Nothing was saved.
  * - `MODEL_REVISION_UNAVAILABLE` (422): the model could not be pinned to an
  *   exact revision because the training service did not answer. Try again
  *   once it does.
@@ -4038,7 +4060,7 @@ export type TrainingRuleRunRefusalCode = 'NOT_ENOUGH_SAMPLES' | 'PIPELINE_NEEDS_
  *   the key every comparison is scored with) did not answer just then. Try
  *   again in a minute.
  */
-export type TrainingRuleSaveRefusalCode = 'PIPELINE_NAME_TAKEN' | 'OWN_TAG_TAKEN' | 'REVISION_MISMATCH' | 'RUN_ACTIVE' | 'NOT_A_SIMPLE_PIPELINE' | 'MODEL_NOT_TRAINABLE' | 'NO_GPU_FITS' | 'MODEL_REVISION_UNAVAILABLE' | 'NO_JUDGE_MODEL' | 'PROMOTION_POLICY_UNKNOWN' | 'PROMOTION_K_REQUIRED' | 'PROMOTION_K_UNREACHABLE' | 'PROMOTION_POLICY_NEEDS_BENCHMARK' | 'TRAINING_NOT_ENABLED' | 'METHOD_NOT_ENABLED' | 'CEILING_TOO_LOW' | 'MODELS_UNAVAILABLE' | 'GPU_OPTIONS_UNAVAILABLE' | 'AGENT_COULD_NOT_START';
+export type TrainingRuleSaveRefusalCode = 'PIPELINE_NAME_TAKEN' | 'OWN_TAG_TAKEN' | 'REVISION_MISMATCH' | 'RUN_ACTIVE' | 'NOT_A_SIMPLE_PIPELINE' | 'MODEL_NOT_TRAINABLE' | 'NO_GPU_FITS' | 'TRAINING_SETTING_OUT_OF_RANGE' | 'MODEL_REVISION_UNAVAILABLE' | 'NO_JUDGE_MODEL' | 'PROMOTION_POLICY_UNKNOWN' | 'PROMOTION_K_REQUIRED' | 'PROMOTION_K_UNREACHABLE' | 'PROMOTION_POLICY_NEEDS_BENCHMARK' | 'TRAINING_NOT_ENABLED' | 'METHOD_NOT_ENABLED' | 'CEILING_TOO_LOW' | 'MODELS_UNAVAILABLE' | 'GPU_OPTIONS_UNAVAILABLE' | 'AGENT_COULD_NOT_START';
 /**
  * The body of a manual run refused `409 MONTHLY_LIMIT_REACHED`, as
  * `ApiError.body` carries it.
@@ -4271,6 +4293,69 @@ export interface PipelineAttempt {
     evaluation_id: string | null;
     /** Its last sentence. */
     reason: string | null;
+    /**
+     * What became of it in plain words, written by the service from its state,
+     * verdict and error. See {@link AttemptExplanation}.
+     */
+    explanation: AttemptExplanation | null;
+}
+/**
+ * An attempt's outcome in plain words: `headline` ("Could not be tested"),
+ * `detail` (what happened and why) and `next` (what happens now; null when
+ * there is nothing to say).
+ */
+export interface AttemptExplanation {
+    headline: string;
+    detail: string;
+    next: string | null;
+}
+/**
+ * A pipeline's own training settings, each null while it is automatic (the
+ * platform's value for its model, {@link PipelineTrainingDefaults}). A change
+ * applies from the next attempt, and every attempt keeps the settings it
+ * trained with on its `recipe` (`custom` true when one of these applied).
+ * LoRA only: there is no full fine-tune, so the rank and alpha always apply.
+ */
+export interface PipelineTrainingSettings {
+    /** Passes over the data, 1 to 15. */
+    epochs: number | null;
+    /** 1e-6 to 1e-2. */
+    learning_rate: number | null;
+    /** 4, 8, 16, 32 or 64. */
+    lora_rank: number | null;
+    /** 1 to 512. */
+    lora_alpha: number | null;
+    /**
+     * 0 to 50: the share of already-learned samples an attempt replays when it
+     * builds on the live version, so the new version does not forget them.
+     */
+    replay_percent: number | null;
+}
+/**
+ * What automatic means for this pipeline's model: what an attempt trains with
+ * where {@link PipelineTrainingSettings} says null. The automatic recipe picks
+ * its passes from `min_epochs` to `max_epochs` (at least 8 for Gemma 4).
+ */
+export interface PipelineTrainingDefaults {
+    learning_rate: number;
+    lora_rank: number;
+    lora_alpha: number;
+    replay_percent: number;
+    min_epochs: number;
+    max_epochs: number;
+}
+/**
+ * The training settings a create or edit sends. Every key is three-state:
+ * absent keeps the pipeline's, null puts it back to automatic, a number sets
+ * it. Out of range is refused 422 `TRAINING_SETTING_OUT_OF_RANGE` naming the
+ * field and its range.
+ */
+export interface PipelineTrainingRequest {
+    epochs?: number | null;
+    learning_rate?: number | null;
+    lora_rank?: number | null;
+    lora_alpha?: number | null;
+    replay_percent?: number | null;
 }
 /** A model and the exact commit of it. */
 export interface PipelineModelRef {
@@ -4425,6 +4510,10 @@ export interface Pipeline {
     holdout: PipelineHoldout;
     /** Rows the next version holds back and never trains on. Detail only; null on the list. */
     holdout_size: number | null;
+    /** Its training settings, each null while automatic. See {@link PipelineTrainingSettings}. */
+    training: PipelineTrainingSettings;
+    /** What automatic means for its model. See {@link PipelineTrainingDefaults}. */
+    training_defaults: PipelineTrainingDefaults;
     minimums: PipelineMinimums;
     /**
      * The pinned base every version is trained over: from it, or, where the
@@ -4499,9 +4588,17 @@ export interface Pipeline {
      */
     month_spent_cents: number;
     active_run: PipelineActiveRun | null;
-    /** Winners only, v1 first. */
+    /** How many versions it has made: every one is in `versions` from `getPipeline`, only the latest few and the live one on `listPipelines`. */
+    versions_total: number;
+    /** How many attempts it has made; `attempts` holds only the latest of them. */
+    attempts_total: number;
+    /** Winners only, v1 first: every one from `getPipeline`, the latest few and the live one on `listPipelines`. */
     versions: PipelineVersion[];
-    /** Every attempt, attempt 1 first. */
+    /**
+     * Its latest attempts, in attempt order: 20 from `getPipeline`, 5 on each
+     * pipeline of `listPipelines`. `attempts_total` says how many there are,
+     * and `listPipelineAttempts` pages through every one.
+     */
     attempts: PipelineAttempt[];
 }
 export interface TrainingRuleDeleteResponse {
@@ -4658,12 +4755,23 @@ export interface BenchmarkHistoryResponse {
     points: BenchmarkHistoryPoint[];
     total: number;
 }
+/**
+ * The pipeline list's `status` filter: `training` (an attempt is running),
+ * `needs_you` (waiting on a member: a review or funds), `serving` (its live
+ * version answers) and `paused`.
+ */
+export type PipelineListStatus = 'training' | 'needs_you' | 'serving' | 'paused';
 export interface PipelineListParams {
+    /** 100 when absent; at most 100. */
+    limit?: number;
     /** How many of the newest pipelines to skip: the page after one that started at N starts at N + its length. */
     offset?: number;
+    /** A case-insensitive substring of the name, the tag or the model. */
+    q?: string;
+    status?: PipelineListStatus;
 }
 export interface PipelineListResponse {
-    /** The newest pipelines first, at most the service's page (100). */
+    /** The newest pipelines first, one page (100 unless `limit` says; at most 100). */
     pipelines: Pipeline[];
     /** Every pipeline in the workspace, including any not returned. */
     total: number;
@@ -4673,6 +4781,22 @@ export interface PipelineListResponse {
 export interface PipelineResponse {
     pipeline: Pipeline;
 }
+/** What became of an attempt, as `listPipelineAttempts` filters it. */
+export type PipelineAttemptResultFilter = 'became_version' | 'not_better' | 'inconclusive' | 'failed' | 'stopped' | 'running' | 'waiting_for_review';
+/** Which model's attempts: the pipeline's own (`main`) or its second model's (`second`). */
+export type PipelineAttemptModelFilter = 'main' | 'second';
+export interface PipelineAttemptListParams {
+    /** 50 when absent; at most 200. */
+    limit?: number;
+    offset?: number;
+    result?: PipelineAttemptResultFilter;
+    model?: PipelineAttemptModelFilter;
+}
+/** One page of a pipeline's attempts, newest first. `total` follows the filters. */
+export interface PipelineAttemptListResponse {
+    attempts: PipelineAttempt[];
+    total: number;
+}
 /**
  * The body of `POST /api/loop/pipelines` and (every field optional)
  * `PUT /api/loop/pipelines/{id}`. Everything else -- the machines, the money,
@@ -4729,6 +4853,12 @@ export interface PipelineWriteRequest {
     /** 1 to 100, or null for no limit (the default). Counts versions, not attempts. */
     max_versions?: number | null;
     enabled?: boolean;
+    /**
+     * The pipeline's training settings. Absent: unchanged on an edit (automatic
+     * on a create). null: every one back to automatic. An object: only the keys
+     * it carries change, each null for automatic. See {@link PipelineTrainingRequest}.
+     */
+    training?: PipelineTrainingRequest | null;
     /** An edit's compare-and-set. */
     expected_revision?: number;
 }
@@ -4781,8 +4911,25 @@ export interface HeldBackFloors {
     max_percent: number;
     scored_rows: number;
 }
+/** Why a model is not offered for a pipeline ({@link LoopUnavailableModel.reason_code}). */
+export type LoopUnavailableReasonCode = 'not_trainable_sft_lora' | 'not_servable_as_adapter' | 'too_large_for_available_gpus' | 'not_verified' | 'registry_missing';
+/**
+ * A model the platform knows that a pipeline cannot use, and why. `reason` is
+ * one plain sentence to show as it is; `reason_code` is one of
+ * {@link LoopUnavailableReasonCode}, typed as a string so a code added later
+ * still carries its sentence.
+ */
+export interface LoopUnavailableModel {
+    id: string;
+    name: string;
+    family: string | null;
+    reason_code: string;
+    reason: string;
+}
 export interface LoopModelsResponse {
     models: LoopModel[];
+    /** Every other model the platform knows, each with why it is not offered here. */
+    unavailable: LoopUnavailableModel[];
     floors: PipelineFloors;
 }
 /** The promotion rule as the API reads it back. */

package/package.json

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