runbios-sdk 0.2.22 → 0.3.0-dev.323

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, LoopSignalManyItem, LoopSignalManyResult, 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.
      *
@@ -79,6 +27,10 @@ export declare class Loop {
      * When the source is not switched on this resolves with `captured: false`
      * and a reason instead of throwing -- capture must never be the thing that
      * breaks your application.
+     *
+     * Already know the answer was good, bad or wrong? Pass `feedback` and it is
+     * written with the exchange, so no second call is needed:
+     * `feedback: { verdict: 'corrected', correction: 'Thirty days from delivery.' }`.
      */
     capture(params: LoopCaptureParams): Promise<LoopCaptureResult>;
     /**
@@ -139,7 +91,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,8 +135,36 @@ 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>;
+    /**
+     * Send many feedback items at once, several in flight together.
+     *
+     * Each item is `signal(item.trace_id, item)`: the same call, the same
+     * `SAMPLE_NOT_YET_RECORDED` retry. At most `concurrency` calls are in flight
+     * (8 by default, at most 32). It never throws for one item: every item
+     * comes back, in the order given, with its `signal` or the `error` it ended
+     * with, so one refused item costs no other.
+     *
+     * @example
+     * ```ts
+     * 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);
+     * ```
+     */
+    signalMany(items: LoopSignalManyItem[], options?: {
+        concurrency?: number;
+    }): Promise<LoopSignalManyResult[]>;
     /**
      * Thumbs up: this answer was good. Shorthand for `signal(id, { verdict:
      * 'accepted' })` — there is one stored vocabulary behind both, so a thumbs-up
@@ -298,6 +285,13 @@ export declare class Loop {
      *
      * `ready.sft` is an upper bound: duplicates, the held-back set and
      * conversations too long to train on come out of it when an attempt trains.
+     *
+     * `capture` is what the one-header capture did not record over the last
+     * `capture.days` days: per tag, `no_pipeline` (no pipeline has the tag),
+     * `too_large` or `incomplete` (the answer could not be kept). Empty when
+     * every call was recorded. Rows are per tag: a call naming two tags is
+     * counted under each, so never add them up as calls. One pipeline's share
+     * is `capture` on its detail.
      */
     stats(): Promise<LoopStats>;
     /**
@@ -356,15 +350,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>;
     /**
@@ -373,11 +373,21 @@ export declare class Loop {
      * `status` says whether it is the platform working (`running`), the member
      * who has to act (`needs_review`, `needs_funds`), or nothing at all until
      * somebody does (`paused`, with `paused_reason` saying why; `complete` at
-     * `max_versions`). `month_spent_cents` is the figure the
-     * monthly limit is enforced against: what runs started this month have cost
-     * at most, not an exact spend.
+     * `max_versions`). The monthly safety limit is the platform's and has no
+     * field: when it holds the pipeline, `next_reason` says so.
      */
     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.
@@ -391,9 +401,12 @@ export declare class Loop {
      * judged on at most `scored_rows` of them). They are read-only.
      * Where a pipeline builds on its live version (its `chain` is set), each
      * attempt trains a new adapter on top of the live version, on what it has
-     * not learned yet plus a replay of what it already learned (about a fifth
+     * 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.
      */
@@ -408,12 +421,14 @@ export declare class Loop {
      * Where the pipeline builds on its live version (`chain`), each attempt
      * waits for 1,000 new samples and trains a new adapter on top of the live
      * version, on what it has not learned plus a replay of what it already
-     * learned (about a fifth of what it trains on, picked at random); a winner
+     * learned (about half of what it trains on, picked at random); a winner
      * is merged in.
      * 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 +436,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 +606,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,28 @@
  * 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;
+/** How many feedback calls `signalMany` keeps in flight, by default and at most. */
+const SIGNAL_MANY_CONCURRENCY = 8;
+const SIGNAL_MANY_CONCURRENCY_MAX = 32;
 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.
@@ -80,6 +97,10 @@ export class Loop {
      * When the source is not switched on this resolves with `captured: false`
      * and a reason instead of throwing -- capture must never be the thing that
      * breaks your application.
+     *
+     * Already know the answer was good, bad or wrong? Pass `feedback` and it is
+     * written with the exchange, so no second call is needed:
+     * `feedback: { verdict: 'corrected', correction: 'Thirty days from delivery.' }`.
      */
     async capture(params) {
         return this._http.fetchPost('/api/loop/traces', params);
@@ -145,9 +166,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 +256,71 @@ 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);
+            }
+        }
+    }
+    /**
+     * Send many feedback items at once, several in flight together.
+     *
+     * Each item is `signal(item.trace_id, item)`: the same call, the same
+     * `SAMPLE_NOT_YET_RECORDED` retry. At most `concurrency` calls are in flight
+     * (8 by default, at most 32). It never throws for one item: every item
+     * comes back, in the order given, with its `signal` or the `error` it ended
+     * with, so one refused item costs no other.
+     *
+     * @example
+     * ```ts
+     * 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);
+     * ```
+     */
+    async signalMany(items, options = {}) {
+        const asked = Math.trunc(options.concurrency ?? SIGNAL_MANY_CONCURRENCY);
+        const limit = Math.max(1, Math.min(Number.isFinite(asked) ? asked : SIGNAL_MANY_CONCURRENCY, SIGNAL_MANY_CONCURRENCY_MAX));
+        const out = new Array(items.length);
+        let next = 0;
+        const worker = async () => {
+            for (;;) {
+                const i = next++;
+                if (i >= items.length)
+                    return;
+                const { trace_id, ...params } = items[i];
+                try {
+                    if (!trace_id)
+                        throw new Error('each feedback item needs its trace_id');
+                    out[i] = { trace_id, signal: await this.signal(trace_id, params) };
+                }
+                catch (error) {
+                    out[i] = { trace_id, error };
+                }
+            }
+        };
+        await Promise.all(Array.from({ length: Math.min(limit, items.length) }, worker));
+        return out;
     }
     /**
      * Thumbs up: this answer was good. Shorthand for `signal(id, { verdict:
@@ -383,6 +474,13 @@ export class Loop {
      *
      * `ready.sft` is an upper bound: duplicates, the held-back set and
      * conversations too long to train on come out of it when an attempt trains.
+     *
+     * `capture` is what the one-header capture did not record over the last
+     * `capture.days` days: per tag, `no_pipeline` (no pipeline has the tag),
+     * `too_large` or `incomplete` (the answer could not be kept). Empty when
+     * every call was recorded. Rows are per tag: a call naming two tags is
+     * counted under each, so never add them up as calls. One pipeline's share
+     * is `capture` on its detail.
      */
     async stats() {
         const res = await this._http.fetchGet('/api/loop/stats');
@@ -481,20 +579,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 || [];
@@ -511,14 +621,38 @@ export class Loop {
      * `status` says whether it is the platform working (`running`), the member
      * who has to act (`needs_review`, `needs_funds`), or nothing at all until
      * somebody does (`paused`, with `paused_reason` saying why; `complete` at
-     * `max_versions`). `month_spent_cents` is the figure the
-     * monthly limit is enforced against: what runs started this month have cost
-     * at most, not an exact spend.
+     * `max_versions`). The monthly safety limit is the platform's and has no
+     * field: when it holds the pipeline, `next_reason` says so.
      */
     async getPipeline(id) {
         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
@@ -538,15 +672,18 @@ export class Loop {
      * judged on at most `scored_rows` of them). They are read-only.
      * Where a pipeline builds on its live version (its `chain` is set), each
      * attempt trains a new adapter on top of the live version, on what it has
-     * not learned yet plus a replay of what it already learned (about a fifth
+     * 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.
@@ -558,12 +695,14 @@ export class Loop {
      * Where the pipeline builds on its live version (`chain`), each attempt
      * waits for 1,000 new samples and trains a new adapter on top of the live
      * version, on what it has not learned plus a replay of what it already
-     * learned (about a fifth of what it trains on, picked at random); a winner
+     * learned (about half of what it trains on, picked at random); a winner
      * is merged in.
      * 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 +712,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 +956,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/resources/training.js

@@ -9,8 +9,9 @@ function trainingIdempotencyKey(explicit) {
 }
 /**
  * `start_from` on the wire. The adapters stay in the order given (oldest
- * first: the order they are merged in), and an empty list is refused here
- * rather than sent, since the API refuses it too.
+ * first: the order they are merged in). An empty list, an `exportStep` other
+ * than 'best' or 'final', and an `exportStep` without `exportMerged: true`
+ * are refused here rather than sent, since the API refuses each of them too.
  */
 function startFromBody(sf) {
     if (!Array.isArray(sf.adapters) || sf.adapters.length === 0) {
@@ -21,6 +22,15 @@ function startFromBody(sf) {
     };
     if (sf.exportMerged !== undefined)
         body.export_merged = sf.exportMerged;
+    if (sf.exportStep !== undefined) {
+        if (sf.exportStep !== 'best' && sf.exportStep !== 'final') {
+            throw new Error("RunBiOS: startFrom.exportStep must be 'best' (the step validation picked) or 'final' (the last step trained)");
+        }
+        if (sf.exportMerged !== true) {
+            throw new Error('RunBiOS: startFrom.exportStep names the step the merged model is made of, so it needs exportMerged: true');
+        }
+        body.export_step = sf.exportStep;
+    }
     return body;
 }
 function buildTrainingRequest(params) {