@toloka-platform/sdk 0.11.2 → 0.11.4

package/examples/app-crowdtesting/nodes/app-flow-test/node.ts

@@ -0,0 +1,381 @@
+import { generation } from "@toloka-platform/sdk";
+
+import { appTestVideo, deviceModel, itemId, osVersion } from "../../fields";
+
+const installLink = "https://example.com/replace-with-real-build-link";
+
+const installSteps = `1. **Uninstall** any existing copy of Acme Fitness
+
+2. **Open the install link** below
+
+3. If Google Play shows an "Unknown app" warning, tap **Install Anyway** — this is expected for a pre-release build
+
+4. **Open the app** once it installs`;
+
+const recordingChecklist = `**Your recording must show:**
+
+- **Installation** — start recording BEFORE installing
+- **Workout scan ×2** — each run through to the form analysis results screen
+- **Meal scan ×2** — each run through to the nutrition breakdown page
+- **Today**, **Programs** and **Insights** screens, each clearly visible
+
+Dismiss any paywall or premium upgrade screens — do not complete them.`;
+
+export const appFlowTest = generation("app_flow_test", {
+  about: {
+    description:
+      "Collect unique screen recordings of testers exercising the full Acme Fitness journey on Android, one per person, to test app stability and flow correctness across real consumer devices.",
+    projectType: "data_collection",
+  },
+  publicName: "Full app flow test recording (Android)",
+  audienceAndPricing: {
+    audienceType: "human",
+    verifiedExperts: false,
+    audience: {
+      languages: { type: "and", values: [{ value: "English" }] },
+      specializations: { type: "and", values: [] },
+      countries: { type: "or", values: [] },
+    },
+    pricePerTask: 3,
+    timeForTask: 1800,
+    perExpertCapEnabled: true,
+    perExpertCapValue: 1,
+  },
+  entities: {
+    input: [
+      {
+        field: itemId,
+        entityType: "METADATA",
+        description: "Placeholder row identifier for this data collection task.",
+      },
+    ],
+    output: [
+      {
+        field: appTestVideo,
+        entityType: "VIDEO",
+        jsonPath: "$.app_test_video[0].sasLink",
+        description: "Screen recording of the full Acme Fitness test session on Android.",
+        relations: [{ field: itemId, rel_type: "context" }],
+        minDurationSeconds: 300,
+        maxDurationSeconds: 1800,
+      },
+      {
+        field: deviceModel,
+        entityType: "SHORT_ANSWER",
+        jsonPath: "$.device_model",
+        description: "Device manufacturer and model, as free text.",
+        relations: [{ field: appTestVideo, rel_type: "context" }],
+      },
+      {
+        field: osVersion,
+        entityType: "SHORT_ANSWER",
+        jsonPath: "$.os_version",
+        description: "Android version number, as free text.",
+        relations: [{ field: appTestVideo, rel_type: "context" }],
+      },
+    ],
+  },
+  qualityCriteria: [
+    {
+      id: "2a604228-ea59-49b4-81ba-7b51f7acd718",
+      qualityElement: "Installation captured",
+      thresholds: {
+        pass: "The recording starts before installation and shows the install link being opened, the install progress, and the app launching. If Google Play shows an 'Unknown app' warning, the recording also shows the tester confirming it with Install Anyway. This is what identifies which build was tested.",
+        fail: "The recording begins with the app already installed, or the installation is cut. The build under test cannot be identified.",
+      },
+      targetEntity: appTestVideo,
+    },
+    {
+      id: "42c05854-cdd5-4ea5-aa98-b43de315d493",
+      qualityElement: "Workout scan — at least 2 complete runs",
+      thresholds: {
+        pass: "The video shows at least 2 Workout scan runs attempted end to end. A run counts when the recording shows: opening the workout scanner and pointing the camera at yourself, the 'Analyzing form...' processing state, and then either the form analysis results screen OR a visible app failure (crash / error message) on that run. Count each attempted cycle you can see.",
+        fail: "Fewer than 2 complete Workout scan runs are visible — either too few were attempted, or runs were started but abandoned before the form analysis results screen appeared. Attempts that the app itself failed or errored on still count as attempted-and-shown cycles when the recording shows the user trying to complete them.",
+      },
+      targetEntity: appTestVideo,
+    },
+    {
+      id: "3b58bd9c-c65c-4445-8234-c87dbf0e053d",
+      qualityElement: "Meal scan — at least 2 complete runs",
+      thresholds: {
+        pass: "The video shows at least 2 Meal scan runs attempted end to end. A run counts when the recording shows: opening the meal scanner and pointing the camera at any food item, the 'Identifying food...' processing state, and then either the nutrition breakdown page OR a visible app failure (crash / error message) on that run. Count each attempted cycle you can see.",
+        fail: "Fewer than 2 complete Meal scan runs are visible — either too few were attempted, or runs were started but abandoned before the nutrition breakdown page appeared. Attempts that the app itself failed or errored on still count as attempted-and-shown cycles when the recording shows the user trying to complete them.",
+      },
+      targetEntity: appTestVideo,
+    },
+    {
+      id: "d4892764-b0c5-439f-acf9-4a29e70f301f",
+      qualityElement: "All required screens shown",
+      thresholds: {
+        pass: "Every required screen appears clearly at least once, identified by its on-screen text: Today, identified on screen by 'Today', 'Daily Plan', 'Activity Log'; Programs, identified on screen by 'Programs', 'Search programs', 'My Plan'; Insights, identified on screen by 'Insights', 'Trends', 'Weekly Summary'. Judge only what is visible on screen — never infer from which control was tapped.",
+        fail: "One or more required screens never appear. Check for the distinctive text of each before failing.",
+      },
+      targetEntity: appTestVideo,
+    },
+    {
+      id: "a870e710-ab78-42b4-a46f-aa8609255680",
+      qualityElement: "Recording legibility",
+      thresholds: {
+        pass: "Text, buttons and result screens are readable throughout, well enough to identify the on-screen text named in the other criteria (install warning, processing states, result screens, screen titles).",
+        fail: "The recording is blurred, cropped, over-compressed or obstructed to the point where the on-screen text named in the other criteria cannot be read.",
+      },
+      targetEntity: appTestVideo,
+    },
+    {
+      id: "93ef853c-740b-4d31-955e-721efeed10ac",
+      qualityElement: "Device model stated",
+      thresholds: {
+        pass: "A real device manufacturer and model is given, specific enough to identify the hardware (for example 'Samsung Galaxy S23' or 'Pixel 7a').",
+        fail: "Blank, placeholder, or too vague to identify the hardware — for example 'phone', 'android', 'mine', or random characters.",
+      },
+      targetEntity: deviceModel,
+    },
+    {
+      id: "d5394490-f327-4ace-a789-996668fdd458",
+      qualityElement: "OS version stated",
+      thresholds: {
+        pass: "A plausible Android version number is given — a positive integer major version, optionally followed by a minor version (for example '14' or '12.1'), that fits the Android release numbering. Do not reject a version only because it is newer than the releases you know about.",
+        fail: "Blank, placeholder, a word instead of a number (for example 'latest' or 'newest'), a codename without a number, random characters, or a number that cannot be an Android release version (for example '0', a year such as '2025', or a build number such as 'UP1A.231005').",
+      },
+      targetEntity: osVersion,
+    },
+  ],
+  instruction: `# Acme Fitness full app flow test (Android)
+
+## What you will do
+Install Acme Fitness on your own Android device, screen-record yourself
+using it, and upload the recording. Your recording tests app stability and
+flow correctness on real hardware. Finding a bug is a good outcome, not a
+failed task.
+
+## Steps
+1. START YOUR SCREEN RECORDING FIRST, before you open the install link.
+2. Uninstall any existing copy of Acme Fitness.
+3. Open the install link and install the build: ${installLink}
+   If Google Play shows an "Unknown app" warning, tap Install Anyway. This is expected for a pre-release build.
+4. Launch the app and sign in. Any supported method works. Answer any
+   onboarding questions so you reach the main app.
+5. Run each of these to completion, the required number of times:
+- Workout scan (at least 2 complete runs): open the workout scanner and point the camera at yourself -> "Analyzing form..." -> the form analysis results screen
+- Meal scan (at least 2 complete runs): open the meal scanner and point the camera at any food item -> "Identifying food..." -> the nutrition breakdown page
+6. Make sure each of these screens appears clearly at least once:
+- Today, identified on screen by "Today", "Daily Plan", "Activity Log"
+- Programs, identified on screen by "Programs", "Search programs", "My Plan"
+- Insights, identified on screen by "Insights", "Trends", "Weekly Summary"
+7. Dismiss any paywall or premium upgrade screens — do not complete them. Nothing can be purchased.
+8. Stop the recording and upload it, then enter your device model and OS version.
+
+## Before you submit
+- Is the installation visible at the start of the recording?
+- Did you run Workout scan at least 2 times, each run ending on the result screen or a visible crash?
+- Did you run Meal scan at least 2 times, each run ending on the result screen or a visible crash?
+- Does Today appear clearly?
+- Does Programs appear clearly?
+- Does Insights appear clearly?
+- Is the video between 5 and 30 minutes?
+- Is the screen readable throughout, with no editing or trimming?
+
+## Examples
+- Pass: the recording begins on your home screen, shows the install link, the
+  installation, and the app launching; two Workout scans reach the form analysis
+  results screen; the first Meal scan crashes the app on "Identifying food...", you
+  relaunch, and the next two reach the nutrition breakdown page; Today, Programs and
+  Insights each appear clearly. Device model "Pixel 7a", Android version "14".
+- Fail: the recording starts with Acme Fitness already installed and shows only one
+  Meal scan. The build cannot be identified and the Meal scan count is short, so
+  the submission is rejected even though every screen appears.
+
+## If the app misbehaves
+Keep recording. Relaunch if it crashes and carry on from where you were, then
+submit the recording including the crash. A recording that captures a real bug
+is more valuable than a clean one.
+
+## Your privacy
+Turn on Do Not Disturb before recording so your notifications stay private, and
+use a throwaway or test account to sign in where the app allows it. Recordings
+are used only to assess app stability and flow correctness: https://example.com/privacy-policy`,
+  ui: {
+    code: `<View.Flex vertical={true} gap={'1.25rem'}>
+  <View.Card title={'Step 1: Install Acme Fitness'} variant={'info'}>
+    <View.Flex vertical={true} gap={'1rem'}>
+      <View.Alert
+        variant={'warning'}
+        title={'Start your screen recording first'}
+        description={'Begin recording BEFORE you tap the install link. We need to see the installation.'}
+      />
+      <View.Markdown content={CONST.INSTALL_STEPS} />
+      <View.Link url={CONST.INSTALL_LINK}>Open the install link</View.Link>
+    </View.Flex>
+  </View.Card>
+  <View.Card title={'Step 2: Record the full test'}>
+    <View.Markdown content={CONST.RECORDING_CHECKLIST} />
+  </View.Card>
+  <View.Card title={'Step 3: Upload and describe your device'}>
+    <View.Flex vertical={true} gap={'1rem'}>
+      <Field.VideoUpload
+        path={'app_test_video'}
+        label={'Screen recording'}
+        multiple={false}
+        linkType={'sasLink'}
+        minimumFiles={1}
+        minDurationSec={300}
+        maxDurationSec={1800}
+      />
+      <Field.Text
+        path={'device_model'}
+        label={'Device model'}
+        placeholder={'e.g. Samsung Galaxy S23'}
+        validation={[
+          { required: true, message: 'Enter your device manufacturer and model.' },
+          { max: 200, message: 'Keep this under 200 characters — just the manufacturer and model.' },
+        ]}
+      />
+      <Field.Text
+        path={'os_version'}
+        label={'Android version'}
+        placeholder={'e.g. 14'}
+        validation={[
+          { required: true, message: 'Enter your Android version.' },
+          { max: 50, message: 'Keep this under 50 characters — just the version number.' },
+        ]}
+      />
+    </View.Flex>
+  </View.Card>
+</View.Flex>`,
+    data: '{"item_id":1}',
+    preprocess: "return {}",
+    postprocess: "return {};",
+    constants: JSON.stringify({
+      INSTALL_LINK: installLink,
+      INSTALL_STEPS: installSteps,
+      RECORDING_CHECKLIST: recordingChecklist,
+    }),
+  },
+  qualityAssurance: {
+    qaMode: "llm_only",
+    llmQaModelId: "gpt-5.4-mini",
+  },
+  onboarding: {
+    enabled: true,
+    steps: [
+      {
+        id: "step-1",
+        blocks: [
+          {
+            id: "intro",
+            type: "text",
+            title: "Testing Acme Fitness on Android",
+            content: [
+              {
+                type: "markdown",
+                value: `You will install Acme Fitness, record yourself using it, and upload the video.
+
+You need: an Android device, free storage for a 30-minute recording, and a stable connection.
+
+**If the app crashes or misbehaves, keep recording and carry on.** Capturing a
+real bug is the most valuable thing you can do here — it will not cost you the task.`,
+              },
+            ],
+          },
+        ],
+      },
+      {
+        id: "step-2",
+        blocks: [
+          {
+            id: "requirements",
+            type: "text",
+            title: "What your recording must show",
+            content: [
+              {
+                type: "markdown",
+                value: `**1. The installation.** Start recording before you open the install link.
+Without it we cannot tell which build you tested.
+
+**2. Each flow, repeated.**
+- Workout scan (at least 2 complete runs): open the workout scanner and point the camera at yourself -> "Analyzing form..." -> the form analysis results screen
+- Meal scan (at least 2 complete runs): open the meal scanner and point the camera at any food item -> "Identifying food..." -> the nutrition breakdown page
+
+**3. Every required screen, clearly visible.**
+- Today, identified on screen by "Today", "Daily Plan", "Activity Log"
+- Programs, identified on screen by "Programs", "Search programs", "My Plan"
+- Insights, identified on screen by "Insights", "Trends", "Weekly Summary"
+
+**4. Nothing purchased.** Dismiss any paywall or premium upgrade screens.
+
+We check what is visible on screen, not which buttons you pressed — so make
+sure each screen actually appears.`,
+              },
+            ],
+          },
+        ],
+      },
+      {
+        id: "step-3",
+        blocks: [
+          {
+            id: "quiz",
+            type: "quiz",
+            title: "Quick check",
+            questions: [
+              {
+                id: "q1",
+                type: "single-choice",
+                question: "When should you start your screen recording?",
+                options: [
+                  { value: "before_install", label: "Before opening the install link" },
+                  { value: "after_install", label: "Once the app is installed" },
+                  { value: "after_signin", label: "After signing in" },
+                ],
+                correctAnswer: "before_install",
+              },
+              {
+                id: "q2",
+                type: "single-choice",
+                question: "How many times must you complete Workout scan?",
+                options: [
+                  { value: "one", label: "Once is enough" },
+                  { value: "required", label: "At least 2 complete runs" },
+                  { value: "many", label: "As many as possible, at least ten" },
+                ],
+                correctAnswer: "required",
+              },
+              {
+                id: "q3",
+                type: "single-choice",
+                question: "The app crashes halfway through your session. What do you do?",
+                options: [
+                  { value: "keep", label: "Keep recording, relaunch, carry on, and submit it" },
+                  { value: "restart", label: "Delete the recording and start over" },
+                  {
+                    value: "abandon",
+                    label: "Abandon the task — a crash means it cannot be submitted",
+                  },
+                ],
+                correctAnswer: "keep",
+              },
+              {
+                id: "q4",
+                type: "single-choice",
+                question: "How do we confirm you visited Today?",
+                options: [
+                  { value: "screen", label: 'The screen itself appears, showing "Today"' },
+                  { value: "tap", label: "We detect which tab you tapped" },
+                  { value: "time", label: "We measure how long you spent there" },
+                ],
+                correctAnswer: "screen",
+              },
+            ],
+          },
+        ],
+      },
+    ],
+    info: {
+      estimatedTime: "5-30 minutes",
+      role: "Android app tester",
+      goal: "Record a full Acme Fitness test session",
+      successCriteria:
+        "Installation captured, every flow completed the required number of times, every required screen shown",
+    },
+  },
+});

package/examples/app-crowdtesting/nodes/collection/node.ts

@@ -0,0 +1,8 @@
+import { root } from "@toloka-platform/sdk";
+
+import { appTestVideo, deviceModel, itemId, osVersion } from "../../fields";
+
+export const collection = root({
+  started: [itemId],
+  completed: [appTestVideo, deviceModel, osVersion],
+});

package/examples/app-crowdtesting/pipeline.browser.integration.spec.ts

@@ -0,0 +1,77 @@
+import { expect, test } from "@toloka-platform/sdk/testing";
+import { describe } from "vitest";
+import { assert } from "es-toolkit";
+import type { TaskUiSession } from "@toloka-platform/sdk/testing";
+
+import pipeline from "./pipeline";
+import { appFlowTest } from "./nodes/app-flow-test/node";
+
+const item = { item_id: 7 };
+const device = { device_model: "Samsung Galaxy S23", os_version: "14" };
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === "object" && value !== null && !Array.isArray(value);
+
+const documentedRecording = async (session: TaskUiSession): Promise<Record<string, unknown>> => {
+  const documentation = await session.componentDocumentation(["Field.VideoUpload"]);
+  const output = documentation["Field.VideoUpload"]?.example?.output;
+  assert(output, "Field.VideoUpload has no documented example output");
+  const example: unknown = JSON.parse(output);
+  assert(isRecord(example), "Field.VideoUpload example output is not an object");
+  const [upload] = Object.values(example);
+  assert(Array.isArray(upload), "Field.VideoUpload example output is not an array");
+  const [recording] = upload;
+  assert(isRecord(recording), "Field.VideoUpload example contains a non-object value");
+  assert(typeof recording.sasLink === "string", "Field.VideoUpload example has no sasLink");
+  return {
+    ...recording,
+    userFileName: "acme-fitness-session.mp4",
+    durationSec: 912.4,
+    videoWidth: 1080,
+    videoHeight: 2400,
+  };
+};
+
+describe("app crowdtesting example", () => {
+  test.ui(pipeline, appFlowTest, "submits a recording with device metadata", async ({ render }) => {
+    const session = await render({ data: item, allowPartialCoverage: true });
+    const recording = await documentedRecording(session);
+    await session.setValue("app_test_video", [recording]);
+
+    expect(await session.getValue("app_test_video")).toEqual([recording]);
+    expect(await session.validationErrors()).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({ path: "device_model" }),
+        expect.objectContaining({ path: "os_version" }),
+      ]),
+    );
+    await session.setValue("device_model", device.device_model);
+    await session.setValue("os_version", device.os_version);
+    await expect(session.submit()).resolves.toMatchObject({
+      ...item,
+      app_test_video: [recording],
+      ...device,
+    });
+    expect(session.coverage.complete).toBe(false);
+    await session.close();
+  });
+
+  test.pipeline(pipeline, "collects one recording per row", async ({ renderUi }) => {
+    const session = await renderUi(appFlowTest, { data: item, allowPartialCoverage: true });
+    const recording = await documentedRecording(session);
+    await session.setValue("app_test_video", [recording]);
+    await session.setValue("device_model", device.device_model);
+    await session.setValue("os_version", device.os_version);
+    const submission = await session.submit();
+    const uploads = submission.app_test_video;
+    assert(Array.isArray(uploads) && isRecord(uploads[0]), "No recording was submitted");
+    const completed = {
+      app_test_video: uploads[0].sasLink,
+      device_model: submission.device_model,
+      os_version: submission.os_version,
+    };
+
+    expect(completed).toEqual({ app_test_video: recording.sasLink, ...device });
+    await session.close();
+  });
+});

package/examples/app-crowdtesting/pipeline.ts

@@ -0,0 +1,17 @@
+import { connect, definePipeline } from "@toloka-platform/sdk";
+
+import { appTestVideo, deviceModel, itemId, osVersion } from "./fields";
+import { appFlowTest } from "./nodes/app-flow-test/node";
+import { collection } from "./nodes/collection/node";
+
+export const pipeline = definePipeline({
+  dataset: "app-test-runs",
+  fields: [itemId, appTestVideo, deviceModel, osVersion],
+  nodes: [collection, appFlowTest],
+  connections: [
+    connect(collection.started, appFlowTest.input),
+    connect(appFlowTest.output, collection.completed),
+  ],
+});
+
+export default pipeline;

package/examples/egocentric-video-collection/README.md

@@ -0,0 +1,35 @@
+# Egocentric video collection
+
+A data-collection pipeline: each dataset item is an empty collection slot, and one participant fills it by recording a first-person video of a household activity with a head-mounted phone, then tagging it with one of 13 activity categories. LLM QA grades every submission against eight quality criteria before it is written back.
+
+## Shape
+
+```
+root.started                 id (one row per collection slot)
+  └─> record_activity        generation  data_collection: record a video, pick its category
+      └─> root.completed     recorded_video, task_category
+```
+
+Two nodes: one root, one `generation`. Training, QA, redo, and the per-expert cap all live inside `record_activity`; none of them is a graph node.
+
+## What to read first
+
+| file                                   | why                                                                        |
+| -------------------------------------- | -------------------------------------------------------------------------- |
+| `fields.ts`                            | the category list is declared once and feeds the enum, labels, and Task UI |
+| `nodes/record-activity/node.ts`        | a complete human collection node: entities, criteria, UI, Training, checks |
+| `pipeline.browser.integration.spec.ts` | how to drive a hardware-backed recorder in the headless Task UI            |
+
+## Patterns this example demonstrates
+
+**Collection with a recording field.** `about.projectType` is `data_collection` and the screen is built around `Field.VideoRecord` with `nativeCamera={true}`, which the component contract requires for egocentric capture: the take is recorded with the phone's native camera in the Toloka app, and hosts without native camera support block the task instead of falling back to the in-browser recorder. The recorder's value is an array of takes, but the task yields one logical video, so `recorded_video` is a scalar URI field and its `VIDEO` entity stays static, reading `$.video_file[0].sasLink`. The entity's duration bounds match the recorder's `minDurationSec` and `maxDurationSec`.
+
+**A category label output.** `task_category` is a `SINGLE_LABEL` entity that depends on the video. `taskCategories` drives the field `enum`, the entity's `allowedLabels`, and the `Field.Select` options through `ui.constants`, so the three can never disagree. The instruction, Training, quiz, and category criterion name the categories with the same labels.
+
+**LLM QA with one criterion per concern.** Seven criteria judge the video (stability, hands, valid task, residential setting, POV angle, PII, originality) and one judges whether the category matches the footage. Where two criteria could overlap, such as setting and originality, each states what it does not judge.
+
+**Training with quizzes and practice.** `onboarding` teaches the setup, checks it with two quizzes, grades a free-text practice review with validators, and ends with a consent block.
+
+**Stored `annotation_qa` checks.** Two platform-side test cases hold a task input and its expected output by field name, built with `JSON.stringify` rather than hand-escaped strings.
+
+**Hardware-backed UI tests.** The headless browser has no camera, so the tests feed the recorder the documented example take through `setValue` and render with `allowPartialCoverage: true`. Local evidence for this node is therefore `partial`; a real device run is still needed to verify recording itself.

package/examples/egocentric-video-collection/fields.ts

@@ -0,0 +1,24 @@
+import { field } from "@toloka-platform/sdk";
+
+export const taskCategories = [
+  { label: "Food Preparation", value: "food_preparation" },
+  { label: "Repair & Assembly", value: "repair_assembly" },
+  { label: "Home Organization", value: "home_organization" },
+  { label: "Desk & Office Tasks", value: "desk_office_tasks" },
+  { label: "Craft / Hobby / Fine Manipulation", value: "craft_hobby_fine_manipulation" },
+  { label: "Personal Care (Bathroom)", value: "personal_care_bathroom" },
+  { label: "Cleaning", value: "cleaning" },
+  { label: "Laundry & Garment Care", value: "laundry_garment_care" },
+  { label: "Miscellaneous Object Interaction", value: "miscellaneous_object_interaction" },
+  { label: "Dining Table Tasks", value: "dining_table_tasks" },
+  { label: "Plant Care Activities", value: "plant_care_activities" },
+  { label: "Animal Care Activities", value: "animal_care_activities" },
+  { label: "Yard & Landscaping Operations", value: "yard_landscaping_operations" },
+];
+
+export const slotId = field("id", { type: "integer" });
+export const recordedVideo = field("recorded_video", { type: "string", format: "uri" });
+export const taskCategory = field("task_category", {
+  type: "string",
+  enum: taskCategories.map((category) => category.value),
+});

package/examples/egocentric-video-collection/nodes/collection/node.ts

@@ -0,0 +1,5 @@
+import { root } from "@toloka-platform/sdk";
+
+import { recordedVideo, slotId, taskCategory } from "../../fields";
+
+export const collection = root({ started: [slotId], completed: [recordedVideo, taskCategory] });