@toloka-platform/sdk 0.11.2 → 0.11.4

package/src/importer.ts

@@ -1,15 +1,17 @@
 import { assert } from "es-toolkit";
-import type { JsonSchema, PipelineGraphV1 } from "../openapi/gen/models";
+import type { InvalidFieldSchema, JsonSchema, PipelineGraphV1 } from "../openapi/gen/models";
 import type { AuthoringIdOptions } from "./authoring";
 
 export type PipelineSourceTree = Readonly<Record<string, string>>;
 export type GeneratePipelineSourceTreeOptions = {
-  readonly dataset: string;
+  readonly dataset?: string;
+  readonly invalidFieldSchemas?: readonly InvalidFieldSchema[];
 };
 
 export type FieldSourceDefinition = {
   readonly name: string;
   readonly jsonSchema: JsonSchema;
+  readonly invalidJsonSchema?: Omit<InvalidFieldSchema, "fieldId">;
   readonly options?: AuthoringIdOptions;
 };
 
@@ -263,30 +265,11 @@ function transformExam<Exam extends { gradedEntities: Array<{ targetEntity: stri
   };
 }
 
-const generationCheckNames: readonly string[] = [
-  "ui",
-  "llmqa",
-  "qc_lint",
-  "ui_types_lint",
-  "exam_dataset",
-  "synthgen",
-];
-const quorumCheckNames: readonly string[] = [
-  "ui",
-  "llmqa",
-  "qc_lint",
-  "ui_types_lint",
-  "exam_dataset",
-];
-
-const normalizeImportedChecks = (
+const withoutEmptyChecks = (
   checks: Record<string, unknown[]> | undefined,
-  requiredNames: readonly string[],
 ): Record<string, unknown[]> | undefined => {
-  if (checks === undefined) return undefined;
-  const normalized = { ...checks };
-  for (const name of requiredNames) normalized[name] ??= [];
-  return normalized;
+  const kept = Object.entries(checks ?? {}).filter(([, cases]) => cases.length > 0);
+  return kept.length === 0 ? undefined : Object.fromEntries(kept);
 };
 
 function authoringSettings(node: GraphNode, fieldReference: FieldReference): unknown {
@@ -310,9 +293,11 @@ function authoringSettings(node: GraphNode, fieldReference: FieldReference): unk
       };
     }
     case "code": {
-      const { fieldProxies, ...settings } = node.settings;
+      const { fieldProxies, checks, ...settings } = node.settings;
+      const authoredChecks = withoutEmptyChecks(checks);
       return {
         ...settings,
+        ...(authoredChecks === undefined ? {} : { checks: authoredChecks }),
         input: fieldProxies.input.map((reference) =>
           transformFieldReference(reference, fieldReference),
         ),
@@ -323,10 +308,10 @@ function authoringSettings(node: GraphNode, fieldReference: FieldReference): unk
     }
     case "generation": {
       const { entities, qualityCriteria, exam, checks, ...settings } = node.settings;
-      const normalizedChecks = normalizeImportedChecks(checks, generationCheckNames);
+      const authoredChecks = withoutEmptyChecks(checks);
       return {
         ...settings,
-        ...(normalizedChecks === undefined ? {} : { checks: normalizedChecks }),
+        ...(authoredChecks === undefined ? {} : { checks: authoredChecks }),
         entities: {
           input: entities.input.map((entity) => transformEntity(entity, fieldReference)),
           output: entities.output.map((entity) => transformEntity(entity, fieldReference)),
@@ -355,10 +340,10 @@ function authoringSettings(node: GraphNode, fieldReference: FieldReference): unk
     }
     case "quorum": {
       const { entities, qualityCriteria, exam, checks, ...settings } = node.settings;
-      const normalizedChecks = normalizeImportedChecks(checks, quorumCheckNames);
+      const authoredChecks = withoutEmptyChecks(checks);
       return {
         ...settings,
-        ...(normalizedChecks === undefined ? {} : { checks: normalizedChecks }),
+        ...(authoredChecks === undefined ? {} : { checks: authoredChecks }),
         entities: {
           input: entities.input.map((entity) => transformEntity(entity, fieldReference)),
           output: entities.output.map((entity) => transformEntity(entity, fieldReference)),
@@ -419,9 +404,13 @@ function fieldDeclarationsSource(
   const declarations = fields
     .map((fieldDefinition) => {
       const binding = bindingFor(fieldDefinition);
+      const jsonSchemaSource =
+        fieldDefinition.invalidJsonSchema === undefined
+          ? formatSource(fieldDefinition.jsonSchema, 1)
+          : `invalidJsonSchema(${formatSource({ field: fieldDefinition.name, ...fieldDefinition.invalidJsonSchema }, 1)})`;
       const argumentsSource = [
         `${indentation(1)}${formatSource(fieldDefinition.name, 1)}`,
-        `${indentation(1)}${formatSource(fieldDefinition.jsonSchema, 1)}`,
+        `${indentation(1)}${jsonSchemaSource}`,
         ...(fieldDefinition.options === undefined
           ? []
           : [`${indentation(1)}${formatSource(fieldDefinition.options, 1)}`]),
@@ -432,7 +421,10 @@ function fieldDeclarationsSource(
       };
     })
     .toSorted((left, right) => compareText(left.binding, right.binding));
-  return `import { field } from '@toloka-platform/sdk';\n\n${declarations.map(({ source }) => source).join("\n\n")}\n`;
+  const imports = fields.some((fieldDefinition) => fieldDefinition.invalidJsonSchema !== undefined)
+    ? "field, invalidJsonSchema"
+    : "field";
+  return `import { ${imports} } from '@toloka-platform/sdk';\n\n${declarations.map(({ source }) => source).join("\n\n")}\n`;
 }
 
 export function generateFieldDeclarationsSource(
@@ -462,13 +454,23 @@ export function generateFieldDeclarationsSource(
   });
 }
 
-function fieldSource(graph: PipelineGraphV1, fieldBindings: ReadonlyMap<string, string>): string {
+function fieldSource(
+  graph: PipelineGraphV1,
+  fieldBindings: ReadonlyMap<string, string>,
+  invalidFieldSchemas: readonly InvalidFieldSchema[],
+): string {
   return fieldDeclarationsSource(
-    graph.fields.map((fieldDefinition) => ({
-      name: fieldDefinition.name,
-      jsonSchema: fieldDefinition.jsonSchema,
-      options: { id: fieldDefinition.id },
-    })),
+    graph.fields.map((fieldDefinition) => {
+      const invalid = invalidFieldSchemas.find(({ fieldId }) => fieldId === fieldDefinition.id);
+      return {
+        name: fieldDefinition.name,
+        jsonSchema: fieldDefinition.jsonSchema,
+        ...(invalid === undefined
+          ? {}
+          : { invalidJsonSchema: { reason: invalid.reason, text: invalid.text } }),
+        options: { id: fieldDefinition.id },
+      };
+    }),
     (fieldDefinition) => {
       const fieldId = fieldDefinition.options?.id;
       assert(fieldId, `Field "${fieldDefinition.name}" has no source ID`);
@@ -527,7 +529,7 @@ function endpointSource(
 
 function pipelineSource(
   graph: PipelineGraphV1,
-  dataset: string,
+  dataset: string | undefined,
   nodeEmissions: ReadonlyArray<NodeEmission>,
   fieldBindings: ReadonlyMap<string, string>,
   nodeBindings: ReadonlyMap<string, string>,
@@ -568,7 +570,8 @@ function pipelineSource(
     if (values.length === 0) return "[]";
     return `[\n${values.map((value) => `${indentation(depth + 1)}${value}`).join(",\n")}\n${indentation(depth)}]`;
   };
-  return `${imports.join("\n")}\n\nexport default definePipeline({\n  dataset: ${formatSource(dataset)},\n  fields: ${formatList(fieldReferences, 1)},\n  nodes: ${formatList(nodeReferences, 1)},\n  connections: ${formatList(connectionReferences, 1)}\n});\n`;
+  const datasetLine = dataset === undefined ? "" : `  dataset: ${formatSource(dataset)},\n`;
+  return `${imports.join("\n")}\n\nexport default definePipeline({\n${datasetLine}  fields: ${formatList(fieldReferences, 1)},\n  nodes: ${formatList(nodeReferences, 1)},\n  connections: ${formatList(connectionReferences, 1)}\n});\n`;
 }
 
 export function generatePipelineSourceTree(
@@ -621,7 +624,10 @@ export function generatePipelineSourceTree(
     return nodeSource(node, binding, `nodes/${directory}/node.ts`, fieldBindings);
   });
   const entries = [
-    { path: "fields.ts", source: fieldSource(graph, fieldBindings) },
+    {
+      path: "fields.ts",
+      source: fieldSource(graph, fieldBindings, options.invalidFieldSchemas ?? []),
+    },
     ...nodeEmissions.map(({ path, source }) => ({ path, source })),
     {
       path: "pipeline.ts",

package/src/index.ts

@@ -42,6 +42,8 @@ export type {
   CodeNode,
   CodeNodeSettings,
   CurrentUser,
+  GenerationBudget,
+  GenerationModel,
   GenerationNode,
   GenerationNodeSettings,
   JsonSchema,
@@ -72,6 +74,7 @@ export {
   connect,
   definePipeline,
   field,
+  invalidJsonSchema,
   optional,
   generation,
   isPipelineDefinition,
@@ -92,6 +95,7 @@ export type {
   Connection,
   Field,
   GenerationAuthoringSettings,
+  InvalidJsonSchemaSource,
   InputPort,
   MatchAuthoringSettings,
   OutputPort,

package/src/transport.ts

@@ -1,4 +1,4 @@
-import { assert } from "es-toolkit";
+import { assert, delay } from "es-toolkit";
 import { PotatoApiError } from "./errors";
 
 const BASE_URL_HEADER = "x-potato-sdk-base-url";
@@ -14,9 +14,16 @@ export type ClientCredential =
     }
   | { readonly scopedToken: string; readonly accessToken?: undefined; readonly apiKey?: undefined };
 
+const RELAY_HEADER = "x-potato-relay";
+const TUNNEL_UNAVAILABLE = "tunnel-unavailable";
+export const TUNNEL_RETRY_DELAYS_MS: readonly number[] = [
+  1_000, 2_000, 4_000, 8_000, 15_000, 15_000, 15_000, 15_000, 15_000,
+];
+
 type TransportRequestInit = RequestInit & {
   readonly fetch?: typeof globalThis.fetch;
   readonly authorization?: () => Promise<string>;
+  readonly tunnelRetryDelaysMs?: readonly number[];
 };
 
 export const createRequestOptions = (
@@ -79,6 +86,7 @@ export async function potatoFetch(url: string, options: TransportRequestInit): P
   const {
     fetch: fetchImplementation = globalThis.fetch,
     authorization,
+    tunnelRetryDelaysMs = TUNNEL_RETRY_DELAYS_MS,
     ...requestOptions
   } = options;
   const headers = new Headers(requestOptions.headers);
@@ -87,10 +95,20 @@ export async function potatoFetch(url: string, options: TransportRequestInit): P
   headers.delete(BASE_URL_HEADER);
   if (authorization !== undefined) headers.set("Authorization", await authorization());
 
-  const response = await fetchImplementation(
-    resolveRequestUrl(url, baseUrl),
-    prepareRequestInit(requestOptions, headers),
-  );
+  const send = () =>
+    fetchImplementation(resolveRequestUrl(url, baseUrl), prepareRequestInit(requestOptions, headers));
+
+  let response = await send();
+  const replayableBody = !(typeof ReadableStream !== "undefined" && requestOptions.body instanceof ReadableStream);
+
+  for (const delayMs of replayableBody ? tunnelRetryDelaysMs : []) {
+    if (response.status !== 503 || response.headers.get(RELAY_HEADER) !== TUNNEL_UNAVAILABLE) break;
+
+    await response.body?.cancel();
+    await delay(delayMs, { signal: requestOptions.signal ?? undefined });
+    response = await send();
+  }
+
   const text = await response.text();
 
   if (!response.ok) {

package/src/validate.ts

@@ -4,6 +4,7 @@ import { assert } from 'es-toolkit';
 import type { PipelineGraphV1 } from '../openapi/gen/models';
 import coreEntityTypes from './core-entity-types.json' with { type: 'json' };
 import { PipelineGraphValidationError, type PipelineGraphValidationIssue } from './errors';
+import graphRules from './graph-rules.json' with { type: 'json' };
 import pipelineGraphV1Contract from './pipeline-graph-v1.contract.json' with { type: 'json' };
 
 const ajv = new Ajv2020({ strict: false });
@@ -52,6 +53,188 @@ const graphEntityIssues = (graph: PipelineGraphV1): PipelineGraphValidationIssue
     ];
   });
 
+const NAME_PATTERN = new RegExp(graphRules.namePattern);
+const MEDIA_UPLOAD_COMPONENT_PATTERN = new RegExp(graphRules.mediaUploadComponentPattern);
+
+type GraphNode = PipelineGraphV1['nodes'][number];
+type HumanWorkNode = Extract<GraphNode, { type: 'generation' | 'quorum' }>;
+type RuleNode = { readonly id: string; readonly type: 'root' } | Exclude<GraphNode, { type: 'root' }>;
+type RuleGraph = {
+  readonly nodes: ReadonlyArray<RuleNode>;
+  readonly connections: ReadonlyArray<PipelineGraphV1['connections'][number]>;
+};
+
+const duplicateIndex = (handle: string) => Number(/\[(\d+)\]$/.exec(handle)?.[1] ?? 0);
+
+const nodesInUse = (graph: RuleGraph): Set<string> => {
+  const root = graph.nodes.find((node) => node.type === 'root');
+  if (root === undefined) return new Set();
+  const inUse = new Set([root.id]);
+  const visited = new Set<string>();
+  const pending: [string, number][] = [[root.id, 0]];
+  for (let state = pending.pop(); state !== undefined; state = pending.pop()) {
+    const [nodeId, duplicate] = state;
+    for (const connection of graph.connections) {
+      if (connection.from.node !== nodeId || duplicateIndex(connection.from.handle) !== duplicate) continue;
+      if (connection.to.node === root.id) continue;
+      const next: [string, number] = [connection.to.node, duplicateIndex(connection.to.handle)];
+      if (visited.has(next.join('#'))) continue;
+      visited.add(next.join('#'));
+      inUse.add(next[0]);
+      pending.push(next);
+    }
+  }
+  return inUse;
+};
+
+const toSnakeCase = (value: string) =>
+  value
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '_')
+    .replace(/^_|_$/g, '');
+
+const nodeNameIssues = (graph: RuleGraph, node: RuleNode, prefix: string): PipelineGraphValidationIssue[] => {
+  if (node.type === 'root') return [];
+  const path = `${prefix}/about/name`;
+  const { name } = node.settings.about;
+  if (name === '') return [{ path, reason: 'The node must have a name' }];
+  if (name.length < graphRules.nodeNameMinLength || name.length > graphRules.nodeNameMaxLength) {
+    return [
+      {
+        path,
+        reason: `The name must be between ${graphRules.nodeNameMinLength} and ${graphRules.nodeNameMaxLength} characters long`,
+      },
+    ];
+  }
+  if (!NAME_PATTERN.test(name)) {
+    return [
+      {
+        path,
+        reason:
+          'The name must start with a letter, can contain only lowercase letters, numbers and underscores, and must end with a letter or number',
+      },
+    ];
+  }
+  const duplicated = graph.nodes.some(
+    (other) => other.id !== node.id && other.type !== 'root' && other.settings.about.name === name,
+  );
+  return duplicated ? [{ path, reason: 'The name must be unique across all nodes' }] : [];
+};
+
+type HumanWorkSettings = HumanWorkNode['settings'];
+
+const thresholdIssues = (
+  criteria: HumanWorkSettings['qualityCriteria'],
+  prefix: string,
+): PipelineGraphValidationIssue[] =>
+  criteria.flatMap((criterion, index) =>
+    (['pass', 'fail'] as const)
+      .filter((side) => criterion.thresholds[side].length < graphRules.minQualityThresholdLength)
+      .map((side) => ({
+        path: `${prefix}/qualityCriteria/${index}/thresholds/${side}`,
+        reason: `${side === 'pass' ? 'Pass' : 'Fail'} condition must be at least ${graphRules.minQualityThresholdLength} characters`,
+      })),
+  );
+
+const qualityElementIssues = (
+  criteria: HumanWorkSettings['qualityCriteria'],
+  prefix: string,
+): PipelineGraphValidationIssue[] => {
+  const keys = criteria.map((criterion) =>
+    criterion.qualityElement === '' ? undefined : toSnakeCase(criterion.qualityElement),
+  );
+  return keys.flatMap((key, index) =>
+    key !== undefined && keys.indexOf(key) !== keys.lastIndexOf(key)
+      ? [{ path: `${prefix}/qualityCriteria/${index}/qualityElement`, reason: 'Quality element names must be unique' }]
+      : [],
+  );
+};
+
+const humanQaIssues = (settings: HumanWorkSettings, prefix: string): PipelineGraphValidationIssue[] => {
+  const { qualityAssurance, qualityCriteria } = settings;
+  if (qualityAssurance?.qaMode !== 'human_only' && qualityAssurance?.qaMode !== 'hybrid') return [];
+  const minimum = Math.max(
+    graphRules.minHumanQaTimeForTaskSeconds,
+    graphRules.humanQaSecondsPerQualityCriterion * qualityCriteria.length,
+  );
+  return (qualityAssurance.humanQaTimeForTask ?? 0) < minimum
+    ? [
+        {
+          path: `${prefix}/qualityAssurance/humanQaTimeForTask`,
+          reason: `Time for one Human QA review must be at least ${minimum} seconds`,
+        },
+      ]
+    : [];
+};
+
+const isSynthetic = ({ audienceAndPricing }: HumanWorkSettings) => audienceAndPricing?.audienceType === 'synthetic';
+
+const humanAudienceIssues = (settings: HumanWorkSettings, prefix: string): PipelineGraphValidationIssue[] => {
+  const { about, audienceAndPricing, ui } = settings;
+  if (isSynthetic(settings)) return [];
+  const issues: PipelineGraphValidationIssue[] = [];
+  if (about.projectType === 'data_collection' && !MEDIA_UPLOAD_COMPONENT_PATTERN.test(ui.code)) {
+    issues.push({
+      path: `${prefix}/ui/code`,
+      reason:
+        'Data collection projects require a media upload component (VideoUpload, VideoRecord, or FileUpload) in the UI',
+    });
+  }
+  if (audienceAndPricing?.audienceType !== 'human') return issues;
+  if (audienceAndPricing.timeForTask < graphRules.minTimeForTaskSeconds) {
+    issues.push({
+      path: `${prefix}/audienceAndPricing/timeForTask`,
+      reason: `The task execution time cannot be less than ${graphRules.minTimeForTaskSeconds} seconds`,
+    });
+  }
+  if (audienceAndPricing.pricePerTask <= 0) {
+    issues.push({ path: `${prefix}/audienceAndPricing/pricePerTask`, reason: 'The price per task must be greater than 0' });
+  }
+  return issues;
+};
+
+const examIssues = (settings: HumanWorkSettings, prefix: string): PipelineGraphValidationIssue[] => {
+  const { exam } = settings;
+  if (!exam?.enabled || isSynthetic(settings)) return [];
+  const issues: PipelineGraphValidationIssue[] = [];
+  if (exam.tasksPerExpert > graphRules.maxExamTasksPerExpert) {
+    issues.push({
+      path: `${prefix}/exam/tasksPerExpert`,
+      reason: `Tasks per expert cannot exceed ${graphRules.maxExamTasksPerExpert}`,
+    });
+  }
+  if (exam.passThreshold < 1) {
+    issues.push({ path: `${prefix}/exam/passThreshold`, reason: 'Pass threshold must be at least 1' });
+  }
+  if (exam.passThreshold > exam.tasksPerExpert) {
+    issues.push({ path: `${prefix}/exam/passThreshold`, reason: 'Pass threshold cannot exceed tasks per expert' });
+  }
+  return issues;
+};
+
+const humanWorkIssues = ({ settings }: HumanWorkNode, prefix: string): PipelineGraphValidationIssue[] => [
+  ...thresholdIssues(settings.qualityCriteria, prefix),
+  ...qualityElementIssues(settings.qualityCriteria, prefix),
+  ...humanQaIssues(settings, prefix),
+  ...humanAudienceIssues(settings, prefix),
+  ...examIssues(settings, prefix),
+];
+
+export type PlatformRuleIssue = PipelineGraphValidationIssue & { readonly node: string };
+
+export const platformRuleIssues = (graph: RuleGraph): PlatformRuleIssue[] => {
+  const inUse = nodesInUse(graph);
+  return graph.nodes.flatMap((node, index) => {
+    if (!inUse.has(node.id)) return [];
+    const prefix = `/nodes/${index}/settings`;
+    const label = node.type === 'root' || node.settings.about.name === '' ? node.id : node.settings.about.name;
+    return [
+      ...nodeNameIssues(graph, node, prefix),
+      ...(node.type === 'generation' || node.type === 'quorum' ? humanWorkIssues(node, prefix) : []),
+    ].map((issue) => ({ ...issue, node: label }));
+  });
+};
+
 const toValidationIssue = (error: ErrorObject): PipelineGraphValidationIssue => {
   const property =
     error.keyword === 'required'