runbios-sdk 0.2.1-dev.105 → 0.2.1-dev.107

package/dist/index.d.ts

@@ -35,7 +35,7 @@ import { Loop } from './resources/loop.js';
  * SDK version. Sent as part of the User-Agent header.
  * Must match package.json "version" -- enforced by a contract test.
  */
-export declare const VERSION = "0.2.1-dev.105";
+export declare const VERSION = "0.2.1-dev.107";
 export declare class RunBiOS {
     /** Search models, fetch configs, check adapter compatibility. */
     readonly models: Models;

package/dist/index.js

@@ -35,7 +35,7 @@ import { Loop } from './resources/loop.js';
  * SDK version. Sent as part of the User-Agent header.
  * Must match package.json "version" -- enforced by a contract test.
  */
-export const VERSION = '0.2.1-dev.105';
+export const VERSION = '0.2.1-dev.107';
 export class RunBiOS {
     /** Search models, fetch configs, check adapter compatibility. */
     models;

package/dist/resources/loop.d.ts

@@ -1,5 +1,5 @@
 import type { HttpClient } from '../client.js';
-import type { LoopTrace, LoopTraceListResponse, LoopTraceListParams, LoopCaptureParams, LoopCaptureResult, LoopSignal, LoopSignalParams, LoopDataset, LoopDatasetListParams, LoopDatasetItem, LoopDatasetCreateParams, LoopConfig, LoopConfigParams, LoopStats } from '../types.js';
+import type { LoopTrace, LoopTraceListResponse, LoopTraceListParams, LoopCaptureParams, LoopCaptureResult, LoopSignal, LoopSignalParams, LoopCandidate, LoopCandidateParams, LoopGrader, LoopGraderParams, LoopGradeResult, LoopDataset, LoopDatasetListParams, LoopDatasetItem, LoopDatasetCreateParams, LoopConfig, LoopConfigParams, LoopStats } from '../types.js';
 /**
  * The Conscious Loop -- capture what your model was asked and answered, record
  * whether it was right, and turn those judgements into training data.
@@ -18,7 +18,7 @@ import type { LoopTrace, LoopTraceListResponse, LoopTraceListParams, LoopCapture
  * 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, OpenAI, your own vLLM.
+ * //    served it -- us, another provider, or your own servers.
  * const { trace_id } = await client.loop.capture({
  *   deployment_id: 'my-agent',
  *   model: 'gpt-4o',
@@ -46,7 +46,7 @@ export declare class Loop {
      * Send one exchange to be captured.
      *
      * Works regardless of who served the model: ours, OpenAI, Fireworks, your own
-     * vLLM, an agent framework. Pass `tool_calls` and `tools` when the turn
+     * 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.
      *
@@ -90,6 +90,37 @@ export declare class Loop {
     signal(traceId: string, params: LoopSignalParams): Promise<LoopSignal>;
     /** Every verdict on one conversation, oldest first. */
     listSignals(traceId: string): Promise<LoopSignal[]>;
+    /**
+     * 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',
+     *   });
+     * }
+     * ```
+     */
+    addCandidate(traceId: string, params: LoopCandidateParams): Promise<LoopCandidate>;
+    /** Every alternative answer recorded for one prompt, oldest first. */
+    listCandidates(traceId: string): Promise<LoopCandidate[]>;
     /**
      * Build a training set from the feedback recorded so far.
      *
@@ -141,6 +172,47 @@ export declare class Loop {
         deleted: boolean;
         dataset_id: string;
     }>;
+    /**
+     * 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.
+     */
+    createGrader(params: LoopGraderParams): Promise<LoopGrader>;
+    /** Every rule this workspace has written. */
+    listGraders(): Promise<LoopGrader[]>;
+    deleteGrader(id: string): Promise<{
+        deleted: boolean;
+        grader_id: string;
+    }>;
+    /**
+     * 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.
+     */
+    grade(traceId: string): Promise<LoopGradeResult>;
     /** Every source this workspace has configured. */
     listConfigs(): Promise<LoopConfig[]>;
     /**

package/dist/resources/loop.js

@@ -16,7 +16,7 @@
  * 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, OpenAI, your own vLLM.
+ * //    served it -- us, another provider, or your own servers.
  * const { trace_id } = await client.loop.capture({
  *   deployment_id: 'my-agent',
  *   model: 'gpt-4o',
@@ -47,7 +47,7 @@ export class Loop {
      * Send one exchange to be captured.
      *
      * Works regardless of who served the model: ours, OpenAI, Fireworks, your own
-     * vLLM, an agent framework. Pass `tool_calls` and `tools` when the turn
+     * 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.
      *
@@ -121,6 +121,44 @@ export class Loop {
         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;
+    }
     // ── training sets ─────────────────────────────────────────────────────
     /**
      * Build a training set from the feedback recorded so far.
@@ -198,6 +236,55 @@ export class Loop {
     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() {

package/dist/types.d.ts

@@ -2140,3 +2140,92 @@ export interface LoopStats {
     /** Upper bounds: deduplication runs when a set is built. */
     ready: Record<LoopMethod, number>;
 }
+export interface LoopCandidateParams {
+    completion?: string;
+    /** An alternative that is itself a tool call. */
+    tool_calls?: LoopToolCall[];
+    /** Which model produced this alternative. The teacher, when distilling. */
+    model?: string;
+    model_version?: string;
+    /** Unscored alternatives cannot pair -- a missing score is not a low one. */
+    score?: number;
+    /** Required alongside a score: human | verifier | judge | behavioural. */
+    score_source?: LoopSource;
+    reason?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface LoopCandidate {
+    id: string;
+    trace_id: string;
+    model: string | null;
+    model_version: string | null;
+    completion: string;
+    tool_calls?: LoopToolCall[];
+    score: number | null;
+    score_source: LoopSource | null;
+    reason: string | null;
+    metadata: Record<string, unknown>;
+    created_at: string;
+}
+/** The deterministic checks a grader can perform. */
+export type LoopGraderKind = 'exact_match' | 'contains' | 'regex' | 'json_valid' | 'numeric' | 'tool_called';
+export interface LoopGraderConfig {
+    expected?: string;
+    /** Every phrase that must appear. */
+    required?: string[];
+    /** Phrases that must not. On their own these are passed by silence. */
+    forbidden?: string[];
+    pattern?: string;
+    /** Keys the answer must carry, for `json_valid`. */
+    keys?: string[];
+    /** How far from `expected` still counts, for `numeric`. */
+    tolerance?: number;
+    /** The function that must have been called, for `tool_called`. */
+    function?: string;
+    case_sensitive?: boolean;
+}
+export interface LoopGraderParams {
+    name: string;
+    kind: LoopGraderKind;
+    config: LoopGraderConfig;
+    /** The multiplier. Twice as important, twice the weight. Must exceed zero. */
+    weight?: number;
+    enabled?: boolean;
+    /** Limit the rule to one capture source. Omit to apply it everywhere. */
+    deployment_id?: string;
+}
+export interface LoopGrader extends LoopGraderParams {
+    id: string;
+    workspace_id: string;
+    weight: number;
+    enabled: boolean;
+    created_by: string | null;
+    created_at: string;
+    updated_at: string;
+}
+export interface LoopGraderResult {
+    grader_id: string;
+    name: string;
+    kind: string;
+    weight: number;
+    passed: boolean;
+    score: number;
+    /** What happened, in words -- "failed" alone sends you to read the rule. */
+    detail: string;
+    /** The rule had no opinion. Excluded from the score rather than counted 0. */
+    skipped: boolean;
+}
+export interface LoopGradeReport {
+    /** Weighted mean over the rules that applied, 0 to 1. */
+    score: number;
+    results: LoopGraderResult[];
+    /** The denominator. 1.0 from one rule is not 1.0 from six. */
+    applied: number;
+    skipped: number;
+}
+export interface LoopGradeResult {
+    report: LoopGradeReport;
+    /** Null when no rule applied, because no verdict was invented. */
+    signal_id: string | null;
+    candidates_graded: number;
+}

package/package.json

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