@toloka-platform/sdk 0.1.0-preview.3

package/openapi/gen/models/validatePipelineGraphBodyGraphNodesItemOneOfThreeoneSettingsOnboardingStepsItemBlocksItemOneOfTwooneContentItem.ts

@@ -0,0 +1,5 @@
+
+export type ValidatePipelineGraphBodyGraphNodesItemOneOfThreeoneSettingsOnboardingStepsItemBlocksItemOneOfTwooneContentItem = {
+  type: 'markdown';
+  value: string;
+};

package/openapi/gen/models/validatePipelineGraphBodyGraphNodesItemOneOfThreeoneSettingsQualityAssurance.ts

@@ -0,0 +1,5 @@
+import type { ValidatePipelineGraphBodyGraphNodesItemOneOfThreeoneSettingsQualityAssuranceOneOf } from './validatePipelineGraphBodyGraphNodesItemOneOfThreeoneSettingsQualityAssuranceOneOf';
+import type { ValidatePipelineGraphBodyGraphNodesItemOneOfThreeoneSettingsQualityAssuranceOneOfThree } from './validatePipelineGraphBodyGraphNodesItemOneOfThreeoneSettingsQualityAssuranceOneOfThree';
+import type { ValidatePipelineGraphBodyGraphNodesItemOneOfThreeoneSettingsQualityAssuranceOneOfFour } from './validatePipelineGraphBodyGraphNodesItemOneOfThreeoneSettingsQualityAssuranceOneOfFour';
+
+export type ValidatePipelineGraphBodyGraphNodesItemOneOfThreeoneSettingsQualityAssurance = ValidatePipelineGraphBodyGraphNodesItemOneOfThreeoneSettingsQualityAssuranceOneOf | ValidatePipelineGraphBodyGraphNodesItemOneOfThreeoneSettingsQualityAssuranceOneOfThree | ValidatePipelineGraphBodyGraphNodesItemOneOfThreeoneSettingsQualityAssuranceOneOfFour;

package/openapi/gen/models/validatePipelineGraphBodyGraphNodesItemOneOfThreeoneSettingsQualityAssuranceOneOf.ts

@@ -0,0 +1,6 @@
+import type { ValidatePipelineGraphBodyGraphNodesItemOneOfThreeoneSettingsQualityAssuranceOneOfLlmQaModelId } from './validatePipelineGraphBodyGraphNodesItemOneOfThreeoneSettingsQualityAssuranceOneOfLlmQaModelId';
+
+export type ValidatePipelineGraphBodyGraphNodesItemOneOfThreeoneSettingsQualityAssuranceOneOf = {
+  qaMode: 'llm_only';
+  llmQaModelId?: ValidatePipelineGraphBodyGraphNodesItemOneOfThreeoneSettingsQualityAssuranceOneOfLlmQaModelId;
+};

package/openapi/gen/models/validatePipelineGraphBodyGraphNodesItemOneOfThreeoneSettingsQualityAssuranceOneOfFour.ts

@@ -0,0 +1,8 @@
+import type { ValidatePipelineGraphBodyGraphNodesItemOneOfThreeoneSettingsQualityAssuranceOneOfFourLlmQaModelId } from './validatePipelineGraphBodyGraphNodesItemOneOfThreeoneSettingsQualityAssuranceOneOfFourLlmQaModelId';
+
+export type ValidatePipelineGraphBodyGraphNodesItemOneOfThreeoneSettingsQualityAssuranceOneOfFour = {
+  qaMode: 'hybrid';
+  smartSamplingPercent?: number;
+  humanQaTimeForTask?: number;
+  llmQaModelId?: ValidatePipelineGraphBodyGraphNodesItemOneOfThreeoneSettingsQualityAssuranceOneOfFourLlmQaModelId;
+};

package/openapi/gen/models/validatePipelineGraphBodyGraphNodesItemOneOfThreeoneSettingsQualityAssuranceOneOfFourLlmQaModelId.ts

@@ -0,0 +1,2 @@
+
+export type ValidatePipelineGraphBodyGraphNodesItemOneOfThreeoneSettingsQualityAssuranceOneOfFourLlmQaModelId = 'gpt-5.4' | 'gpt-5.4-mini' | 'gpt-5' | 'gpt-5-mini' | 'claude-sonnet-4-6';

package/openapi/gen/models/validatePipelineGraphBodyGraphNodesItemOneOfThreeoneSettingsQualityAssuranceOneOfLlmQaModelId.ts

@@ -0,0 +1,2 @@
+
+export type ValidatePipelineGraphBodyGraphNodesItemOneOfThreeoneSettingsQualityAssuranceOneOfLlmQaModelId = 'gpt-5.4' | 'gpt-5.4-mini' | 'gpt-5' | 'gpt-5-mini' | 'claude-sonnet-4-6';

package/openapi/gen/models/validatePipelineGraphBodyGraphNodesItemOneOfThreeoneSettingsQualityAssuranceOneOfThree.ts

@@ -0,0 +1,6 @@
+
+export type ValidatePipelineGraphBodyGraphNodesItemOneOfThreeoneSettingsQualityAssuranceOneOfThree = {
+  qaMode: 'human_only';
+  smartSamplingPercent?: number;
+  humanQaTimeForTask?: number;
+};

package/openapi/gen/models/validatePipelineGraphBodyGraphNodesItemOneOfThreeoneSettingsQualityCriteriaItem.ts

@@ -0,0 +1,9 @@
+import type { ValidatePipelineGraphBodyGraphNodesItemOneOfThreeoneSettingsQualityCriteriaItemThresholds } from './validatePipelineGraphBodyGraphNodesItemOneOfThreeoneSettingsQualityCriteriaItemThresholds';
+
+export type ValidatePipelineGraphBodyGraphNodesItemOneOfThreeoneSettingsQualityCriteriaItem = {
+  id: string;
+  qualityElement: string;
+  thresholds: ValidatePipelineGraphBodyGraphNodesItemOneOfThreeoneSettingsQualityCriteriaItemThresholds;
+  targetEntity: string;
+  llmQaInstruction?: string;
+};

package/openapi/gen/models/validatePipelineGraphBodyGraphNodesItemOneOfThreeoneSettingsQualityCriteriaItemThresholds.ts

@@ -0,0 +1,5 @@
+
+export type ValidatePipelineGraphBodyGraphNodesItemOneOfThreeoneSettingsQualityCriteriaItemThresholds = {
+  pass: string;
+  fail: string;
+};

package/openapi/gen/models/validatePipelineGraphBodyGraphNodesItemOneOfThreeoneSettingsReuseAudienceWithNodeId.ts

@@ -0,0 +1,3 @@
+import type { ValidatePipelineGraphBodyGraphNodesItemOneOfThreeoneSettingsReuseAudienceWithNodeIdAnyOf } from './validatePipelineGraphBodyGraphNodesItemOneOfThreeoneSettingsReuseAudienceWithNodeIdAnyOf';
+
+export type ValidatePipelineGraphBodyGraphNodesItemOneOfThreeoneSettingsReuseAudienceWithNodeId = ValidatePipelineGraphBodyGraphNodesItemOneOfThreeoneSettingsReuseAudienceWithNodeIdAnyOf | null;

package/openapi/gen/models/validatePipelineGraphBodyGraphNodesItemOneOfThreeoneSettingsReuseAudienceWithNodeIdAnyOf.ts

@@ -0,0 +1,5 @@
+
+export type ValidatePipelineGraphBodyGraphNodesItemOneOfThreeoneSettingsReuseAudienceWithNodeIdAnyOf = {
+  pipelineId: string;
+  nodeId: string;
+};

package/openapi/gen/models/validatePipelineGraphBodyGraphNodesItemOneOfThreeoneSettingsSmartSearch.ts

@@ -0,0 +1,3 @@
+import type { ValidatePipelineGraphBodyGraphNodesItemOneOfThreeoneSettingsSmartSearchAnyOf } from './validatePipelineGraphBodyGraphNodesItemOneOfThreeoneSettingsSmartSearchAnyOf';
+
+export type ValidatePipelineGraphBodyGraphNodesItemOneOfThreeoneSettingsSmartSearch = ValidatePipelineGraphBodyGraphNodesItemOneOfThreeoneSettingsSmartSearchAnyOf | null;

package/openapi/gen/models/validatePipelineGraphBodyGraphNodesItemOneOfThreeoneSettingsSmartSearchAnyOf.ts

@@ -0,0 +1,12 @@
+import type { ValidatePipelineGraphBodyGraphNodesItemOneOfThreeoneSettingsSmartSearchAnyOfProjectDescription } from './validatePipelineGraphBodyGraphNodesItemOneOfThreeoneSettingsSmartSearchAnyOfProjectDescription';
+
+export type ValidatePipelineGraphBodyGraphNodesItemOneOfThreeoneSettingsSmartSearchAnyOf = {
+  briefDescription: string;
+  projectDescription: ValidatePipelineGraphBodyGraphNodesItemOneOfThreeoneSettingsSmartSearchAnyOfProjectDescription;
+  extraHardRequirements: string[];
+  relevanceCriteria: string[];
+  typicalJobTitles: string[];
+  idealCandidateProfile: string;
+  whoIsNotAFit: string[];
+  sourceFingerprint?: string;
+};

package/openapi/gen/models/validatePipelineGraphBodyGraphNodesItemOneOfThreeoneSettingsSmartSearchAnyOfProjectDescription.ts

@@ -0,0 +1,2 @@
+
+export type ValidatePipelineGraphBodyGraphNodesItemOneOfThreeoneSettingsSmartSearchAnyOfProjectDescription = string | null;

package/openapi/gen/models/validatePipelineGraphBodyGraphNodesItemOneOfThreeoneSettingsUi.ts

@@ -0,0 +1,8 @@
+
+export type ValidatePipelineGraphBodyGraphNodesItemOneOfThreeoneSettingsUi = {
+  code: string;
+  data: string;
+  preprocess: string;
+  postprocess?: string;
+  constants: string;
+};

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@toloka-platform/sdk",
+  "version": "0.1.0-preview.3",
+  "private": false,
+  "description": "Preview. Build, inspect, and operate Toloka pipeline projects as TypeScript source. The public API may change.",
+  "license": "Apache-2.0",
+  "bin": {
+    "toloka": "dist/cli/toloka.js"
+  },
+  "files": [
+    "README.md",
+    "docs",
+    "dist",
+    "examples",
+    "openapi/gen",
+    "skills",
+    "src"
+  ],
+  "type": "module",
+  "main": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./examples/face-image-collection": "./examples/face-image-collection/pipeline.ts"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/",
+    "tag": "preview"
+  },
+  "scripts": {
+    "build": "bun ./scripts/build-cli.ts ./dist/cli",
+    "generate": "orval --config ./openapi/orval.config.js",
+    "prepack": "bun run build",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@inquirer/select": "5.2.1",
+    "ajv": "8.17.1",
+    "ajv-formats": "3.0.1",
+    "commander": "15.0.0",
+    "es-toolkit": "1.42.0",
+    "posthog-node": "5.46.1"
+  },
+  "devDependencies": {
+    "@types/node": "24.10.1",
+    "orval": "7.17.0",
+    "typescript": "7.0.2",
+    "vitest": "4.1.0",
+    "yaml": "2.9.0"
+  },
+  "engines": {
+    "bun": "1.4.0"
+  }
+}

package/skills/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: toloka-build
+description: Build, inspect, and change Toloka platform pipeline projects as TypeScript source with @toloka-platform/sdk and toloka. Use when the user wants to create, adopt, inspect, plan, or apply a pipeline project as code.
+---
+
+# Build Toloka pipelines as code
+
+This SDK is Preview software. The authoring API, the CLI, and generated source can change. Do not invent helpers or flags that are not in the installed package.
+
+Use this skill when the user wants to create, inspect, or change a Toloka pipeline project as code. Work in the project source tree; do not translate the request into direct platform API calls.
+
+## Follow the reconciliation loop
+
+1. Read `toloka.json` when present, then read the relevant `pipelines/**/pipeline.ts` module and everything it imports.
+2. Edit the TypeScript source. Treat it as authoritative desired state.
+3. Run the project's typecheck, then validate each changed pipeline against the platform:
+   ```sh
+   bunx tsc --noEmit
+   toloka validate
+   ```
+4. Run `toloka plan`. Read the complete diff and resolve every conflict or missing prerequisite.
+5. Run `toloka apply`. Apply only after the plan matches the request.
+6. Run `toloka plan` again and require `No changes.`
+
+The CLI reads source, compares it with live state, and reconciles the platform. Edit files; never mutate a pipeline through raw HTTP, SDK client methods, or internal platform tool calls. Do not make a live edit and then reverse-engineer it into source.
+
+## Orient before editing
+
+Use the directory containing `toloka.json` as the source root. Commands default to the current directory; use `--source-root <directory>` from elsewhere.
+
+- If `toloka.json` exists, read it as CLI-managed identity state. It maps the project, pipeline source directories, and dataset names to live IDs. Do not hand-edit it.
+- If it is absent and the user is adopting an existing project, run `toloka project add <alias> <projectId>`, then `toloka import` in the intended source root. Import refuses an existing `pipelines/` directory unless you pass `--force`.
+- If it is absent and the user is authoring from scratch, run `toloka project create <alias>`. Create `pipelines/<name>/pipeline.ts`, then run `toloka plan` and `toloka apply`.
+
+Never assume a project ID from conversation context. Resolve it from `--project-id`, `TOLOKA_PROJECT_ID` / `POTATO_PROJECT_ID`, `toloka.json`, or `toloka project current`.
+
+## Author with the typed graph API
+
+Import authoring helpers from `@toloka-platform/sdk`.
+
+- Declare every data contract once with `field(name, jsonSchema)`.
+- Use exactly these constructors: `root`, `code`, `generation`, `match`, and `quorum`.
+- Connect typed ports with `connect(from, to)`: `started`, `completed`, `input`, `output`, `matchNode.matched(0)`, and `default`.
+- Export a default `definePipeline({ dataset, fields, nodes, connections })` from every `pipelines/**/pipeline.ts`.
+- Keep the graph acyclic. Put review, retry, training, exam, appeal, and payment behavior in the owning human-work node rather than adding loop nodes.
+
+Let constructors mint IDs for new declarations. Preserve `id` options generated by `toloka import`, but never invent or hand-edit raw `fp_…`, `ds.…`, `pl.…`, or `pp.…` values in authored settings. Never add a `layout` block: layout is not authored, existing layout is preserved, and the server supplies defaults.
+
+Read [node semantics](references/node-semantics.md) before selecting or configuring a node. Use the published [face image collection example](../examples/face-image-collection/) as a concrete authoring pattern.
+
+## Get human-work settings right the first time
+
+These are server rules that `definePipeline` does not check. Each one costs an apply or a failed deployment to discover.
+
+- **Do not pair `projectType: 'general'` with `verifiedExperts: false`.** The server answers `General projects require an ID-verified audience`. Specializations also require a verified audience.
+- **Training is part of the node, not extra.** A quorum node requires `onboarding`, and while it is enabled the platform wants at least three steps and at least one quiz block. Preserve an explicit `enabled: false` that a user or `toloka import` put there; never switch Training on to satisfy your own sense of completeness.
+- **Run scope belongs to the platform.** `itemFilter` and `itemLimit` on the root node are set from the platform, and apply preserves whatever is live unless source declares its own value. Do not add an item limit to source to "restore" one you saw in the UI.
+
+## Know the validation boundary
+
+`definePipeline` and typed ports check local declaration and connection invariants. The published JSON contract is still available as `validate(graph)` for importer and fixture tests; it makes no server call.
+
+`toloka validate` posts each bound pipeline graph to `POST /pipelines/:pipelineId/graph/validate`. That is the platform's spec validation plus the latest matching check jobs. It does not write the graph. Pipelines that have not been applied yet are skipped until `toloka apply` creates them.
+
+A successful `toloka validate` is necessary, not proof the pipeline can be launched. The labeler UI on a human-work node still needs a fresh successful validation receipt after every UI edit, and some per-node checks must be started separately. When apply succeeds but deployment is refused, stop and hand off to the platform UI for that node instead of editing source in circles.
+
+## Keep data and credentials out of source
+
+- Never put dataset items in pipeline source or `toloka.json`. After apply has created or resolved the dataset, upload JSONL objects with `toloka dataset upload <dataset> <file>`. If a later upload fails as schema-incompatible, run `toloka dataset fields <dataset>` and copy the printed `field()` declarations into source.
+- Put secret references in node settings, but never secret values. Set values through stdin with `toloka secret set <name>`, or use `toloka secret set <name> --from-env <variable>`.
+
+## Credentials
+
+`toloka login` verifies an API key and stores it with owner-only permissions, so no later command needs
+`--api-key`. Precedence is flag, then environment variable (`POTATO_API_KEY`, `POTATO_BASE_URL`), then
+that file. `toloka auth-status` reports what is in effect and where it came from; `toloka logout`
+removes it. If a command reports missing credentials, run `toloka login`; never invent a key.
+Anonymous command telemetry is on by default; set `TOLOKA_TELEMETRY=0` or `DO_NOT_TRACK=1` to disable it.
+
+## Recover from expected failures
+
+- **Dataset field schema conflict:** Stop trying to edit the field. Dataset fields are immutable after creation: they can be added, never altered or removed. Declare a new column name with the wanted schema, or bind the pipeline to a new dataset, then plan again.
+- **Missing secret:** Set every name listed by plan with `toloka secret set <name>`, keep the value out of files and shell arguments, then rerun plan and apply.
+- **409 stale version:** Another writer changed the graph after it was read. Do not retry blindly. Run `toloka plan` to re-read live state, review the new diff, preserve intentional remote changes in source when needed, then run `toloka apply` again.
+
+## Run a deployed pipeline
+
+Start a run with `toloka pipeline run <name> --wait --timeout <ms>`, then read its exit code: `0` succeeded, `1` reached a failed terminal state, `2` still running when the window closed. Without `--wait`, exit `0` only means the run was accepted. Nothing reports back later, so never describe a started run as a finished one. Name the live pipeline; there is no implicit only-pipeline.
+
+Always bound the wait. A queue with no one working it stays in progress indefinitely, so an unbounded poll loop ends with you killed and reporting nothing. On exit `2`, stop waiting and report what you observed: item counts, current states, and that the run had not finished. A bounded honest report beats an unbounded silent wait. Use `toloka pipeline status <name>` and `toloka pipeline results <runId> --failed` for counts, states, and errors. `toloka status` (no prefix) is project health, not the latest run.
+
+Deliver that report in the same reply that does the work. There is no later turn and no background poller that will speak for you: if you end by promising to report once a window closes, the observation is lost and the work counts for nothing. Poll in the foreground, then state what you saw before you finish.
+
+Read [workflow and CLI recipes](references/workflow-and-cli.md) for source layout, configuration precedence, adoption, scratch authoring, upload, secret, run, multi-project, and recovery details.

package/skills/references/node-semantics.md

@@ -0,0 +1,291 @@
+# Node semantics
+
+Use this reference to decide the smallest correct graph, then edit the node's TypeScript source and reconcile it with `toloka plan` and `toloka apply`. Configure only properties accepted by the exported authoring types; do not translate an internal platform operation into a made-up SDK method.
+
+## Decide the graph before configuring it
+
+Choose by behavior, not by the data format:
+
+- Choose `root` once, to bind dataset columns into and out of the pipeline.
+- Choose `code` for deterministic transforms, filtering, parsing, math, string work, scripts, HTTP calls, and programmatic LLM calls such as classification, summarization, or extraction.
+- Choose `generation` when a person or synthetic generator produces one annotation: image, video, or audio annotation; text writing or rewriting; ranking, rating, comparison, validation, correction, or original-content collection.
+- Choose `quorum` when the same item must go independently to a fixed number of human labelers and the collected disagreement is part of the result. Typical tasks are classification, rating, and short labels.
+- Choose `match` for if/then/else routing by predicates. Do not use it for parallel fan-out.
+
+**Cycles live inside components, not in the graph.** Keep the authored graph acyclic. “Add a QA step,” “add a review loop,” and “add a redo” mean configure the owning `generation` node. Its QA, sampling, redo, appeal, and payment-retry cycles are internal behavior, not downstream nodes. Post-generation graph work is either deterministic `code` or predicate routing with `match`.
+
+**Training and Exam are stages of the same `generation` or `quorum` node.** Configure `onboarding` and optional `exam` in that node's settings. Never create separate Training, Exam, UI, review, or redo nodes, and never invent extra expert labor to represent those stages.
+
+## Ports and connections
+
+Use the typed node properties; never write handle strings yourself:
+
+| Node | Input | Output |
+| --- | --- | --- |
+| `root` | `collection.completed` | `collection.started` |
+| `code` | `transform.input` | `transform.output` |
+| `generation` | `annotate.input` | `annotate.output` |
+| `quorum` | `rate.input` | `rate.output` |
+| `match` | `route.input` | `route.matched(0)`, `route.matched(1)`, …, `route.default` |
+
+Connect them in the direction of data flow:
+
+```ts
+connect(collection.started, transform.input)
+connect(transform.output, route.input)
+connect(route.matched(0), annotate.input)
+connect(annotate.output, collection.completed)
+```
+
+`match.matched(index)` corresponds by index to `settings.conditions[index]`. The first matching condition wins; `default` receives items that match none.
+
+## `root`
+
+### Pick and configure it
+
+Create exactly one `root` node. Use `started` for dataset fields the pipeline reads and `completed` for fields it writes back to the same dataset. A completed field is not a separate output destination: the platform creates or uses that dataset column per item.
+
+The public authoring shape is `RootAuthoringSettings`:
+
+- `started`: fields exposed through the `started` output port.
+- `completed`: fields accepted through the `completed` input port and written to the dataset.
+- Each entry can be a `Field` or `{ field, optional }`; a bare `Field` is required.
+- `itemLimit` exists in both `RootNodeSettings` and `RootAuthoringSettings`. Do not invent a limit; author one only when the user explicitly requests a bounded test or batch. Apply preserves a live `itemLimit` unless source declares its own.
+
+
+The dataset name belongs in `definePipeline({ dataset: 'name', ... })`, not in the root settings. `toloka apply` resolves or creates the named dataset and supplies its ID.
+
+### Traps
+
+- Do not author `datasetId` or `itemFilter`; `RootAuthoringSettings` omits both. `toloka apply` binds the dataset and preserves the live `itemFilter` and `itemLimit` unless source declares its own `itemLimit`. Do not add a limit to source to restore one you saw in the UI.
+
+- Do not put a field in `completed` unless the final connected branch actually produces it.
+- Declare every referenced `Field` in `definePipeline({ fields })`.
+- Dataset fields are immutable after creation. You may add a column, never alter or remove one. On a schema conflict, use a new column name or a new dataset.
+
+## `code`
+
+### Pick it
+
+Use `code` whenever the result can be computed from inputs without a human task. This includes deterministic transforms, ETL, filtering, parsing, arithmetic, string manipulation, scripts, HTTP APIs, and LLM API calls. An LLM call made programmatically is still `code`; choose `generation` only when the platform's human or synthetic generation journey is wanted.
+
+Use a downstream `code` node after `quorum` only when the user asks for a derived consensus value such as majority vote, average, or deduplication. Quorum itself returns raw collected annotations.
+
+### Configure it
+
+Set `CodeAuthoringSettings`, derived from `CodeNodeSettings`, through `code(name, settings)`:
+
+- `about`: node `name`, optional `description`, and optional `projectType`.
+- `fieldProxies.input` and `.output`: `{ field, optional }` references to declared `Field` objects.
+- `code.code`: Python source.
+- `envVars`: optional static values or secret bindings:
+  - `{ type: 'static', name, value }`
+  - `{ type: 'secret', name, secretName }`
+- `checks`: optional source-held code check cases grouped by check type.
+
+Write Python with this exact entry contract:
+
+```py
+from main_types import Inputs, Outputs
+
+async def main(inputs: Inputs) -> Outputs:
+    return {"normalized": inputs["raw_text"].strip()}
+```
+
+The sandbox generates `main_types.py` from the bound fields. Read and return keys by `field()` name, not by minted field ID. Return every required output key; an optional output may be omitted.
+
+For third-party SDKs that read the environment implicitly, bind every needed variable in `envVars`. Reference project secrets by name and set their values separately with `toloka secret set <name>`; use `os.environ['NAME']` in Python. The sandbox has no ambient credentials.
+
+### Traps
+
+- Do not use a human node for deterministic work merely because an LLM is involved.
+- Do not omit `async`, the single `inputs` parameter, `Inputs`/`Outputs` annotations, or the `main_types` import.
+- Do not return field IDs or arbitrary keys. Output keys must match output field names.
+- Do not put secret values in source or static environment entries.
+- Keep dependencies light unless the task requires one; the standard library is available.
+
+## `generation`
+
+### Pick it
+
+Use `generation` for a single human-in-the-loop task type:
+
+- annotating images, video, or audio with boxes, labels, or captions;
+- writing or rewriting text;
+- ranking, rating, or comparing outputs;
+- validating or correcting model output with a human judge;
+- collecting original video, audio, photos, files, or other content from experts.
+
+Use `about.projectType: 'general'` when experts act on existing items: annotation, classification, judgment, ranking, rating, comparison, or rewriting.
+
+Use `about.projectType: 'data_collection'` when experts produce new original content instead of labeling an existing item. Build the UI with the corresponding upload or recording component. Prefer the larger unverified crowd for this work by setting `audienceAndPricing.verifiedExperts: false` unless the task specifically requires verified expertise. Do not use an unverified audience for a `general` project.
+
+### Configure it
+
+`generation(name, settings)` accepts the public `GenerationAuthoringSettings`, derived from `GenerationNodeSettings`:
+
+- `about`: optional `name`, `description`, and `projectType`. The constructor uses its first argument as `about.name` when omitted.
+- `publicName`: brand-neutral, human-readable title shown to experts.
+- `entities.input` and `.output`: map declared fields into the labeler data model.
+- `qualityCriteria`: semantic pass/fail rubrics targeting output `Field` objects.
+- `instruction`: English labeler guidance reflecting the actual entities, UI, and criteria.
+- `ui`: `{ code, data, preprocess, postprocess?, constants }` for the task interface.
+- `qualityAssurance`: `llm_only`, `hybrid`, or `human_only`.
+- `audienceAndPricing`: either a human audience or synthetic generation.
+- `onboarding`: built-in Training stage.
+- `exam`: optional built-in qualification gate.
+- `reuseAudienceWithNodeId`, `smartSearch`, and `checks`: source-representable advanced settings.
+
+#### Entities
+
+An authored entity uses `field`, not `fieldProxyId`. Set `entityType`, `optional`, `jsonPath`, `description`, `relations`, and the discriminant:
+
+- `dynamic: false` means one value in one annotation; use a path without `[*]` and omit `maxEntities`.
+- `dynamic: true` means repeated values inside one annotation; use exactly one `[*]` in `jsonPath` and set `maxEntities` from 1 through 50.
+- Use `allowedLabels: [{ label, value }]` for fixed choices. Use `SINGLE_LABEL` for exactly one stored value and `MULTI_LABEL` for multiple values.
+- Set both `minDurationSeconds` and `maxDurationSeconds` on `VIDEO` entities.
+- Give every output entity at least one relation to the input it uses: `{ field, rel_type: 'context' | 'references' | 'depends_on' | 'evaluates' }`, or a conditional relation supported by the public type.
+
+Entities enforce format, not meaning. Put types, ranges, cardinality, requiredness, and labels in the field schema and entity. Put accuracy, correctness, completeness, and clarity in quality criteria.
+
+For video `data_collection`, the upload or recorder returns an array even when one video is requested. Use an output `VIDEO` entity with `dynamic: true`, `maxEntities: 1`, and a `jsonPath` ending in `[*]`; align its duration bounds with the UI component.
+
+#### Quality and instructions
+
+Write at least one criterion for every output entity. Each criterion needs an authored UUID `id`, `qualityElement`, mutually exclusive and exhaustive `thresholds.pass` and `thresholds.fail`, and `targetEntity: outputField`. Invert the task into an observable check: “tag every car” becomes “every visible car has exactly one tag.” Keep format validation out of criteria.
+
+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' }`. Do not ask whether QA is wanted. Use `hybrid` only when the user explicitly requests human review; it adds sampled Human QA while retaining LLM review. Use `human_only` only when the user explicitly prohibits LLM grading. Human-bearing modes require `humanQaTimeForTask` of at least 10 seconds; omit `smartSamplingPercent` for the platform defaults of 30 for hybrid and 100 for human-only unless the user asks for another rate. QA mode applies to the whole node, not individual criteria. The redo cap is platform-controlled and is not an SDK setting.
+
+Keep `instruction` actionable and in English. Include the workflow, concepts, quality rules, and at least one pass and fail example grounded in the task. Do not mention project schedules, dataset volume, workforce requirements, or compensation in labeler instructions.
+
+#### Audience and pricing
+
+For humans, set `audienceType: 'human'`, `verifiedExperts`, all three audience filters, `pricePerTask`, and `timeForTask`. The public shapes differ by filter: languages use `{ type: 'and' | 'or', values: [{ value: 'English' }] }`; specializations use `{ type: 'and' | 'or', values: [{ value, qualificationId }] }`; countries use `{ type: 'or', values: ['United States'] }`. Start unspecified filters with English, no specializations, and no countries. Do not put specializations on an unverified audience. A specialization's `qualificationId` is platform identity: preserve an imported value, and do not invent one when the SDK cannot discover it.
+
+Start with `$0.20` and 120 seconds when the task gives no stronger signal, then change them only for an explicit rate or clearly longer work. The per-expert cap is normally off. For `data_collection`, use a cap of 50 by default; use 1 for one-response-per-expert collection.
+
+Use `audienceType: 'synthetic'` only when the user explicitly asks for synthetic or model-generated data. Configure its optional `generationModelId`, `reasoningEffort`, and `llmInstruction`; do not include human pricing or audience fields. Synthetic generation is incompatible with `data_collection`, human QA, audience reuse, expert sourcing, and Training.
+
+#### Training, Exam, UI, and advanced settings
+
+Treat `onboarding` as the node's Training course. It has `enabled`, `steps`, and `info` (`estimatedTime`, `role`, `goal`, `successCriteria`). Build it from the real instruction, criteria, UI, edge cases, and verified examples. 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 uses public `mode: 'ground_truth' | 'quality_criteria'` plus `groundTruthType: 'direct' | 'custom'`. 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.
+
+The `ui` strings are authored directly. Build one expert's task view, ensure component value shapes match entity schemas, read inputs by bare field name, and use `postprocess` when a component's native value needs reshaping. Hardware-backed upload and recording controls require real UI verification.
+
+Use `reuseAudienceWithNodeId` only with real imported `{ pipelineId, nodeId }` values from a compatible deployed task in another pipeline; never invent IDs. `smartSearch` can hold the public sourcing profile, but `sourceFingerprint` is server-derived. Preserve an imported fingerprint; do not invent one for new source. `checks` can preserve or author stored test cases, but running and interpreting them is a server operation, not an offline constructor feature.
+
+### Traps
+
+- Do not represent QA, review, redo, Training, or Exam as graph nodes.
+- Do not omit relations from outputs or confuse format validation with semantic quality.
+- Do not add fields, explanations, comments, or labor the task does not require.
+- Do not choose synthetic generation merely because a model could do the task; require an explicit request.
+- Do not treat the constructor's generated placeholder Training or blank UI as production-ready configuration.
+- Do not pair `projectType: 'general'` with `verifiedExperts: false`. General projects require an ID-verified audience, and the server rejects the graph with `General projects require an ID-verified audience`. `data_collection` supports both modes but requires a media upload component (`VideoUpload`, `VideoRecord`, or `FileUpload`) in the `ui` code. An annotation task with an unverified audience therefore cannot be expressed: `general` demands verified experts and `data_collection` demands an upload widget the task has no use for. When a request asks for one, say so and let the requester choose, rather than quietly flipping a setting.
+- Do not omit `ui.constants`. It is required alongside `code`, `data`, `preprocess`, and `postprocess`; `'{}'` is the right value when there is nothing to pass. Omitting it fails validation with `must have required property 'constants'`, usually reported together with a misleading `type must be equal to constant` from the failed node discrimination.
+- Do not ship a generation node without Training. `onboarding` is mandatory: at least three `steps`, of which at least one carries a `quiz` block. The server rejects fewer with `Onboarding must have at least 3 steps` and `Onboarding must include at least one quiz block`.
+- Do not treat the server's materialized defaults as your configuration. A deployed node reports `qualityAssurance`, `exam`, `reuseAudienceWithNodeId`, and `smartSearch` even when source never set them. Leave them out of source unless you mean to control them; `plan` compares only what source declares.
+
+## `quorum`
+
+### Pick it
+
+Use `quorum` only when the same item needs a fixed number of independent human annotations and visible disagreement. Classification, rating, and short-label tasks are the common fit. Use `generation` for one annotation. Do not approximate adaptive consensus by chaining human nodes or routing with `match`.
+
+### Configure it
+
+`quorum(name, settings)` accepts `QuorumAuthoringSettings`, derived from `QuorumNodeSettings`:
+
+- `about`, `publicName`, `entities`, `qualityCriteria`, `instruction`, `ui`, `audienceAndPricing`, `onboarding`, `exam`, `reuseAudienceWithNodeId`, `smartSearch`, and `checks` follow the human-node rules above.
+- `overlap` is the fixed number of independent labelers per item: 1–100. Default to 3 when the user does not specify it; 3 gives a majority, 5 gives stronger consensus, and cost grows linearly.
+- `qualityAssurance` is either `llm_only` or `none`.
+- `offboardingRules` supports majority-vote agreement rules in No-QA mode.
+
+Quorum is human-only in the current public shape; its `audienceAndPricing.audienceType` is `'human'`.
+
+#### The quorum data shape
+
+**Every quorum output `field()` must have a top-level array JSON schema.** The array is the collected-annotation dimension: one element per labeler, nominally `overlap` elements. Its `items` schema is one labeler's contribution.
+
+Configure entities for one labeler's contribution, not for the outer array. A single label per person therefore uses `dynamic: false` and `jsonPath: '$.label'`, while the declared output field is `{ type: 'array', items: { type: 'string' } }`. `dynamic: true` means an array inside each labeler's contribution and therefore produces an array of arrays. Build the UI to submit one value at `$.label`, never `$.label[0]`; the platform assembles the outer array.
+
+Quorum does not aggregate. It writes all raw annotations back, including rejected ones. Add a downstream `code` node only when the user asks for one consensus value, and make it tolerate arrays longer than `overlap`.
+
+#### Explanation-driven quality
+
+With `llm_only` QA, include a required output entity of type `EXPLANATION` and a corresponding top-level array string field unless the task makes that impossible. Put the strongest criterion on this explanation. Evaluate whether the reasoning is substantive and applies the task's definitions; do not rely primarily on judging the raw label. Different labels can be reasonable, while reasoning reveals annotation quality. Label outputs do not each require their own criterion on quorum.
+
+With `qaMode: 'none'`, no LLM reads the explanation. Do not require an explanation by default unless the user asks for written reasoning or comments. Keep at least one quality criterion as labeler-facing Quality Panel guidance, even though no model evaluates it.
+
+#### QA and escalation
+
+Default to `qualityAssurance: { qaMode: 'llm_only' }`. The LLM accepts or rejects each annotation. If all initial annotations are rejected, the platform adds fresh annotations one at a time until one is accepted or the total reaches `2 × overlap`. Therefore result arrays may be longer than `overlap`.
+
+**Quorum has no redo cycle.** A rejected annotation is never reopened or sent back to the same expert. Escalation adds a fresh annotation, and all collected annotations—accepted and rejected—remain in the output arrays. Hitting the cap with zero accepted annotations still returns the collected results.
+
+Use `qaMode: 'none'` only when the user explicitly asks for agreement-based quality control instead of LLM QA. Then:
+
+- set `overlap` to at least 3;
+- disable the per-expert cap;
+- add at least one `{ id, type: 'mv_agreement', agreementScale }` offboarding rule;
+- set `agreementScale` to the authored output field ID for a top-level `SINGLE_LABEL` entity.
+
+The authoring helper does not translate `offboardingRules.agreementScale` from `Field` to ID. Use `agreementScale: labelField.id`; this is a derived field reference, not an invented raw ID. Do not combine No-QA mode with a per-expert cap.
+
+### Traps
+
+- Do not model the quorum array twice. The field schema owns the outer annotation array; entity `dynamic` owns repetition inside one annotation.
+- Do not promise exactly `overlap` results or exactly `overlap` accepted results.
+- Do not add majority-vote or averaging logic inside the node.
+- Do not call escalation dynamic overlap. Per-item or agreement-threshold-dependent overlap is unsupported.
+- Do not configure human-only or hybrid QA; quorum supports only `llm_only` and `none`.
+- Do not invent a redo path.
+
+## `match`
+
+### Pick it
+
+Use `match` when one item must take one conditional path based on data. Do not use it for parallel fan-out, loops, review cycles, adaptive quorum, or consensus aggregation.
+
+### Configure it
+
+Set `MatchAuthoringSettings`, derived from `MatchNodeSettings`, through `match(name, settings)`:
+
+- `about`: `name`, optional `description`, optional `projectType`.
+- `fieldProxies.input`: every declared `Field` referenced by a predicate, each with `optional`.
+- `conditions`: ordered branches. Each has `name`, optional `logic: 'and' | 'or'`, and `predicates`.
+- Each authored predicate uses `field`, `jsonPath`, `operator`, and scalar `value`.
+
+The current public type accepts only `operator: 'text_eq' | 'text_neq'` and `value: string | number | boolean | null`. Do not copy broader internal operator lists into source. Use `jsonPath: '$'` for the whole scalar or a restricted path into an object.
+
+Ordering is semantic: `conditions[0]` routes to `matched(0)`, the first true condition wins, and an implicit `default` handles no match. Every predicate field must also appear in `fieldProxies.input`.
+
+### Traps
+
+- Do not write a default condition; connect `route.default`.
+- Do not assume all matching branches run.
+- Do not use unsupported comparison, set-membership, range, or emptiness operators. Put that logic in `code`, emit a routing key, then compare it with `text_eq` or `text_neq`.
+- Do not reference a field in a predicate without binding it in `fieldProxies.input`.
+
+## Public-surface gaps
+
+When the requirement depends on one of these capabilities, state the gap instead of inventing source syntax:
+
+- Audience discovery and validation helpers have no SDK or CLI path: valid-language/country/specialization suggestions, audience-size statistics, and recommended-rate calculation.
+- 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.
+- The interactive task-interface toolkit has no SDK/CLI testing path for component discovery, component documentation, rendered tree/value inspection, screenshots, TypeScript reports, or submission validation. Source can set `ui`; final UI verification remains server/UI work.
+- 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.
+- Exam golden-dataset discovery, creation by symbolic dataset name, dataset lint execution, and generated-golden confirmation flow have no high-level SDK authoring path. `exam.goldenDatasetId` requires a real ID.
+- Per-node strict validation is not exposed separately. `definePipeline` and offline `validate(graph)` check the public contract; `toloka validate` runs platform spec validation and reports the latest matching check jobs without writing the graph.
+- Stored checks can be represented in settings and the low-level client can list/start pipeline checks, but `toloka` has no command that discovers check contracts, configures check cases, starts each required lint/test, waits, and explains reports.
+- Project rename and runtime item-filter authoring have no `toloka` source path. The CLI preserves the live item filter and a live `itemLimit` unless source declares its own limit.
+
+- Generation's platform-controlled redo cap, appeal behavior, payment retry, and exact terminal handling are intentionally not configurable SDK settings.
+- Dynamic quorum and per-item overlap are unsupported by both surfaces; this is a platform limitation, not missing TypeScript syntax.
+
+For every representable change above, edit the node's source file, run `toloka validate`, inspect `toloka plan`, and apply with `toloka apply`.