runbios-sdk 0.2.1-dev.97 → 0.2.1-rc.118

package/dist/resources/loop.js

@@ -0,0 +1,530 @@
+/**
+ * The Conscious Loop -- capture what your model was asked and answered, record
+ * whether it was right, and turn those judgements into training data.
+ *
+ * Nothing is captured until you turn it on for a source, and you can turn it
+ * off again at any time. 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.
+ *
+ * @example
+ * ```ts
+ * // 1. Decide that this source is recorded.
+ * await client.loop.setConfig('my-agent', { enabled: true, retention_days: 30 });
+ *
+ * // 2. Send what your model was asked and what it answered. Works whoever
+ * //    served it -- us, another provider, or your own servers.
+ * const { trace_id } = await client.loop.capture({
+ *   deployment_id: 'my-agent',
+ *   model: 'gpt-4o',
+ *   messages: [{ role: 'user', content: 'what is our refund window' }],
+ *   completion: 'thirty days',
+ * });
+ *
+ * // 3. Say whether it was right. A rewrite is the most valuable answer here:
+ * //    the model learns your version AND learns to avoid its own.
+ * await client.loop.signal(trace_id, {
+ *   verdict: 'edited',
+ *   correction: 'Thirty days from delivery, no questions asked.',
+ * });
+ *
+ * // 4. Turn the judgements into a training set and take the file.
+ * const ds = await client.loop.createDataset({ name: 'support', method: 'sft' });
+ * const jsonl = await client.loop.downloadDataset(ds.id);
+ * ```
+ */
+export class Loop {
+    _http;
+    /** @internal */
+    constructor(_http) {
+        this._http = _http;
+    }
+    // ── capture ───────────────────────────────────────────────────────────
+    /**
+     * Send one exchange to be captured.
+     *
+     * Works regardless of who served the model: ours, OpenAI, Fireworks, your own
+     * own servers, an agent framework. Pass `tool_calls` and `tools` when the turn
+     * invoked a function -- without them a tool-using exchange trains the model to
+     * answer in prose where it should have called something.
+     *
+     * The returned `trace_id` is OURS. If you pass your own `request_id` it is
+     * kept as an idempotency handle: sending the same one again returns the same
+     * trace rather than storing a second copy, so a retry is safe.
+     *
+     * When the source is not enabled this resolves with `captured: false` and a
+     * reason instead of throwing -- capture must never be the thing that breaks
+     * your application.
+     */
+    async capture(params) {
+        return this._http.fetchPost('/api/loop/traces', params);
+    }
+    /**
+     * Bring data you already have into the loop.
+     *
+     * This does NOT create a training set. It creates conversations, in the same
+     * place captured ones live and subject to the same review, rules, judges and
+     * labels. A row becomes trainable when something says it is good, never
+     * because it arrived in a file -- which is the one guarantee that separates
+     * a corpus from a pile.
+     *
+     * Each row is read for what it actually is. A `prompt`/`chosen`/`rejected`
+     * triple becomes a preference pair; an answer plus a yes-or-no becomes a
+     * thumbs verdict; a question and an answer waits for review; a question with
+     * no answer waits for an answer; a paragraph of prose is refused, because it
+     * is not a conversation.
+     *
+     * A verdict that arrives *with* the file is kept -- discarding somebody's
+     * judgement would be worse -- but it is recorded as having come from your
+     * earlier process rather than from a reviewer here, and the conversation
+     * records that it was imported. Neither fact can be reconstructed later, so
+     * both are written at the door.
+     *
+     * `source` is required and becomes the id every imported conversation is
+     * filed under: "everything in one bucket called import" is a corpus nobody
+     * can slice afterwards. At most 5000 rows per call, because the call is
+     * synchronous and somebody is waiting on it.
+     */
+    async importRows(params) {
+        return this._http.fetchPost('/api/loop/import', params);
+    }
+    // ── traces ────────────────────────────────────────────────────────────
+    /** List captured conversations, newest first. */
+    async listTraces(params = {}) {
+        const q = new URLSearchParams();
+        if (params.deployment_id)
+            q.set('deployment_id', params.deployment_id);
+        if (params.conversation_id)
+            q.set('conversation_id', params.conversation_id);
+        if (params.from)
+            q.set('from', params.from);
+        if (params.to)
+            q.set('to', params.to);
+        if (params.signalled)
+            q.set('signalled', 'true');
+        if (params.label)
+            q.set('label', params.label);
+        // Repeated rather than comma-joined: a value containing a comma would
+        // otherwise silently split into two filters that match nothing.
+        for (const [k, v] of Object.entries(params.attributes ?? {})) {
+            if (k && v)
+                q.append('attr', `${k}:${v}`);
+        }
+        if (params.unlabelled)
+            q.set('unlabelled', 'true');
+        if (params.limit != null)
+            q.set('limit', String(params.limit));
+        if (params.offset != null)
+            q.set('offset', String(params.offset));
+        const qs = q.toString();
+        return this._http.fetchGet(`/api/loop/traces${qs ? `?${qs}` : ''}`);
+    }
+    /** Read one conversation, with every verdict recorded on it. */
+    async getTrace(id) {
+        const res = await this._http.fetchGet(`/api/loop/traces/${encodeURIComponent(id)}`);
+        return res.trace;
+    }
+    /**
+     * Delete a conversation.
+     *
+     * It also leaves every training set built from it, including sets already
+     * exported -- so a customer asking you to delete a conversation genuinely
+     * removes it from what the model will learn next. Training runs that have
+     * already finished are not affected.
+     */
+    async deleteTrace(id) {
+        return this._http.fetchDelete(`/api/loop/traces/${encodeURIComponent(id)}`);
+    }
+    // ── feedback ──────────────────────────────────────────────────────────
+    /**
+     * Record a verdict on a conversation.
+     *
+     * Append-only: posting a second verdict does not replace the first. Two
+     * reviewers disagreeing about an answer is information worth keeping.
+     *
+     * `source` says who judged: `human`, `verifier` (a deterministic check --
+     * tests passed, schema valid), `judge` (a model grading a model), or
+     * `behavioural` (what the user did next). When several disagree, a human
+     * outranks a verifier, a verifier outranks a judge, and a judge outranks a
+     * behavioural hint.
+     */
+    async signal(traceId, params) {
+        const res = await this._http.fetchPost(`/api/loop/traces/${encodeURIComponent(traceId)}/signals`, params);
+        return res.signal;
+    }
+    /**
+     * Thumbs up: this answer was good. Shorthand for `signal(id, { verdict:
+     * 'accepted' })` — there is one stored vocabulary behind both, so a thumbs-up
+     * and an "accepted" can never disagree in your corpus.
+     */
+    async upvote(traceId, reason) {
+        return this.signal(traceId, { verdict: 'accepted', reason });
+    }
+    /**
+     * Thumbs down: this answer was bad, and you have nothing better to offer.
+     *
+     * On its own this REMOVES the answer from training rather than teaching
+     * anything — there is no better version to learn. If you know what it should
+     * have said, `correct()` is worth far more.
+     */
+    async downvote(traceId, reason) {
+        return this.signal(traceId, { verdict: 'rejected', reason });
+    }
+    /**
+     * The model was wrong; here is what it should have said.
+     *
+     * The most valuable feedback there is, because it produces BOTH halves of a
+     * preference pair from one action: the model learns your answer and learns to
+     * avoid its own.
+     */
+    async correct(traceId, answer, reason) {
+        return this.signal(traceId, { verdict: 'edited', correction: answer, reason });
+    }
+    /**
+     * Record the GOLD answer for this question — the reference, regardless of
+     * what the model happened to say.
+     *
+     * Different from `correct()` in a way that matters: a correction asserts the
+     * model was wrong, so the original becomes the rejected half of a pair. A gold
+     * answer asserts nothing about the model, so if it MATCHES what was said, no
+     * preference pair is invented — but SFT still learns it.
+     *
+     * It is the most reusable thing you can record: it trains SFT, forms a DPO
+     * pair when it differs from the answer, and stands in as the GRPO reference
+     * when you have not supplied a separate ground truth.
+     */
+    async gold(traceId, answer, reason) {
+        return this.signal(traceId, { verdict: 'gold', correction: answer, reason });
+    }
+    /** Every verdict on one conversation, oldest first. */
+    async listSignals(traceId) {
+        const res = await this._http.fetchGet(`/api/loop/traces/${encodeURIComponent(traceId)}/signals`);
+        return res.signals;
+    }
+    // ── alternative answers ───────────────────────────────────────────────
+    /**
+     * Submit an alternative answer to a prompt already captured.
+     *
+     * This is what makes preference learning scale. A human rewrite is the best
+     * signal there is and the least available -- somebody has to sit down and
+     * write it. Sample the model several times for the same prompt, score the
+     * samples, and a DPO pair falls out automatically: best becomes chosen,
+     * worst becomes rejected. Point a stronger model at the prompt instead and
+     * the same machinery does distillation.
+     *
+     * Score them, or they cannot pair: an unscored alternative says nothing about
+     * which answer anybody prefers. `score_source` is required alongside a score,
+     * because precedence between a verifier, a judge and a person is the whole
+     * reason we record who judged.
+     *
+     * A human correction always outranks any score.
+     *
+     * @example
+     * ```ts
+     * for (const sample of await sampleMyModel(prompt, 4)) {
+     *   await client.loop.addCandidate(traceId, {
+     *     completion: sample.text,
+     *     score: await myVerifier(sample.text),
+     *     score_source: 'verifier',
+     *   });
+     * }
+     * ```
+     */
+    async addCandidate(traceId, params) {
+        const res = await this._http.fetchPost(`/api/loop/traces/${encodeURIComponent(traceId)}/candidates`, params);
+        return res.candidate;
+    }
+    /** Every alternative answer recorded for one prompt, oldest first. */
+    async listCandidates(traceId) {
+        const res = await this._http.fetchGet(`/api/loop/traces/${encodeURIComponent(traceId)}/candidates`);
+        return res.candidates;
+    }
+    // ── labels ────────────────────────────────────────────────────────────
+    /**
+     * Label a conversation, so it can be selected later.
+     *
+     * An average over everything is the least useful thing to train on. A model
+     * weak at refunds is fixed with refund examples, and you can only select
+     * those if you said so when the conversation arrived.
+     *
+     * A label may name a `parent`, which is what makes a MASTER GROUP: labelling
+     * something `refunds` with parent `billing` makes it selectable as either,
+     * and selecting `billing` later gathers every child without you maintaining
+     * a list of them.
+     *
+     * Labels are lowercased and trimmed, so `Refunds` and `refunds` are one label.
+     */
+    async label(traceId, labels, parent, attributes) {
+        const res = await this._http.fetchPost(`/api/loop/traces/${encodeURIComponent(traceId)}/labels`, { labels, parent, attributes });
+        return res.labels;
+    }
+    /**
+     * Set named dimensions on a conversation: `{ category: 'billing',
+     * language: 'es' }`.
+     *
+     * An upsert per dimension, so correcting `category` leaves `task` and any
+     * bare tags exactly where they were — no delete-then-add.
+     */
+    async setAttributes(traceId, attributes) {
+        const res = await this._http.fetchPost(`/api/loop/traces/${encodeURIComponent(traceId)}/labels`, { attributes });
+        return res.labels;
+    }
+    async unlabel(traceId, label, key) {
+        const q = key ? `?key=${encodeURIComponent(key)}` : '';
+        return this._http.fetchDelete(`/api/loop/traces/${encodeURIComponent(traceId)}/labels/${encodeURIComponent(label)}${q}`);
+    }
+    /** Every label in the workspace, with how many conversations carry it. */
+    async listLabels() {
+        const res = await this._http.fetchGet('/api/loop/labels');
+        return res.labels;
+    }
+    // ── training sets ─────────────────────────────────────────────────────
+    /**
+     * Build a training set from the feedback recorded so far.
+     *
+     * The three methods need genuinely different things, so one set cannot be
+     * reshaped into another afterwards:
+     *
+     * - `sft` -- answers you marked right, and answers you rewrote.
+     * - `dpo` -- answers you REWROTE, so a better and a worse version of the same
+     *   reply exist. Nothing else produces a pair.
+     * - `grpo` -- answers with a value or fact they can be checked against, or
+     *   a judge rubric, which scores answers the run has not written yet.
+     * - `kto` -- anything carrying a yes or a no, INCLUDING a thumbs-down with
+     *   nothing written. That row trains nothing under the other three methods,
+     *   which is why this one exists: it is the feedback people actually give.
+     *
+     * `holdout_percent` holds back your most recent work rather than a random
+     * slice, so the evaluation measures whether the model generalised instead of
+     * memorised the same week.
+     *
+     * The result always reports `rejected_counts`: why rows were left out. A
+     * small set with a reason is useful; a small set without one is just alarming.
+     */
+    async createDataset(params) {
+        const res = await this._http.fetchPost('/api/loop/datasets', params);
+        return res.dataset;
+    }
+    /** List training sets, newest first. */
+    async listDatasets(params = {}) {
+        const q = new URLSearchParams();
+        if (params.method)
+            q.set('method', params.method);
+        if (params.limit != null)
+            q.set('limit', String(params.limit));
+        if (params.offset != null)
+            q.set('offset', String(params.offset));
+        const qs = q.toString();
+        const res = await this._http.fetchGet(`/api/loop/datasets${qs ? `?${qs}` : ''}`);
+        return res.datasets;
+    }
+    /** Read one training set and its curation report. */
+    async getDataset(id) {
+        const res = await this._http.fetchGet(`/api/loop/datasets/${encodeURIComponent(id)}`);
+        return res.dataset;
+    }
+    /**
+     * Page through the rows a training set actually contains.
+     *
+     * Worth reading before you spend money on a run: each row carries the address
+     * of the conversation it was built from.
+     */
+    async listDatasetItems(id, params = {}) {
+        const q = new URLSearchParams();
+        if (params.limit != null)
+            q.set('limit', String(params.limit));
+        if (params.offset != null)
+            q.set('offset', String(params.offset));
+        const qs = q.toString();
+        const res = await this._http.fetchGet(`/api/loop/datasets/${encodeURIComponent(id)}/items${qs ? `?${qs}` : ''}`);
+        return res.items;
+    }
+    /**
+     * Download a training set as JSONL -- one training row per line, the format
+     * every trainer in this space reads.
+     *
+     * `split` defaults to the training rows; pass `holdout` for the slice held
+     * back, or `all` for both.
+     */
+    async downloadDataset(id, split) {
+        const qs = split ? `?split=${split}` : '';
+        return this._http.fetchGet(`/api/loop/datasets/${encodeURIComponent(id)}/download${qs}`);
+    }
+    /**
+     * Delete a training set.
+     *
+     * The conversations it was built from are untouched -- a set is a selection,
+     * and discarding the selection must not discard the evidence.
+     */
+    async deleteDataset(id) {
+        return this._http.fetchDelete(`/api/loop/datasets/${encodeURIComponent(id)}`);
+    }
+    // ── graders ───────────────────────────────────────────────────────────
+    /**
+     * Write a rule that scores answers without a person.
+     *
+     * Human review is the most trustworthy feedback and the least available. A
+     * grader is written once and applied to every answer afterwards: did it
+     * contain the required phrase, did it parse as the schema you asked for, is
+     * the number within tolerance of the known answer, did it call the function
+     * it should have.
+     *
+     * Every kind here is DETERMINISTIC -- no model call, no network. That is why
+     * a verifier outranks a judge when they disagree: it cannot be flattered and
+     * it cannot drift between runs.
+     *
+     * `weight` is the multiplier: a criterion that matters twice as much gets
+     * twice the weight, and the combined score is the weighted mean over the
+     * rules that actually applied.
+     *
+     * A caution worth knowing before you write a set: a rule made only of
+     * `forbidden` phrases is satisfied VACUOUSLY by an answer that says nothing.
+     * Pair it with a `required` phrase, or you are rewarding silence.
+     */
+    async createGrader(params) {
+        const res = await this._http.fetchPost('/api/loop/graders', params);
+        return res.grader;
+    }
+    /** Every rule this workspace has written. */
+    async listGraders() {
+        const res = await this._http.fetchGet('/api/loop/graders');
+        return res.graders;
+    }
+    async deleteGrader(id) {
+        return this._http.fetchDelete(`/api/loop/graders/${encodeURIComponent(id)}`);
+    }
+    /**
+     * Apply this workspace's rules to one captured answer AND to every
+     * alternative sampled for it.
+     *
+     * Grading both in one pass is the point: scoring only the original gives a
+     * verdict, while scoring the samples as well gives the preference pair. Sample
+     * your model, call this, and you have DPO data with nobody reading anything.
+     *
+     * A run where no rule could apply writes NOTHING -- no verdict, no scores.
+     * Recording a zero that no rule produced would poison curation with a
+     * judgement nobody reached, so `applied: 0` is reported instead.
+     */
+    async grade(traceId) {
+        return this._http.fetchPost(`/api/loop/traces/${encodeURIComponent(traceId)}/grade`);
+    }
+    // ── capture settings ──────────────────────────────────────────────────
+    /** Every source this workspace has configured. */
+    async listConfigs() {
+        const res = await this._http.fetchGet('/api/loop/configs');
+        return res.configs;
+    }
+    /**
+     * Read the capture setting for one source. A source nobody has configured
+     * reads back as disabled rather than missing, because "we are not recording
+     * this" is the honest answer.
+     */
+    async getConfig(source) {
+        const res = await this._http.fetchGet(`/api/loop/configs/${encodeURIComponent(source)}`);
+        return res.config;
+    }
+    /**
+     * Turn capture on or off for a source, and choose how long it is kept.
+     *
+     * This is the consent decision the whole feature rests on: nothing is
+     * recorded until it is made, and the row remembers who made it and when.
+     * `sample_rate` below 1 records a deterministic fraction, chosen so that every
+     * turn of one conversation is captured or skipped together -- half a
+     * conversation makes training rows with holes in them.
+     */
+    async setConfig(source, params) {
+        const res = await this._http.fetchPut(`/api/loop/configs/${encodeURIComponent(source)}`, params);
+        return res.config;
+    }
+    /**
+     * How much there is, and how much of it each method could actually use.
+     *
+     * The `ready` numbers are upper bounds: duplicate questions are folded into
+     * one row while a set is built, so the finished count can be lower.
+     */
+    async stats() {
+        const res = await this._http.fetchGet('/api/loop/stats');
+        return res.stats;
+    }
+    // ── judges ────────────────────────────────────────────────────────────
+    //
+    // A grader is a rule: deterministic, cheap, and blind to anything it was not
+    // told to look for. A judge is a rubric handed to a model, which is the only
+    // thing that can answer "was this answer actually helpful".
+    //
+    // YOU run the model. This service stores raw prompts and completions and
+    // holds them with no outbound credentials at all, which is most of the reason
+    // it is safe to store them there -- so it hands the work out instead. Open a
+    // run, take the batch, send each `prompt` to whatever model you like, and
+    // post the scores back.
+    /** Write a rubric: what makes an answer good here, and what to score. */
+    async createJudge(params) {
+        const res = await this._http.fetchPost('/api/loop/judges', params);
+        return res.judge;
+    }
+    async listJudges() {
+        const res = await this._http.fetchGet('/api/loop/judges');
+        return res.judges;
+    }
+    /**
+     * Rewrite a rubric. Runs already recorded keep the instructions they used:
+     * a verdict has to keep meaning what it meant when it was given.
+     */
+    async updateJudge(judgeId, params) {
+        const res = await this._http.fetchPut(`/api/loop/judges/${encodeURIComponent(judgeId)}`, params);
+        return res.judge;
+    }
+    /**
+     * Retire a rubric. Its runs go with it; the verdicts they wrote stay. A score
+     * is evidence about an answer, and it does not stop being true because the
+     * rubric was retired.
+     */
+    async deleteJudge(judgeId) {
+        await this._http.fetchDelete(`/api/loop/judges/${encodeURIComponent(judgeId)}`);
+    }
+    /**
+     * Open a run: select the conversations now, and freeze the rubric onto them.
+     *
+     * The selection is fixed at this moment on purpose. A run whose selection is
+     * a live query silently grows as conversations arrive, so "we scored the
+     * refunds slice" becomes a claim about a set that no longer exists.
+     */
+    async startRun(judgeId, limit) {
+        const res = await this._http.fetchPost(`/api/loop/judges/${encodeURIComponent(judgeId)}/runs`, limit ? { limit } : {});
+        return res.run;
+    }
+    async listRuns(judgeId) {
+        const path = judgeId
+            ? `/api/loop/judges/${encodeURIComponent(judgeId)}/runs`
+            : '/api/loop/runs';
+        const res = await this._http.fetchGet(path);
+        return res.runs;
+    }
+    async getRun(runId) {
+        const res = await this._http.fetchGet(`/api/loop/runs/${encodeURIComponent(runId)}`);
+        return res.run;
+    }
+    /**
+     * Take the next conversations to score, each rendered into a ready-to-send
+     * prompt. Nothing is marked taken, so a caller that dies half way loses
+     * nothing: ask again and the same items come back.
+     */
+    async takeWork(runId, limit = 20) {
+        return this._http.fetchGet(`/api/loop/runs/${encodeURIComponent(runId)}/work?limit=${limit}`);
+    }
+    /**
+     * Hand the scores back. A verdict for a conversation outside this run, or
+     * scoring something the rubric never asked for, is refused and reported in
+     * `rejected` rather than silently dropped.
+     *
+     * Pass `finish` to close a run you have decided to stop early. Without it an
+     * unfinished run stays open, which is the honest state for work that was
+     * abandoned rather than completed.
+     */
+    async postVerdicts(runId, verdicts, finish = false) {
+        return this._http.fetchPost(`/api/loop/runs/${encodeURIComponent(runId)}/verdicts`, { verdicts, finish });
+    }
+}

package/dist/resources/training.d.ts

@@ -1,5 +1,5 @@
 import type { HttpClient } from '../client.js';
-import type { TrainingCreateParams, TrainingListParams, TrainingJob, TrainingListResponse, TrainingMetrics, TrainingCheckpoint, TrainingLogs, TrainingStopResponse, TrainingResumeResponse, TrainingPreflightResponse, TrainingCapabilities } from '../types.js';
+import type { TrainingCreateParams, TrainingListParams, TrainingJob, TrainingListResponse, TrainingMetrics, TrainingCheckpoint, TrainingLogs, TrainingStopResponse, TrainingResumeResponse, TrainingPreflightResponse, TrainingRecommendParams, TrainingAdvisorVerdict, TrainingCapabilities } from '../types.js';
 /**
  * Create, monitor, and manage fine-tuning training jobs.
  */
@@ -12,8 +12,11 @@ export declare class Training {
     /**
      * Create a new training job (book-before-reveal).
      *
-     * The call blocks while the ranked GPU ladder is booked (~40s typical). A
-     * training id and the "training started" email exist only once a real machine is
+     * Choose method, adapter, datasets and the complete hyperparameter config
+     * first, call {@link preflight}, then choose one returned GPU configuration
+     * last. Its minimum is derived from every earlier choice. This call blocks
+     * while that placement is booked (~40s typical). A training id and the
+     * "training started" email exist only once a real machine is
      * secured, so the returned `status` is one of:
      *
      * - `"booked"` — a GPU was secured (booked == secured); the job then
@@ -25,11 +28,12 @@ export declare class Training {
      *   (`queueIfUnavailable: true`); waits for stock at zero charge and books
      *   via the same path.
      *
-     * If the ladder is exhausted at booking time without queue consent, this
-     * rejects with a `CAPACITY_UNAVAILABLE` (HTTP 409) carrying neutral
-     * alternatives — no phantom job remains and nothing is billed. The SDK never
-     * auto-substitutes a GPU; a transient 503 is a retry, never a capacity
-     * verdict.
+     * If booking fails, this rejects with `CAPACITY_UNAVAILABLE` (HTTP 409)
+     * carrying fresh qualifying alternatives — no phantom job and no charge.
+     * Keep every earlier field unchanged, select one alternative and retry. The
+     * rejected type is never recommended back. Queue consent is appropriate only
+     * when the alternatives list is empty; waiting is unbilled. The SDK never
+     * auto-substitutes a GPU; a transient 503 is a retry, never a capacity verdict.
      *
      * @example
      * ```ts
@@ -51,6 +55,14 @@ export declare class Training {
     create(params: TrainingCreateParams): Promise<TrainingJob>;
     /** Validate and canonicalize a training request without creating or billing a job. */
     preflight(params: TrainingCreateParams): Promise<TrainingPreflightResponse>;
+    /**
+     * Ask the trainer's own sizing model what to run: per-device batch,
+     * accumulation, learning rate, warmup, predicted peak memory, minimum GPU
+     * count and a wall-clock estimate for this model on this GPU type, with the
+     * basis of every number. Side-effect free. When `available` is false no
+     * advisor is deployed and the other fields are absent -- nothing is guessed.
+     */
+    recommend(params: TrainingRecommendParams): Promise<TrainingAdvisorVerdict>;
     /** Return one server-driven page with pagination metadata. */
     listPage(params?: TrainingListParams): Promise<TrainingListResponse>;
     /**

package/dist/resources/training.js

@@ -67,8 +67,6 @@ function buildTrainingRequest(params) {
         body.integration_id = params.integrationId;
     if (params.networkVolumeId !== undefined)
         body.network_volume_id = params.networkVolumeId;
-    if (params.cacheDataset !== undefined)
-        body.cache_dataset = params.cacheDataset;
     if (params.datasetSampleLimits !== undefined)
         body.dataset_sample_limits = params.datasetSampleLimits;
     if (params.datasetMixing !== undefined)
@@ -78,6 +76,8 @@ function buildTrainingRequest(params) {
     const config = {};
     if (params.epochs !== undefined)
         config.num_train_epochs = params.epochs;
+    if (params.maxSteps !== undefined)
+        config.max_steps = params.maxSteps;
     if (params.batchSize !== undefined)
         config.per_device_train_batch_size = params.batchSize;
     if (params.gradientAccumulation !== undefined)
@@ -183,8 +183,11 @@ export class Training {
     /**
      * Create a new training job (book-before-reveal).
      *
-     * The call blocks while the ranked GPU ladder is booked (~40s typical). A
-     * training id and the "training started" email exist only once a real machine is
+     * Choose method, adapter, datasets and the complete hyperparameter config
+     * first, call {@link preflight}, then choose one returned GPU configuration
+     * last. Its minimum is derived from every earlier choice. This call blocks
+     * while that placement is booked (~40s typical). A training id and the
+     * "training started" email exist only once a real machine is
      * secured, so the returned `status` is one of:
      *
      * - `"booked"` — a GPU was secured (booked == secured); the job then
@@ -196,11 +199,12 @@ export class Training {
      *   (`queueIfUnavailable: true`); waits for stock at zero charge and books
      *   via the same path.
      *
-     * If the ladder is exhausted at booking time without queue consent, this
-     * rejects with a `CAPACITY_UNAVAILABLE` (HTTP 409) carrying neutral
-     * alternatives — no phantom job remains and nothing is billed. The SDK never
-     * auto-substitutes a GPU; a transient 503 is a retry, never a capacity
-     * verdict.
+     * If booking fails, this rejects with `CAPACITY_UNAVAILABLE` (HTTP 409)
+     * carrying fresh qualifying alternatives — no phantom job and no charge.
+     * Keep every earlier field unchanged, select one alternative and retry. The
+     * rejected type is never recommended back. Queue consent is appropriate only
+     * when the alternatives list is empty; waiting is unbilled. The SDK never
+     * auto-substitutes a GPU; a transient 503 is a retry, never a capacity verdict.
      *
      * @example
      * ```ts
@@ -240,6 +244,41 @@ export class Training {
         const { body } = buildTrainingRequest(params);
         return this._http.fetchPost('/api/training/preflight', body);
     }
+    /**
+     * Ask the trainer's own sizing model what to run: per-device batch,
+     * accumulation, learning rate, warmup, predicted peak memory, minimum GPU
+     * count and a wall-clock estimate for this model on this GPU type, with the
+     * basis of every number. Side-effect free. When `available` is false no
+     * advisor is deployed and the other fields are absent -- nothing is guessed.
+     */
+    async recommend(params) {
+        const q = new URLSearchParams({ model_id: params.model, gpu_type: params.gpuType });
+        if (params.modelRevision)
+            q.set('model_revision', params.modelRevision);
+        if (params.integrationId)
+            q.set('integration_id', params.integrationId);
+        if (params.gpuCount !== undefined)
+            q.set('gpu_count', String(params.gpuCount));
+        if (params.adapter)
+            q.set('train_type', params.adapter);
+        if (params.method)
+            q.set('method', params.method === 'cpt' ? 'pt' : params.method);
+        if (params.maxLength !== undefined)
+            q.set('max_length', String(params.maxLength));
+        if (params.epochs !== undefined)
+            q.set('num_train_epochs', String(params.epochs));
+        if (params.maxSteps !== undefined)
+            q.set('max_steps', String(params.maxSteps));
+        if (params.perDeviceTrainBatchSize !== undefined)
+            q.set('per_device_train_batch_size', String(params.perDeviceTrainBatchSize));
+        if (params.gradientAccumulationSteps !== undefined)
+            q.set('gradient_accumulation_steps', String(params.gradientAccumulationSteps));
+        if (params.datasetIds?.length)
+            q.set('dataset_ids', params.datasetIds.join(','));
+        if (params.workspaceId)
+            q.set('workspace_id', params.workspaceId);
+        return this._http.fetchGet(`/api/training/recommend?${q}`);
+    }
     /** Return one server-driven page with pagination metadata. */
     async listPage(params = {}) {
         const q = new URLSearchParams();