runbios-sdk 0.4.0-rc.337 → 0.5.0-dev.338

package/dist/resources/loop.d.ts

@@ -1,11 +1,42 @@
 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, LoopDataset, LoopDatasetWrite, LoopDatasetCreate, LoopDatasetListParams, LoopDatasetListResponse, LoopDatasetDeleteResponse, LoopDatasetPreview, LoopDatasetPreviewParams } from '../types.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, BenchmarkQuestionsParams, BenchmarkQuestionsResponse, TrainingCurve, BenchmarkItemListParams, BenchmarkItemsResponse, BenchmarkListParams, BenchmarkListResponse, BenchmarkRetireParams, BenchmarkRun, BenchmarkRunItemListParams, BenchmarkRunItemsResponse, Pipeline, PipelineAttemptListParams, PipelineAttemptListResponse, PipelineListParams, PipelineListResponse, PipelineWriteRequest, PipelineMutationResponse, LoopModelsResponse, PipelineImportParams, PipelineBenchmarksResponse, PipelineBenchmarkAttachParams, PipelineBenchmarkMoveParams, VersionCompareResponse, VersionCompareParams, AttemptCompareResponse, AttemptCompareParams, LoopDataset, LoopDatasetWrite, LoopDatasetCreate, LoopDatasetListParams, LoopDatasetListResponse, LoopDatasetDeleteResponse, LoopDatasetPreview, LoopDatasetPreviewParams, LoopDatasetExport, LoopDatasetExportParams } from '../types.js';
+import type { Inference } from './inference.js';
+import { type LoopChatParams, type LoopChatResult } from './loop-chat.js';
 export declare class Loop {
     private readonly _http;
-    /** @internal */
-    constructor(_http: HttpClient);
+    private readonly _inference?;
+    /**
+     * @internal The SDK client hands Loop its Inference resource, which `chat`
+     * calls. A Loop made without one can do everything but `chat`.
+     */
+    constructor(_http: HttpClient, _inference?: Inference | undefined);
     /** @internal How feedback waits between tries; tests replace it so nothing sleeps. */
     _sleep: (ms: number) => Promise<void>;
+    /**
+     * Ask a model and save the conversation as a sample of a pipeline, in one
+     * call; the result carries the answer, its sample ID and the feedback for it.
+     *
+     * It is `client.inference.chatCompletions` with the pipeline ID in the
+     * `X-Loop-Pipeline` header: a normal, billed model call. `model` defaults to
+     * the pipeline's own model, `loop-<pipeline ID>`, which answers with the live
+     * version. While the pipeline has no live version (before its first one)
+     * nothing answers to that name, so pass `model` (the model your app uses
+     * now); left out then, this rejects with `LoopNoVersionError` (an
+     * `ApiError`) and no model answered. The pipeline ID is lowercased, as the
+     * platform reads it.
+     *
+     * @example
+     * ```ts
+     * const reply = await client.loop.chat({
+     *   pipeline: 'support-replies',
+     *   messages: [{ role: 'user', content: 'Where is my order?' }],
+     * });
+     * console.log(reply.answer);
+     * await reply.good();                     // or reply.bad()
+     * // await reply.correct('It ships on Monday.');
+     * ```
+     */
+    chat(params: LoopChatParams): Promise<LoopChatResult>;
     /**
      * Send one exchange to be captured.
      *
@@ -349,6 +380,17 @@ export declare class Loop {
      * the attempt as its pipeline's own list says it, `explanation` included.
      */
     listTrainingRuns(params?: TrainingRunListParams): Promise<TrainingRunListResponse>;
+    /**
+     * How a training went while it trained, step by step: its loss on the
+     * samples it trained on (`train_loss`) and on the practice questions it set
+     * aside (`check_loss`), at most 200 points with every practice check among
+     * them, and the step whose model it kept (`kept_step`). `keeps_last` is a
+     * training that keeps its last step rather than its best practice score.
+     * With nothing to chart -- no training job yet, or no practice check --
+     * `points` is empty and `reason` says why. 503
+     * `TRAINING_CURVE_UNAVAILABLE` when it could not be read just now.
+     */
+    getTrainingCurve(id: string): Promise<TrainingCurve>;
     /**
      * One run with its timeline, the addresses of everything it created, and
      * what you may do with it right now.
@@ -370,7 +412,9 @@ export declare class Loop {
      * refused rather than promote against a consent that moved underneath the
      * decision, and `force` only to promote a comparison the evaluation called
      * inconclusive -- without it that case is refused with
-     * `INCONCLUSIVE_REQUIRES_FORCE`.
+     * `INCONCLUSIVE_REQUIRES_FORCE`. A training that was never tested (`tested`
+     * false) is refused `NOT_TESTED` whatever `force` says: nothing untested
+     * goes live; {@link retestTrainingRun} tests it again.
      */
     promoteTrainingRun(id: string, params?: TrainingRunPromoteRequest): Promise<TrainingRunActionResponse>;
     /** Retire the candidate. What serves your traffic does not change. */
@@ -397,6 +441,18 @@ export declare class Loop {
      * cancelling a training job does not refund the hours it burned.
      */
     cancelTrainingRun(id: string, params?: TrainingRunCancelRequest): Promise<TrainingRunActionResponse>;
+    /**
+     * Test again: book the comparison of a training that trained and was never
+     * tested (`tested` false, `available_actions.retest` true) again, on the
+     * same training. It is tested against what is live now, on the questions it
+     * was held back for, and spends what is left of the amount set aside for
+     * testing it -- never a second amount. Answers 202 with the run back in
+     * `checkpoint_ready`; a second call while that test is under way answers the
+     * same. Refusals are a `TrainingRunRetestRefusalCode`, with the reason in
+     * plain words. A training that was never tested can never be promoted:
+     * {@link promoteTrainingRun} answers `NOT_TESTED`.
+     */
+    retestTrainingRun(id: string): Promise<TrainingRunActionResponse>;
     /**
      * 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
@@ -549,13 +605,19 @@ export declare class Loop {
      * that brought no verdict of its own as a good example to learn from.
      */
     importIntoPipeline(id: string, params: PipelineImportParams): Promise<LoopImportResult>;
-    /** The workspace's datasets, the most recently changed first: `{ datasets, total, limit, offset }`. */
+    /**
+     * The workspace's datasets, the most recently changed first:
+     * `{ datasets, total, limit, offset }`. `q` keeps the ones whose name
+     * contains it, whatever its case; `total` counts those.
+     */
     listDatasets(params?: LoopDatasetListParams): Promise<LoopDatasetListResponse>;
     /**
      * One dataset: its conditions, how many samples it selects now (`samples`,
      * the same number `listTraces({ dataset: id })` totals) by feedback, how
-     * many are in a benchmark (never trained on), and the pipelines that train
-     * on it (`used_by`).
+     * many are in a benchmark (never trained on), the pipelines that train on
+     * it (`used_by`), who saved it (`created_by`) and the trainings that
+     * learned from it (`learned_by`, newest first, at most 50 of
+     * `learned_by_total`).
      */
     getDataset(id: string): Promise<LoopDataset>;
     /**
@@ -590,6 +652,20 @@ export declare class Loop {
      * numbers. It writes nothing.
      */
     previewDataset(params?: LoopDatasetPreviewParams): Promise<LoopDatasetPreview>;
+    /**
+     * Download a dataset's samples as a file: one line a sample, oldest first,
+     * in the import's chat format, with the feedback a person gave each in the
+     * import's words -- so `importRows` takes the lines back as they are.
+     * `jsonl` is the file exactly as sent, `lines` each line parsed. A sample
+     * whose text could not be read (kept in your own storage and refused just
+     * now, or gone) is left out; `stored_elsewhere` is how many of the
+     * dataset's samples have no conversation kept with them on the platform
+     * (kept in your own storage, or none at all), the most that can be left
+     * out. A long file keeps coming as long as lines keep arriving: the
+     * client's `timeout` is the longest wait for the next part, not for the
+     * whole file.
+     */
+    exportDataset(id: string, params?: LoopDatasetExportParams): Promise<LoopDatasetExport>;
     /** The pipeline's benchmarks in priority order (1 is the primary), the ones it stopped using, and its promotion policy. */
     listPipelineBenchmarks(id: string): Promise<PipelineBenchmarksResponse>;
     /** Add a benchmark to a pipeline, last unless `priority` says where. Every version from now on is replayed on it. */
@@ -747,6 +823,16 @@ export declare class Loop {
      * different set, which is the exact defect a standing benchmark removes.
      */
     getBenchmarkRun(id: string): Promise<BenchmarkRun>;
+    /**
+     * Every question of a benchmark with how one pipeline's newest trainings
+     * did on each -- right or wrong (`passed`: a score of 0.70 or more) and
+     * the score -- so you can see which questions a new version got wrong that
+     * the one before got right. `trainings` lists them oldest first and each
+     * question's `results` follows that order; a training that did not score a
+     * question has null there. `pipeline` is required (training numbers are
+     * per pipeline); `trainings` is 5 when absent, 1 to 20.
+     */
+    listBenchmarkQuestions(id: string, params: BenchmarkQuestionsParams): Promise<BenchmarkQuestionsResponse>;
     /**
      * The conversations behind one replay, in the benchmark's order: the pinned
      * prompt and its reference, both answers, what the judge made of each (its

package/dist/resources/loop.js

@@ -1,56 +1,67 @@
 import { ApiError } from '../client.js';
+import { LoopNoVersionError, PIPELINE_ID_PATTERN, PIPELINE_MODEL_PREFIX, chatAnswerText, } from './loop-chat.js';
 /**
- * The Conscious Loop -- pipelines that keep improving a model from the
- * conversations you send them.
+ * The Conscious Loop -- pipelines that keep improving a model from your app's
+ * conversations and your feedback.
  *
- * 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).
+ * A pipeline is one use case: a model, the samples it learns from, and when
+ * to train. Each time it trains, that is a training (#1, #2, ...; the API
+ * calls them attempts). A training that goes live becomes the next version:
+ * one that does better than the live version on its tests, 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). The
+ * live version is the version your app gets answers from right now; it
+ * answers to the model name `loop-<pipeline ID>`, and each new version takes
+ * that name over.
  *
- * 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.
+ * What is saved. A call that carries the pipeline ID in the `X-Loop-Pipeline`
+ * header -- `chat` here, or the `loop` option of `client.inference` -- is
+ * saved as a sample of that pipeline: the header is your consent for that one
+ * call, whatever the recording switches say. Without the header nothing is
+ * saved unless recording is switched on for a source (`setConfig`). Creating
+ * a pipeline switches on the source named by its pipeline ID (`own_tag`), so
+ * `capture` to it is saved too, and deleting the pipeline 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
+ * Requires an API key carrying `loop:read` and/or `loop:write` (and, for
+ * `chat`, the scope that calls the model: `serverless`, or `deployments:read`
+ * for a deployment or a pipeline's own model). The loop 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.
+ * Where the platform has the Conscious Loop switched off, 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. The exceptions are the five a member needs to
+ * stop paying, which answer as usual: `listPipelines`, `getPipeline`,
+ * `updatePipeline(id, { enabled: false })` with nothing else but
+ * `expected_revision` (switch it off), `deletePipeline` (which stops its live
+ * version and removes its data) and `cancelTrainingRun`.
  *
  * @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 },
+ * // 1. Send your app's conversations. One call asks the model and saves the
+ * //    conversation as a sample of the pipeline. Before the pipeline's first
+ * //    version, pass the model your app uses now.
+ * const reply = await client.loop.chat({
+ *   pipeline: 'support-replies',
+ *   messages: [{ role: 'user', content: 'What is our refund window?' }],
+ *   model: 'meta-llama/Llama-3.1-8B-Instruct',
  * });
+ * console.log(reply.answer);
  *
- * // 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.');
- * }
+ * // 2. Tell it how the answer did: good, wrong, or wrong with the right answer.
+ * await reply.good();
+ * // await reply.bad();
+ * // await reply.correct('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);
+ * // 3. Once a version is live, leave model out: loop-support-replies answers
+ * //    with the live version.
+ * const next = await client.loop.chat({
+ *   pipeline: 'support-replies',
+ *   messages: [{ role: 'user', content: 'Can I return a gift?' }],
+ * });
  * ```
  */
 /**
@@ -69,12 +80,90 @@ const SIGNAL_MANY_CONCURRENCY = 8;
 const SIGNAL_MANY_CONCURRENCY_MAX = 32;
 export class Loop {
     _http;
-    /** @internal */
-    constructor(_http) {
+    _inference;
+    /**
+     * @internal The SDK client hands Loop its Inference resource, which `chat`
+     * calls. A Loop made without one can do everything but `chat`.
+     */
+    constructor(_http, _inference) {
         this._http = _http;
+        this._inference = _inference;
     }
     /** @internal How feedback waits between tries; tests replace it so nothing sleeps. */
     _sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+    // ── chat: ask, save the sample, give feedback ─────────────────────────
+    /**
+     * Ask a model and save the conversation as a sample of a pipeline, in one
+     * call; the result carries the answer, its sample ID and the feedback for it.
+     *
+     * It is `client.inference.chatCompletions` with the pipeline ID in the
+     * `X-Loop-Pipeline` header: a normal, billed model call. `model` defaults to
+     * the pipeline's own model, `loop-<pipeline ID>`, which answers with the live
+     * version. While the pipeline has no live version (before its first one)
+     * nothing answers to that name, so pass `model` (the model your app uses
+     * now); left out then, this rejects with `LoopNoVersionError` (an
+     * `ApiError`) and no model answered. The pipeline ID is lowercased, as the
+     * platform reads it.
+     *
+     * @example
+     * ```ts
+     * const reply = await client.loop.chat({
+     *   pipeline: 'support-replies',
+     *   messages: [{ role: 'user', content: 'Where is my order?' }],
+     * });
+     * console.log(reply.answer);
+     * await reply.good();                     // or reply.bad()
+     * // await reply.correct('It ships on Monday.');
+     * ```
+     */
+    async chat(params) {
+        if (!this._inference) {
+            throw new Error('loop.chat calls a model, so it needs the SDK client: new RunBiOS({ apiKey }).loop.chat(...)');
+        }
+        if (!params || typeof params !== 'object') {
+            throw new Error('loop.chat takes { pipeline, messages, model? }');
+        }
+        const { pipeline: asked, model: askedModel, loop: _ignored, ...rest } = params;
+        // Lowercased as the gateways read the header, so the default model name
+        // (matched case for case) is the pipeline's own.
+        const pipeline = typeof asked === 'string' ? asked.trim().toLowerCase() : '';
+        if (!PIPELINE_ID_PATTERN.test(pipeline)) {
+            throw new Error(`pipeline must be one pipeline ID, e.g. "support-replies": lowercase letters, digits, dot, dash or underscore (got ${JSON.stringify(asked)})`);
+        }
+        const explicit = typeof askedModel === 'string' && askedModel.trim() !== '';
+        const model = explicit ? askedModel.trim() : PIPELINE_MODEL_PREFIX + pipeline;
+        let raw;
+        try {
+            raw = await this._inference.chatCompletions({ ...rest, messages: params.messages, model, loop: { pipeline } });
+        }
+        catch (err) {
+            if (!explicit && err instanceof ApiError && err.status === 404) {
+                throw new LoopNoVersionError(pipeline, model, err);
+            }
+            throw err;
+        }
+        const sampleId = raw.loop_sample_id ?? null;
+        const needId = () => {
+            if (!sampleId) {
+                throw new Error('No sample ID came back with this answer, so it was not saved as a sample and cannot take feedback.');
+            }
+            return sampleId;
+        };
+        return {
+            answer: chatAnswerText(raw),
+            sample_id: sampleId,
+            raw,
+            good: async (reason) => this.signal(needId(), { verdict: 'good', reason }),
+            bad: async (reason) => this.signal(needId(), { verdict: 'bad', reason }),
+            correct: async (rightAnswer, reason) => {
+                const id = needId();
+                if (typeof rightAnswer !== 'string' || !rightAnswer.trim()) {
+                    throw new Error('correct needs the right answer: the text the model should have given');
+                }
+                return this.signal(id, { verdict: 'corrected', correction: rightAnswer, reason });
+            },
+        };
+    }
     // ── capture ───────────────────────────────────────────────────────────
     /**
      * Send one exchange to be captured.
@@ -577,6 +666,20 @@ export class Loop {
         const qs = q.toString();
         return this._http.fetchGet(`/api/loop/training-runs${qs ? `?${qs}` : ''}`);
     }
+    /**
+     * How a training went while it trained, step by step: its loss on the
+     * samples it trained on (`train_loss`) and on the practice questions it set
+     * aside (`check_loss`), at most 200 points with every practice check among
+     * them, and the step whose model it kept (`kept_step`). `keeps_last` is a
+     * training that keeps its last step rather than its best practice score.
+     * With nothing to chart -- no training job yet, or no practice check --
+     * `points` is empty and `reason` says why. 503
+     * `TRAINING_CURVE_UNAVAILABLE` when it could not be read just now.
+     */
+    async getTrainingCurve(id) {
+        const res = await this._http.fetchGet(`/api/loop/training-runs/${encodeURIComponent(id)}/training-curve`);
+        return { ...res, points: res.points || [] };
+    }
     /**
      * One run with its timeline, the addresses of everything it created, and
      * what you may do with it right now.
@@ -600,7 +703,9 @@ export class Loop {
      * refused rather than promote against a consent that moved underneath the
      * decision, and `force` only to promote a comparison the evaluation called
      * inconclusive -- without it that case is refused with
-     * `INCONCLUSIVE_REQUIRES_FORCE`.
+     * `INCONCLUSIVE_REQUIRES_FORCE`. A training that was never tested (`tested`
+     * false) is refused `NOT_TESTED` whatever `force` says: nothing untested
+     * goes live; {@link retestTrainingRun} tests it again.
      */
     async promoteTrainingRun(id, params = {}) {
         return this._http.fetchPost(`/api/loop/training-runs/${encodeURIComponent(id)}/promote`, params);
@@ -635,6 +740,20 @@ export class Loop {
     async cancelTrainingRun(id, params = {}) {
         return this._http.fetchPost(`/api/loop/training-runs/${encodeURIComponent(id)}/cancel`, params);
     }
+    /**
+     * Test again: book the comparison of a training that trained and was never
+     * tested (`tested` false, `available_actions.retest` true) again, on the
+     * same training. It is tested against what is live now, on the questions it
+     * was held back for, and spends what is left of the amount set aside for
+     * testing it -- never a second amount. Answers 202 with the run back in
+     * `checkpoint_ready`; a second call while that test is under way answers the
+     * same. Refusals are a `TrainingRunRetestRefusalCode`, with the reason in
+     * plain words. A training that was never tested can never be promoted:
+     * {@link promoteTrainingRun} answers `NOT_TESTED`.
+     */
+    async retestTrainingRun(id) {
+        return this._http.fetchPost(`/api/loop/training-runs/${encodeURIComponent(id)}/retest`, {});
+    }
     // ── pipelines ─────────────────────────────────────────────────────────
     /**
      * The workspace's pipelines, a page at a time: its versions (the attempts
@@ -852,9 +971,15 @@ export class Loop {
     // match later join it. Every pipeline already trains on its own tag; add a
     // dataset to a pipeline (`datasets` on create or edit) to train it on more.
     // One dataset can feed any number of pipelines.
-    /** The workspace's datasets, the most recently changed first: `{ datasets, total, limit, offset }`. */
+    /**
+     * The workspace's datasets, the most recently changed first:
+     * `{ datasets, total, limit, offset }`. `q` keeps the ones whose name
+     * contains it, whatever its case; `total` counts those.
+     */
     async listDatasets(params = {}) {
         const q = new URLSearchParams();
+        if (params.q)
+            q.set('q', params.q);
         if (params.limit != null)
             q.set('limit', String(params.limit));
         if (params.offset)
@@ -867,8 +992,10 @@ export class Loop {
     /**
      * One dataset: its conditions, how many samples it selects now (`samples`,
      * the same number `listTraces({ dataset: id })` totals) by feedback, how
-     * many are in a benchmark (never trained on), and the pipelines that train
-     * on it (`used_by`).
+     * many are in a benchmark (never trained on), the pipelines that train on
+     * it (`used_by`), who saved it (`created_by`) and the trainings that
+     * learned from it (`learned_by`, newest first, at most 50 of
+     * `learned_by_total`).
      */
     async getDataset(id) {
         return this._http.fetchGet(`/api/loop/datasets/${encodeURIComponent(id)}`);
@@ -914,6 +1041,31 @@ export class Loop {
     async previewDataset(params = {}) {
         return this._http.fetchPost('/api/loop/datasets/preview', params);
     }
+    /**
+     * Download a dataset's samples as a file: one line a sample, oldest first,
+     * in the import's chat format, with the feedback a person gave each in the
+     * import's words -- so `importRows` takes the lines back as they are.
+     * `jsonl` is the file exactly as sent, `lines` each line parsed. A sample
+     * whose text could not be read (kept in your own storage and refused just
+     * now, or gone) is left out; `stored_elsewhere` is how many of the
+     * dataset's samples have no conversation kept with them on the platform
+     * (kept in your own storage, or none at all), the most that can be left
+     * out. A long file keeps coming as long as lines keep arriving: the
+     * client's `timeout` is the longest wait for the next part, not for the
+     * whole file.
+     */
+    async exportDataset(id, params = {}) {
+        const q = new URLSearchParams();
+        q.set('format', params.format ?? 'jsonl');
+        if (params.limit != null)
+            q.set('limit', String(params.limit));
+        const { text, headers } = await this._http.fetchText(`/api/loop/datasets/${encodeURIComponent(id)}/export?${q.toString()}`);
+        const lines = text.split('\n').filter((line) => line.trim() !== '')
+            .map((line) => JSON.parse(line));
+        const elsewhere = headers.get('X-Loop-Stored-Elsewhere');
+        const stored = elsewhere != null && /^\d+$/.test(elsewhere) ? Number(elsewhere) : null;
+        return { jsonl: text, lines, stored_elsewhere: stored };
+    }
     // ── a pipeline's benchmarks, and its versions side by side ─────────────
     /** The pipeline's benchmarks in priority order (1 is the primary), the ones it stopped using, and its promotion policy. */
     async listPipelineBenchmarks(id) {
@@ -1153,6 +1305,27 @@ export class Loop {
         const res = await this._http.fetchGet(`/api/loop/benchmark-runs/${encodeURIComponent(id)}`);
         return res.benchmark_run;
     }
+    /**
+     * Every question of a benchmark with how one pipeline's newest trainings
+     * did on each -- right or wrong (`passed`: a score of 0.70 or more) and
+     * the score -- so you can see which questions a new version got wrong that
+     * the one before got right. `trainings` lists them oldest first and each
+     * question's `results` follows that order; a training that did not score a
+     * question has null there. `pipeline` is required (training numbers are
+     * per pipeline); `trainings` is 5 when absent, 1 to 20.
+     */
+    async listBenchmarkQuestions(id, params) {
+        const q = new URLSearchParams();
+        q.set('pipeline', params.pipeline);
+        if (params.trainings != null)
+            q.set('trainings', String(params.trainings));
+        if (params.limit != null)
+            q.set('limit', String(params.limit));
+        if (params.offset != null)
+            q.set('offset', String(params.offset));
+        const res = await this._http.fetchGet(`/api/loop/benchmarks/${encodeURIComponent(id)}/questions?${q.toString()}`);
+        return { ...res, trainings: res.trainings || [], items: res.items || [] };
+    }
     /**
      * The conversations behind one replay, in the benchmark's order: the pinned
      * prompt and its reference, both answers, what the judge made of each (its