> ## Documentation Index
> Fetch the complete documentation index at: https://docs.platform.toloka.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Pipelines as code

> Define Data Labeling pipelines as TypeScript source, then check, plan, and apply them.

Fields describe the data contract, nodes describe the work, and connections describe how data moves through a Data Labeling pipeline. Keep these definitions in TypeScript so your team and coding agents can review and test changes.

Pipeline authoring covers Data Labeling. To operate Training or Models, use the [SDK client](https://docs.platform.toloka.ai/docs/sdk/reference/client-methods.md), [CLI](https://docs.platform.toloka.ai/docs/cli.md#train), or [HTTP API](https://docs.platform.toloka.ai/docs/api-reference.md#train).

## Set up a project

Install [Bun and the SDK](https://docs.platform.toloka.ai/docs/sdk.md#install) and the [standalone CLI](https://docs.platform.toloka.ai/docs/cli.md#install). Existing SDK projects use `bun install` to restore their dependencies.

Run `toloka init` from the project root to install the CLI's bundled coding-agent guidance. To bind this directory to a project, pass `--project-id`, set `TOLOKA_PROJECT_ID`, or use an existing `toloka.json` binding. Selecting a project with `project switch` alone does not bind `init`.

After updating the CLI, run `toloka init` again to refresh its guidance. Updating the SDK dependency alone does not update the CLI.

## Define fields and a pipeline

Save each pipeline in a file named `pipeline.ts` under `pipelines/`, with a default export from [`definePipeline`](https://docs.platform.toloka.ai/docs/sdk/reference/define-pipeline):

```ts pipelines/example/pipeline.ts theme={null}
import { connect, definePipeline, field, root } from "@toloka-platform/sdk";

const text = field("text", { type: "string" });
const boundary = root({ started: [text], completed: [text] });

export default definePipeline({
  dataset: "example-items",
  fields: [text],
  nodes: [boundary],
  connections: [connect(boundary.started, boundary.completed)],
});
```

`dataset` names the platform dataset. [`field()`](https://docs.platform.toloka.ai/docs/sdk/reference/field) declares a field and its JSON Schema. [`root()`](https://docs.platform.toloka.ai/docs/sdk/reference/root) defines the fields that enter and leave the pipeline; it takes no name argument.

Use [`code()`](https://docs.platform.toloka.ai/docs/sdk/reference/code), [`generation()`](https://docs.platform.toloka.ai/docs/sdk/reference/generation), [`quorum()`](https://docs.platform.toloka.ai/docs/sdk/reference/quorum), and [`match()`](https://docs.platform.toloka.ai/docs/sdk/reference/match) to add work. Their reference pages describe the authoring arguments and link to the [node settings](https://docs.platform.toloka.ai/docs/data/reference/nodes.md).

## Connect nodes

[`connect()`](https://docs.platform.toloka.ai/docs/sdk/reference/connect) takes an output port and an input port. TypeScript checks the port direction. [`definePipeline()`](https://docs.platform.toloka.ai/docs/sdk/reference/define-pipeline) checks that referenced fields and connection endpoints are declared, then builds the graph.

Reuse the same `Field` objects in node settings and the pipeline's `fields` array. A new [`field()`](https://docs.platform.toloka.ai/docs/sdk/reference/field) call with the same name is a different object and does not satisfy that declaration check.

Keep dataset rows, API keys, and secret values out of pipeline source. Author secret names in node settings and set their values through the [CLI](https://docs.platform.toloka.ai/docs/cli.md#the-reconcile-loop).

## Check, plan, and apply

Add [local tests](https://docs.platform.toloka.ai/docs/sdk/testing.md), authenticate, and [select a project](https://docs.platform.toloka.ai/docs/cli.md#select-a-project). Then run:

```sh theme={null}
toloka check
toloka validate
toloka plan
toloka apply
toloka plan
```

| Command | Purpose |
| - | - |
| `check` | Run TypeScript, labeling-interface typechecks, Vitest, and required node and pipeline-flow tests without platform credentials. |
| `validate` | Validate bound graphs against the platform and report matching checks without writing the graph. |
| `plan` | Compare source with live state and show the changes. |
| `apply` | Rerun local checks, then write the planned changes. |

`check` also reports `platform-rules` warnings with the node and setting path. These warnings do not fail `check`, but `apply` refuses new or changed pipelines that violate those rules. Fix them before applying.

A final `No changes.` from `plan` confirms that source and the platform agree. For project selection, immutable fields, and graph-write restrictions after a run, see the [CLI reconciliation loop](https://docs.platform.toloka.ai/docs/cli.md#the-reconcile-loop).

## Configure expert onboarding

The Generation constructor's default onboarding contains one text step and no quiz. Replace it before applying a node with onboarding enabled. A course needs a role, goal, success criteria, 3–6 steps with content, and at least one quiz. Practice and worked examples cannot appear in the same course; worked examples require a built labeling interface.

All text within one `onboarding` setting counts toward its 150,000-character limit. Other settings, such as `instruction` and `ui`, have separate limits. Local checks validate course structure and block content; platform checks also exercise worked examples against the labeling interface.

Use [Generation node onboarding](https://docs.platform.toloka.ai/docs/data/reference/nodes/generation.md#onboarding) for block contents and course requirements shared with Quorum nodes. Use [`validate()`](https://docs.platform.toloka.ai/docs/sdk/reference/validate) when you need to validate a graph directly; it checks the local graph contract, while `toloka check` and platform validation cover additional rules.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.