@toloka-platform/sdk 0.12.2 → 0.13.1

package/openapi/gen/models/createBatchInferenceRunBodyItemFilterFieldValuesItemSourcesItemOneOfTwo.ts

@@ -0,0 +1,5 @@
+
+export type CreateBatchInferenceRunBodyItemFilterFieldValuesItemSourcesItemOneOfTwo = {
+  type: 'system';
+  source: string;
+};

package/openapi/gen/models/createBatchInferenceRunBodyItemFilterFieldValuesItemValue.ts

@@ -0,0 +1,2 @@
+
+export type CreateBatchInferenceRunBodyItemFilterFieldValuesItemValue = string | number | boolean | null;

package/openapi/gen/models/createBatchInferenceRunBodyItemFilterParts.ts

@@ -0,0 +1,5 @@
+
+export type CreateBatchInferenceRunBodyItemFilterParts = {
+  fieldId: string;
+  names: string[];
+};

package/openapi/gen/models/createBatchInferenceRunBodyItemFilterSlice.ts

@@ -0,0 +1,4 @@
+
+export type CreateBatchInferenceRunBodyItemFilterSlice = {
+  sliceId: string;
+};

package/openapi/gen/models/createBatchInferenceRunBodyOutput.ts

@@ -0,0 +1,4 @@
+import type { CreateBatchInferenceRunBodyOutputOneOf } from './createBatchInferenceRunBodyOutputOneOf';
+import type { CreateBatchInferenceRunBodyOutputOneOfTwo } from './createBatchInferenceRunBodyOutputOneOfTwo';
+
+export type CreateBatchInferenceRunBodyOutput = CreateBatchInferenceRunBodyOutputOneOf | CreateBatchInferenceRunBodyOutputOneOfTwo;

package/openapi/gen/models/createBatchInferenceRunBodyOutputOneOf.ts

@@ -0,0 +1,5 @@
+
+export type CreateBatchInferenceRunBodyOutputOneOf = {
+  type: 'field';
+  fieldName: string;
+};

package/openapi/gen/models/createBatchInferenceRunBodyOutputOneOfTwo.ts

@@ -0,0 +1,5 @@
+
+export type CreateBatchInferenceRunBodyOutputOneOfTwo = {
+  type: 'dataset';
+  name: string;
+};

package/openapi/gen/models/createBatchInferenceRunBodySampling.ts

@@ -0,0 +1,9 @@
+
+export type CreateBatchInferenceRunBodySampling = {
+  maxOutputTokens: number;
+  temperature?: number;
+  topP?: number;
+  stop?: string[];
+  seed?: number;
+  samplesPerRow?: number;
+};

package/openapi/gen/models/datasetFieldOperation.ts

@@ -1,4 +1,5 @@
 import type { DatasetFieldCopyOperation } from './datasetFieldCopyOperation';
 import type { DatasetFieldSplitFillOperation } from './datasetFieldSplitFillOperation';
+import type { DatasetFieldWriteOperation } from './datasetFieldWriteOperation';
 
-export type DatasetFieldOperation = DatasetFieldCopyOperation | DatasetFieldSplitFillOperation;
+export type DatasetFieldOperation = DatasetFieldCopyOperation | DatasetFieldSplitFillOperation | DatasetFieldWriteOperation;

package/openapi/gen/models/datasetFieldWriteOperation.ts

@@ -0,0 +1,8 @@
+import type { DatasetFieldWriteOperationProgress } from './datasetFieldWriteOperationProgress';
+
+export interface DatasetFieldWriteOperation {
+  type: 'write';
+  writer: string;
+  progress: DatasetFieldWriteOperationProgress;
+  blocking: boolean;
+}

package/openapi/gen/models/datasetFieldWriteOperationProgress.ts

@@ -0,0 +1,3 @@
+import type { DatasetFieldWriteOperationProgressAnyOf } from './datasetFieldWriteOperationProgressAnyOf';
+
+export type DatasetFieldWriteOperationProgress = DatasetFieldWriteOperationProgressAnyOf | null;

package/openapi/gen/models/datasetFieldWriteOperationProgressAnyOf.ts

@@ -0,0 +1,5 @@
+
+export type DatasetFieldWriteOperationProgressAnyOf = {
+  done: number;
+  total: number;
+};

package/openapi/gen/models/index.ts

@@ -25,6 +25,35 @@ export * from './attachPipelineDatasetBodyItemFilterSlice';
 export * from './baseModel';
 export * from './baseModelId';
 export * from './baseModelIdProperty';
+export * from './batchInferenceMode';
+export * from './batchInferenceModeOneOf';
+export * from './batchInferenceModel';
+export * from './batchInferenceModelOneOf';
+export * from './batchInferenceModelOneOfBaseModelId';
+export * from './batchInferenceModelOneOfThree';
+export * from './batchInferenceRun';
+export * from './batchInferenceRunBlockedReason';
+export * from './batchInferenceRunChargedAmount';
+export * from './batchInferenceRunError';
+export * from './batchInferenceRunErrorAnyOf';
+export * from './batchInferenceRunErrorAnyOfCode';
+export * from './batchInferenceRunId';
+export * from './batchInferenceRunMessage';
+export * from './batchInferenceRunOutput';
+export * from './batchInferenceRunOutputType';
+export * from './batchInferenceRunProgress';
+export * from './batchInferenceRunProgressAnyOf';
+export * from './batchInferenceRunProgressAnyOfPhase';
+export * from './batchInferenceRunProgressAnyOfRequests';
+export * from './batchInferenceRunQuote';
+export * from './batchInferenceRunQuoteAnyOf';
+export * from './batchInferenceRunQuoteAnyOfConfirmBefore';
+export * from './batchInferenceRunResult';
+export * from './batchInferenceRunResultAnyOf';
+export * from './batchInferenceRunResultAnyOfErrorCounts';
+export * from './batchInferenceRunResultAnyOfErrorSamplesItem';
+export * from './batchInferenceRunSampling';
+export * from './batchInferenceRunStatus';
 export * from './checkJob';
 export * from './checkJobError';
 export * from './checkJobResult';
@@ -78,6 +107,25 @@ export * from './codeNodeSettingsFieldProxies';
 export * from './codeNodeSettingsFieldProxiesInputItem';
 export * from './codeNodeSettingsFieldProxiesOutputItem';
 export * from './copyPipelineBody';
+export * from './createBatchInferenceRunBody';
+export * from './createBatchInferenceRunBodyItemFilter';
+export * from './createBatchInferenceRunBodyItemFilterExcludePartsItem';
+export * from './createBatchInferenceRunBodyItemFilterFieldSourcesItem';
+export * from './createBatchInferenceRunBodyItemFilterFieldSourcesItemSourcesItem';
+export * from './createBatchInferenceRunBodyItemFilterFieldSourcesItemSourcesItemOneOf';
+export * from './createBatchInferenceRunBodyItemFilterFieldSourcesItemSourcesItemOneOfTwo';
+export * from './createBatchInferenceRunBodyItemFilterFieldValuesItem';
+export * from './createBatchInferenceRunBodyItemFilterFieldValuesItemOperator';
+export * from './createBatchInferenceRunBodyItemFilterFieldValuesItemSourcesItem';
+export * from './createBatchInferenceRunBodyItemFilterFieldValuesItemSourcesItemOneOf';
+export * from './createBatchInferenceRunBodyItemFilterFieldValuesItemSourcesItemOneOfTwo';
+export * from './createBatchInferenceRunBodyItemFilterFieldValuesItemValue';
+export * from './createBatchInferenceRunBodyItemFilterParts';
+export * from './createBatchInferenceRunBodyItemFilterSlice';
+export * from './createBatchInferenceRunBodyOutput';
+export * from './createBatchInferenceRunBodyOutputOneOf';
+export * from './createBatchInferenceRunBodyOutputOneOfTwo';
+export * from './createBatchInferenceRunBodySampling';
 export * from './createDatasetBody';
 export * from './createDatasetBodyProfile';
 export * from './createDatasetExportBody';
@@ -168,6 +216,9 @@ export * from './datasetFieldSplitAnyOfRecipeAnyOfBalanceByFieldId';
 export * from './datasetFieldSplitAnyOfRecipeAnyOfSharesItem';
 export * from './datasetFieldSplitAnyOfStatus';
 export * from './datasetFieldSplitFillOperation';
+export * from './datasetFieldWriteOperation';
+export * from './datasetFieldWriteOperationProgress';
+export * from './datasetFieldWriteOperationProgressAnyOf';
 export * from './datasetId';
 export * from './datasetItem';
 export * from './datasetItemCurrentSubmissionId';
@@ -356,6 +407,8 @@ export * from './jsonSchemaTypeAnyOfItem';
 export * from './listAudienceSpecializations200';
 export * from './listAudienceSpecializationsParams';
 export * from './listBaseModels200';
+export * from './listBatchInferenceRuns200';
+export * from './listBatchInferenceRunsParams';
 export * from './listDatasetFields200';
 export * from './listDatasetFieldsParams';
 export * from './listDatasetItems200';

package/openapi/gen/models/listBatchInferenceRuns200.ts

@@ -0,0 +1,7 @@
+import type { BatchInferenceRun } from './batchInferenceRun';
+import type { Pagination } from './pagination';
+
+export type ListBatchInferenceRuns200 = {
+  batchInferenceRuns: BatchInferenceRun[];
+  pagination: Pagination;
+};

package/openapi/gen/models/listBatchInferenceRunsParams.ts

@@ -0,0 +1,5 @@
+
+export type ListBatchInferenceRunsParams = {
+limit?: number;
+offset?: number;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@toloka-platform/sdk",
-  "version": "0.12.2",
+  "version": "0.13.1",
   "private": false,
   "description": "Build, inspect, and operate Toloka pipeline projects as TypeScript source. The public API may change between minor versions before 1.0.",
   "license": "Apache-2.0",
@@ -77,6 +77,6 @@
     "bun": ">=1.4.0"
   },
   "tolokaBuild": {
-    "commit": "72b9ea77f616c7f9c3c564c550eac42f703929b2"
+    "commit": "52c25c9c833bf57bbbf04f6cb9847fc577c0116a"
   }
 }

package/skills/catalog.json

@@ -11,8 +11,8 @@
         "testing",
         "checks"
       ],
-      "version": "0.12.2",
-      "digest": "7e6b79b9b85fbfc86cf98f33ebd30fdb4617707d22f7c24440bee2fedecb5f71",
+      "version": "0.13.1",
+      "digest": "d7d6b0e5003031cbd356b64c5341f2db090ebe87986e0eb7e767e0f97aa59345",
       "files": [
         "SKILL.md",
         "references/human-work.md",
@@ -33,7 +33,7 @@
         "bug",
         "report"
       ],
-      "version": "0.12.2",
+      "version": "0.13.1",
       "digest": "70f0bd2c80b32f87896aeb27c363b8a2d37f40e22424f57fe1aad142e125ad67",
       "files": [
         "SKILL.md",
@@ -50,7 +50,7 @@
         "getting-started",
         "agent"
       ],
-      "version": "0.12.2",
+      "version": "0.13.1",
       "digest": "2278adeb46a792356579395fcf73c42322cb23bcd0c61e20856ccabdad6762d1",
       "files": [
         "SKILL.md"
@@ -67,7 +67,7 @@
         "sft",
         "models"
       ],
-      "version": "0.12.2",
+      "version": "0.13.1",
       "digest": "3ce10dee5d3c283d8b5fdea15134a58fc738c7af2c1bb19eb5a0bf70ea0bca13",
       "files": [
         "SKILL.md"
@@ -84,7 +84,7 @@
         "prompt",
         "models"
       ],
-      "version": "0.12.2",
+      "version": "0.13.1",
       "digest": "be8bce8d9cf7241ccb60d2b2a9b7cc07d7755a76e8ff8ec1b0847c49efbb3469",
       "files": [
         "SKILL.md"

package/skills/toloka-build/references/human-work.md

@@ -49,7 +49,7 @@ Write at least one criterion for every output entity. Each criterion needs an au
 
 Use `llmQaInstruction` only when the evaluator needs a specific verification method, authoritative source, tool, or pinned edge case beyond the thresholds. It is evaluator guidance, not labeler guidance, and has no effect in `human_only` mode.
 
-Default QA is `qualityAssurance: { qaMode: 'llm_only' }`. Keep it when it fits the task. `hybrid` adds sampled Human QA while retaining LLM review; `human_only` is appropriate when LLM grading is prohibited or human review alone is required. Recommend a mode based on the user's quality and privacy requirements, explaining cost and turnaround implications before changing it. Human-bearing modes require `humanQaTimeForTask` of at least 30 seconds and at least 3 seconds per quality criterion of the node, whichever is larger; `smartSamplingPercent` defaults to 30 for hybrid and 100 for human-only. Use those defaults unless the task justifies a different rate. Human QA on a node is capped at the node's expected review count from the frozen estimate, which uses the items the estimate expects at that node. Behind a `match`, the estimate assumes an even split across branches, so a branch that receives more items reaches the cap early and its later items skip Human QA; say so in the cost forecast when branch volumes are known to be uneven. QA mode applies to the whole node, not individual criteria. The redo cap is platform-controlled and is not an SDK setting.
+Default QA is `qualityAssurance: { qaMode: 'llm_only' }`. Keep it when it fits the task. `hybrid` adds sampled Human QA while retaining LLM review; `human_only` is appropriate when LLM grading is prohibited or human review alone is required. Recommend a mode based on the user's quality and privacy requirements, explaining cost and turnaround implications before changing it. Human-bearing modes require `humanQaTimeForTask` in whole seconds: at least 30 and at least 3 per quality criterion of the node, whichever is larger, and at most 359,999 (99:59:59); `smartSamplingPercent` defaults to 30 for hybrid and 100 for human-only. Use those defaults unless the task justifies a different rate. Human QA on a node is capped at the node's expected review count from the frozen estimate, which uses the items the estimate expects at that node. Behind a `match`, the estimate assumes an even split across branches, so a branch that receives more items reaches the cap early and its later items skip Human QA; say so in the cost forecast when branch volumes are known to be uneven. QA mode applies to the whole node, not individual criteria. The redo cap is platform-controlled and is not an SDK setting.
 
 The platform also writes annotator fields on human-expert generation nodes. `<snake_cased node name>_annotator_id` is an optional string: the ID of the expert whose answer was accepted, not of earlier rejected attempts. `<snake_cased node name>_qa_annotator_id` exists only in `human_only` and `hybrid` modes: the ID of the expert who made the last human review decision, missing when sampling skipped human review. Both are missing on canceled items and on items completed before they existed; synthetic nodes have neither. The platform also writes one `*_evaluation_result` field per quality criterion with LLM or Human QA verdicts, `<snake_cased node name>_qa_metadata`, and, on a synthetic node with LLM QA, `<snake_cased node name>_evaluation_summary`. Never declare any of these with `field()`: the platform owns them, and an authored field with that name collides with it. Read them from the dataset with `toloka dataset load`.
 
@@ -57,9 +57,9 @@ Keep `instruction` actionable and in English. Include the workflow, concepts, qu
 
 #### Audience and pricing
 
-For humans, set `audienceType: 'human'`, `verifiedExperts`, all three audience filters, `pricePerTask`, and `timeForTask`. Set `verifiedExperts: true` unless the task explicitly asks for the broad unverified crowd. The public shapes differ by filter: languages use `{ type: 'and' | 'or', values: [{ value: 'English' }] }`; specializations use `{ type: 'and' | 'or', values: [{ value, qualificationId }] }`; countries use ISO 3166-1 alpha-2 codes, for example `{ type: 'or', values: ['US'] }`. Verify every country value matches `/^[A-Z]{2}$/`; apply currently accepts arbitrary strings that can match no experts. Derive languages and expertise from the task and its inputs, leaving specialization and country filters unrestricted unless needed. English is a reasonable starting language for an English-language task, not a universal audience default. Ask when an unresolved audience requirement changes who can do the work. Do not put specializations on an unverified audience. A specialization's `qualificationId` is platform identity: preserve an imported value, and discover new ones with `toloka audience specialization list`, copying `ID` into `qualificationId` and `NAME` into `value`; never invent one.
+For humans, set `audienceType: 'human'`, `verifiedExperts`, all three audience filters, `pricePerTask`, and `timeForTask`. Set `verifiedExperts: true` unless the task explicitly asks for the broad unverified crowd. The public shapes differ by filter: languages use `{ type: 'and' | 'or', values: [{ value: 'English' }] }`; specializations use `{ type: 'and' | 'or', values: [{ value, qualificationId }] }`; countries use ISO 3166-1 alpha-2 codes, for example `{ type: 'or', values: ['US'] }`. Apply rejects a country code, language, or specialization that is not in the audience catalog, and an audience that matches no experts. Derive languages and expertise from the task and its inputs, leaving specialization and country filters unrestricted unless needed. English is a reasonable starting language for an English-language task, not a universal audience default. Ask when an unresolved audience requirement changes who can do the work. Do not put specializations on an unverified audience. A specialization's `qualificationId` is platform identity: preserve an imported value, and discover new ones with `toloka audience specialization list`, copying `ID` into `qualificationId` and `NAME` into `value`; never invent one.
 
-`$0.20` and 120 seconds are a starting point for a short task, not a universal rate. Estimate effort from the work and required expertise, respect explicit rates, and explain meaningful adjustments in the cost forecast. The per-expert cap is normally off. For collection tasks, choose a cap based on contributor diversity and repetition requirements; 1 fits one-response-per-expert collection. Avoid copying an arbitrary cap into a task that does not need one.
+You choose `pricePerTask`: apply accepts any value inside the audience's range and rejects one outside it with an error that names the exact bounds. The range is set per hour of work and converted to one task as `rate × timeForTask / 3600`: $12–$90 for ID-verified experts without a specialization (the editor suggests $21) and $3–$24 for the broad crowd (the editor suggests $6). With a specialization it starts at $12 and its top follows that specialization's rates. `timeForTask` is a whole number of seconds from 10 to 359,999 (99:59:59). `$0.40` for 120 seconds is the lowest price an ID-verified audience allows: a starting point for a short task, not a universal rate. Estimate effort from the work and required expertise, respect explicit rates, and explain meaningful adjustments in the cost forecast. The per-expert cap is normally off. For collection tasks, choose a cap based on contributor diversity and repetition requirements; 1 fits one-response-per-expert collection. Avoid copying an arbitrary cap into a task that does not need one.
 
 Use `audienceType: 'synthetic'` only when the user explicitly asks for model-generated output instead of human work; otherwise the audience is human. Explain the quality and cost tradeoff when you set it up. Set the required `maxCostPerAttempt`, the per-attempt ceiling in charged US dollars across fresh input, cached input, and output together, and configure the optional `generationModelId`, `reasoningEffort`, and `llmInstruction`; do not include human pricing or audience fields. Pick the model, its reasoning effort and the budget from `toloka generation-model list`: copy `ID` into `generationModelId` (it must also be in the `generationModelId` union of the installed SDK; a newer model needs an SDK update), set `reasoningEffort` only for a model that lists reasoning efforts (apply rejects it on any other model), and keep `maxCostPerAttempt` between `MIN` and `MAX`, at or above `TYPICAL`. Use a model suited to the task when there is evidence for that choice, or omit `generationModelId` to use the default model the command names; do not guess IDs or capabilities. Synthetic generation is incompatible with `data_collection`, human QA, audience reuse, expert sourcing, and Training.
 
@@ -67,7 +67,7 @@ Use `audienceType: 'synthetic'` only when the user explicitly asks for model-gen
 
 Treat `onboarding` as the node's Training course. It has `enabled`, `steps`, and `info` (`estimatedTime`, `role`, `goal`, `successCriteria`). Give every new human node a real course built from the instruction, criteria, UI, edge cases, and verified examples; the constructor's placeholder is not one. While it is enabled, validation requires non-empty `info.role`, `info.goal`, and `info.successCriteria`, three to six steps, and at least one quiz block; a course uses either a practice block or an examples block, not both, and an examples block needs a built UI. A practice block together with an enabled Exam draws a warning, because the Exam already tests experts on real tasks. Preserve an explicit `enabled: false`. Never invent golden answers or media URLs. Training teaches with retries; it is not an admission gate.
 
-Treat `exam` as the optional one-attempt pass/fail gate after Training and before production. Configure it before finalizing Training. `tasksPerExpert` is 1–10; `passThreshold` is a count from 1 through `tasksPerExpert`. Each `gradedEntities` entry targets an output `Field` and sets `mode: 'ground_truth' | 'quality_criteria' | 'not_graded'`, `groundTruthType: 'direct' | 'custom'`, `customInstruction` (at least 10 characters for custom ground truth, otherwise `''`), and `disabledCriterionIds` (`[]` to keep every criterion). Exact labels favor direct ground truth; free-form work with criteria favors quality criteria; structured comparisons that need tolerance favor custom ground truth. `goldenDatasetId` is a live dataset ID and cannot be derived from a dataset name by the authoring helper; only preserve an imported ID or obtain a real one. Never fabricate one.
+Treat `exam` as the optional one-attempt pass/fail gate after Training and before production. Configure it before finalizing Training. `tasksPerExpert` is 1–10; `passThreshold` is a count from 1 through `tasksPerExpert`. Each `gradedEntities` entry targets an output `Field` and sets `mode: 'ground_truth' | 'quality_criteria' | 'not_graded'`, `groundTruthType: 'direct' | 'custom'`, `customInstruction` (at least 10 characters for custom ground truth, otherwise `''`), and `disabledCriterionIds` (`[]` to keep every criterion). Exact labels favor direct ground truth; free-form work with criteria favors quality criteria; structured comparisons that need tolerance favor custom ground truth. `goldenDatasetId` is a live dataset ID and cannot be derived from a dataset name by the authoring helper; only preserve an imported ID or obtain a real one. Never fabricate one. With `verifiedExperts: false`, the exam also limits how many experts can join the node. Deploy sizes that limit from the tasks the run estimate expects at this node (its expected items, times the overlap on a `quorum` node), the per-expert cap, and the measured exam pass rate, between 100 and 10,000. Behind a `match` router the estimate splits items evenly across the branches, so each branch gets a limit for its share, not for the whole run.
 
 The `ui` strings are authored directly. Build one expert's task view, ensure component value shapes match entity schemas, read inputs as [Task UI](task-ui.md) describes, and use `postprocess` when a component's native value needs reshaping. Hardware-backed upload and recording controls require real UI verification.
 
@@ -146,7 +146,7 @@ The authoring helper does not translate `offboardingRules.agreementScale` from `
 
 When a requirement depends on one of these capabilities, state the gap instead of inventing source syntax:
 
-- Audience discovery beyond specializations has no SDK or CLI path: valid-language/country suggestions, audience-size statistics for a composed filter, and recommended-rate calculation. Specializations and their expert counts come from `toloka audience specialization list`.
+- Audience discovery beyond specializations has no SDK or CLI path: valid-language/country suggestions, audience-size statistics for a composed filter, and recommended-rate calculation. `toloka validate` does report an audience that matches no experts, and states the allowed range when `pricePerTask` falls outside it. Specializations and their expert counts come from `toloka audience specialization list`.
 - Audience-reuse candidate discovery has no SDK or CLI path. Source can store a known cross-pipeline pointer, but cannot search candidates.
 - Smart Search rendering, source-fingerprint computation, and stale-profile diagnosis have no SDK or CLI path. Source can carry the public profile; it cannot generate the server-owned fingerprint or preview rendered sourcing documents.
 - Training's examples playbooks and automatic course authoring have no SDK/CLI path. Source can set `onboarding`, but cannot request geometry/numeric check templates or validate hands-on examples locally beyond the public graph schema.

package/skills/toloka-build/references/workflow-and-cli.md

@@ -35,7 +35,7 @@ Run `toloka --help` and `toloka <command> --help` for the exact commands and opt
 - source reconciliation: `init`, `import`, `check`, `validate`, `plan`, `apply`, `status`, `secret set`;
 - catalogs: `audience specialization list`, `generation-model list`, `ui components`;
 - data and runs: `dataset` (`list`, `create`, `fields`, `fields add`, `columns`, `load`, `upload`, `split`, `slice`), `pipeline` (`list`, `run`, `status`, `runs`, `cost`, `results`, `cancel`);
-- models and training: `base-model`, `model` (including `model version download`), `training`;
+- models and training: `base-model`, `model` (including `model version download`), `training`, `batch-inference` (`run`, `list`, `status`, `confirm`, `resume`, `cancel`);
 - skills and reports: `skill` (`list`, `search`, `install`), `report`.
 
 `toloka audience specialization list` prints the global specialization catalog: `ID`, `NAME`, and `EXPERTS` columns (`--json` for the array). Run it before setting `audience.specializations` on a node, pick entries by name, and copy `ID` into `qualificationId` and `NAME` into `value`; never invent a `qualificationId`. `EXPERTS` counts ID-verified experts currently eligible for tasks; a `0` means the id is valid but nobody currently qualifies, so prefer another specialization or widen the audience.
@@ -58,6 +58,10 @@ Hyperparameters are optional flags on `training create` and `training update`; t
 
 Use `training cost` to validate inputs and show the maximum charge before `training run`. A blocked estimate exits 1 and lists the issues on stderr instead of printing the estimate; fix them and recalculate. `training run` accepts that ready estimate JSON through `--estimate-file`; without it, the command calculates a fresh ready estimate itself before creating the run. `--version-name` defaults to the Training name; pass it when a Model Version with that name already exists. Use `training status`, `training logs`, `training metrics`, `training resume`, and `training cancel` with the returned Training Run ID. `training metrics` lists each metric's latest value while the run is still training; `--key` prints one metric's point history instead. `training cancel` before training starts is free; on a run that is already training it stops the GPU job, and the run is charged only for the GPU seconds used until then and produces no Model Version.
 
+## Answer dataset rows with a model
+
+`toloka batch-inference run --dataset <id> (--base-model <id> | --model-version <id>) (--output-field <name> | --output-dataset <name>) --max-output-tokens <n>` sends each selected row's `messages` to a qwen3-4b or qwen3-8b Base Model, or a Model Version trained from one, and writes one answer per row into a text column or a new dataset. An existing `--output-field` column must allow strings; one whose schema allows none is refused with "does not accept text", so pick or create a text column. `--filter field=value`, `--slice <id>` and `--parts <names>` (with `--split-column` when the dataset has several) narrow the rows; a slice answers the prompts it froze. `run` waits for the quote and prints the rows and the maximum charge: show them to the user and confirm only with their approval, through `--yes` on `run` or `toloka batch-inference confirm <run-id>` within 24 hours. Follow a run with `status --wait`. A `blocked` run names its reason: after `funds` or `payment`, `resume` continues it once the user adds funds; `billing_review` waits for support to reconcile the charge, and `resume` does not apply to it. `cancel` stops a run and charges the GPU time used, and `list` shows the project's runs. A scoped token needs `inference:deploy` (the `deploy` preset) to run, confirm, resume or cancel. `toloka batch-inference <command> --help` lists every flag.
+
 ## Check locally and validate against the platform
 
 Run the complete local gate first, then validate every bound pipeline remotely:
@@ -149,7 +153,7 @@ When rows are added later, run `dataset split` again: it places only the new row
 
 ## Run a pipeline and report results
 
-A run needs an applied pipeline. Apply any requested source changes and verify convergence first; an already-applied unchanged pipeline does not need another apply. SKILL.md covers cost approval, exit codes, and bounded monitoring. The commands below are available operations, not a sequence that requires starting or canceling a run.
+A run needs an applied pipeline. Apply any requested source changes and verify convergence first; an already-applied unchanged pipeline does not need another apply. It also needs at least one dataset item matching the root node's dataset and filter: otherwise `toloka pipeline run` fails with `No dataset items match, so a run would have nothing to process.` even though `apply` and `validate` succeeded. Upload items or widen the filter, then run again. SKILL.md covers cost approval, exit codes, and bounded monitoring. The commands below are available operations, not a sequence that requires starting or canceling a run.
 
 ```sh
 toloka pipeline run <name> --wait --timeout 900000

package/src/cli/analytics.ts

@@ -108,6 +108,14 @@ const COMMAND_GROUPS: Readonly<Record<string, CommandGroup>> = {
     metrics: true,
     logs: true,
   },
+  "batch-inference": {
+    run: true,
+    list: true,
+    status: true,
+    confirm: true,
+    resume: true,
+    cancel: true,
+  },
   "base-model": { list: true, get: true },
   "generation-model": { list: true },
   model: {

package/src/cli/batch-inference.ts

@@ -0,0 +1,267 @@
+import { randomUUID } from "node:crypto";
+
+import type { BatchInferenceRun, PotatoClient } from "../client";
+import type { BaseModelId, CreateBatchInferenceRunBody } from "../../openapi/gen/models";
+import { assertCli } from "./cli-error";
+import { resolveFieldValueFilters } from "./filters";
+import { resolveModelVersion } from "./models";
+import { resolveSplitParts } from "./splits";
+import { formatTable, type TableIo as BatchInferenceIo, writeOutput } from "./table";
+
+type BatchInferenceApi = Pick<PotatoClient, "batchInference">;
+type BatchInferenceStartApi = Pick<
+  PotatoClient,
+  "batchInference" | "datasets" | "models" | "baseModels"
+>;
+
+const QUOTE_WAIT_MS = 10 * 60 * 1_000;
+const SETTLED_STATUSES: ReadonlySet<BatchInferenceRun["status"]> = new Set([
+  "awaiting_confirmation",
+  "blocked",
+  "completed",
+  "failed",
+  "canceled",
+]);
+
+const sleep = (ms: number) =>
+  new Promise<void>((resolve) => {
+    setTimeout(resolve, ms);
+  });
+
+export const formatBatchInferenceRun = (run: BatchInferenceRun): string =>
+  formatTable([
+    ["ID", run.id],
+    ["Status", run.status],
+    ["Dataset", run.datasetId],
+    ["Model", run.model.type === "base_model" ? run.model.baseModelId : run.model.modelVersionId],
+    [
+      "Output",
+      run.output.type === "field"
+        ? `field ${run.output.fieldId} on dataset ${run.output.datasetId}`
+        : `new dataset ${run.output.datasetId}`,
+    ],
+    ...(run.quote
+      ? [
+          ["Rows", String(run.quote.requests)],
+          ["Skipped rows", String(run.quote.skippedRows)],
+          ["Maximum charge", `$${run.quote.maximumCharge}`],
+          ...(run.quote.confirmBefore ? [["Confirm before", run.quote.confirmBefore]] : []),
+        ]
+      : []),
+    ...(run.progress?.requests
+      ? [["Progress", `${run.progress.requests.done}/${run.progress.requests.total} rows`]]
+      : []),
+    ...(run.chargedAmount ? [["Charged", `$${run.chargedAmount}`]] : []),
+    ...(run.result
+      ? [
+          ["Written", String(run.result.written)],
+          ["Failed", String(run.result.failed)],
+          ["Cut at max tokens", String(run.result.truncated)],
+          ["Tokens", `${run.result.inputTokens} in, ${run.result.outputTokens} out`],
+        ]
+      : []),
+    ...(run.message ? [["Message", run.message]] : []),
+  ]);
+
+const waitUntil = async (
+  client: BatchInferenceApi,
+  batchInferenceRunId: string,
+  isReady: (run: BatchInferenceRun) => boolean,
+  pollIntervalMs: number,
+  timeoutMs: number,
+): Promise<BatchInferenceRun> => {
+  const deadline = Date.now() + timeoutMs;
+  for (;;) {
+    const run = await client.batchInference.getRun({ batchInferenceRunId });
+    if (isReady(run)) return run;
+    assertCli(Date.now() < deadline, `Batch Inference Run ${run.id} is still ${run.status}.`, {
+      hint: { description: `Check it later with toloka batch-inference status ${run.id}.` },
+    });
+    await sleep(pollIntervalMs);
+  }
+};
+
+export type StartBatchInferenceRunInput = {
+  projectId: string;
+  datasetId: string;
+  filter?: string;
+  slice?: string;
+  parts?: string[];
+  splitColumn?: string;
+  baseModel?: BaseModelId;
+  modelVersion?: string;
+  outputField?: string;
+  outputDataset?: string;
+  maxOutputTokens: number;
+  temperature?: number;
+  topP?: number;
+  stop: string[];
+  seed?: number;
+  samplesPerRow?: number;
+  idempotencyKey?: string;
+  yes: boolean;
+  json: boolean;
+  pollIntervalMs?: number;
+};
+
+const resolveItemFilter = async (
+  client: BatchInferenceStartApi,
+  input: StartBatchInferenceRunInput,
+): Promise<CreateBatchInferenceRunBody["itemFilter"]> => {
+  assertCli(
+    input.splitColumn === undefined || input.parts !== undefined,
+    "--split-column needs --parts.",
+    { hint: { description: "Pass --parts test to answer the rows of the test part." } },
+  );
+  const itemFilter = {
+    ...(input.filter !== undefined &&
+      (await resolveFieldValueFilters(
+        client,
+        { datasetId: input.datasetId, name: input.datasetId, nameIsUnique: false },
+        [input.filter],
+      ))),
+    ...(input.slice !== undefined && { slice: { sliceId: input.slice } }),
+    ...(input.parts !== undefined && {
+      parts: await resolveSplitParts(client, input.datasetId, {
+        splitColumn: input.splitColumn,
+        parts: input.parts,
+      }),
+    }),
+  };
+  return Object.keys(itemFilter).length > 0 ? itemFilter : undefined;
+};
+
+export const startBatchInferenceRun = async (
+  client: BatchInferenceStartApi,
+  input: StartBatchInferenceRunInput,
+  io: BatchInferenceIo,
+): Promise<void> => {
+  assertCli(
+    (input.baseModel === undefined) !== (input.modelVersion === undefined),
+    "Pass exactly one of --base-model or --model-version.",
+    {
+      hint: {
+        description: "Run toloka base-model list or toloka model versions <model> to pick one.",
+      },
+    },
+  );
+  assertCli(
+    (input.outputField === undefined) !== (input.outputDataset === undefined),
+    "Pass exactly one of --output-field or --output-dataset.",
+    {
+      hint: {
+        description:
+          "--output-field writes a column on the dataset; --output-dataset creates a new dataset with the prompts and answers.",
+      },
+    },
+  );
+  const itemFilter = await resolveItemFilter(client, input);
+  const model: CreateBatchInferenceRunBody["model"] = input.baseModel
+    ? { type: "base_model", baseModelId: input.baseModel }
+    : {
+        type: "model_version",
+        modelVersionId: (await resolveModelVersion(client, input.projectId, input.modelVersion!))
+          .id,
+      };
+  const created = await client.batchInference.createRun({
+    projectId: input.projectId,
+    idempotencyKey: input.idempotencyKey ?? randomUUID(),
+    datasetId: input.datasetId,
+    ...(itemFilter && { itemFilter }),
+    model,
+    sampling: {
+      maxOutputTokens: input.maxOutputTokens,
+      ...(input.temperature !== undefined && { temperature: input.temperature }),
+      ...(input.topP !== undefined && { topP: input.topP }),
+      ...(input.stop.length > 0 && { stop: input.stop }),
+      ...(input.seed !== undefined && { seed: input.seed }),
+      ...(input.samplesPerRow !== undefined && { samplesPerRow: input.samplesPerRow }),
+    },
+    output:
+      input.outputField === undefined
+        ? { type: "dataset", name: input.outputDataset! }
+        : { type: "field", fieldName: input.outputField },
+  });
+  const quoted = await waitUntil(
+    client,
+    created.id,
+    (run) => run.status !== "preparing",
+    input.pollIntervalMs ?? 1_000,
+    QUOTE_WAIT_MS,
+  );
+  assertCli(quoted.status === "awaiting_confirmation", formatBatchInferenceRun(quoted), {
+    hint: { description: "Fix the selection or the model, then start a new run." },
+  });
+  if (!input.yes) {
+    writeOutput(
+      io,
+      input.json,
+      quoted,
+      `${formatBatchInferenceRun(quoted)}\n\nConfirm the maximum charge with: toloka batch-inference confirm ${quoted.id}`,
+    );
+    return;
+  }
+  const confirmed = await client.batchInference.confirmRun({ batchInferenceRunId: quoted.id });
+  writeOutput(io, input.json, confirmed, formatBatchInferenceRun(confirmed));
+};
+
+export const listBatchInferenceRuns = async (
+  client: BatchInferenceApi,
+  input: { projectId: string; json: boolean },
+  io: BatchInferenceIo,
+): Promise<void> => {
+  const page = await client.batchInference.listRunsPage({
+    projectId: input.projectId,
+    limit: 100,
+    offset: 0,
+  });
+  writeOutput(
+    io,
+    input.json,
+    page.batchInferenceRuns,
+    page.batchInferenceRuns.length === 0
+      ? "No Batch Inference Runs found."
+      : formatTable([
+          ["ID", "STATUS", "DATASET", "MAXIMUM CHARGE", "CHARGED"],
+          ...page.batchInferenceRuns.map((run) => [
+            run.id,
+            run.status,
+            run.datasetId,
+            run.quote ? `$${run.quote.maximumCharge}` : "-",
+            run.chargedAmount ? `$${run.chargedAmount}` : "-",
+          ]),
+        ]),
+  );
+};
+
+export const getBatchInferenceRun = async (
+  client: BatchInferenceApi,
+  input: { batchInferenceRunId: string; wait: boolean; json: boolean; pollIntervalMs?: number },
+  io: BatchInferenceIo,
+): Promise<void> => {
+  const run = input.wait
+    ? await waitUntil(
+        client,
+        input.batchInferenceRunId,
+        (candidate) => SETTLED_STATUSES.has(candidate.status),
+        input.pollIntervalMs ?? 5_000,
+        Number.POSITIVE_INFINITY,
+      )
+    : await client.batchInference.getRun({ batchInferenceRunId: input.batchInferenceRunId });
+  writeOutput(io, input.json, run, formatBatchInferenceRun(run));
+};
+
+export const changeBatchInferenceRun = async (
+  client: BatchInferenceApi,
+  input: { batchInferenceRunId: string; action: "confirm" | "cancel" | "resume"; json: boolean },
+  io: BatchInferenceIo,
+): Promise<void> => {
+  const request = { batchInferenceRunId: input.batchInferenceRunId };
+  const run =
+    input.action === "confirm"
+      ? await client.batchInference.confirmRun(request)
+      : input.action === "cancel"
+        ? await client.batchInference.cancelRun(request)
+        : await client.batchInference.resumeRun(request);
+  writeOutput(io, input.json, run, formatBatchInferenceRun(run));
+};