@toloka-platform/sdk 0.1.0-preview.3

package/dist/cli/toloka.js.jsc.sha256

@@ -0,0 +1 @@
+b49171675daa5e2af94f0a18451b88060dc190ab82da325e2f3938efd12a29f2  toloka.js.jsc

package/dist/cli/toloka.js.sha256

@@ -0,0 +1 @@
+6d6ae339d253bfe8afb656551bfcfe344c262b006658b5768a057b29a56217c8  toloka.js

package/docs/authoring.md

@@ -0,0 +1,275 @@
+# Authoring
+
+How to express a pipeline project in TypeScript: fields, nodes, ports, and assembly.
+
+## Source layout
+
+A project root is the directory holding `toloka.json` and `pipelines/`. Commands walk up from the working directory to find it.
+
+```
+toloka.json                       CLI-managed identity state, never hand-edited
+fields.ts                         field declarations shared across nodes
+pipelines/
+  cat-labeling/
+    pipeline.ts                   default-exports definePipeline(...)
+    nodes/
+      collection/node.ts
+      annotate-cats/node.ts
+```
+
+One file per node keeps edits local: changing a prompt or a price touches one file, and a reviewer sees exactly which node changed. `pipeline.ts` holds the topology and nothing else.
+
+## Declare fields once
+
+A field is a named data contract with a JSON Schema. Declare it once and import it wherever it is used.
+
+```ts
+import { field } from "@toloka-platform/sdk";
+
+export const imageUrl = field("image_url", { type: "string", format: "uri" });
+export const annotations = field("annotations", {
+  type: "array",
+  items: { type: "object", additionalProperties: true },
+});
+```
+
+The name is a bare identifier. When a field is a pipeline **input**, its name must match a column on the bound dataset, case-sensitively. Output-only and intermediate fields can be named freely.
+
+## Node constructors
+
+Five constructors cover the whole palette. Each takes a name, a settings object, and optional `{ id }`.
+
+### root
+
+Defines the pipeline's input and output contract. `started` is what each item carries in from the dataset; `completed` is what gets written back.
+
+```ts
+import { root } from "@toloka-platform/sdk";
+
+export const collection = root({ started: [imageUrl], completed: [annotations] });
+```
+
+Pass `{ field, optional: true }` instead of a bare field to make a binding optional.
+
+### code
+
+Deterministic work: transformations, HTTP calls, LLM calls. The Python program is an inline string.
+
+```ts
+import { code } from "@toloka-platform/sdk";
+
+export const orderFaces = code("order_faces", {
+  about: { name: "order_faces", description: "Sort annotations top-left to bottom-right." },
+  envVars: [],
+  fieldProxies: {
+    input: [{ field: draftFaces, optional: false }],
+    output: [{ field: faces, optional: false }],
+  },
+  code: {
+    code: `from main_types import Inputs, Outputs
+
+async def main(inputs: Inputs) -> Outputs:
+    ordered = sorted(inputs["draft_faces"], key=lambda f: (f["boundingBox"]["y"], f["boundingBox"]["x"]))
+    return {"faces": ordered}`,
+  },
+});
+```
+
+If the program calls an external service, list the secret names in `envVars`. The sandbox has no ambient environment.
+
+### generation
+
+One human-work task type. The node owns the entire expert journey: instruction, UI, entity schemas, quality criteria, quality assurance, audience, pricing, Training, and Exam.
+
+```ts
+import { generation } from "@toloka-platform/sdk";
+
+export const annotateFaces = generation("annotate_faces", {
+  about: { description: "Draw a box around every visible face.", projectType: "general" },
+  publicName: "Face annotation",
+  instruction: "Draw one tight rectangular box around every visible human face.",
+  entities: {
+    input: [{ field: imageUrl, entityType: "IMAGE", description: "Public URL of the image." }],
+    output: [
+      {
+        field: draftFaces,
+        entityType: "ANNOTATION",
+        jsonPath: "$.draft_faces[*]",
+        description: "One tight box per visible face.",
+        dynamic: true,
+        maxEntities: 50,
+      },
+    ],
+  },
+  qualityCriteria: [
+    {
+      id: "123e4567-e89b-42d3-a456-426614174000",
+      qualityElement: "Completeness",
+      thresholds: { pass: "Every visible face is boxed.", fail: "A visible face is missing." },
+      targetEntity: draftFaces,
+    },
+  ],
+  ui: {
+    code: "<Field.ImageAnnotation path={'draft_faces'} image={actions.get('image_url', '')} tools={['rectangle']} />",
+    data: '{"image_url":"https://example.com/face.jpg"}',
+    preprocess: "return {}",
+    postprocess: "return {};",
+    constants: "{}",
+  },
+  audienceAndPricing: {
+    audienceType: "human",
+    verifiedExperts: true,
+    audience: {
+      languages: { type: "and", values: [{ value: "English" }] },
+      specializations: { type: "and", values: [] },
+      countries: { type: "or", values: [] },
+    },
+    pricePerTask: 0.2,
+    timeForTask: 60,
+    perExpertCapEnabled: false,
+    perExpertCapValue: 1,
+  },
+});
+```
+
+### quorum
+
+The same item labeled by N independent people, with disagreement preserved. Every output field becomes a top-level array with one element per labeler.
+
+```ts
+import { quorum } from "@toloka-platform/sdk";
+
+export const ratePair = quorum("rate_pair", {
+  about: { name: "rate_pair" },
+  publicName: "Rate the pair",
+  overlap: 3,
+  entities: {
+    input: [{ field: pairUrl, entityType: "TEXT" }],
+    output: [{ field: verdict, entityType: "TEXT" }],
+  },
+  qualityCriteria: [],
+  instruction: "Pick the better of the two videos.",
+  ui: {
+    code: "<></>",
+    data: "{}",
+    preprocess: "return {}",
+    postprocess: "return {};",
+    constants: "{}",
+  },
+  onboarding: {
+    enabled: true,
+    steps: [
+      {
+        id: "step-1",
+        blocks: [
+          {
+            id: "block-1",
+            type: "text",
+            content: [{ type: "markdown", value: "Watch both videos." }],
+          },
+        ],
+      },
+    ],
+    info: {
+      estimatedTime: "1 minute",
+      role: "Rater",
+      goal: "Rate the pair",
+      successCriteria: "Submit a rating",
+    },
+  },
+});
+```
+
+A quorum node **requires** an `onboarding` block: the Training course is part of the node, not an optional extra. The platform additionally requires at least three steps with at least one quiz block before the pipeline can deploy, which the type system does not enforce — a one-step placeholder compiles and applies but will not launch.
+
+### match
+
+Predicate routing. Conditions are evaluated in declaration order.
+
+```ts
+import { match } from "@toloka-platform/sdk";
+
+export const routeDisputed = match("route_disputed", {
+  about: { name: "route_disputed" },
+  conditions: [
+    {
+      name: "is disputed",
+      predicates: [{ field: verdict, jsonPath: "$", operator: "text_eq", value: "disputed" }],
+    },
+  ],
+  fieldProxies: { input: [{ field: verdict, optional: false }] },
+});
+```
+
+## Connect ports
+
+`connect(from, to)` is the only way to create an edge. Ports are typed, so a wrong direction is a compile error.
+
+| node         | ports                                             |
+| ------------ | ------------------------------------------------- |
+| `root`       | `started` (out), `completed` (in)                 |
+| `code`       | `input` (in), `output` (out)                      |
+| `generation` | `input` (in), `output` (out)                      |
+| `quorum`     | `input` (in), `output` (out)                      |
+| `match`      | `input` (in), `matched(i)` (out), `default` (out) |
+
+```ts
+connections: [
+  connect(collection.started, annotateFaces.input),
+  connect(annotateFaces.output, orderFaces.input),
+  connect(orderFaces.output, collection.completed),
+  connect(routeDisputed.matched(0), adjudicate.input),
+  connect(routeDisputed.default, merge.input),
+];
+```
+
+The graph is acyclic. Review, retry, redo, Training, Exam, appeal, and payment retry are **settings inside the owning human-work node**, not extra nodes — there is no loop to draw.
+
+## Assemble the project
+
+```ts
+import { connect, definePipeline } from "@toloka-platform/sdk";
+
+export default definePipeline({
+  dataset: "cat-images",
+  fields: [imageUrl, annotations],
+  nodes: [collection, annotateCats],
+  connections: [
+    connect(collection.started, annotateCats.input),
+    connect(annotateCats.output, collection.completed),
+  ],
+});
+```
+
+`dataset` names the source dataset. `plan` creates it if it is absent and records the resolved id in `toloka.json`.
+
+Each `pipelines/<name>/pipeline.ts` is one pipeline. A project can hold several; each names its own dataset, and a dataset can be shared.
+
+Because assembly is ordinary TypeScript, a family of near-identical pipelines can be produced by a function that returns `definePipeline(...)`. The `connections` array stays literal and readable, which is the property worth protecting: topology should never be something a reader has to infer from a helper's implementation.
+
+## Identity
+
+Constructors mint deterministic ids from the node name, so authored source needs no ids at all.
+
+`toloka import` emits explicit `{ id }` options for nodes and fields that already exist on the platform. **Preserve them.** They are how reconciliation recognizes the same resource instead of replacing it.
+
+Never hand-write `fp_…`, `ds.…`, `pl.…`, or `pp.…` values into settings, and never author a `layout` block: layout is not authored, existing layout is preserved, and the server supplies defaults.
+
+## Validate
+
+```sh
+bunx tsc --noEmit
+toloka validate
+```
+
+`definePipeline` and the typed ports add local declaration and connection invariants. `toloka validate` posts each bound pipeline to `POST /pipelines/:pipelineId/graph/validate` and reports platform spec errors, warnings, and the latest matching check jobs. It does not write the graph.
+
+A pipeline that is not on the platform yet is skipped until `toloka apply` creates it. The published JSON contract is still available as `validate(graph)` for importer and fixture tests; that helper makes no network call.
+
+A successful validate is necessary, not sufficient for launch. Gates outside the graph contract — an underpriced audience, a Training course that is enabled but unbuilt, a task UI that was never validated — can still block deployment. See [limitations](./limitations.md).
+
+## Next
+
+- [Nodes](./nodes.md) — choosing a node, and the pricing floors
+- [Datasets](./datasets.md) — columns and immutability
+- [CLI](./cli.md) — the reconcile loop

package/docs/cli-v2.md

@@ -0,0 +1,218 @@
+# CLI v2: project as the root
+
+How `toloka` should work in the next version. Preview is unreleased, so this is a clean cutover, not a compatibility layer.
+
+The platform object is a **project** (`pp.…`, today's pipeline project). Windmill calls the same role a workspace. PostHog calls it a project. We keep **project** so the CLI matches the API and the console.
+
+## Why the current CLI is wrong
+
+Today the checkout is a pipeline tree that happens to mention a project.
+
+- A directory is a project root if it has `toloka.json` **or** a `pipelines/` folder. No pipelines, no root.
+- `init` writes agent skills before a project exists; if one is already selected, it also binds the directory.
+- A checkout attaches when `project create` or `import` writes `toloka.json`, or when `init` finds an already selected project.
+- `run`, `status`, `runs`, and `cost` pick a pipeline from `toloka.json`. Zero pipelines is an error. Several pipelines opens a picker. The command names pretend there is "the" pipeline.
+- `status` means "latest run of some pipeline", not "this project".
+
+That design cannot grow. Datasets, secrets, files, checks, and anything we add later are project children. Some projects will never have a pipeline. Searching for a pipeline before those commands can run is the bug.
+
+Windmill and PostHog both invert this: pick the project (workspace), then operate on resources inside it. A Windmill workspace with no flows is still a workspace. A PostHog project with no dashboards is still a project.
+
+## Two layers of context
+
+### Machine auth
+
+`~/.config/toloka/credentials.json` stays the home for the API key and base URL. `login` / `logout` / `whoami` do not need a project.
+
+The file also becomes a small local registry, Windmill-style:
+
+```json
+{
+  "baseUrl": "https://platform.toloka.ai",
+  "apiKey": "…",
+  "current": "cat-labeling",
+  "projects": {
+    "cat-labeling": { "id": "pp.019f…", "name": "Cat labeling" },
+    "staging": { "id": "pp.019e…", "name": "Staging" }
+  }
+}
+```
+
+`current` is a local alias, not a platform field. Same key, several projects, switch without re-login. CI never uses this file.
+
+### Checkout
+
+A directory becomes a project checkout when it contains `toloka.json`. That is the only root marker. `pipelines/` alone is not a project.
+
+```json
+{
+  "projectId": "pp.019f…",
+  "pipelines": {},
+  "datasets": {}
+}
+```
+
+Empty `pipelines` and `datasets` are valid. Bindings are a cache of live ids after import/apply, not a requirement to run commands. Do not hand-edit this file.
+
+A checkout can later grow other folders (`datasets/`, `files/`, whatever we author). None of them define the root.
+
+## How a command finds its project
+
+Highest wins:
+
+1. `--project-id`
+2. `TOLOKA_PROJECT_ID` (keep accepting `POTATO_PROJECT_ID` until we rename the rest of the env surface)
+3. `toloka.json` in the discovered checkout (walk up from cwd, or `--source-root`)
+4. `current` in the machine registry
+5. Fail: `No project selected. Run toloka project add, or cd into a checkout.`
+
+A checkout wins over the machine default so a repo is self-describing for agents and CI. Flags and env still win over both, same as PostHog (`POSTHOG_CLI_PROJECT_ID`) and Windmill (`--workspace`).
+
+`whoami` prints the resolved project and which layer supplied it.
+
+## Setting up a project
+
+This is the Windmill `workspace add` / PostHog "this is project 12345" step. Every later command assumes it already happened.
+
+```sh
+toloka login
+toloka project list                          # remote projects this key can see
+toloka project add cat-labeling pp.019f…     # register + select
+toloka project switch cat-labeling
+toloka project current                       # alias of the project line in whoami
+toloka project remove cat-labeling           # local unbind only
+```
+
+`project add` with no arguments prompts for alias and id, like `wmill workspace add`. The new alias becomes `current`.
+
+Create a live project and bind it in one step:
+
+```sh
+toloka project create cat-labeling --team-id <teamId>
+```
+
+`POST /projects` requires `teamId`. There is no public team-list endpoint today, so `--team-id` is required unless every visible project shares one team, in which case we reuse that id. If teams differ, refuse and ask.
+
+`project create` writes the machine alias, sets `current`, and if cwd has no `toloka.json`, writes one.
+
+### init
+
+`init` sets up **this directory** for an agent. A selected platform project is optional.
+
+```sh
+toloka init
+```
+
+It writes the agent entry points without calling the platform. When a project is already selected, it also writes `toloka.json` with empty bindings. It does not require `pipelines/`; `project create` creates the live project.
+
+`import` stays the "pull an existing live project into this checkout" path. After v2 it uses the selected project when the id is omitted:
+
+```sh
+toloka import                 # pull the current project
+toloka import pp.019f…        # pull that id, then bind it
+```
+
+## Commands after a project is selected
+
+Resource commands never search the disk for a pipeline first. They load the project, then the named child if the verb needs one.
+
+| Command                       | Scope                         | Pipeline required? |
+| ----------------------------- | ----------------------------- | ------------------ |
+| `plan` / `apply` / `validate` | whole project                 | no                 |
+| `secret set`                  | project                       | no                 |
+| `dataset list`                | project                       | no                 |
+| `dataset fields <name>`       | named dataset in this project | no                 |
+| `dataset load <name>`         | named dataset in this project | no                 |
+| `dataset upload <name>`       | named dataset in this project | no                 |
+| `status`                      | project                       | no                 |
+| `pipeline list`               | project                       | no                 |
+| `pipeline run <name>`         | one pipeline                  | yes                |
+| `pipeline status <name>`      | one pipeline                  | yes                |
+| `pipeline runs <name>`        | one pipeline                  | yes                |
+| `pipeline cost <name>`        | one pipeline                  | yes                |
+| `pipeline cancel <runId>`     | run id                        | run id only        |
+| `pipeline results <runId>`    | run id                        | run id only        |
+
+`status` (no prefix) is project health: id, name, team, how many pipelines/datasets/secrets, and pending source changes (`Source has no pending changes.`). Unbound live resources are not pending. It is valid on an empty project.
+
+Pipeline verbs move under `pipeline` and take an explicit name. No implicit "the only pipeline". No interactive picker as the default for scripts. A TTY may still offer a picker if the name is omitted **and** the project has more than one pipeline; non-TTY still errors with the list.
+
+A project with zero pipelines:
+
+```
+$ toloka pipeline run
+This project has no pipelines.
+```
+
+`plan` / `apply` on that same project: `No changes.`
+
+## Datasets: catalog, not the table
+
+A live dataset can be huge. The checkout never holds the rows unless you ask.
+
+What is always local:
+
+- name and platform id in `toloka.json`
+- field names and JSON schemas (authored, or pulled as declarations)
+
+What stays on the platform until you pull it:
+
+- every item
+- upload history
+- anything a pipeline writes back
+
+`import`, `init`, `plan`, `apply`, `status`, and `dataset list` talk to the catalog only: names, ids, field schemas, item counts if the API returns them. They do not page items and they do not write a data file. `apply` may create an empty dataset and missing columns. It never copies rows down or up.
+
+Loading rows is a separate, explicit command:
+
+```sh
+toloka dataset list
+toloka dataset fields images
+toloka dataset load images --out ./data/images.jsonl
+toloka dataset load images --limit 100 --out ./data/images.sample.jsonl
+toloka dataset upload images ./new.jsonl
+```
+
+`load` starts a platform export, waits (default 60s; pass `--timeout`), downloads a JSON array, and writes JSONL to `--out`. Omit `--limit` only when you mean the whole table. `--limit` slices after that download; it still waits for the full export. There is no implicit load on `import` or `init`. A 10-million-row dataset and an empty one look the same in the checkout until you run `load`.
+
+Same rule as today, restated for a project-first CLI: source describes shape; the platform stores data; you pull or push rows when you want them on disk.
+
+## What we stop doing
+
+- Discovering a root from `pipelines/`.
+- Making `run` / `status` / `runs` / `cost` top-level commands that hunt a pipeline.
+- Requiring a pipeline binding before the CLI will talk to a project.
+- Using "pipeline project" in user-facing CLI text. The noun is project.
+
+## Later entities
+
+New resources attach to the same project the same way Windmill attaches `script` / `flow` / `app` to a workspace, and the same way PostHog attaches dashboards and flags to a project.
+
+```
+toloka <resource> list
+toloka <resource> get <name>
+toloka <resource> …
+```
+
+Do not add those groups until the resource exists. The rule is already fixed: the project is in context; the command names the child.
+
+## Mapping from v1
+
+| v1                                            | v2                                                                 |
+| --------------------------------------------- | ------------------------------------------------------------------ |
+| `toloka init` (skills only)                   | `toloka init` (checkout + skills)                                  |
+| `toloka import <id>`                          | `toloka project add` then `toloka import`, or `toloka import <id>` |
+| `toloka plan --project-id`                    | `toloka project add` / checkout, then `toloka plan`                |
+| `toloka run [pipeline]`                       | `toloka pipeline run <name>`                                       |
+| `toloka status [pipeline]`                    | `toloka status` (project) or `toloka pipeline status <name>`       |
+| `toloka runs` / `cost` / `cancel` / `results` | `toloka pipeline …`                                                |
+| root = `toloka.json` or `pipelines/`          | root = `toloka.json` only                                          |
+
+No shims. Preview callers update.
+
+## Out of scope
+
+- Browser login, key rotation, revoke-on-logout.
+- Multi-project apply from one checkout (one `toloka.json`, one `projectId`).
+- Deletes (`destroy`).
+- Authoring a project that is not a platform project. If we ever have a different project type, it is still selected the same way; only the child commands change.