runbios-sdk 0.2.1-dev.145 → 0.2.1-dev.146

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-import type { BiOSConfig, ApiErrorBody, AvailableGpuAlternative, CapacityMinimumRequirement } from './types.js';
+import type { BiOSConfig, ApiErrorBody, AvailableGpuAlternative, CapacityMinimumRequirement, LoopImportResult } from './types.js';
 /**
  * Typed error thrown by every SDK method when the API returns a non-2xx status.
  *
@@ -135,6 +135,53 @@ export declare const COMING_SOON_CODES: readonly ["TRAINING_COMING_SOON", "DATAS
 export declare class ComingSoonError extends ApiError {
     constructor(status: number, body: ApiErrorBody);
 }
+/** The code an import answers with when some rows were understood and then could not be stored. */
+export declare const IMPORT_INCOMPLETE_CODE = "IMPORT_INCOMPLETE";
+/**
+ * An import that did not finish: some rows could not be stored, or some
+ * verdicts that arrived with them could not be written.
+ *
+ * The rows it names were read and understood, so there is nothing to fix in
+ * the file: this is a storage failure, not a shape one. The full outcome is on
+ * {@link LoopImportIncompleteError.outcome} — what landed, which conversations
+ * it became, and which row positions did not — because a failure that reports
+ * only "it failed" leaves the caller with no move except sending everything
+ * again.
+ *
+ * HOW TO RECOVER. Send the same rows again with `importId`, the token this
+ * call was filed under. That is what makes the second call a RETRY: rows that
+ * already arrived come back under `already_present` instead of being stored
+ * twice, and a verdict that failed to write is attempted again. Repeat it
+ * exactly; a call that repeats nothing is a second import, on purpose, because
+ * a repeat is otherwise indistinguishable from the next page of a longer file.
+ *
+ * THE WHOLE FILE, not the rows this names, unless you sent `row_ids`. Without
+ * them a row is identified by its place in the call, so a shorter list moves
+ * every row after the gap and each is imported again.
+ */
+export declare class LoopImportIncompleteError extends ApiError {
+    /** Counts, notes and ids for the import, in the same shape a success returns. */
+    readonly outcome: LoopImportResult;
+    constructor(status: number, body: ApiErrorBody);
+    /**
+     * The token to repeat as `import_id` to retry this call. Without it the retry
+     * is a second import rather than a retry, and what already landed is stored
+     * again.
+     */
+    get importId(): string | undefined;
+    /**
+     * Row positions that were not stored, counting from 1 in the order you sent
+     * them. They say what is missing; they are a smaller file to send back only
+     * if you sent `row_ids`.
+     */
+    get notSavedRows(): number[];
+    /**
+     * Row positions whose conversation stored and whose verdict did not. Those
+     * conversations are in the loop waiting for review; retrying records the
+     * verdict.
+     */
+    get verdictsNotSavedRows(): number[];
+}
 /** Whether a machine code is one of the permanent GPU rejections. */
 export declare function isPermanentGpuCode(code: string | undefined): boolean;
 /**

package/dist/client.js

@@ -191,6 +191,63 @@ export class ComingSoonError extends ApiError {
         this.name = 'ComingSoonError';
     }
 }
+/** The code an import answers with when some rows were understood and then could not be stored. */
+export const IMPORT_INCOMPLETE_CODE = 'IMPORT_INCOMPLETE';
+/**
+ * An import that did not finish: some rows could not be stored, or some
+ * verdicts that arrived with them could not be written.
+ *
+ * The rows it names were read and understood, so there is nothing to fix in
+ * the file: this is a storage failure, not a shape one. The full outcome is on
+ * {@link LoopImportIncompleteError.outcome} — what landed, which conversations
+ * it became, and which row positions did not — because a failure that reports
+ * only "it failed" leaves the caller with no move except sending everything
+ * again.
+ *
+ * HOW TO RECOVER. Send the same rows again with `importId`, the token this
+ * call was filed under. That is what makes the second call a RETRY: rows that
+ * already arrived come back under `already_present` instead of being stored
+ * twice, and a verdict that failed to write is attempted again. Repeat it
+ * exactly; a call that repeats nothing is a second import, on purpose, because
+ * a repeat is otherwise indistinguishable from the next page of a longer file.
+ *
+ * THE WHOLE FILE, not the rows this names, unless you sent `row_ids`. Without
+ * them a row is identified by its place in the call, so a shorter list moves
+ * every row after the gap and each is imported again.
+ */
+export class LoopImportIncompleteError extends ApiError {
+    /** Counts, notes and ids for the import, in the same shape a success returns. */
+    outcome;
+    constructor(status, body) {
+        super(status, body);
+        this.name = 'LoopImportIncompleteError';
+        this.outcome = body;
+    }
+    /**
+     * The token to repeat as `import_id` to retry this call. Without it the retry
+     * is a second import rather than a retry, and what already landed is stored
+     * again.
+     */
+    get importId() {
+        return this.outcome.import_id;
+    }
+    /**
+     * Row positions that were not stored, counting from 1 in the order you sent
+     * them. They say what is missing; they are a smaller file to send back only
+     * if you sent `row_ids`.
+     */
+    get notSavedRows() {
+        return this.outcome.not_saved_rows ?? [];
+    }
+    /**
+     * Row positions whose conversation stored and whose verdict did not. Those
+     * conversations are in the loop waiting for review; retrying records the
+     * verdict.
+     */
+    get verdictsNotSavedRows() {
+        return this.outcome.verdicts_not_saved_rows ?? [];
+    }
+}
 /** Whether a machine code is one of the permanent GPU rejections. */
 export function isPermanentGpuCode(code) {
     return typeof code === 'string' && PERMANENT_GPU_CODES.includes(code);
@@ -225,6 +282,12 @@ export function buildApiError(status, body) {
     if (code && COMING_SOON_CODES.includes(code)) {
         return new ComingSoonError(status, body);
     }
+    // A half-finished import carries its whole outcome in the body. Leaving it as
+    // a plain ApiError makes the counts reachable only by casting `.body`, which
+    // is the same as not publishing them.
+    if (code === IMPORT_INCOMPLETE_CODE) {
+        return new LoopImportIncompleteError(status, body);
+    }
     return new ApiError(status, body);
 }
 // ============================================================================

package/dist/index.d.ts

@@ -36,7 +36,7 @@ import { Loop } from './resources/loop.js';
  * SDK version. Sent as part of the User-Agent header.
  * Must match package.json "version" -- enforced by a contract test.
  */
-export declare const VERSION = "0.2.1-dev.145";
+export declare const VERSION = "0.2.1-dev.146";
 export declare class RunBiOS {
     /** Search models, fetch configs, check adapter compatibility. */
     readonly models: Models;
@@ -67,7 +67,7 @@ export declare class RunBiOS {
 }
 /** @deprecated Use {@link RunBiOS}. */
 export { RunBiOS as BiOS };
-export { ApiError, GpuRejectionError, CapacityUnavailableError, ComingSoonError, CAPACITY_UNAVAILABLE_CODE, COMING_SOON_CODES, PERMANENT_GPU_CODES, isPermanentGpuCode, gpuRejectionCodeForReason, } from './client.js';
+export { ApiError, GpuRejectionError, CapacityUnavailableError, ComingSoonError, LoopImportIncompleteError, CAPACITY_UNAVAILABLE_CODE, COMING_SOON_CODES, IMPORT_INCOMPLETE_CODE, PERMANENT_GPU_CODES, isPermanentGpuCode, gpuRejectionCodeForReason, } from './client.js';
 export { Models } from './resources/models.js';
 export { Datasets } from './resources/datasets.js';
 export { Integrations, type HuggingFaceIntegration, type IntegrationBrowseParams } from './resources/integrations.js';

package/dist/index.js

@@ -36,7 +36,7 @@ import { Loop } from './resources/loop.js';
  * SDK version. Sent as part of the User-Agent header.
  * Must match package.json "version" -- enforced by a contract test.
  */
-export const VERSION = '0.2.1-dev.145';
+export const VERSION = '0.2.1-dev.146';
 export class RunBiOS {
     /** Search models, fetch configs, check adapter compatibility. */
     models;
@@ -95,7 +95,7 @@ export { RunBiOS as BiOS };
 // ---------------------------------------------------------------------------
 // Re-exports
 // ---------------------------------------------------------------------------
-export { ApiError, GpuRejectionError, CapacityUnavailableError, ComingSoonError, CAPACITY_UNAVAILABLE_CODE, COMING_SOON_CODES, PERMANENT_GPU_CODES, isPermanentGpuCode, gpuRejectionCodeForReason, } from './client.js';
+export { ApiError, GpuRejectionError, CapacityUnavailableError, ComingSoonError, LoopImportIncompleteError, CAPACITY_UNAVAILABLE_CODE, COMING_SOON_CODES, IMPORT_INCOMPLETE_CODE, PERMANENT_GPU_CODES, isPermanentGpuCode, gpuRejectionCodeForReason, } from './client.js';
 export { Models } from './resources/models.js';
 export { Datasets } from './resources/datasets.js';
 export { Integrations } from './resources/integrations.js';

package/dist/resources/loop.d.ts

@@ -84,6 +84,37 @@ export declare class Loop {
      * 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.
+     *
+     * WHAT COMES BACK. `imported` is what this call created and `trace_ids` names
+     * the conversations from the file that are now in the loop, so a caller can
+     * label, review or delete them. `by_shape`, `reviewed` and `needs_review`
+     * count what THIS CALL created, not what was merely recognised and not rows
+     * an earlier import already had, and the sentences in `notes` are written
+     * from those counts, so the numbers and the prose describe the same call and
+     * a re-send cannot report a reviewed conversation as waiting for review.
+     * `refused` is rows whose shape could not be read, which the file fixes;
+     * `not_saved` is rows that were understood and then could not be stored,
+     * which the file cannot fix.
+     *
+     * A call with any `not_saved`, or any `verdicts_not_saved` (the conversation
+     * stored and the judgement that came with it did not), REJECTS with
+     * `LoopImportIncompleteError`, whose `outcome` carries all of the above and
+     * whose `notSavedRows` and `verdictsNotSavedRows` name the positions.
+     *
+     * HOW A RETRY IS SAFE. Every response carries `import_id`, the token this
+     * call was filed under. Send the same rows again with it, and rows that
+     * already arrived come back on `already_present` instead of being stored
+     * twice, while a verdict that failed to write is attempted again. A call that
+     * repeats no token is its own import, deliberately: two calls carrying the
+     * same rows are as likely to be two pages of one export as one call twice,
+     * and guessing "retry" silently drops the second copy of every conversation a
+     * file lists more than once.
+     *
+     * SENDING A FILE IN PAGES. Either give each row its own `row_ids` entry, and
+     * then chunking, ordering and subsets all stop mattering; or send one
+     * `import_id` with the `row_offset` each page starts at. Do not send back
+     * only the rows `notSavedRows` names unless you used `row_ids`: without them
+     * a shorter list moves every row after the gap and imports it again.
      */
     importRows(params: LoopImportParams): Promise<LoopImportResult>;
     /** List captured conversations, newest first. */

package/dist/resources/loop.js

@@ -87,6 +87,37 @@ export class Loop {
      * 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.
+     *
+     * WHAT COMES BACK. `imported` is what this call created and `trace_ids` names
+     * the conversations from the file that are now in the loop, so a caller can
+     * label, review or delete them. `by_shape`, `reviewed` and `needs_review`
+     * count what THIS CALL created, not what was merely recognised and not rows
+     * an earlier import already had, and the sentences in `notes` are written
+     * from those counts, so the numbers and the prose describe the same call and
+     * a re-send cannot report a reviewed conversation as waiting for review.
+     * `refused` is rows whose shape could not be read, which the file fixes;
+     * `not_saved` is rows that were understood and then could not be stored,
+     * which the file cannot fix.
+     *
+     * A call with any `not_saved`, or any `verdicts_not_saved` (the conversation
+     * stored and the judgement that came with it did not), REJECTS with
+     * `LoopImportIncompleteError`, whose `outcome` carries all of the above and
+     * whose `notSavedRows` and `verdictsNotSavedRows` name the positions.
+     *
+     * HOW A RETRY IS SAFE. Every response carries `import_id`, the token this
+     * call was filed under. Send the same rows again with it, and rows that
+     * already arrived come back on `already_present` instead of being stored
+     * twice, while a verdict that failed to write is attempted again. A call that
+     * repeats no token is its own import, deliberately: two calls carrying the
+     * same rows are as likely to be two pages of one export as one call twice,
+     * and guessing "retry" silently drops the second copy of every conversation a
+     * file lists more than once.
+     *
+     * SENDING A FILE IN PAGES. Either give each row its own `row_ids` entry, and
+     * then chunking, ordering and subsets all stop mattering; or send one
+     * `import_id` with the `row_offset` each page starts at. Do not send back
+     * only the rows `notSavedRows` names unless you used `row_ids`: without them
+     * a shorter list moves every row after the gap and imports it again.
      */
     async importRows(params) {
         return this._http.fetchPost('/api/loop/import', params);

package/dist/types.d.ts

@@ -2233,13 +2233,91 @@ export interface LoopImportParams {
     /** Applied to every row: importing a dump is when somebody knows what it is. */
     labels?: string[];
     attributes?: Record<string, string>;
+    /**
+     * Repeat the `import_id` a previous call reported to make this call a RETRY
+     * of that one: rows that already arrived come back under `already_present`
+     * instead of being stored again.
+     *
+     * Leave it out and this call is its own import. The endpoint will NOT guess:
+     * two calls carrying the same rows are as likely to be two pages of one
+     * export as one call sent twice, and guessing "retry" silently drops the
+     * second copy of every conversation a file lists more than once. Every
+     * response carries the token it was filed under, so a retry is always
+     * available and never has to be inferred.
+     *
+     * SEND THE ROWS AS YOU SENT THEM. Without `row_ids` a row is matched on its
+     * text, and the match survives re-ordered keys and different whitespace but
+     * NOT a number that has been re-spelled: `100`, `1e2` and `100.0` are three
+     * different rows. A round trip through most JSON libraries re-spells numbers
+     * (Python turns `1e2` into `100.0`), so a retry built by re-serialising a
+     * parsed file can store rows a second time. Keep the bytes you sent, or send
+     * `row_ids` and stop depending on the text at all.
+     */
+    import_id?: string;
+    /**
+     * Where this page starts in the file, counting from 0. Send it when you split
+     * one import across several calls under one `import_id`, so two pages are not
+     * matched against each other row for row. Ignored when you send `row_ids`.
+     */
+    row_offset?: number;
+    /**
+     * Your own id for each row, in the same order as `rows`: a ticket number, a
+     * conversation id, whatever the export already carries.
+     *
+     * The strongest form of identity, and the one to reach for with a file big
+     * enough to page. It SUPERSEDES `import_id` and `row_offset`: with it,
+     * chunking, ordering and subsets all stop mattering and any part of the file
+     * can be re-sent exactly. One per row or none at all, and no two rows in a
+     * call may share an id: both are refused rather than silently merging two
+     * conversations into one.
+     *
+     * THE ID IS THE IDENTITY, AND THE ROW'S TEXT IS NOT PART OF IT. A row sent
+     * again under an id this source already imported comes back under
+     * `already_present` and the stored conversation is left as it was, even if
+     * you changed its text. A CORRECTION DOES NOT LAND THIS WAY: send it under a
+     * new id. That is the trade for making every retry, page and subset safe -
+     * the text is never compared, so nothing your serialiser does to it can turn
+     * a retry into a second import.
+     */
+    row_ids?: string[];
 }
+/**
+ * What an import did.
+ *
+ * A call where every row stored resolves with this. A call where SOME rows
+ * could not be stored rejects with {@link LoopImportIncompleteError}, whose
+ * `outcome` is this same shape: the counts are the whole answer either way, so
+ * read them from the error exactly as you would from a success.
+ */
 export interface LoopImportResult {
+    /**
+     * The token this call was filed under, whether you sent one or it was minted
+     * for you. Send the same rows again with this `import_id` to retry the call.
+     * Present on every response, success or failure, because a call can succeed
+     * and still need retrying when the answer never reached you.
+     */
+    import_id?: string;
+    /** How many conversations this call created. */
     imported: number;
     /**
-     * How many arrived carrying a verdict. Reported apart from `imported`
-     * because it is the difference between data you can train on and data
-     * somebody still has to look at.
+     * How many rows an earlier call under the SAME `import_id` (or carrying the
+     * same `row_ids`) had already imported, and so were not stored a second time.
+     * Zero on a first import, and zero on any call that repeated neither: a call
+     * that does not say it is a retry is its own import, which is what lets a
+     * file sent in pages land complete.
+     */
+    already_present?: number;
+    /**
+     * How many verdicts THIS CALL WROTE. Reported apart from `imported` because
+     * it is the difference between data you can train on and data somebody still
+     * has to look at.
+     *
+     * Re-sending a row whose verdict already landed writes nothing and counts
+     * nothing, so a plain retry reads 0. Re-sending one that came back in
+     * `verdicts_not_saved` DOES count here when the write succeeds this time,
+     * even though the row itself is counted under `already_present`: that is the
+     * first time anybody recorded that verdict, not a second reviewer. This is
+     * the field to read to confirm a repair landed.
      */
     reviewed: number;
     needs_review: number;
@@ -2251,17 +2329,47 @@ export interface LoopImportResult {
     /**
      * How many rows were understood and then could not be stored. Counted apart
      * from `refused`, because the two are different claims and rewriting a file
-     * that was already correct fixes nothing. A call with any of these fails
-     * rather than succeeding, and the failure carries these same fields.
+     * that was already correct fixes nothing. A call with any of these rejects
+     * rather than resolving; read it off {@link LoopImportIncompleteError.outcome}.
      */
     not_saved?: number;
-    /** How many rows of each recognised shape, so a mis-shaped file is visible. */
+    /**
+     * WHICH rows those were, counting from 1 in the order you sent them, so you
+     * can say what is missing rather than only how much.
+     *
+     * NOT A SMALLER FILE TO SEND BACK unless you sent `row_ids`. Without them a
+     * row is identified by its place in the call, so a shorter list moves every
+     * row after the gap and each one is stored again. Re-send the whole set of
+     * rows, in the same order, with the same `import_id`; what already arrived
+     * comes back under `already_present`. With `row_ids` a row carries its own
+     * identity and any subset is exact.
+     */
+    not_saved_rows?: number[];
+    /**
+     * Rows whose CONVERSATION stored and whose VERDICT did not, and which rows
+     * those were. A preference pair or a thumbs label is two writes, and the
+     * second can fail on its own: the conversation is then in the loop carrying
+     * nobody's judgement, counted under `needs_review` rather than `reviewed`,
+     * and not trainable. The call rejects with {@link LoopImportIncompleteError},
+     * and sending the rows again under the same `import_id` records the verdict
+     * without storing the conversation twice.
+     */
+    verdicts_not_saved?: number;
+    verdicts_not_saved_rows?: number[];
+    /**
+     * How many conversations of each shape THIS CALL created. Rows that were
+     * refused, rows that failed to store and rows an earlier import already had
+     * are not in here: the counts and the sentences in `notes` describe the same
+     * call, so neither can claim a conversation is waiting for review when none
+     * was written.
+     */
     by_shape: Record<string, number>;
     refused_why: Record<string, number>;
     /**
-     * The conversations this call created, in file order. Without them a caller
-     * whose import half-failed has a number and no way to reach what landed: no
-     * way to label it, review it, or delete it and start again.
+     * The conversations from this file that are now in the loop, in file order:
+     * the ones this call created and the ones it found already there. Without
+     * them a caller whose import half-failed has a number and no way to reach
+     * what landed: no way to label it, review it, or delete it and start again.
      */
     trace_ids?: string[];
     notes: string[];

package/package.json

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