runbios-sdk 0.2.22 → 0.3.0-dev.323

package/CHANGELOG.md

@@ -0,0 +1,53 @@
+# Changelog
+
+`runbios-sdk` on npm. Versions are 0.x semver: the minor moves when a public
+surface is added, renamed or removed, the patch for a fix inside an unchanged
+surface. The SDK, the Python SDK (`runbios-sdk` on PyPI) and the MCP server
+(`runbios-mcp`) are released together, at one version.
+
+## 0.3.0
+
+Added
+
+- `training.create` and `training.preflight` take `startFrom.exportStep`
+  (`'best'`, the default, or `'final'`): which step of a job trained on top of
+  earlier versions its merged model is made of. It needs `exportMerged: true`;
+  without it, or with any other value, the SDK refuses before sending, as the
+  API does. `TrainingStartFrom` echoes `export_step`.
+- Conscious Loop: `inference` chat and messages calls take
+  `loop: { pipeline, onSampleId }`, which sends `X-Loop-Pipeline` and hands
+  back the sample id (`loop_sample_id`, or to `onSampleId` before the first
+  streamed chunk).
+- Conscious Loop: `loop.listPipelineAttempts` pages a pipeline's attempts;
+  `loop.listPipelines` takes `limit`, `q` and `status`; a pipeline's training
+  settings (`training`, three-state on a write) and `training_defaults`;
+  `loop.listModels` also lists the models not offered, with why;
+  `loop.getBenchmarkHistory` takes `pipeline`; `loop.listTraces` takes `q`.
+- Feedback (`signal`, `upvote`, `downvote`, `correct`, `gold`) is sent again
+  after `Retry-After` while its sample is still being recorded
+  (`409 SAMPLE_NOT_YET_RECORDED`), at most 6 tries; `ApiError` carries
+  `retryAfter`.
+
+Changed
+
+- `LoopSignalParams` takes a person's feedback only: `verdict` is
+  `LoopFeedbackVerdict` (`accepted`, `rejected`, `edited` or `gold`) and
+  `source` is `'human'`; `score` is gone. The API refuses a `scored` verdict,
+  any other source, and a `score` on any verdict with 400.
+- A merge-chain attempt replays about half of what it trains on (was a fifth),
+  and a version built on one that learned a deleted conversation says so in
+  its lineage.
+
+Removed
+
+- `Pipeline.champion_version` (use `live_version`) and
+  `PipelineVersion.is_champion` (use `is_live`), `benchmark_id` and
+  `benchmark_name` (use `listPipelineBenchmarks`), `benchmark_min_delta` (the
+  least rise a benchmark must show is the platform's; each measurement's
+  `reason` in `promotion` says whether it was met), `auto_promote` (use
+  `promotion.policy`), and `monthly_ceiling_cents` and `month_spent_cents`:
+  the API no longer sends them. `TrainingRuleMonthlyLimitRefusal` keeps
+  `error` and `resumes_at`. The monthly safety limit's figures are not fields
+  of any answer, and no sentence states them either: `next_reason` and the
+  `MONTHLY_LIMIT_REACHED` message say the limit holds the pipeline and when
+  the next attempt can start, with no amount.

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,79 @@ 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. With `chatCompletions` and `streamChatCompletions`
+it works for serverless models and dedicated deployments, including the
+pipeline's own `loop-<tag>` model. `messages` and `streamMessages` (the
+Anthropic shape) work for serverless models; a dedicated deployment, and so a
+pipeline's `loop-<tag>` model, serves the OpenAI shape and refuses
+`/v1/messages` with 400, so call it with `chatCompletions`. Only the tags of a
+pipeline that exists are recorded: a call naming a misspelt tag, or a deleted
+pipeline's, is not recorded under it, and `client.loop.stats()` lists such
+calls under `capture`.
+
+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 (it is counted in
+`client.loop.stats()` under `capture`). 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.
+
+Many feedback items at once: `signalMany` sends each as `signal` does, the same
+retry included, with up to 8 in flight (`{ concurrency }`, at most 32), and
+returns every item in order with its `signal` or its `error`:
+
+```typescript
+const results = await client.loop.signalMany([
+  { trace_id: idA, verdict: 'good' },
+  { trace_id: idB, verdict: 'corrected', correction: 'Refunds take five working days.' },
+]);
+const failed = results.filter((r) => r.error);
+```
+
+Sending a sample yourself with `client.loop.capture` and already know the
+verdict? Pass `feedback: { verdict: 'good' | 'bad' | 'corrected', correction }`
+and it is written with the sample, in one transaction: both are stored or
+neither is. `good`, `bad` and `corrected` work in `signal` and `signalMany` too,
+stored as `accepted`, `rejected` and `edited`.
+
 #### 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
@@ -344,7 +370,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;
@@ -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";
+export declare const VERSION = "0.3.0-dev.323";
 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, TrainingExportStep, 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, LoopCaptureFeedback, LoopFeedbackWord, LoopCaptureHealth, LoopCaptureMiss, LoopSignalManyItem, LoopSignalManyResult, 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';
+export const VERSION = '0.3.0-dev.323';
 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,54 @@ 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 on `/v1/chat/completions` for serverless models and dedicated
+ * deployments, a pipeline's own `loop-<tag>` model included, and on
+ * `/v1/messages` for serverless models: a dedicated deployment serves the
+ * OpenAI shape and refuses an Anthropic body with 400. Only the tags of a
+ * pipeline that exists are recorded; `client.loop.stats()` lists the calls
+ * that were not, under `capture`.
+ */
+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 +123,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 +149,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 +413,30 @@ 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}). For serverless models:
+     * a dedicated deployment, a pipeline's `loop-<tag>` model included, serves
+     * the OpenAI shape and refuses this with 400; call it with `chatCompletions`.
+     */
+    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)) {
@@ -336,7 +373,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;
     }
@@ -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,20 @@ 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}). For serverless models:
+     * a dedicated deployment, a pipeline's `loop-<tag>` model included, serves
+     * the OpenAI shape and refuses this with 400; call it with `chatCompletions`.
+     */
     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 +1050,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 +1065,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 +1079,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 +1096,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)) {