@toloka-platform/sdk 0.1.0 → 0.2.0-preview.2

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,
@@ -79,6 +80,20 @@ 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";
@@ -129,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;
@@ -798,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");

package/src/cli/project-context.ts

@@ -35,10 +35,10 @@ export type ProjectCreateApi = {
 };
 
 export const MISSING_PROJECT_ID_MESSAGE =
-  "Missing project ID. Pass --project-id, set TOLOKA_PROJECT_ID, set projectId in toloka.json, or run toloka project add.";
+  "Missing project ID. Pass --project-id, set TOLOKA_PROJECT_ID, use a bound toloka.json, run toloka project create for a new project, or run toloka project add for an existing project.";
 
 export const NO_PROJECT_SELECTED_MESSAGE =
-  "No project selected. Run toloka project add, or cd into a checkout.";
+  "No project selected. Run toloka project create for a new project, toloka project add for an existing project, or cd into a checkout.";
 
 const NETWORK_MISMATCH_MESSAGE =
   "project add writes the machine registry; unset --api-key / --base-url / POTATO_API_KEY / POTATO_BASE_URL, or run login against that platform first.";
@@ -168,7 +168,8 @@ export const formatProjectContextLine = (
   project: ProjectContext | undefined,
   stored?: StoredCredentials,
 ): string => {
-  if (project === undefined) return "Project:  (none). Run toloka project add.";
+  if (project === undefined)
+    return "Project:  (none). Run toloka project create or toloka project add.";
   const alias = project.alias === undefined ? "" : `alias ${project.alias}, `;
   const registryNote =
     project.source !== "registry" && stored?.current !== undefined
@@ -232,14 +233,12 @@ export async function listRemoteProjects(options: {
 }): Promise<{ readonly output: string }> {
   const limit = options.limit ?? 20;
   const page = await options.client.projects.listPage({ limit });
-  const lines = page.projects.map((project) => {
-    const mark = options.context?.id === project.id ? "*" : " ";
-    const alias =
-      options.context?.id === project.id && options.context.alias !== undefined
-        ? `\t${options.context.alias}`
-        : "";
-    return `${mark}\t${project.id}\t${project.name}\t${project.teamId}${alias}`;
+  const rows = page.projects.map((project) => {
+    const current = options.context?.id === project.id;
+    const alias = current ? (options.context.alias ?? "-") : "-";
+    return `${current ? "*" : "-"}\t${project.id}\t${project.name}\t${alias}`;
   });
+  const lines = rows.length === 0 ? [] : ["CURRENT\tID\tNAME\tALIAS", ...rows];
   if (page.pagination.hasMore) {
     lines.push(
       `Showing ${page.projects.length} of ${page.pagination.total} projects. Raise --limit to see more.`,

package/src/cli/project.ts

@@ -848,10 +848,11 @@ export async function applyProject(
   if (valueKey(inspection.state) !== valueKey(nextState))
     await writeTolokaState(options.sourceRoot, nextState);
   const action = writes === 0 ? "unchanged" : "changed";
+  const plannedChanges = inspection.changes.length;
   const output =
     writes === 0
       ? "No changes."
-      : `Applied ${writes} ${writes === 1 ? "write" : "writes"} to project ${inspection.projectId}.`;
+      : `Applied ${plannedChanges} planned ${plannedChanges === 1 ? "change" : "changes"} with ${writes} platform ${writes === 1 ? "write" : "writes"} to project ${inspection.projectId}.`;
   return {
     action,
     state: nextState,

package/src/cli/secrets.ts

@@ -1,13 +1,13 @@
-import type { PipelineGraphV1 } from '../../openapi/gen/models';
+import type { PipelineGraphV1 } from "../../openapi/gen/models";
 
 export function collectGraphSecretNames(graph: {
-  readonly nodes: ReadonlyArray<PipelineGraphV1['nodes'][number]>;
+  readonly nodes: ReadonlyArray<PipelineGraphV1["nodes"][number]>;
 }): readonly string[] {
   const names = new Set<string>();
   for (const node of graph.nodes) {
-    if (node.type !== 'code') continue;
+    if (node.type !== "code") continue;
     for (const environmentVariable of node.settings.envVars ?? []) {
-      if (environmentVariable.type === 'secret') names.add(environmentVariable.secretName);
+      if (environmentVariable.type === "secret") names.add(environmentVariable.secretName);
     }
   }
   return [...names].toSorted((left, right) => left.localeCompare(right));