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

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));