@toloka-platform/sdk 0.11.4 → 0.12.1

package/skills/toloka-fine-tuning/SKILL.md

@@ -14,10 +14,11 @@ For first-time setup details, read `https://platform.toloka.ai/agents/fine-tunin
 ## Domain model
 
 - **SFT** adapts model weights from representative chat examples. Each training row must follow the platform chat contract and end with the assistant response the model should learn to produce.
-- A **Training** is an editable project-owned draft. A **Training Run** is one immutable, billable execution of a frozen draft and Dataset selections.
+- A **Training** is an editable project-owned draft. A **Training Run** is one immutable, billable execution of a frozen draft and the rows of its slice.
 - A run can start from a catalog **Base Model** or an exact existing **Model Version**. An explicit Model Version is the source; do not also select a Base Model.
 - A completed run publishes a durable Model Version. It does not prove deployment or inference readiness.
-- Training and validation are data roles, not file-layout rules. Separate Datasets and disjoint top-level filters are both valid. Without a validation selection, the provider reserves 10% of the training rows as a holdout.
+- Training and validation are data roles, not file-layout rules. A **split column** puts each Dataset row in a part such as `train`, `validate` or `test`, and a **slice** freezes rows together with their split columns. A Training learns on a slice's rows in the train parts of one split column and validates on its validate parts, which may include a part that also tests. Without validation rows, the provider reserves 10% of the training rows as a holdout.
+- A Training needs `--dataset <dataset>` or `--slice <id>`. `--dataset` fills the empty cells of the Dataset's split column (a new `split` column, 80/10/10, when it has none) and freezes a slice named after the Training; `--slice` takes a slice frozen with `toloka dataset slice create`, which must freeze a split column. Rows without a part are never trained on. Rows that any split column puts in a test part never reach training, nor validation unless they sit in a validate + test part of the Training's own split column; the cost estimate reports any train rows they remove as `Left out as test`. `toloka dataset split <dataset>` places only rows without a part, so after adding rows, run it again and take a new slice: no test row moves into training. `toloka dataset columns <dataset>` shows the split columns and their roles.
 
 ## Working posture
 
@@ -58,15 +59,23 @@ toloka dataset list
 toloka dataset fields <dataset-name-or-id>
 ```
 
-Use the user's authorized data and existing role assignments. If local JSONL files must be uploaded, organize Datasets by training and validation role, not automatically by file. `dataset upload` appends, so compatible files for one role can share a Dataset:
+Use the user's authorized data and existing role assignments. If local JSONL files must be uploaded, put them in one Dataset for the task; `dataset upload` appends, and a split column records each row's role:
 
 ```sh
-toloka dataset create <role-dataset-name>
-toloka dataset upload <role-dataset-name> <absolute-jsonl-path>
-toloka dataset fields <role-dataset-name>
+toloka dataset create <dataset-name>
+toloka dataset upload <dataset-name> <absolute-jsonl-path>
+toloka dataset fields <dataset-name>
 ```
 
-CLI uploads to an otherwise undeclared Dataset store each row whole. A nested `split` value in that uploaded object is not a top-level Dataset field and cannot be used by `--train-filter` or `--validation-filter`. In that case, use separate role Datasets or omit validation flags and use the provider's 10% holdout. Existing Datasets with a real top-level split field can use disjoint filters. Never use overlapping selections or mix a supplied validation set back into training.
+When the user supplied separate training and validation files, give each file its role before uploading the next one: `toloka dataset split <dataset-name> --parts train:100 --json` after the training file, then `toloka dataset split <dataset-name> --parts validate:100 --json` after the validation file. Each fill places only rows without a part, so a supplied validation set never mixes into training; pass `--parts` on every such fill, because a fill without it repeats the column's last shares. For one undivided file, let the split sample it: `toloka dataset split <dataset-name> --ratios 80/10/10 [--balance-by <label-field>] --json`, or leave it to `training create --dataset`, which splits 80/10/10.
+
+CLI uploads to an otherwise undeclared Dataset store each row whole in its `uploaded` field, so the rows' own fields are not dataset fields yet. `toloka dataset fields add <dataset> <field>…` adds top-level fields of the uploaded rows as dataset fields, for filters and `--balance-by`, and copies their values from every upload. When the rows carry their own role, such as a Hugging Face `split` field, add it, then adopt it: `toloka dataset fields add <dataset> split`, then `toloka dataset split <dataset> --column split`. Roles follow the values `train`, `validation`/`validate`/`val`/`dev` and `test`, and `--parts train,dev=validate,test` maps other names. `dataset split` and `training create --dataset` refuse a split column name that is a field of the uploaded rows but not a dataset field, and print the `fields add` command.
+
+To train on a subset or reuse rows across Trainings, freeze a slice once every upload and split has finished; `--filter <field>=<value>` keeps only matching rows, and split columns are always frozen:
+
+```sh
+toloka dataset slice create <dataset-name> --name "<slice-name>" --json
+```
 
 ### 3. Choose and verify the source
 
@@ -98,18 +107,17 @@ When a new draft is needed, use a descriptive name and create normalized SFT con
 ```sh
 toloka training create "<training-name>" \
   --base-model <base-model-id> \
-  --dataset <training-dataset-id> \
-  --validation-dataset <validation-dataset-id> \
+  --dataset <dataset-name-or-id> \
   --json
 ```
 
-Without `--validation-dataset`, the platform holds out 10% of training rows for evaluation. To select disjoint rows from top-level Dataset fields, use `--train-filter <field>=<value>` and `--validation-filter <field>=<value>`.
+`--dataset` fills the empty cells of the Dataset's split column, freezes a slice named after the Training, and prints a line for each step; pass `--split-column <name>` when the Dataset has several split columns. To train on a slice frozen earlier, pass `--slice <slice-id>` instead. The Training learns on the column's train parts, or the ones `--parts <names>` lists, and validates on its validate parts; without validate rows, the platform holds out 10% of training rows for evaluation.
 
 To continue from a Model Version, replace `--base-model` with `--model-version <model-version-id>`.
 
-Preserve requested hyperparameters. The current CLI uses `--lora-rank 8|16|32` (default 16), `--epochs 1..5` (default 3), `--learning-rate` within 0.00001–0.001 (default 0.00015), `--batch-size 8|16|32|64` (default 8), and `--max-sequence-length 64..16384` (default 12288), rather than `regime`. Use defaults when suitable; rank 8 can fit narrow tasks or small data, while 32 may help when 16 underfits and the data supports more capacity. Choose sequence length from actual examples within the supported limit. `--gist-tokens` is rejected for SFT. `training update <name-or-id>` takes the same flags except `--method`; omitted flags retain current values.
+Preserve requested hyperparameters. The current CLI uses `--lora-rank 8|16|32` (default 16), `--epochs 1..5` (default 3), `--learning-rate` within 0.00001–0.001 (default 0.00015), `--batch-size 8|16|32|64` (default 8), and `--max-sequence-length 64..16384` (default 12288), rather than `regime`. Use defaults when suitable; rank 8 can fit narrow tasks or small data, while 32 may help when 16 underfits and the data supports more capacity. Choose sequence length from actual examples within the supported limit. `--gist-tokens` is rejected for SFT. `training update <name-or-id>` takes the same flags except `--method`; omitted flags retain current values. A new `--slice` or `--dataset` resets `--split-column` and `--parts` unless you pass them again.
 
-Verify the saved method, exact source, selections, filters, and configuration with `toloka training get <training-id> --json`.
+Verify the saved method, exact source, slice, split column, train parts, and configuration with `toloka training get <training-id> --json`.
 
 ### 5. Validate and estimate
 
@@ -121,7 +129,7 @@ A blocked estimate exits 1, leaves the redirected file empty, and prints `Traini
 
 For a duration issue, use the reported rows, tokens, epochs, GPU count, and wall time to compare supported options. `qwen3-32b` and `qwen3-235b` use 8 GPUs and can reduce wall time, but changing the model also changes quality, serving constraints, and cost; reducing rows can weaken coverage; reducing epochs can weaken adaptation. Do not change the requested model, silently discard data, or alter epochs merely to make the estimate pass. Present the tradeoff, obtain direction when it is material, then update the draft, re-estimate, and obtain approval for the new quote.
 
-For a ready estimate, report the source and selections, training and validation row counts, token totals, maximum GPU seconds, `maximumCharge`, currency, and fingerprint. If the user asked only for an estimate, stop here.
+For a ready estimate, report the source, slice and split column, training and validation row counts, any rows left out as test, token totals, maximum GPU seconds, `maximumCharge`, currency, and fingerprint. If the user asked only for an estimate, stop here.
 
 ### 6. Run only after explicit cost approval
 

package/skills/toloka-gisting/SKILL.md

@@ -14,10 +14,11 @@ For first-time setup details, read `https://platform.toloka.ai/agents/gisting.md
 ## Domain model
 
 - **Prompt gisting** learns soft prompt tokens that stand in for a static instruction prompt. Training examples should contain the dynamic inputs and desired assistant responses; do not repeat the static prompt in every user message.
-- A **Training** is an editable project-owned draft. A **Training Run** is one immutable, billable execution of a frozen draft, prompt, and Dataset selections.
+- A **Training** is an editable project-owned draft. A **Training Run** is one immutable, billable execution of a frozen draft, prompt, and the rows of its slice.
 - A run can start from a catalog **Base Model** or an exact existing **Model Version**. An explicit Model Version is the source; do not also select a Base Model.
 - A completed run publishes a durable Model Version. It does not prove deployment or inference readiness.
-- Training and validation are data roles, not file-layout rules. Separate Datasets and disjoint top-level filters are both valid. Without a validation selection, the provider reserves 10% of the training rows as a holdout.
+- Training and validation are data roles, not file-layout rules. A **split column** puts each Dataset row in a part such as `train`, `validate` or `test`, and a **slice** freezes rows together with their split columns. A Training learns on a slice's rows in the train parts of one split column and validates on its validate parts, which may include a part that also tests. Without validation rows, the provider reserves 10% of the training rows as a holdout.
+- A Training needs `--dataset <dataset>` or `--slice <id>`. `--dataset` fills the empty cells of the Dataset's split column (a new `split` column, 80/10/10, when it has none) and freezes a slice named after the Training; `--slice` takes a slice frozen with `toloka dataset slice create`, which must freeze a split column. Rows without a part are never trained on. Rows that any split column puts in a test part never reach training, nor validation unless they sit in a validate + test part of the Training's own split column; the cost estimate reports any train rows they remove as `Left out as test`. `toloka dataset split <dataset>` places only rows without a part, so after adding rows, run it again and take a new slice: no test row moves into training. `toloka dataset columns <dataset>` shows the split columns and their roles.
 
 ## Working posture
 
@@ -59,15 +60,23 @@ toloka dataset list
 toloka dataset fields <dataset-name-or-id>
 ```
 
-Use the user's authorized data and existing role assignments. If local JSONL files must be uploaded, organize Datasets by training and validation role, not automatically by file. `dataset upload` appends, so compatible files for one role can share a Dataset:
+Use the user's authorized data and existing role assignments. If local JSONL files must be uploaded, put them in one Dataset for the task; `dataset upload` appends, and a split column records each row's role:
 
 ```sh
-toloka dataset create <role-dataset-name>
-toloka dataset upload <role-dataset-name> <absolute-jsonl-path>
-toloka dataset fields <role-dataset-name>
+toloka dataset create <dataset-name>
+toloka dataset upload <dataset-name> <absolute-jsonl-path>
+toloka dataset fields <dataset-name>
 ```
 
-CLI uploads to an otherwise undeclared Dataset store each row whole. A nested `split` value in that uploaded object is not a top-level Dataset field and cannot be used by `--train-filter` or `--validation-filter`. In that case, use separate role Datasets or omit validation flags and use the provider's 10% holdout. Existing Datasets with a real top-level split field can use disjoint filters. Never use overlapping selections or mix a supplied validation set back into training.
+When the user supplied separate training and validation files, give each file its role before uploading the next one: `toloka dataset split <dataset-name> --parts train:100 --json` after the training file, then `toloka dataset split <dataset-name> --parts validate:100 --json` after the validation file. Each fill places only rows without a part, so a supplied validation set never mixes into training; pass `--parts` on every such fill, because a fill without it repeats the column's last shares. For one undivided file, let the split sample it: `toloka dataset split <dataset-name> --ratios 80/10/10 [--balance-by <label-field>] --json`, or leave it to `training create --dataset`, which splits 80/10/10.
+
+CLI uploads to an otherwise undeclared Dataset store each row whole in its `uploaded` field, so the rows' own fields are not dataset fields yet. `toloka dataset fields add <dataset> <field>…` adds top-level fields of the uploaded rows as dataset fields, for filters and `--balance-by`, and copies their values from every upload. When the rows carry their own role, such as a Hugging Face `split` field, add it, then adopt it: `toloka dataset fields add <dataset> split`, then `toloka dataset split <dataset> --column split`. Roles follow the values `train`, `validation`/`validate`/`val`/`dev` and `test`, and `--parts train,dev=validate,test` maps other names. `dataset split` and `training create --dataset` refuse a split column name that is a field of the uploaded rows but not a dataset field, and print the `fields add` command.
+
+To train on a subset or reuse rows across Trainings, freeze a slice once every upload and split has finished; `--filter <field>=<value>` keeps only matching rows, and split columns are always frozen:
+
+```sh
+toloka dataset slice create <dataset-name> --name "<slice-name>" --json
+```
 
 Check that the examples demonstrate the desired behavior under the prompt: dynamic input in user messages, target output in the final assistant message, representative edge cases, and no prompt or answer leakage across validation.
 
@@ -107,16 +116,15 @@ toloka training create "<training-name>" \
   --method gisting \
   --prompt-file <absolute-prompt-path> \
   --base-model <base-model-id> \
-  --dataset <training-dataset-id> \
-  --validation-dataset <validation-dataset-id> \
+  --dataset <dataset-name-or-id> \
   --json
 ```
 
-Without `--validation-dataset`, the platform holds out 10% of training rows for evaluation. To select disjoint rows from top-level Dataset fields, use `--train-filter <field>=<value>` and `--validation-filter <field>=<value>`.
+`--dataset` fills the empty cells of the Dataset's split column, freezes a slice named after the Training, and prints a line for each step; pass `--split-column <name>` when the Dataset has several split columns. To train on a slice frozen earlier, pass `--slice <slice-id>` instead. The Training learns on the column's train parts, or the ones `--parts <names>` lists, and validates on its validate parts; without validate rows, the platform holds out 10% of training rows for evaluation.
 
-Preserve requested hyperparameters. The current CLI uses `--gist-tokens` (default `1/8`), `--epochs 1..5` (default 3), `--learning-rate` within 0.001–0.3 (default 0.03), `--batch-size 8|16|32|64` (default 8), and `--max-sequence-length 64..16384` (default 3072), rather than `regime`. Use defaults when suitable. `--gist-tokens` takes an absolute count `8|32|64` or a fraction of the prompt being compressed — `1/4`, `1/8`, `1/16`, `1/32`. An absolute count fixes the soft-prompt size: 8 favors compression for simple prompts, while 64 may help when 32 loses holdout accuracy. A fraction fixes the compression ratio instead — the run resolves it to `ceil(prompt tokens / N)` and clamps it to 8..256 — so the default `1/8` suits a prompt whose length changes between drafts; go to `1/16` or `1/32` for harder compression when holdout accuracy holds. `training get` reports the fraction you set, not the count it resolved to. Choose sequence length from actual examples within the supported limit. `--lora-rank` is rejected for gisting. `training update <name-or-id>` takes the same flags except `--method`; omitted flags retain current values.
+Preserve requested hyperparameters. The current CLI uses `--gist-tokens` (default `1/8`), `--epochs 1..5` (default 3), `--learning-rate` within 0.001–0.3 (default 0.03), `--batch-size 8|16|32|64` (default 8), and `--max-sequence-length 64..16384` (default 3072), rather than `regime`. Use defaults when suitable. `--gist-tokens` takes an absolute count `8|32|64` or a fraction of the prompt being compressed — `1/4`, `1/8`, `1/16`, `1/32`. An absolute count fixes the soft-prompt size: 8 favors compression for simple prompts, while 64 may help when 32 loses holdout accuracy. A fraction fixes the compression ratio instead — the run resolves it to `ceil(prompt tokens / N)` and clamps it to 8..256 — so the default `1/8` suits a prompt whose length changes between drafts; go to `1/16` or `1/32` for harder compression when holdout accuracy holds. `training get` reports the fraction you set, not the count it resolved to. Choose sequence length from actual examples within the supported limit. `--lora-rank` is rejected for gisting. `training update <name-or-id>` takes the same flags except `--method`; omitted flags retain current values. A new `--slice` or `--dataset` resets `--split-column` and `--parts` unless you pass them again.
 
-Verify the saved method, exact source, prompt file, selections, filters, and configuration with `toloka training get <training-id> --json`.
+Verify the saved method, exact source, prompt file, slice, split column, train parts, and configuration with `toloka training get <training-id> --json`.
 
 ### 5. Validate and estimate
 
@@ -128,7 +136,7 @@ A blocked estimate exits 1, leaves the redirected file empty, and prints `Traini
 
 For a duration issue, use the reported rows, tokens, epochs, GPU count, and wall time to compare supported options. Gisting publishes full model weights, so only `qwen3-4b` and `qwen3-8b` are supported; switching to the larger 8-GPU tiers is not a valid workaround. Reducing rows can weaken coverage and reducing epochs can weaken compression quality. Do not silently change the requested model, discard data, or alter epochs merely to make the estimate pass. Explain the tradeoff, obtain direction when material, update the draft, re-estimate, and obtain approval for the new quote.
 
-For a ready estimate, report the source, prompt, and selections, training and validation row counts, token totals, maximum GPU seconds, `maximumCharge`, currency, and fingerprint. If the user asked only for an estimate, stop here.
+For a ready estimate, report the source, prompt, slice and split column, training and validation row counts, any rows left out as test, token totals, maximum GPU seconds, `maximumCharge`, currency, and fingerprint. If the user asked only for an estimate, stop here.
 
 ### 6. Run only after explicit cost approval
 

package/src/cli/commands/dataset.ts

@@ -1,6 +1,17 @@
 import { resolve } from "node:path";
 import type { Command } from "commander";
-import { positiveInteger, resolveContext, type CommandHost } from "../context";
+import {
+  collectValues,
+  columnList,
+  fieldList,
+  positiveInteger,
+  resolveContext,
+  splitParts,
+  splitRatios,
+  splitSeed,
+  type CommandHost,
+  type SplitPartSpec,
+} from "../context";
 import {
   createDataset,
   generateDatasetFieldDeclarations,
@@ -8,7 +19,10 @@ import {
   loadDataset,
   uploadDataset,
 } from "../data";
+import { addDatasetFields } from "../fields";
 import { assertProjectSelected } from "../project-context";
+import { createDatasetSlice, listDatasetSlices, showDatasetSlice } from "../slices";
+import { listDatasetColumns, splitDataset, type SplitRatios } from "../splits";
 
 export const registerDatasetCommands = (program: Command, host: CommandHost): void => {
   const { context, globals } = host;
@@ -34,8 +48,11 @@ export const registerDatasetCommands = (program: Command, host: CommandHost): vo
       const result = await createDataset(client, { projectId, name });
       context.io.stdout(result.output);
     });
-  dataset
+  const fields = dataset
     .command("fields")
+    .description("print field declarations inferred from uploaded rows, or add dataset fields from them");
+  fields
+    .command("declarations", { isDefault: true })
     .argument("<name>", "dataset name or id")
     .description("print field declarations inferred from uploaded rows")
     .action(async (name: string) => {
@@ -47,20 +64,57 @@ export const registerDatasetCommands = (program: Command, host: CommandHost): vo
       });
       context.io.stdout(result.output);
     });
+  fields
+    .command("add")
+    .argument("<name>", "dataset name or id")
+    .argument("[fields...]", "top-level fields of the uploaded rows to add as dataset fields")
+    .option("--all", "add every top-level field of the uploaded rows that is not a dataset field yet", false)
+    .option("--no-wait", "return as soon as the fields are added, while their values are still being copied")
+    .option("--timeout <ms>", "how long to wait for the values to be copied", positiveInteger)
+    .option("--json", "print JSON", false)
+    .description(
+      "add dataset fields from fields of the uploaded rows, so filters, --balance-by and split columns can use their values; uploads after this fill them too",
+    )
+    .action(
+      async (
+        name: string,
+        names: string[],
+        options: { all: boolean; wait: boolean; timeout?: number; json: boolean },
+      ) => {
+        const { sourceRoot, client, projectId } = await resolveContext(globals(), context);
+        const result = await addDatasetFields(client, {
+          sourceRoot,
+          datasetName: name,
+          fields: names,
+          all: options.all,
+          wait: options.wait,
+          json: options.json,
+          ...(projectId === undefined ? {} : { projectId }),
+          ...(options.timeout === undefined ? {} : { waitFor: { timeoutMs: options.timeout } }),
+        });
+        context.io.stdout(result.output);
+      },
+    );
   dataset
     .command("load")
     .argument("<name>", "dataset name or id")
     .requiredOption("--out <file>", "JSONL file to write")
+    .option(
+      "--fields <fields>",
+      "comma-separated dataset fields to write (default: every field); uploaded holds each uploaded row whole, as one value",
+      fieldList,
+    )
     .option("--limit <n>", "how many rows to keep after download", positiveInteger)
     .option("--timeout <ms>", "how long to wait for the export", positiveInteger)
-    .description("download live dataset rows into a JSONL file")
-    .action(async (name: string, options: { out: string; limit?: number; timeout?: number }) => {
+    .description("download live dataset rows into a JSONL file, one object of the chosen fields per row")
+    .action(async (name: string, options: { out: string; fields?: string[]; limit?: number; timeout?: number }) => {
       const { sourceRoot, client, projectId } = await resolveContext(globals(), context);
       const result = await loadDataset(client, {
         sourceRoot,
         datasetName: name,
         outPath: resolve(options.out),
         ...(projectId === undefined ? {} : { projectId }),
+        ...(options.fields === undefined ? {} : { fields: options.fields }),
         ...(options.limit === undefined ? {} : { limit: options.limit }),
         ...(options.timeout === undefined ? {} : { timeoutMs: options.timeout }),
       });
@@ -82,4 +136,154 @@ export const registerDatasetCommands = (program: Command, host: CommandHost): vo
       context.io.stdout(result.output);
       if (result.warning !== undefined) context.io.stderr(result.warning);
     });
+
+  const slice = dataset
+    .command("slice")
+    .description("freeze the rows of a dataset, with chosen columns read as they were then");
+  slice
+    .command("create")
+    .argument("<name>", "dataset name or id")
+    .option("--name <name>", "a name to tell slices apart (default Slice 1, Slice 2 and so on)")
+    .option(
+      "--filter <field=value>",
+      "freeze only rows whose field equals the value; repeat for more fields (default: every row)",
+      collectValues,
+    )
+    .option("--from <slice-id>", "take an earlier slice again with its filter, picking up rows added or changed since")
+    .option(
+      "--freeze <columns>",
+      "comma-separated columns read as they were at the cutoff (default: every column); split columns are always frozen",
+      columnList,
+    )
+    .option("--no-wait", "return as soon as the slice starts")
+    .option("--timeout <ms>", "how long to wait for the rows to be frozen", positiveInteger)
+    .option("--json", "print JSON", false)
+    .description("freeze the rows that match a filter, or every row, so the same slice always selects the same rows")
+    .action(
+      async (
+        name: string,
+        options: {
+          name?: string;
+          filter?: string[];
+          from?: string;
+          freeze?: string[];
+          wait: boolean;
+          timeout?: number;
+          json: boolean;
+        },
+      ) => {
+        const { sourceRoot, client, projectId } = await resolveContext(globals(), context);
+        const { timeout, filter, ...forwarded } = options;
+        const result = await createDatasetSlice(client, {
+          sourceRoot,
+          datasetName: name,
+          projectId,
+          ...forwarded,
+          ...(filter === undefined ? {} : { filters: filter }),
+          ...(timeout === undefined ? {} : { waitFor: { timeoutMs: timeout } }),
+        });
+        context.io.stdout(result.output);
+      },
+    );
+  slice
+    .command("list")
+    .argument("<name>", "dataset name or id")
+    .description("list the slices of a dataset, newest first")
+    .action(async (name: string) => {
+      const { sourceRoot, client, projectId } = await resolveContext(globals(), context);
+      const result = await listDatasetSlices(client, {
+        sourceRoot,
+        datasetName: name,
+        ...(projectId === undefined ? {} : { projectId }),
+      });
+      context.io.stdout(result.output);
+    });
+  slice
+    .command("show")
+    .argument("<slice-id>", "slice id (dsl.…)")
+    .option("--json", "print JSON", false)
+    .description("show the status, filter, frozen columns and row count of a slice")
+    .action(async (sliceId: string, options: { json: boolean }) => {
+      const { client } = await resolveContext(globals(), context);
+      const result = await showDatasetSlice(client, { sliceId, json: options.json });
+      context.io.stdout(result.output);
+    });
+
+  dataset
+    .command("split")
+    .argument("<name>", "dataset name or id")
+    .option(
+      "--column <name>",
+      "split column to fill: a new name creates it, an existing split column gets its empty cells filled, an ordinary column whose values are part names becomes a split column (default split)",
+    )
+    .option(
+      "--ratios <train/validate/test>",
+      "whole percentages that add up to 100 (default 80/10/10 for a new column, then the column's own shares)",
+      splitRatios,
+    )
+    .option(
+      "--parts <parts>",
+      "parts as name[=roles][:percent], for example train:70,dev=validate:10,holdout=test:20; without percentages the column's values name the parts",
+      splitParts,
+    )
+    .option(
+      "--validate-on-test",
+      "the test part is also the validation set, common when data is scarce; needs a validate ratio of 0, for example --ratios 80/0/20",
+      false,
+    )
+    .option("--balance-by <field>", "label column to balance: every label value is split by the shares")
+    .option("--seed <n>", "seed for the row order; generated when omitted, then kept by the column", splitSeed)
+    .option("--filter <field=value>", "place only rows whose field equals the value; repeat for more fields", collectValues)
+    .option("--slice <slice-id>", "place only the rows of this slice")
+    .option("--no-wait", "return as soon as placing starts")
+    .option("--timeout <ms>", "how long to wait for the rows to be placed", positiveInteger)
+    .option("--json", "print JSON", false)
+    .description(
+      "put every row without a part in one, sampled by share; rows that already have a part keep it, so test rows stay test as the dataset grows",
+    )
+    .action(
+      async (
+        name: string,
+        options: {
+          column?: string;
+          ratios?: SplitRatios;
+          parts?: SplitPartSpec[];
+          validateOnTest: boolean;
+          balanceBy?: string;
+          seed?: number;
+          filter?: string[];
+          slice?: string;
+          wait: boolean;
+          timeout?: number;
+          json: boolean;
+        },
+      ) => {
+        const { sourceRoot, client, projectId } = await resolveContext(globals(), context);
+        const { timeout, filter, ...forwarded } = options;
+        const result = await splitDataset(client, {
+          sourceRoot,
+          datasetName: name,
+          projectId,
+          ...forwarded,
+          ...(filter === undefined ? {} : { filters: filter }),
+          ...(timeout === undefined ? {} : { waitFor: { timeoutMs: timeout } }),
+        });
+        context.io.stdout(result.output);
+      },
+    );
+  dataset
+    .command("columns")
+    .argument("<name>", "dataset name or id")
+    .option("--json", "print JSON", false)
+    .description("list the columns of a dataset, with the parts and roles of split columns")
+    .action(async (name: string, options: { json: boolean }) => {
+      const { sourceRoot, client, projectId } = await resolveContext(globals(), context);
+      const result = await listDatasetColumns(client, {
+        sourceRoot,
+        datasetName: name,
+        json: options.json,
+        ...(projectId === undefined ? {} : { projectId }),
+      });
+      context.io.stdout(result.output);
+    });
 };

package/src/cli/commands/training.ts

@@ -1,5 +1,6 @@
 import type { Command } from "commander";
 import {
+  partNames,
   positiveInteger,
   resolveContext,
   trainingBatchSize,
@@ -59,10 +60,13 @@ export const registerTrainingCommands = (program: Command, host: CommandHost): v
     .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(
+      "--dataset <name-or-id>",
+      "Dataset to train on: fills the empty cells of its split column (a new split column, 80/10/10, when it has none) and freezes a slice named after the Training; pass --dataset or --slice",
+    )
+    .option("--slice <id>", "ready Dataset Slice that freezes a split column; pass --dataset or --slice")
+    .option("--split-column <name-or-id>", "split column to train with, when the dataset has more than one")
+    .option("--parts <names>", "train parts to learn on, comma-separated (default: every part with the train role)", partNames)
     .option("--lora-rank <rank>", "SFT LoRA adapter rank: 8, 16, or 32 (default 16)", trainingLoraRank)
     .option(
       "--gist-tokens <count>",
@@ -89,12 +93,13 @@ export const registerTrainingCommands = (program: Command, host: CommandHost): v
     .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);
+      const { sourceRoot, client, projectId } = await resolveContext(globals(), context);
       assertProjectSelected(projectId);
       await createTraining(
         client,
         {
           ...trainingDraftOptions(options),
+          sourceRoot,
           projectId,
           name,
           json: options.json,
@@ -107,13 +112,13 @@ export const registerTrainingCommands = (program: Command, host: CommandHost): v
     .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",
+      "--dataset <name-or-id>",
+      "split the Dataset again and freeze a new slice named after the Training: rows added since get parts, rows that had one keep it",
     )
+    .option("--slice <id>", "replacement ready Dataset Slice that freezes a split column")
+    .option("--split-column <name-or-id>", "split column to train with, when the slice freezes more than one")
+    .option("--parts <names>", "train parts to learn on, comma-separated (default: every part with the train role)", partNames)
     .option("--lora-rank <rank>", "SFT LoRA adapter rank: 8, 16, or 32 (default 16)", trainingLoraRank)
     .option(
       "--gist-tokens <count>",
@@ -140,12 +145,13 @@ export const registerTrainingCommands = (program: Command, host: CommandHost): v
     .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);
+      const { sourceRoot, client, projectId } = await resolveContext(globals(), context);
       assertProjectSelected(projectId);
       await updateTraining(
         client,
         {
           ...trainingDraftOptions(options),
+          sourceRoot,
           projectId,
           nameOrId,
           json: options.json,

package/src/cli/context.ts

@@ -125,6 +125,88 @@ export const trainingGistTokens = (raw: string): 8 | 32 | 64 | "1/4" | "1/8" | "
   return value;
 };
 
+export const splitRatios = (raw: string): { train: number; validate: number; test: number } => {
+  const parts = raw.split("/").map(Number);
+  const [train, validate, test] = parts;
+  if (
+    parts.length !== 3 ||
+    !parts.every((part) => Number.isInteger(part) && part >= 0) ||
+    train === undefined ||
+    validate === undefined ||
+    test === undefined ||
+    train + validate + test !== 100
+  ) {
+    throw new InvalidArgumentError(
+      "Expected train/validate/test whole percentages that add up to 100, for example 80/10/10.",
+    );
+  }
+  return { train: train / 100, validate: validate / 100, test: test / 100 };
+};
+
+export const collectValues = (value: string, previous: readonly string[] = []): string[] => [...previous, value];
+
+const nameList =
+  (noun: string) =>
+  (raw: string): string[] => {
+    const names = raw
+      .split(",")
+      .map((name) => name.trim())
+      .filter((name) => name.length > 0);
+    if (names.length === 0) {
+      throw new InvalidArgumentError(`Expected one or more ${noun} names separated by commas, for example text,intent.`);
+    }
+    return names;
+  };
+
+export const columnList = nameList("column");
+
+export const fieldList = nameList("field");
+
+const SPLIT_PART_ROLES = ["train", "validate", "test"] as const;
+
+type SplitPartRole = (typeof SPLIT_PART_ROLES)[number];
+
+export type SplitPartSpec = { readonly name: string; readonly roles: SplitPartRole[]; readonly share?: number };
+
+const isSplitPartRole = (value: string): value is SplitPartRole => SPLIT_PART_ROLES.some((role) => role === value);
+
+export const splitParts = (raw: string): SplitPartSpec[] =>
+  raw.split(",").map((entry) => {
+    const [part = "", percentText] = entry.trim().split(":");
+    const [name = "", roleText = name] = part.split("=");
+    const roles = roleText === "none" ? [] : roleText.split("+");
+    const percent = percentText === undefined ? undefined : Number(percentText);
+    if (
+      name.length === 0 ||
+      !roles.every(isSplitPartRole) ||
+      (percent !== undefined && !(Number.isInteger(percent) && percent >= 1 && percent <= 100))
+    ) {
+      throw new InvalidArgumentError(
+        "Expected parts as name[=roles][:percent], with roles train, validate, test, validate+test or none, for example train:80,dev=validate:10,test:10.",
+      );
+    }
+    return { name, roles, ...(percent === undefined ? {} : { share: percent / 100 }) };
+  });
+
+export const partNames = (raw: string): string[] => {
+  const names = raw
+    .split(",")
+    .map((name) => name.trim())
+    .filter((name) => name.length > 0);
+  if (names.length === 0) {
+    throw new InvalidArgumentError("Expected one or more part names separated by commas, for example train.");
+  }
+  return names;
+};
+
+export const splitSeed = (raw: string): number => {
+  const value = Number(raw);
+  if (!Number.isInteger(value) || value < 0 || value > 2_147_483_647) {
+    throw new InvalidArgumentError("Expected a whole seed from 0 through 2147483647.");
+  }
+  return value;
+};
+
 export const trainingEpochs = (raw: string): number => {
   const value = Number(raw);
   if (!Number.isInteger(value) || value < 1 || value > 5) {
@@ -162,9 +244,9 @@ export type RawTrainingDraftOptions = {
   baseModel?: TrainingDraftOptions["baseModelId"];
   modelVersion?: string;
   dataset?: string;
-  validationDataset?: string;
-  trainFilter?: string;
-  validationFilter?: string;
+  slice?: string;
+  splitColumn?: string;
+  parts?: string[];
   loraRank?: TrainingDraftOptions["loraRank"];
   gistTokens?: TrainingDraftOptions["gistTokens"];
   epochs?: number;
@@ -178,10 +260,10 @@ export const trainingDraftOptions = (options: RawTrainingDraftOptions): Training
   method: options.method,
   baseModelId: options.baseModel,
   modelVersionId: options.modelVersion,
-  datasetId: options.dataset,
-  validationDatasetId: options.validationDataset,
-  trainingFilter: options.trainFilter,
-  validationFilter: options.validationFilter,
+  datasetName: options.dataset,
+  sliceId: options.slice,
+  splitColumn: options.splitColumn,
+  trainParts: options.parts,
   loraRank: options.loraRank,
   gistTokens: options.gistTokens,
   epochs: options.epochs,