@toloka-platform/sdk 0.1.0-preview.9 → 0.2.0-preview.1

package/src/cli/check.ts

@@ -114,6 +114,18 @@ export type CheckProjectResult = {
   readonly source?: ProjectSource;
   readonly output: string;
 };
+
+export type FreshCheckFailurePhase = "spawn" | "execute" | "read_result" | "parse_result";
+
+export class FreshCheckProcessError extends Error {
+  readonly phase: FreshCheckFailurePhase;
+
+  constructor(phase: FreshCheckFailurePhase, message: string, options?: ErrorOptions) {
+    super(message, options);
+    this.name = "FreshCheckProcessError";
+    this.phase = phase;
+  }
+}
 const MAX_DIAGNOSTIC_CHARS = 5_000;
 const MAX_TOOL_OUTPUT_BYTES = 64 * 1024;
 export const CHECK_RESULT_FILE_ENV = "TOLOKA_INTERNAL_CHECK_RESULT_FILE";
@@ -865,44 +877,93 @@ const parseFreshCheckResult = (value: unknown, json: boolean): CheckProjectResul
     output: json ? JSON.stringify({ exitCode, results }) : formatCheckResults(results),
   };
 };
+
+const checkProcessOutput = (run: ToolRunResult): string =>
+  [run.stderr, run.stdout].filter(Boolean).join("\n");
+
+export const readFreshCheckResult = async (
+  run: ToolRunResult,
+  readResult: () => Promise<string>,
+  json = false,
+): Promise<CheckProjectResult> => {
+  let raw: string;
+  try {
+    raw = await readResult();
+  } catch (error) {
+    if (run.exitCode !== 0) {
+      const output = checkProcessOutput(run);
+      throw new FreshCheckProcessError(
+        "execute",
+        output.length === 0
+          ? `Local check process exited ${run.exitCode} before producing results`
+          : `Local check process failed before producing results:\n${output}`,
+        { cause: error },
+      );
+    }
+    throw new FreshCheckProcessError(
+      "read_result",
+      "Local check process completed without producing a result file",
+      { cause: error },
+    );
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (error) {
+    throw new FreshCheckProcessError("parse_result", "Local check process returned invalid JSON", {
+      cause: error,
+    });
+  }
+
+  try {
+    return parseFreshCheckResult(parsed, json);
+  } catch (error) {
+    throw new FreshCheckProcessError(
+      "parse_result",
+      `Local check process returned an invalid result: ${error instanceof Error ? error.message : String(error)}`,
+      { cause: error },
+    );
+  }
+};
 export const runFreshCheck = async (options: CheckProjectOptions): Promise<CheckProjectResult> => {
   const entry = resolveCliEntry();
   const resultDirectory = await mkdtemp(join(tmpdir(), "toloka-check-watch-result-"));
   const resultPath = join(resultDirectory, "result.json");
-  let run: ToolRunResult | undefined;
   try {
-    run = await runModule(
-      options.sourceRoot,
-      entry,
-      [
-        "--source-root",
+    let run: ToolRunResult;
+    try {
+      run = await runModule(
         options.sourceRoot,
-        "check",
-        ...(options.pipeline === undefined ? [] : [options.pipeline]),
-        ...(options.node === undefined ? [] : ["--node", options.node]),
-        "--json",
-      ],
-      {
-        ...(process.env.PATH === undefined ? {} : { PATH: process.env.PATH }),
-        ...(options.environment ?? process.env),
-        [CHECK_RESULT_FILE_ENV]: resultPath,
-      },
-      options.signal,
-      "bun",
-    );
-    return parseFreshCheckResult(
-      JSON.parse(await readFile(resultPath, "utf8")),
+        entry,
+        [
+          "--source-root",
+          options.sourceRoot,
+          "check",
+          ...(options.pipeline === undefined ? [] : [options.pipeline]),
+          ...(options.node === undefined ? [] : ["--node", options.node]),
+          "--json",
+        ],
+        {
+          ...(process.env.PATH === undefined ? {} : { PATH: process.env.PATH }),
+          ...(options.environment ?? process.env),
+          [CHECK_RESULT_FILE_ENV]: resultPath,
+        },
+        options.signal,
+        "bun",
+      );
+    } catch (error) {
+      throw new FreshCheckProcessError(
+        "spawn",
+        `Unable to start the local check process: ${error instanceof Error ? error.message : String(error)}`,
+        { cause: error },
+      );
+    }
+    return await readFreshCheckResult(
+      run,
+      async () => readFile(resultPath, "utf8"),
       options.json === true,
     );
-  } catch (error) {
-    const detail = [
-      run?.stderr,
-      run?.stdout,
-      error instanceof Error ? error.message : String(error),
-    ]
-      .filter(Boolean)
-      .join("\n");
-    throw new Error(`Fresh check process returned unreadable output: ${detail}`, { cause: error });
   } finally {
     await rm(resultDirectory, { recursive: true, force: true });
   }

package/src/cli/cost.ts

@@ -80,9 +80,15 @@ const collectNodeRows = (
 };
 
 const collectTotalRows = (total: PipelineCostEstimate["total"]): TableRow[] => {
-  const totals: TableRow[] = [["Total", total.expected, total.worstCase]];
+  const totals: TableRow[] =
+    total.expected === total.worstCase
+      ? [["Run cost", total.expected, ""]]
+      : [
+          ["Expected run cost", total.expected, ""],
+          ["Maximum run cost", "", total.worstCase],
+        ];
   if (total.bestCase != null) {
-    totals.push(["Best case", total.bestCase, ""]);
+    totals.push(["Best case", total.bestCase, "N/A"]);
   }
   if (total.perItemExpected != null) {
     totals.push(["Per item", total.perItemExpected, total.perItemWorstCase ?? ""]);

package/src/cli/models.ts

@@ -1,3 +1,10 @@
+import { createHash, randomUUID } from "node:crypto";
+import { constants } from "node:fs";
+import { mkdir, open, realpath, rename, rm } from "node:fs/promises";
+import { isAbsolute, relative, resolve, sep } from "node:path";
+import { Readable, Transform } from "node:stream";
+import { pipeline } from "node:stream/promises";
+
 import { assert } from "es-toolkit";
 
 import type { BaseModel, BaseModelId, Model, ModelVersion, PotatoClient } from "../client";
@@ -73,6 +80,29 @@ const resolveModel = async (
   return matches[0]!;
 };
 
+const resolveModelVersion = async (
+  client: ModelApi,
+  projectId: string | undefined,
+  nameOrId: string,
+): Promise<ModelVersion> => {
+  if (nameOrId.startsWith("mdv.")) return client.models.getVersion({ modelVersionId: nameOrId });
+  const separator = nameOrId.lastIndexOf("@");
+  assert(separator > 0, `Model Version ${nameOrId} was not found. Use mdv.<id> or Model@name.`);
+  assert(projectId, "Select a project to resolve Model Version names.");
+  const model = await resolveModel(client, projectId, nameOrId.slice(0, separator));
+  const versionName = nameOrId.slice(separator + 1);
+  const matches: ModelVersion[] = [];
+  for await (const version of client.models.listAllVersions({
+    projectId,
+    modelId: model.id,
+    limit: 100,
+  })) {
+    if (version.name === versionName) matches.push(version);
+  }
+  assert(matches.length === 1, `Model Version ${nameOrId} was not found or is ambiguous.`);
+  return matches[0]!;
+};
+
 export const listBaseModels = async (
   client: ModelApi,
   input: { json: boolean },
@@ -155,8 +185,13 @@ export const listModelVersions = async (
     versions.length === 0
       ? "No Model Versions found."
       : formatTable([
-          ["VERSION", "ID", "CREATED AT"],
-          ...versions.map((version) => [version.version, version.id, version.createdAt]),
+          ["REVISION", "NAME", "ID", "CREATED AT"],
+          ...versions.map((version) => [
+            String(version.revision),
+            version.name,
+            version.id,
+            version.createdAt,
+          ]),
         ]),
   );
 };
@@ -186,3 +221,73 @@ export const archiveModel = async (
   const archived = await client.models.archive({ projectId: input.projectId, modelId: model.id });
   writeOutput(io, input.json, archived, `Archived Model ${archived.id}.`);
 };
+
+export const downloadModelVersion = async (
+  client: ModelApi,
+  input: { projectId?: string; modelVersionId: string; out: string },
+  io: ModelIo,
+): Promise<void> => {
+  const version = await resolveModelVersion(client, input.projectId, input.modelVersionId);
+  const descriptor = await client.models.getVersionContent({
+    modelVersionId: version.id,
+  });
+  const root = resolve(input.out);
+  await mkdir(root, { recursive: true });
+  const realRoot = await realpath(root);
+
+  for (const file of descriptor.files) {
+    const target = resolve(root, file.path);
+    const relativeTarget = relative(root, target);
+    assert(
+      relativeTarget !== "" &&
+        relativeTarget !== ".." &&
+        !relativeTarget.startsWith(`..${sep}`) &&
+        !isAbsolute(relativeTarget),
+      `Invalid Model Version file path: ${file.path}`,
+    );
+    let parent = root;
+    for (const segment of file.path.split("/").slice(0, -1)) {
+      parent = resolve(parent, segment);
+      await mkdir(parent, { recursive: true });
+      const realParent = await realpath(parent);
+      assert(
+        realParent === realRoot || realParent.startsWith(`${realRoot}${sep}`),
+        `Invalid Model Version file path: ${file.path}`,
+      );
+    }
+    const response = await fetch(file.url, { redirect: "error" });
+    assert(response.ok && response.body, `Failed to download Model Version file ${file.path}.`);
+    const hash = createHash("sha256");
+    let byteSize = 0;
+    const verify = new Transform({
+      transform(chunk: Buffer, _encoding, callback) {
+        byteSize += chunk.byteLength;
+        hash.update(chunk);
+        callback(null, chunk);
+      },
+    });
+    const temporary = `${target}.${randomUUID()}.tmp`;
+    try {
+      const handle = await open(
+        temporary,
+        constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY | constants.O_NOFOLLOW,
+        0o600,
+      );
+      await pipeline(Readable.from(response.body), verify, handle.createWriteStream());
+      assert(
+        byteSize === file.byteSize,
+        `Downloaded Model Version file ${file.path} has an unexpected size.`,
+      );
+      assert(
+        hash.digest("hex") === file.sha256,
+        `Downloaded Model Version file ${file.path} has an invalid hash.`,
+      );
+      await rename(temporary, target);
+    } catch (error) {
+      await rm(temporary, { force: true });
+      throw error;
+    }
+  }
+
+  io.stdout(`Downloaded Model Version ${descriptor.id} revision ${descriptor.revision} to ${root}`);
+};

package/src/cli/program.ts

@@ -48,6 +48,7 @@ import {
 import {
   archiveModel,
   createModel,
+  downloadModelVersion,
   getBaseModel,
   getModel,
   listBaseModels,
@@ -64,6 +65,7 @@ import {
   removeProject,
   resolveProjectContext,
   switchProject,
+  untrackProjectResource,
 } from "./project-context";
 import { estimatePipelineCost } from "./cost";
 import { submitIssueReport } from "./report";
@@ -78,9 +80,24 @@ import {
   pipelineRunStatus,
   startPipelineRun,
 } from "./runs";
+import {
+  cancelTrainingRun,
+  createTraining,
+  createTrainingRun,
+  estimateTrainingCost,
+  getTraining,
+  getTrainingRun,
+  readTrainingRunLogs,
+  listTrainingRuns,
+  resumeTrainingRun,
+  listTrainings,
+  updateTraining,
+} from "./trainings";
+import type { TrainingDraftOptions } from "./trainings";
 
 import type { RunOutcome } from "./runs";
 import { skillInstallCommand, skillListCommand, skillSearchCommand } from "./skill";
+import { cliVersionInfo } from "./version";
 import { findSourceRoot } from "./source";
 
 export type CliIo = {
@@ -127,6 +144,55 @@ const positiveInteger = (raw: string): number => {
   return value;
 };
 
+const nonNegativeInteger = (raw: string): number => {
+  const value = Number(raw);
+  if (!Number.isInteger(value) || value < 0)
+    throw new InvalidArgumentError("Expected a non-negative integer.");
+  return value;
+};
+
+const trainingMethod = (raw: string): "sft" | "gisting" => {
+  if (raw !== "sft" && raw !== "gisting") {
+    throw new InvalidArgumentError('Expected training method "sft" or "gisting".');
+  }
+  return raw;
+};
+
+const trainingRegime = (raw: string): "low" | "medium" | "high" => {
+  if (raw !== "low" && raw !== "medium" && raw !== "high") {
+    throw new InvalidArgumentError('Expected regime "low", "medium", or "high".');
+  }
+  return raw;
+};
+
+type RawTrainingDraftOptions = {
+  method?: TrainingDraftOptions["method"];
+  baseModel?: TrainingDraftOptions["baseModelId"];
+  modelVersion?: string;
+  dataset?: string;
+  validationDataset?: string;
+  trainFilter?: string;
+  validationFilter?: string;
+  regime?: TrainingDraftOptions["regime"];
+  epochs?: number;
+  evalSteps?: number;
+  promptFile?: string;
+};
+
+const trainingDraftOptions = (options: RawTrainingDraftOptions): TrainingDraftOptions => ({
+  method: options.method,
+  baseModelId: options.baseModel,
+  modelVersionId: options.modelVersion,
+  datasetId: options.dataset,
+  validationDatasetId: options.validationDataset,
+  trainingFilter: options.trainFilter,
+  validationFilter: options.validationFilter,
+  regime: options.regime,
+  epochs: options.epochs,
+  evalSteps: options.evalSteps,
+  promptFilePath: options.promptFile,
+});
+
 const exitCodeForOutcome = (outcome: RunOutcome): number => {
   if (outcome === "failed") return 1;
   if (outcome === "timedOut") return 2;
@@ -242,7 +308,7 @@ export function createProgram(context: ProgramContext): CreatedProgram {
 
   program
     .description(
-      "Preview. Build and operate Toloka pipeline projects from TypeScript source. The public API may change.",
+      "Beta. Build and operate Toloka pipeline projects from TypeScript source. The public API may change before general availability.",
     )
     .version(SDK_VERSION, "-v, --version", "output the current version")
     .option(
@@ -282,10 +348,14 @@ export function createProgram(context: ProgramContext): CreatedProgram {
     warnedAboutStaleSkills = true;
     context.io.stderr(warning);
   });
+
   program
     .command("version")
+    .option("--json", "print version and build provenance as JSON", false)
     .description("print the current CLI version")
-    .action(() => context.io.stdout(SDK_VERSION));
+    .action((options: { json: boolean }) =>
+      context.io.stdout(options.json ? JSON.stringify(cliVersionInfo()) : SDK_VERSION),
+    );
 
   const config = program.command("config").description("read and write machine CLI settings");
   config
@@ -472,6 +542,26 @@ export function createProgram(context: ProgramContext): CreatedProgram {
         io: context.io,
       });
     });
+  project
+    .command("untrack")
+    .argument("<type>", "pipeline or dataset")
+    .argument("<name>", "tracked resource name")
+    .option("--confirm", "confirm untracking in a non-interactive environment", false)
+    .description("remove a pipeline or dataset from local tracking without deleting it")
+    .action(async (type: string, name: string, options: { confirm: boolean }) => {
+      assert(
+        type === "pipeline" || type === "dataset",
+        "Resource type must be pipeline or dataset.",
+      );
+      const sourceRoot = await resolveSourceRoot(globals(), context.io);
+      await untrackProjectResource({
+        sourceRoot,
+        type,
+        name,
+        confirm: options.confirm,
+        io: context.io,
+      });
+    });
   project
     .command("create")
     .argument("[alias]", "local name for the new project")
@@ -772,6 +862,185 @@ export function createProgram(context: ProgramContext): CreatedProgram {
       await archiveModel(client, { projectId, nameOrId, json: options.json }, context.io);
     });
 
+  const modelVersion = model.command("version").description("manage one immutable Model Version");
+  modelVersion
+    .command("download")
+    .argument("<model-version>", "Model Version ID or Model@name")
+    .requiredOption("--out <directory>", "output directory")
+    .description("download and verify Model Version content")
+    .action(async (modelVersionId: string, options: { out: string }) => {
+      const { client, projectId } = await resolveContext(globals(), context);
+      await downloadModelVersion(
+        client,
+        { projectId, modelVersionId, out: options.out },
+        context.io,
+      );
+    });
+
+  const training = program.command("training").description("manage project Training drafts");
+  training
+    .command("list")
+    .option("--json", "print JSON", false)
+    .description("list active Trainings owned by the selected project")
+    .action(async (options: { json: boolean }) => {
+      const { client, projectId } = await resolveContext(globals(), context);
+      assert(projectId, MISSING_PROJECT_ID_MESSAGE);
+      await listTrainings(client, { projectId, json: options.json }, context.io);
+    });
+  training
+    .command("get")
+    .argument("<name-or-id>", "Training name or ID")
+    .option("--json", "print JSON", false)
+    .description("show one Training draft")
+    .action(async (nameOrId: string, options: { json: boolean }) => {
+      const { client, projectId } = await resolveContext(globals(), context);
+      assert(projectId, MISSING_PROJECT_ID_MESSAGE);
+      await getTraining(client, { projectId, nameOrId, json: options.json }, context.io);
+    });
+  training
+    .command("create")
+    .argument("<name>", "new Training name")
+    .option("--method <method>", "Training method", trainingMethod, "sft")
+    .option("--base-model <id>", "catalog Base Model source", parseBaseModelId)
+    .option("--model-version <id>", "exact Model Version source")
+    .requiredOption("--dataset <id>", "required training Dataset ID")
+    .option("--validation-dataset <id>", "optional validation Dataset ID")
+    .option("--train-filter <field=value>", "training Dataset field equality filter")
+    .option("--validation-filter <field=value>", "validation Dataset field equality filter")
+    .option("--regime <regime>", "Python training regime", trainingRegime)
+    .option("--epochs <count>", "training epochs", nonNegativeInteger)
+    .option("--eval-steps <count>", "SFT eval steps", positiveInteger)
+    .option("--prompt-file <path>", "gisting prompt text file")
+    .option("--json", "print JSON", false)
+    .description("create a normalized Training draft")
+    .action(async (name: string, options: RawTrainingDraftOptions & { json: boolean }) => {
+      const { client, projectId } = await resolveContext(globals(), context);
+      assert(projectId, MISSING_PROJECT_ID_MESSAGE);
+      await createTraining(
+        client,
+        {
+          ...trainingDraftOptions(options),
+          projectId,
+          name,
+          json: options.json,
+        },
+        context.io,
+      );
+    });
+  training
+    .command("update")
+    .argument("<name-or-id>", "Training name or ID")
+    .option("--base-model <id>", "catalog Base Model source", parseBaseModelId)
+    .option("--model-version <id>", "exact Model Version source")
+    .option("--dataset <id>", "required training Dataset ID")
+    .option("--validation-dataset <id>", "replacement validation Dataset ID")
+    .option("--train-filter <field=value>", "replacement training Dataset field equality filter")
+    .option("--validation-filter <field=value>", "replacement validation Dataset field equality filter")
+    .option("--regime <regime>", "Python training regime", trainingRegime)
+    .option("--epochs <count>", "training epochs", nonNegativeInteger)
+    .option("--eval-steps <count>", "SFT eval steps", positiveInteger)
+    .option("--prompt-file <path>", "replacement gisting prompt text file")
+    .option("--json", "print JSON", false)
+    .description("replace the complete Training draft")
+    .action(async (nameOrId: string, options: RawTrainingDraftOptions & { json: boolean }) => {
+      const { client, projectId } = await resolveContext(globals(), context);
+      assert(projectId, MISSING_PROJECT_ID_MESSAGE);
+      await updateTraining(
+        client,
+        {
+          ...trainingDraftOptions(options),
+          projectId,
+          nameOrId,
+          json: options.json,
+        },
+        context.io,
+      );
+    });
+  training
+    .command("cost")
+    .argument("<name-or-id>", "Training name or ID")
+    .option("--idempotency-key <key>", "reuse one Cost Estimate input preparation")
+    .option("--json", "print JSON", false)
+    .description("validate Training inputs and calculate the maximum charge")
+    .action(async (nameOrId: string, options: { idempotencyKey?: string; json: boolean }) => {
+      const { client, projectId } = await resolveContext(globals(), context);
+      assert(projectId, MISSING_PROJECT_ID_MESSAGE);
+      await estimateTrainingCost(
+        client,
+        { projectId, nameOrId, idempotencyKey: options.idempotencyKey, json: options.json },
+        context.io,
+      );
+    });
+  training
+    .command("run")
+    .argument("<name-or-id>", "Training name or ID")
+    .requiredOption("--estimate-file <path>", "ready Training Cost Estimate JSON")
+    .requiredOption("--version-name <name>", "unique Model Version name for this run")
+    .option("--idempotency-key <key>", "reuse one Training Run creation")
+    .option("--json", "print JSON", false)
+    .description("create one queued Training Run from a ready Cost Estimate")
+    .action(
+      async (
+        nameOrId: string,
+        options: {
+          estimateFile: string;
+          versionName: string;
+          idempotencyKey?: string;
+          json: boolean;
+        },
+      ) => {
+        const { client, projectId } = await resolveContext(globals(), context);
+        assert(projectId, MISSING_PROJECT_ID_MESSAGE);
+        await createTrainingRun(client, { projectId, nameOrId, ...options }, context.io);
+      },
+    );
+  training
+    .command("runs")
+    .argument("<name-or-id>", "Training name or ID")
+    .option("--json", "print JSON", false)
+    .description("list Training Run history")
+    .action(async (nameOrId: string, options: { json: boolean }) => {
+      const { client, projectId } = await resolveContext(globals(), context);
+      assert(projectId, MISSING_PROJECT_ID_MESSAGE);
+      await listTrainingRuns(client, { projectId, nameOrId, json: options.json }, context.io);
+    });
+  training
+    .command("status")
+    .argument("<training-run-id>", "Training Run ID")
+    .option("--json", "print JSON", false)
+    .description("show one Training Run")
+    .action(async (trainingRunId: string, options: { json: boolean }) => {
+      const { client } = await resolveContext(globals(), context);
+      await getTrainingRun(client, { trainingRunId, json: options.json }, context.io);
+    });
+  training
+    .command("resume")
+    .argument("<training-run-id>", "Training Run ID")
+    .option("--json", "print JSON", false)
+    .description("resume a Training Run blocked on funds or payment")
+    .action(async (trainingRunId: string, options: { json: boolean }) => {
+      const { client } = await resolveContext(globals(), context);
+      await resumeTrainingRun(client, { trainingRunId, json: options.json }, context.io);
+    });
+  training
+    .command("cancel")
+    .argument("<training-run-id>", "Training Run ID")
+    .option("--json", "print JSON", false)
+    .description("cancel a Training Run before provider work completes")
+    .action(async (trainingRunId: string, options: { json: boolean }) => {
+      const { client } = await resolveContext(globals(), context);
+      await cancelTrainingRun(client, { trainingRunId, json: options.json }, context.io);
+    });
+  training
+    .command("logs")
+    .argument("<training-run-id>", "Training Run ID")
+    .option("--follow", "wait for new log entries until complete", false)
+    .description("read sanitized Training Run logs")
+    .action(async (trainingRunId: string, options: { follow: boolean }) => {
+      const { client } = await resolveContext(globals(), context);
+      await readTrainingRunLogs(client, { trainingRunId, follow: options.follow }, context.io);
+    });
+
   const dataset = program
     .command("dataset")
     .description("inspect and move dataset catalog and rows");