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

package/src/cli/commands/source.ts

@@ -0,0 +1,204 @@
+import { writeFile } from "node:fs/promises";
+import type { Command } from "commander";
+import {
+  CHECK_RESULT_FILE_ENV,
+  checkProject,
+  watchProjectChecks,
+  runFreshCheck,
+  type CheckProjectOptions,
+  type CheckProjectResult,
+} from "../check";
+import { resolveContext, resolveInitRoot, resolveSourceRoot, type CommandHost } from "../context";
+import { initProject } from "../init";
+import { applyProject, importProject, planProject, validateProject } from "../project";
+import { assertProjectSelected, resolveProjectContext } from "../project-context";
+import { readTolokaState } from "../../state";
+import { assertCli, REPORT_HINT } from "../cli-error";
+
+const runChecksInterruptibly = async (
+  options: CheckProjectOptions,
+  runner: (options: CheckProjectOptions) => Promise<CheckProjectResult>,
+): Promise<{ result: CheckProjectResult; interruptedExitCode?: number }> => {
+  const abortController = new AbortController();
+  let interruptedExitCode: number | undefined;
+  const interrupt = (code: number) => {
+    interruptedExitCode = code;
+    abortController.abort();
+  };
+  const interruptSigint = () => interrupt(130);
+  const interruptSigterm = () => interrupt(143);
+  process.on("SIGINT", interruptSigint);
+  process.on("SIGTERM", interruptSigterm);
+  try {
+    const result = await runner({ ...options, signal: abortController.signal });
+    return { result, ...(interruptedExitCode === undefined ? {} : { interruptedExitCode }) };
+  } finally {
+    process.off("SIGINT", interruptSigint);
+    process.off("SIGTERM", interruptSigterm);
+  }
+};
+
+export const registerSourceCommands = (program: Command, host: CommandHost): void => {
+  const { context, exitCode, globals } = host;
+  const runChecks = context.runChecks ?? checkProject;
+
+  program
+    .command("init")
+    .description("initialize this project directory and install the agent bootstrap")
+    .action(async () => {
+      const flags = globals();
+      const sourceRoot = resolveInitRoot(flags);
+      const state = await readTolokaState(sourceRoot);
+      const selected = resolveProjectContext({
+        flags,
+        environment: context.environment,
+        ...(state === undefined ? {} : { state }),
+      });
+      const result = await initProject(
+        sourceRoot,
+        selected === undefined ? {} : { projectId: selected.id },
+      );
+      context.io.stdout(result.output);
+      if (result.warning !== undefined) context.io.stderr(result.warning);
+    });
+
+  program
+    .command("import")
+    .argument(
+      "[projectId]",
+      "existing project to write into source; defaults to the selected project",
+    )
+    .option("-f, --force", "replace an existing pipelines/ directory", false)
+    .description("generate TypeScript source from a live project")
+    .action(async (projectId?: string, options?: { force?: boolean }) => {
+      const {
+        sourceRoot,
+        client,
+        projectId: selectedProjectId,
+      } = await resolveContext(globals(), context);
+      const id = projectId ?? selectedProjectId;
+      assertProjectSelected(id);
+      const result = await importProject(client, {
+        sourceRoot,
+        projectId: id,
+        ...(options?.force === true ? { force: true } : {}),
+      });
+      context.io.stdout(result.output);
+    });
+
+  program
+    .command("plan")
+    .description("show what apply would change")
+    .action(async () => {
+      const { sourceRoot, client, projectId } = await resolveContext(globals(), context);
+      const result = await planProject(client, {
+        sourceRoot,
+        ...(projectId === undefined ? {} : { projectId }),
+      });
+      context.io.stdout(result.output);
+    });
+
+  program
+    .command("validate")
+    .description("run platform spec validation and report matching checks")
+    .action(async () => {
+      const { sourceRoot, client, projectId } = await resolveContext(globals(), context);
+      const result = await validateProject(client, {
+        sourceRoot,
+        ...(projectId === undefined ? {} : { projectId }),
+      });
+      context.io.stdout(result.output);
+      if (!result.valid) exitCode.value = 1;
+    });
+
+  program
+    .command("check")
+    .argument("[pipeline]", "pipeline source directory or name")
+    .option("--node <node>", "check one code or human-work node by name or id")
+    .option("--json", "print the structured check report", false)
+    .option("--watch", "rerun checks when project files change", false)
+    .description("run the complete local source, type, and test gate")
+    .action(
+      async (
+        pipeline: string | undefined,
+        options: { node?: string; json: boolean; watch: boolean },
+      ) => {
+        const sourceRoot = await resolveSourceRoot(globals(), context.io);
+        const checkOptions = {
+          environment: context.environment,
+          sourceRoot,
+          ...(pipeline === undefined ? {} : { pipeline }),
+          ...(options.node === undefined ? {} : { node: options.node }),
+          ...(options.json ? { json: true } : {}),
+        };
+        const writeCheckOutput = async (output: string): Promise<void> => {
+          const resultPath = context.environment[CHECK_RESULT_FILE_ENV];
+          if (resultPath === undefined) context.io.stdout(output);
+          else await writeFile(resultPath, output, "utf8");
+        };
+        const checkRunner =
+          context.runChecks === undefined &&
+          context.environment[CHECK_RESULT_FILE_ENV] === undefined
+            ? runFreshCheck
+            : runChecks;
+        if (options.watch) {
+          const abortController = new AbortController();
+          const stop = () => abortController.abort();
+          process.on("SIGINT", stop);
+          process.on("SIGTERM", stop);
+          try {
+            await watchProjectChecks(
+              checkOptions,
+              async (result) => {
+                await writeCheckOutput(result.output);
+                exitCode.value = result.exitCode;
+              },
+              undefined,
+              abortController.signal,
+            );
+          } finally {
+            process.off("SIGINT", stop);
+            process.off("SIGTERM", stop);
+          }
+          return;
+        }
+        const { result, interruptedExitCode } = await runChecksInterruptibly(
+          checkOptions,
+          checkRunner,
+        );
+        await writeCheckOutput(result.output);
+        exitCode.value = interruptedExitCode ?? result.exitCode;
+      },
+    );
+
+  program
+    .command("apply")
+    .description("check source, then make the platform match it")
+    .action(async () => {
+      const sourceRoot = await resolveSourceRoot(globals(), context.io);
+      const { result: checked, interruptedExitCode } = await runChecksInterruptibly(
+        {
+          sourceRoot,
+          environment: context.environment,
+        },
+        runChecks,
+      );
+      context.io.stdout(checked.output);
+      if (interruptedExitCode !== undefined) {
+        exitCode.value = interruptedExitCode;
+        return;
+      }
+      if (checked.exitCode !== 0) {
+        exitCode.value = checked.exitCode;
+        return;
+      }
+      assertCli(checked.source, "Passing checks must return project source", { hint: REPORT_HINT });
+      const { client, projectId } = await resolveContext(globals(), context);
+      const result = await applyProject(client, {
+        sourceRoot,
+        source: checked.source,
+        ...(projectId === undefined ? {} : { projectId }),
+      });
+      context.io.stdout(result.output);
+    });
+};

package/src/cli/commands/status.ts

@@ -0,0 +1,17 @@
+import type { Command } from "commander";
+import { resolveContext, type CommandHost } from "../context";
+import { projectStatus } from "../project";
+import { assertProjectSelected } from "../project-context";
+
+export const registerStatusCommand = (program: Command, host: CommandHost): void => {
+  const { context, globals } = host;
+  program
+    .command("status")
+    .description("report project health: live counts and pending source changes")
+    .action(async () => {
+      const { sourceRoot, client, projectId } = await resolveContext(globals(), context);
+      assertProjectSelected(projectId);
+      const result = await projectStatus(client, { sourceRoot, projectId });
+      context.io.stdout(result.output);
+    });
+};

package/src/cli/commands/training.ts

@@ -0,0 +1,261 @@
+import type { Command } from "commander";
+import {
+  positiveInteger,
+  resolveContext,
+  trainingBatchSize,
+  trainingDraftOptions,
+  trainingEpochs,
+  trainingGistTokens,
+  trainingLearningRate,
+  trainingLoraRank,
+  trainingMaxSequenceLength,
+  trainingMethod,
+  type CommandHost,
+  type RawTrainingDraftOptions,
+} from "../context";
+import { parseBaseModelId } from "../models";
+import { assertProjectSelected } from "../project-context";
+import {
+  cancelTrainingRun,
+  createTraining,
+  createTrainingRun,
+  estimateTrainingCost,
+  getTraining,
+  getTrainingRun,
+  listTrainingRuns,
+  listTrainings,
+  readTrainingRunLogs,
+  readTrainingRunMetricHistory,
+  readTrainingRunMetrics,
+  resumeTrainingRun,
+  updateTraining,
+} from "../trainings";
+
+export const registerTrainingCommands = (program: Command, host: CommandHost): void => {
+  const { context, globals } = host;
+  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);
+      assertProjectSelected(projectId);
+      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);
+      assertProjectSelected(projectId);
+      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("--lora-rank <rank>", "SFT LoRA adapter rank: 8, 16, or 32 (default 16)", trainingLoraRank)
+    .option("--gist-tokens <count>", "gisting soft tokens: 8, 32, or 64 (default 32)", trainingGistTokens)
+    .option("--epochs <count>", "training epochs, 1 through 5 (default 3)", trainingEpochs)
+    .option(
+      "--learning-rate <rate>",
+      "optimizer learning rate (default 0.00015 for SFT, 0.03 for gisting)",
+      trainingLearningRate,
+    )
+    .option(
+      "--batch-size <count>",
+      "sequences per optimizer step: 8, 16, 32, or 64 (default 8)",
+      trainingBatchSize,
+    )
+    .option(
+      "--max-sequence-length <tokens>",
+      "token budget per example, 64 through 16384 (default 12288 for SFT, 3072 for gisting)",
+      trainingMaxSequenceLength,
+    )
+    .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);
+      assertProjectSelected(projectId);
+      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("--lora-rank <rank>", "SFT LoRA adapter rank: 8, 16, or 32 (default 16)", trainingLoraRank)
+    .option("--gist-tokens <count>", "gisting soft tokens: 8, 32, or 64 (default 32)", trainingGistTokens)
+    .option("--epochs <count>", "training epochs, 1 through 5 (default 3)", trainingEpochs)
+    .option(
+      "--learning-rate <rate>",
+      "optimizer learning rate (default 0.00015 for SFT, 0.03 for gisting)",
+      trainingLearningRate,
+    )
+    .option(
+      "--batch-size <count>",
+      "sequences per optimizer step: 8, 16, 32, or 64 (default 8)",
+      trainingBatchSize,
+    )
+    .option(
+      "--max-sequence-length <tokens>",
+      "token budget per example, 64 through 16384 (default 12288 for SFT, 3072 for gisting)",
+      trainingMaxSequenceLength,
+    )
+    .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);
+      assertProjectSelected(projectId);
+      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);
+      assertProjectSelected(projectId);
+      await estimateTrainingCost(
+        client,
+        { projectId, nameOrId, idempotencyKey: options.idempotencyKey, json: options.json },
+        context.io,
+      );
+    });
+  training
+    .command("run")
+    .argument("<name-or-id>", "Training name or ID")
+    .option("--estimate-file <path>", "ready Training Cost Estimate JSON")
+    .option("--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("calculate a ready Cost Estimate and create one queued Training Run")
+    .action(
+      async (
+        nameOrId: string,
+        options: {
+          estimateFile?: string;
+          versionName?: string;
+          idempotencyKey?: string;
+          json: boolean;
+        },
+      ) => {
+        const { client, projectId } = await resolveContext(globals(), context);
+        assertProjectSelected(projectId);
+        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);
+      assertProjectSelected(projectId);
+      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("metrics")
+    .argument("<training-run-id>", "Training Run ID")
+    .option("--key <metric>", "read the point history of one metric instead of the summary")
+    .option("--resolution <count>", "history points to return, 2 to 500 (default 200)", positiveInteger)
+    .option("--json", "print JSON", false)
+    .description("read Training Run metrics")
+    .action(
+      async (
+        trainingRunId: string,
+        options: { key?: string; resolution?: number; json: boolean },
+      ) => {
+        const { client } = await resolveContext(globals(), context);
+        if (options.key === undefined) {
+          await readTrainingRunMetrics(client, { trainingRunId, json: options.json }, context.io);
+          return;
+        }
+        await readTrainingRunMetricHistory(
+          client,
+          {
+            trainingRunId,
+            metricKey: options.key,
+            resolution: options.resolution,
+            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);
+    });
+};

package/src/cli/commands/version.ts

@@ -0,0 +1,14 @@
+import type { Command } from "commander";
+import type { CommandHost } from "../context";
+import { cliVersionInfo } from "../version";
+import { SDK_VERSION } from "../sdk-version";
+
+export const registerVersionCommand = (program: Command, host: CommandHost): void => {
+  program
+    .command("version")
+    .option("--json", "print version and build provenance as JSON", false)
+    .description("print the current CLI version")
+    .action((options: { json: boolean }) =>
+      host.context.io.stdout(options.json ? JSON.stringify(cliVersionInfo()) : SDK_VERSION),
+    );
+};

package/src/cli/config.ts

@@ -1,7 +1,7 @@
-import { assert } from "es-toolkit";
 import type { TolokaState } from "../state";
 import type { StoredCredentials } from "./credentials";
 import { resolveProjectContext } from "./project-context";
+import { assertCli } from "./cli-error";
 
 export type TolokaCliFlags = {
   readonly apiKey?: string;
@@ -10,9 +10,8 @@ export type TolokaCliFlags = {
 };
 
 export type TolokaEnvironment = Readonly<Record<string, string | undefined>> & {
-  readonly POTATO_API_KEY?: string;
-  readonly POTATO_BASE_URL?: string;
-  readonly POTATO_PROJECT_ID?: string;
+  readonly TOLOKA_API_KEY?: string;
+  readonly TOLOKA_BASE_URL?: string;
   readonly TOLOKA_PROJECT_ID?: string;
 };
 
@@ -54,7 +53,7 @@ const missingApiKeyMessage = [
   "  toloka login",
   "",
   "It explains how to generate an API key and where it is saved. To override per command,",
-  "pass --api-key or set POTATO_API_KEY. Run toloka auth-status to see what is in effect.",
+  "pass --api-key or set TOLOKA_API_KEY. Run toloka auth-status to see what is in effect.",
 ].join("\n");
 
 export function resolveTolokaConfig(
@@ -63,10 +62,10 @@ export function resolveTolokaConfig(
   environment: TolokaEnvironment,
   stored?: StoredCredentials,
 ): ResolvedTolokaConfig {
-  const apiKey = flags.apiKey ?? environment.POTATO_API_KEY ?? stored?.apiKey;
+  const apiKey = flags.apiKey ?? environment.TOLOKA_API_KEY ?? stored?.apiKey;
   const baseUrl =
     flags.baseUrl ??
-    environment.POTATO_BASE_URL ??
+    environment.TOLOKA_BASE_URL ??
     resolveInternalBaseUrl(environment) ??
     stored?.baseUrl ??
     PRODUCTION_BASE_URL;
@@ -77,6 +76,6 @@ export function resolveTolokaConfig(
     stored,
     effectiveBaseUrl: baseUrl,
   });
-  assert(apiKey, missingApiKeyMessage);
+  assertCli(apiKey, missingApiKeyMessage, { hint: { disabled: true } });
   return { apiKey, baseUrl, ...(project === undefined ? {} : { projectId: project.id }) };
 }