@toloka-platform/sdk 0.2.0-preview.3 → 0.2.0-preview.4

package/src/cli/source.ts

@@ -1,9 +1,9 @@
-import { assert } from "es-toolkit";
 import { readdir, stat } from "node:fs/promises";
 import { basename, dirname, join, relative, resolve, sep } from "node:path";
 import { pathToFileURL } from "node:url";
 import { validatePipelineDefinition } from "../authoring";
 import type { PipelineDefinition } from "../authoring";
+import { assertCli } from "./cli-error";
 
 export type ProjectPipelineSource = {
   readonly sourceDirectory: string;
@@ -64,9 +64,10 @@ export async function loadProjectSource(sourceRoot: string): Promise<ProjectSour
       const moduleUrl = pathToFileURL(modulePath);
       moduleUrl.searchParams.set("version", `${moduleStat.mtimeMs}-${moduleStat.size}`);
       const module: unknown = await import(moduleUrl.href);
-      assert(
+      assertCli(
         typeof module === "object" && module !== null,
         `Invalid ${modulePath}: expected a module`,
+        { hint: { description: "Make the file a TypeScript module that exports the pipeline definition." } },
       );
       const definition: unknown = Reflect.get(module, "default");
       validatePipelineDefinition(definition);

package/src/cli/terminal-io.ts

@@ -2,6 +2,15 @@ import { createInterface } from "node:readline/promises";
 import type { AuthPrompt } from "./auth";
 import type { CliIo } from "./context";
 import { pickPipeline } from "./runs";
+import { TolokaCliError } from "./cli-error";
+
+const stdinClosedError = () =>
+  new TolokaCliError("Standard input closed before an API key was entered.", {
+    hint: {
+      description:
+        "Run toloka login in an interactive terminal, or pipe the key with toloka login --api-key-stdin.",
+    },
+  });
 
 const readStandardInput = async (): Promise<string> => {
   process.stdin.setEncoding("utf8");
@@ -35,7 +44,7 @@ const readMaskedLine = async (question: string): Promise<string> => {
 
   const onEnd = () => {
     finish();
-    reject(new Error("Standard input closed before an API key was entered."));
+    reject(stdinClosedError());
   };
 
   const onError = (error: Error) => {
@@ -53,11 +62,9 @@ const readMaskedLine = async (question: string): Promise<string> => {
       if (character === "\u0003" || character === "\u0004") {
         finish();
         reject(
-          new Error(
-            character === "\u0003"
-              ? "Canceled."
-              : "Standard input closed before an API key was entered.",
-          ),
+          character === "\u0003"
+            ? new TolokaCliError("Canceled.", { hint: { disabled: true } })
+            : stdinClosedError(),
         );
         return;
       }

package/src/cli/trainings.ts

@@ -3,8 +3,6 @@ import { readFile, stat } from "node:fs/promises";
 
 import { randomUUID } from "node:crypto";
 
-import { assert } from "es-toolkit";
-
 import type {
   PotatoClient,
   Training,
@@ -14,6 +12,12 @@ import type {
   TrainingRunMetrics,
 } from "../client";
 import type { BaseModelId, TrainingConfigurationInput } from "../../openapi/gen/models";
+import { assertCli, RETRY_OR_REPORT_HINT, TolokaCliError } from "./cli-error";
+import type { CliErrorHint } from "./cli-error";
+
+const ESTIMATE_FILE_HINT: CliErrorHint = {
+  description: "Regenerate it with toloka training cost <training> --json > <file>.",
+};
 
 type TrainingMethod = TrainingConfigurationInput["method"];
 type TrainingSource = TrainingConfigurationInput["source"];
@@ -30,9 +34,12 @@ export type TrainingDraftOptions = {
   validationDatasetId?: string;
   trainingFilter?: string;
   validationFilter?: string;
-  regime?: "low" | "medium" | "high";
+  loraRank?: SftConfigurationInput["loraRank"];
+  gistTokens?: GistingConfigurationInput["gistTokens"];
   epochs?: number;
-  evalSteps?: number;
+  learningRate?: number;
+  batchSize?: SftConfigurationInput["batchSize"];
+  maxSequenceLength?: number;
   promptFilePath?: string;
   fetch?: typeof globalThis.fetch;
 };
@@ -72,6 +79,13 @@ const formatTraining = (training: Training): string =>
       "Method",
       training.configuration.method === "sft" ? "Supervised fine-tuning (SFT)" : "Prompt gisting",
     ],
+    training.configuration.method === "sft"
+      ? ["LoRA rank", String(training.configuration.loraRank)]
+      : ["Gist tokens", String(training.configuration.gistTokens)],
+    ["Epochs", String(training.configuration.epochs)],
+    ["Learning rate", String(training.configuration.learningRate)],
+    ["Batch size", String(training.configuration.batchSize)],
+    ["Max sequence length", String(training.configuration.maxSequenceLength)],
     ["Output Model", training.modelId ?? "-"],
     ["Archived at", training.archivedAt ?? "-"],
     ["Created at", training.createdAt],
@@ -115,27 +129,32 @@ type ReadyEstimateFile = {
 };
 
 const parseReadyEstimateFile = (value: unknown): ReadyEstimateFile => {
-  assert(
+  assertCli(
     typeof value === "object" && value !== null && !Array.isArray(value),
     "The estimate file must contain a JSON object.",
+    { hint: ESTIMATE_FILE_HINT },
   );
-  assert(
+  assertCli(
     "status" in value && value.status === "ready",
     "The estimate file is not a ready Training Cost Estimate.",
+    { hint: ESTIMATE_FILE_HINT },
   );
-  assert(
+  assertCli(
     "trainingId" in value && typeof value.trainingId === "string",
     "The estimate file has no Training ID.",
+    { hint: ESTIMATE_FILE_HINT },
   );
-  assert(
+  assertCli(
     "inputSetId" in value && typeof value.inputSetId === "string",
     "The estimate file has no Input Set ID.",
+    { hint: ESTIMATE_FILE_HINT },
   );
-  assert(
+  assertCli(
     "fingerprint" in value &&
       typeof value.fingerprint === "string" &&
       /^[0-9a-f]{64}$/.test(value.fingerprint),
     "The estimate file has no valid fingerprint.",
+    { hint: ESTIMATE_FILE_HINT },
   );
 
   return {
@@ -171,9 +190,10 @@ const resolveTraining = async (
 ): Promise<Training> => {
   if (nameOrId.startsWith("trg.")) {
     const training = await client.trainings.get({ trainingId: nameOrId });
-    assert(
+    assertCli(
       training.projectId === projectId,
       `Training ${nameOrId} was not found in project ${projectId}.`,
+      { hint: { description: "Run toloka training list; a Training belongs to one project." } },
     );
     return training;
   }
@@ -182,7 +202,9 @@ const resolveTraining = async (
   for await (const training of client.trainings.listAll({ projectId, limit: 100 })) {
     if (training.name === nameOrId) matches.push(training);
   }
-  assert(matches.length === 1, `Training ${nameOrId} was not found or is ambiguous.`);
+  assertCli(matches.length === 1, `Training ${nameOrId} was not found or is ambiguous.`, {
+    hint: { description: "Run toloka training list and pass the training id (trg.…)." },
+  });
   return matches[0]!;
 };
 
@@ -199,12 +221,18 @@ const resolveSelection = async (
   datasetId: string,
   filter: string | undefined,
 ): Promise<TrainingSelection> => {
-  assert(datasetId, "A Dataset is required when specifying a filter.");
+  assertCli(datasetId, "A Dataset is required when specifying a filter.", {
+    hint: {
+      description:
+        "Pass --dataset together with --train-filter, and --validation-dataset together with --validation-filter.",
+    },
+  });
   if (filter === undefined) return { datasetId };
   const separator = filter.indexOf("=");
-  assert(
+  assertCli(
     separator > 0 && separator < filter.length - 1,
     "Dataset filters must use FIELD=VALUE syntax.",
+    { hint: { description: "Write the filter as field=value, for example split=train." } },
   );
   const fieldName = filter.slice(0, separator);
   const rawValue = filter.slice(separator + 1);
@@ -213,9 +241,10 @@ const resolveSelection = async (
     if (field.name === fieldName) matches.push(field);
   }
   const [field] = matches;
-  assert(
+  assertCli(
     field && matches.length === 1,
     `Dataset field ${fieldName} was not found or is ambiguous.`,
+    { hint: { description: "Run toloka dataset fields <dataset> to see the field names." } },
   );
   return {
     datasetId,
@@ -240,14 +269,17 @@ const sourceFromOptions = (
   options: Pick<TrainingDraftOptions, "baseModelId" | "modelVersionId">,
   fallback?: TrainingSource,
 ): TrainingSource => {
-  assert(
+  assertCli(
     !(options.baseModelId && options.modelVersionId),
     "Choose exactly one of --base-model and --model-version.",
+    { hint: { disabled: true } },
   );
   if (options.baseModelId) return { type: "base_model", baseModelId: options.baseModelId };
   if (options.modelVersionId)
     return { type: "model_version", modelVersionId: options.modelVersionId };
-  assert(fallback, "Choose exactly one of --base-model and --model-version.");
+  assertCli(fallback, "Choose exactly one of --base-model and --model-version.", {
+    hint: { disabled: true },
+  });
   return fallback;
 };
 
@@ -258,20 +290,29 @@ const uploadPromptFile = async (
   fetchImplementation: typeof globalThis.fetch,
 ): Promise<string> => {
   const metadata = await stat(filePath);
-  assert(metadata.isFile(), "--prompt-file must point to a file.");
-  assert(metadata.size > 0, "The gisting prompt file is empty.");
-  assert(
+  assertCli(metadata.isFile(), "--prompt-file must point to a file.", {
+    hint: { description: "Pass the absolute path of the prompt text file." },
+  });
+  assertCli(metadata.size > 0, "The gisting prompt file is empty.", {
+    hint: { description: "Put the full prompt text into the file before creating the Training." },
+  });
+  assertCli(
     metadata.size <= GISTING_PROMPT_MAX_BYTES,
     "The gisting prompt file exceeds the 256 KiB limit.",
+    { hint: { description: "Shorten the prompt to under 256 KiB." } },
   );
   const payload = await readFile(filePath);
   let prompt: string;
   try {
     prompt = new TextDecoder("utf-8", { fatal: true }).decode(payload);
   } catch {
-    throw new Error("The gisting prompt file must contain valid UTF-8 text.");
+    throw new TolokaCliError("The gisting prompt file must contain valid UTF-8 text.", {
+      hint: { description: "Save the prompt file as UTF-8 text." },
+    });
   }
-  assert(prompt.trim().length > 0, "The gisting prompt file is empty.");
+  assertCli(prompt.trim().length > 0, "The gisting prompt file is empty.", {
+    hint: { description: "Put the full prompt text into the file before creating the Training." },
+  });
   const started = await client.files.startUpload({
     projectId,
     filename: basename(filePath),
@@ -283,7 +324,9 @@ const uploadPromptFile = async (
       headers: { "x-ms-blob-type": "BlockBlob", "Content-Type": "text/plain; charset=utf-8" },
       body: payload,
     });
-    assert(response.ok, `Failed to upload gisting prompt: HTTP ${response.status}.`);
+    assertCli(response.ok, `Failed to upload gisting prompt: HTTP ${response.status}.`, {
+      hint: RETRY_OR_REPORT_HINT,
+    });
     return (await client.files.finalizeUpload({ projectId, fileId: started.file.id })).id;
   } catch (error) {
     await client.files.delete({ projectId, fileId: started.file.id }).catch(() => undefined);
@@ -301,7 +344,9 @@ const resolveSelections = async ({
   options: TrainingDraftOptions;
 }): Promise<ResolvedSelections> => {
   const trainingDatasetId = options.datasetId ?? current?.training.datasetId;
-  assert(trainingDatasetId, "--dataset is required.");
+  assertCli(trainingDatasetId, "--dataset is required.", {
+    hint: { description: "Pass --dataset <dataset-id>; toloka dataset list shows the ids." },
+  });
   const training =
     options.datasetId === undefined && options.trainingFilter === undefined && current
       ? current.training
@@ -317,6 +362,14 @@ const resolveSelections = async ({
   return { training, validation };
 };
 
+const sharedHyperparameters = (options: TrainingDraftOptions) => ({
+  ...(options.learningRate === undefined ? {} : { learningRate: options.learningRate }),
+  ...(options.batchSize === undefined ? {} : { batchSize: options.batchSize }),
+  ...(options.maxSequenceLength === undefined
+    ? {}
+    : { maxSequenceLength: options.maxSequenceLength }),
+});
+
 const buildSftConfiguration = ({
   source,
   selections,
@@ -328,15 +381,28 @@ const buildSftConfiguration = ({
   current: SftConfigurationInput | undefined;
   options: TrainingDraftOptions;
 }): SftConfigurationInput => {
-  assert(options.promptFilePath === undefined, "Gisting options cannot be used with SFT.");
+  assertCli(options.promptFilePath === undefined, "--prompt-file applies to gisting only.", {
+    hint: {
+      description: "Pass --method gisting to use --prompt-file, or omit --prompt-file for SFT.",
+    },
+  });
+  assertCli(
+    options.gistTokens === undefined,
+    "--gist-tokens applies to gisting; SFT takes --lora-rank.",
+    {
+      hint: {
+        description: "Use --lora-rank for SFT, or pass --method gisting to use --gist-tokens.",
+      },
+    },
+  );
   return {
     ...current,
     method: "sft",
     source,
     ...selections,
-    ...(options.regime === undefined ? {} : { regime: options.regime }),
+    ...(options.loraRank === undefined ? {} : { loraRank: options.loraRank }),
     ...(options.epochs === undefined ? {} : { epochs: options.epochs }),
-    ...(options.evalSteps === undefined ? {} : { evalSteps: options.evalSteps }),
+    ...sharedHyperparameters(options),
   };
 };
 
@@ -355,7 +421,15 @@ const buildGistingConfiguration = async ({
   current: GistingConfigurationInput | undefined;
   options: TrainingDraftOptions;
 }): Promise<GistingConfigurationInput> => {
-  assert(options.evalSteps === undefined, "SFT options cannot be used with gisting.");
+  assertCli(
+    options.loraRank === undefined,
+    "--lora-rank applies to SFT; gisting takes --gist-tokens.",
+    {
+      hint: {
+        description: "Use --gist-tokens for gisting, or omit --method gisting to create SFT.",
+      },
+    },
+  );
   const promptFileId = options.promptFilePath
     ? await uploadPromptFile(
         client,
@@ -364,15 +438,18 @@ const buildGistingConfiguration = async ({
         options.fetch ?? globalThis.fetch,
       )
     : current?.promptFileId;
-  assert(promptFileId, "--prompt-file is required for gisting.");
+  assertCli(promptFileId, "--prompt-file is required for gisting.", {
+    hint: { description: "Pass --prompt-file <absolute-path> with the prompt text." },
+  });
   return {
     ...current,
     method: "gisting",
     source,
     ...selections,
     promptFileId,
-    ...(options.regime === undefined ? {} : { regime: options.regime }),
+    ...(options.gistTokens === undefined ? {} : { gistTokens: options.gistTokens }),
     ...(options.epochs === undefined ? {} : { epochs: options.epochs }),
+    ...sharedHyperparameters(options),
   };
 };
 
@@ -453,10 +530,13 @@ export const createTraining = async (
   },
   io: TrainingIo,
 ): Promise<void> => {
-  assert(input.datasetId, "--dataset is required.");
-  assert(
+  assertCli(input.datasetId, "--dataset is required.", {
+    hint: { description: "Pass --dataset <dataset-id>; toloka dataset list shows the ids." },
+  });
+  assertCli(
     !input.validationFilter || input.validationDatasetId,
     "--validation-filter requires --validation-dataset.",
+    { hint: { disabled: true } },
   );
 
   const configuration = await buildTrainingConfiguration({
@@ -526,6 +606,9 @@ export const estimateTrainingCost = async (
   io: TrainingIo,
 ): Promise<void> => {
   const { estimate } = await prepareTrainingCostEstimate(client, input);
+  assertCli(estimate.status === "ready", formatCostEstimate(estimate), {
+    hint: { description: "Fix the blocked issues above, then run toloka training cost again." },
+  });
   writeOutput(io, input.json, estimate, formatCostEstimate(estimate));
 };
 
@@ -549,10 +632,19 @@ export const createTrainingRun = async (
           projectId: input.projectId,
           nameOrId: input.nameOrId,
         });
-        assert(prepared.estimate.status === "ready", formatCostEstimate(prepared.estimate));
+        assertCli(prepared.estimate.status === "ready", formatCostEstimate(prepared.estimate), {
+          hint: {
+            description: "Fix the blocked issues above, then run toloka training cost again.",
+          },
+        });
         return parseReadyEstimateFile(prepared.estimate);
       })();
-  assert(estimate.trainingId === training.id, "The estimate file belongs to another Training.");
+  assertCli(estimate.trainingId === training.id, "The estimate file belongs to another Training.", {
+    hint: {
+      description:
+        "Run toloka training cost <training> --json > <file> for this Training, get its maximumCharge approved, then re-run with that file.",
+    },
+  });
   const run = await client.trainings.createRun({
     trainingId: training.id,
     inputSetId: estimate.inputSetId,
@@ -657,8 +749,10 @@ const formatMetricValue = (point: {
 };
 
 const METRICS_UNAVAILABLE: Record<"not_configured" | "unresolved", string> = {
-  not_configured: "This Training Run has no metrics: it started before metrics were available, or the server records none.",
-  unresolved: "Metrics are temporarily unreachable. The Training Run itself is unaffected; try again later.",
+  not_configured:
+    "This Training Run has no metrics: it started before metrics were available, or the server records none.",
+  unresolved:
+    "Metrics are temporarily unreachable. The Training Run itself is unaffected; try again later.",
 };
 
 const formatTrainingRunMetrics = (metrics: TrainingRunMetrics): string => {

package/src/cli/version.ts

@@ -2,8 +2,8 @@ import { realpathSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join, resolve, sep } from "node:path";
 
-import { assert } from "es-toolkit";
 import { SDK_VERSION } from "./sdk-version";
+import { assertCli, REPORT_HINT } from "./cli-error";
 
 export type CliInstallChannel = "global-registry" | "linked" | "project-local";
 
@@ -36,7 +36,7 @@ const classifyInstallChannel = (
 };
 
 export const cliVersionInfo = (entryPath = process.argv[1], options: VersionInfoOptions = {}) => {
-  assert(entryPath, "CLI entry path is unavailable");
+  assertCli(entryPath, "CLI entry path is unavailable", { hint: REPORT_HINT });
   const globalBinDirectory =
     options.globalBinDirectory ??
     resolve(process.env.BUN_INSTALL ?? join(homedir(), ".bun"), "bin");

package/src/client.ts

@@ -228,12 +228,6 @@ export type WaitForTarget =
 const createClientImplementation = (config: ClientConfig) => {
   const requestOptions = createRequestOptions(config.baseUrl, config.apiKey, config.fetch);
 
-  const emptyJsonRequestOptions = (): RequestInit => {
-    const headers = new Headers(requestOptions.headers);
-    headers.set("Content-Type", "application/json");
-    return { ...requestOptions, headers, body: "{}" };
-  };
-
   function waitFor(
     target: DatasetUploadWaitTarget,
     options?: WaitForOptions,
@@ -564,9 +558,9 @@ const createClientImplementation = (config: ClientConfig) => {
     startUpload: ({ datasetId, ...body }: { datasetId: DatasetId } & CreateDatasetUploadBody) =>
       wire.createDatasetUpload(datasetId, body, requestOptions),
     finalizeUpload: ({ uploadId }: { uploadId: UploadId }) =>
-      wire.finalizeDatasetUpload(uploadId, emptyJsonRequestOptions()),
+      wire.finalizeDatasetUpload(uploadId, requestOptions),
     cancelUpload: ({ uploadId }: { uploadId: UploadId }) =>
-      wire.cancelDatasetUpload(uploadId, emptyJsonRequestOptions()),
+      wire.cancelDatasetUpload(uploadId, requestOptions),
     getUpload: ({ uploadId }: { uploadId: UploadId }) =>
       wire.getDatasetUpload(uploadId, requestOptions),
     startExport: ({ datasetId, ...body }: { datasetId: DatasetId } & CreateDatasetExportBody) =>
@@ -577,7 +571,7 @@ const createClientImplementation = (config: ClientConfig) => {
 
   const runs = {
     start: ({ pipelineId }: { pipelineId: PipelineId }) =>
-      wire.createPipelineRun(pipelineId, emptyJsonRequestOptions()),
+      wire.createPipelineRun(pipelineId, requestOptions),
     get: ({ runId }: { runId: RunId }) => wire.getPipelineRun(runId, requestOptions),
     cancel: ({ runId }: { runId: RunId }) => wire.cancelPipelineRun(runId, requestOptions),
     listPage: ({ pipelineId, ...params }: { pipelineId: PipelineId } & ListPipelineRunsParams) =>

package/src/transport.ts

@@ -25,6 +25,15 @@ export const createRequestOptions = (
   };
 };
 
+const prepareRequestInit = (requestOptions: RequestInit, headers: Headers): RequestInit => {
+  const method = (requestOptions.method ?? "GET").toUpperCase();
+  if (method === "GET" || method === "HEAD" || requestOptions.body !== undefined) {
+    return { ...requestOptions, headers };
+  }
+  headers.set("Content-Type", "application/json");
+  return { ...requestOptions, headers, body: "{}" };
+};
+
 export function potatoFetch<T>(url: string, options: TransportRequestInit): Promise<T>;
 export async function potatoFetch(url: string, options: TransportRequestInit): Promise<unknown> {
   const { fetch: fetchImplementation = globalThis.fetch, ...requestOptions } = options;
@@ -33,7 +42,10 @@ export async function potatoFetch(url: string, options: TransportRequestInit): P
   assert(baseUrl, "The SDK base URL is missing");
   headers.delete(BASE_URL_HEADER);
 
-  const response = await fetchImplementation(new URL(url, baseUrl), { ...requestOptions, headers });
+  const response = await fetchImplementation(
+    new URL(url, baseUrl),
+    prepareRequestInit(requestOptions, headers),
+  );
   const text = await response.text();
 
   if (!response.ok) {

package/openapi/gen/models/gistingTrainingConfigurationInputRegime.ts

@@ -1,2 +0,0 @@
-
-export type GistingTrainingConfigurationInputRegime = 'low' | 'medium' | 'high';

package/openapi/gen/models/gistingTrainingConfigurationRegime.ts

@@ -1,2 +0,0 @@
-
-export type GistingTrainingConfigurationRegime = 'low' | 'medium' | 'high';

package/openapi/gen/models/sftTrainingConfigurationInputRegime.ts

@@ -1,2 +0,0 @@
-
-export type SftTrainingConfigurationInputRegime = 'low' | 'medium' | 'high';

package/openapi/gen/models/sftTrainingConfigurationRegime.ts

@@ -1,2 +0,0 @@
-
-export type SftTrainingConfigurationRegime = 'low' | 'medium' | 'high';