@toloka-platform/sdk 0.1.0-preview.3

package/src/authoring/index.ts

@@ -0,0 +1,650 @@
+import { assert } from 'es-toolkit';
+import type {
+  CodeNode,
+  CodeNodeSettings,
+  GenerationNode,
+  GenerationNodeSettings,
+  JsonSchema,
+  MatchNode,
+  MatchNodeSettings,
+  PipelineGraphV1,
+  QuorumNode,
+  QuorumNodeSettings,
+  RootNode,
+  RootNodeSettings
+} from '../../openapi/gen/models';
+import { validate } from '../validate';
+
+const FIELD_DEFINITION = Symbol('fieldDefinition');
+const PIPELINE_DEFINITION = Symbol('pipelineDefinition');
+const PORT_DEFINITION = Symbol('portDefinition');
+const NODE_FIELD_REFERENCES = Symbol('nodeFieldReferences');
+
+export interface Field<Name extends string = string> {
+  readonly id: string;
+  readonly name: Name;
+  readonly jsonSchema: JsonSchema;
+  readonly [FIELD_DEFINITION]: true;
+}
+
+export type AuthoringIdOptions = {
+  readonly id?: string;
+};
+
+export interface InputPort {
+  readonly node: string;
+  readonly handle: string;
+  readonly direction: 'input';
+  readonly [PORT_DEFINITION]: 'input';
+}
+
+export interface OutputPort {
+  readonly node: string;
+  readonly handle: string;
+  readonly direction: 'output';
+  readonly [PORT_DEFINITION]: 'output';
+}
+
+export interface Connection {
+  readonly from: OutputPort;
+  readonly to: InputPort;
+  readonly settings: PipelineGraphV1['connections'][number]['settings'];
+}
+
+type FieldProxyReference = {
+  readonly field: Field;
+  readonly optional: boolean;
+};
+
+type RootFieldReference = Field | { readonly field: Field; readonly optional?: boolean };
+
+type FieldRelation<Relation> = Relation extends { id: string }
+  ? Omit<Relation, 'id'> & { readonly field: Field }
+  : never;
+
+type FieldRelations<Relations> = NonNullable<Relations> extends Array<infer Relation>
+  ? ReadonlyArray<FieldRelation<Relation>>
+  : never;
+
+type FieldEntity<Entity> = Entity extends {
+  fieldProxyId: string;
+  optional: boolean;
+  jsonPath: string;
+  description: string;
+  relations?: infer Relations;
+  dynamic: true;
+}
+  ? Omit<Entity, 'fieldProxyId' | 'optional' | 'jsonPath' | 'description' | 'relations'> & {
+      readonly field: Field;
+      readonly optional?: boolean;
+      readonly jsonPath?: string;
+      readonly description?: string;
+      readonly relations?: FieldRelations<Relations>;
+    }
+  : Entity extends {
+        fieldProxyId: string;
+        optional: boolean;
+        jsonPath: string;
+        description: string;
+        relations?: infer Relations;
+        dynamic: false;
+      }
+    ? Omit<Entity, 'fieldProxyId' | 'optional' | 'jsonPath' | 'description' | 'relations' | 'dynamic'> & {
+        readonly field: Field;
+        readonly optional?: boolean;
+        readonly jsonPath?: string;
+        readonly description?: string;
+        readonly relations?: FieldRelations<Relations>;
+        readonly dynamic?: false;
+      }
+    : never;
+
+type FieldTarget<Target> = Target extends { targetEntity: string }
+  ? Omit<Target, 'targetEntity'> & { readonly targetEntity: Field }
+  : never;
+
+type FieldExam<Exam extends { gradedEntities: Array<{ targetEntity: string }> }> = Omit<Exam, 'gradedEntities'> & {
+  readonly gradedEntities: ReadonlyArray<FieldTarget<Exam['gradedEntities'][number]>>;
+};
+
+type GenerationInputEntity = FieldEntity<GenerationNodeSettings['entities']['input'][number]>;
+type GenerationOutputEntity = FieldEntity<GenerationNodeSettings['entities']['output'][number]>;
+type GenerationQualityCriterion = FieldTarget<GenerationNodeSettings['qualityCriteria'][number]>;
+type GenerationExam = FieldExam<NonNullable<GenerationNodeSettings['exam']>>;
+
+type QuorumInputEntity = FieldEntity<QuorumNodeSettings['entities']['input'][number]>;
+type QuorumOutputEntity = FieldEntity<QuorumNodeSettings['entities']['output'][number]>;
+type QuorumQualityCriterion = FieldTarget<QuorumNodeSettings['qualityCriteria'][number]>;
+type QuorumExam = FieldExam<NonNullable<QuorumNodeSettings['exam']>>;
+
+type MatchPredicate = Omit<MatchNodeSettings['conditions'][number]['predicates'][number], 'fieldProxyId'> & {
+  readonly field: Field;
+};
+
+export type RootAuthoringSettings = Omit<
+  RootNodeSettings,
+  'datasetId' | 'itemFilter' | 'startedFieldProxies' | 'completedFieldProxies'
+> & {
+  readonly started: ReadonlyArray<RootFieldReference>;
+  readonly completed: ReadonlyArray<RootFieldReference>;
+};
+
+export type CodeAuthoringSettings = Omit<CodeNodeSettings, 'fieldProxies'> & {
+  readonly fieldProxies: {
+    readonly input: ReadonlyArray<FieldProxyReference>;
+    readonly output: ReadonlyArray<FieldProxyReference>;
+  };
+};
+
+export type GenerationAuthoringSettings = Omit<
+  GenerationNodeSettings,
+  'about' | 'entities' | 'qualityCriteria' | 'instruction' | 'ui' | 'onboarding' | 'exam'
+> & {
+  readonly about?: Omit<GenerationNodeSettings['about'], 'name'> & { readonly name?: string };
+  readonly entities: {
+    readonly input: ReadonlyArray<GenerationInputEntity>;
+    readonly output: ReadonlyArray<GenerationOutputEntity>;
+  };
+  readonly qualityCriteria?: ReadonlyArray<GenerationQualityCriterion>;
+  readonly instruction?: string;
+  readonly ui?: GenerationNodeSettings['ui'];
+  readonly onboarding?: GenerationNodeSettings['onboarding'];
+  readonly exam?: GenerationExam;
+};
+
+export type MatchAuthoringSettings = Omit<MatchNodeSettings, 'conditions' | 'fieldProxies'> & {
+  readonly conditions: ReadonlyArray<
+    Omit<MatchNodeSettings['conditions'][number], 'predicates'> & {
+      readonly predicates: ReadonlyArray<MatchPredicate>;
+    }
+  >;
+  readonly fieldProxies: {
+    readonly input: ReadonlyArray<FieldProxyReference>;
+  };
+};
+
+export type QuorumAuthoringSettings = Omit<QuorumNodeSettings, 'entities' | 'qualityCriteria' | 'exam'> & {
+  readonly entities: {
+    readonly input: ReadonlyArray<QuorumInputEntity>;
+    readonly output: ReadonlyArray<QuorumOutputEntity>;
+  };
+  readonly qualityCriteria: ReadonlyArray<QuorumQualityCriterion>;
+  readonly exam?: QuorumExam;
+};
+
+type WireNode = PipelineGraphV1['nodes'][number];
+
+interface AuthoredNode<Node extends WireNode, Settings = Node['settings']> {
+  readonly id: string;
+  readonly type: Node['type'];
+  readonly settings: Settings;
+  readonly [NODE_FIELD_REFERENCES]: ReadonlyArray<Field>;
+}
+
+export interface AuthoredRootNode
+  extends AuthoredNode<RootNode, Omit<RootNodeSettings, 'datasetId' | 'itemFilter'>> {
+  readonly started: OutputPort;
+  readonly completed: InputPort;
+}
+
+export interface AuthoredCodeNode extends AuthoredNode<CodeNode> {
+  readonly input: InputPort;
+  readonly output: OutputPort;
+}
+
+export interface AuthoredGenerationNode extends AuthoredNode<GenerationNode> {
+  readonly input: InputPort;
+  readonly output: OutputPort;
+}
+
+export interface AuthoredMatchNode extends AuthoredNode<MatchNode> {
+  readonly input: InputPort;
+  readonly default: OutputPort;
+  matched(index: number): OutputPort;
+}
+
+export interface AuthoredQuorumNode extends AuthoredNode<QuorumNode> {
+  readonly input: InputPort;
+  readonly output: OutputPort;
+}
+
+export type PipelineNode =
+  | AuthoredRootNode
+  | AuthoredCodeNode
+  | AuthoredGenerationNode
+  | AuthoredMatchNode
+  | AuthoredQuorumNode;
+
+type UnboundRootNode = Omit<RootNode, 'settings'> & {
+  readonly settings: Omit<RootNodeSettings, 'datasetId' | 'itemFilter'>;
+};
+
+export type UnboundPipelineGraphV1 = {
+  readonly version: 1;
+  readonly fields: ReadonlyArray<PipelineGraphV1['fields'][number]>;
+  readonly nodes: ReadonlyArray<UnboundRootNode | Exclude<WireNode, RootNode>>;
+  readonly connections: ReadonlyArray<PipelineGraphV1['connections'][number]>;
+};
+
+export type PipelineDefinitionInput<DatasetName extends string = string> = {
+  readonly dataset: DatasetName;
+  readonly fields: ReadonlyArray<Field>;
+  readonly nodes: ReadonlyArray<PipelineNode>;
+  readonly connections: ReadonlyArray<Connection>;
+};
+
+export type PipelineDefinition<DatasetName extends string = string> = {
+  readonly dataset: DatasetName;
+  readonly graph: UnboundPipelineGraphV1;
+  readonly [PIPELINE_DEFINITION]: true;
+};
+
+export type PipelineDefinitionBindings = {
+  readonly datasetId: string;
+};
+
+function hash(value: string): string {
+  let result = 0x811c9dc5;
+  for (let index = 0; index < value.length; index += 1) {
+    result ^= value.charCodeAt(index);
+    result = Math.imul(result, 0x01000193);
+  }
+  return (result >>> 0).toString(16).padStart(8, '0');
+}
+
+function readableName(name: string): string {
+  return name
+    .normalize('NFKD')
+    .replace(/[\u0300-\u036f]/g, '')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '_')
+    .replace(/^_+|_+$/g, '')
+    .slice(0, 48) || 'unnamed';
+}
+
+function mintedId(kind: 'field' | Exclude<WireNode['type'], 'root'>, name: string): string {
+  const prefix = kind === 'field' ? 'fp' : kind;
+  return `${prefix}_${readableName(name)}_${hash(`${kind}:${name}`)}`;
+}
+
+function inputPort(node: string, handle: string): InputPort {
+  return { node, handle, direction: 'input', [PORT_DEFINITION]: 'input' };
+}
+
+function outputPort(node: string, handle: string): OutputPort {
+  return { node, handle, direction: 'output', [PORT_DEFINITION]: 'output' };
+}
+
+function isField(value: unknown): value is Field {
+  return typeof value === 'object' && value !== null && FIELD_DEFINITION in value;
+}
+
+function collectFieldReferences(value: unknown, references: Field[]): void {
+  if (isField(value)) {
+    references.push(value);
+    return;
+  }
+  if (Array.isArray(value)) {
+    for (const item of value) collectFieldReferences(item, references);
+    return;
+  }
+  if (typeof value === 'object' && value !== null) {
+    for (const item of Object.values(value)) collectFieldReferences(item, references);
+  }
+}
+
+function referencedFields(value: unknown): ReadonlyArray<Field> {
+  const references: Field[] = [];
+  collectFieldReferences(value, references);
+  return references;
+}
+
+function compileFieldProxy(reference: FieldProxyReference): { id: string; optional: boolean } {
+  return { id: reference.field.id, optional: reference.optional };
+}
+
+function compileRootFieldProxy(reference: RootFieldReference): { id: string; optional: boolean } {
+  return isField(reference)
+    ? { id: reference.id, optional: false }
+    : { id: reference.field.id, optional: reference.optional ?? false };
+}
+
+function compileGenerationInputRelation(
+  relation: NonNullable<GenerationInputEntity['relations']>[number]
+): NonNullable<GenerationNodeSettings['entities']['input'][number]['relations']>[number] {
+  const { field: referencedField, ...settings } = relation;
+  return { ...settings, id: referencedField.id };
+}
+
+function compileGenerationInputEntity(entity: GenerationInputEntity): GenerationNodeSettings['entities']['input'][number] {
+  if (entity.dynamic === true) {
+    const {
+      field: referencedField,
+      optional = false,
+      jsonPath = '$',
+      description = '',
+      relations = [],
+      ...settings
+    } = entity;
+    return {
+      ...settings,
+      fieldProxyId: referencedField.id,
+      optional,
+      jsonPath,
+      description,
+      relations: relations.map(compileGenerationInputRelation)
+    };
+  }
+  const {
+    field: referencedField,
+    optional = false,
+    jsonPath = '$',
+    description = '',
+    relations = [],
+    dynamic = false,
+    ...settings
+  } = entity;
+  return {
+    ...settings,
+    fieldProxyId: referencedField.id,
+    optional,
+    jsonPath,
+    description,
+    relations: relations.map(compileGenerationInputRelation),
+    dynamic
+  };
+}
+
+function compileGenerationSettings(name: string, settings: GenerationAuthoringSettings): GenerationNodeSettings {
+  const { exam, ...settingsWithoutExam } = settings;
+  return {
+    ...settingsWithoutExam,
+    about: { ...settings.about, name: settings.about?.name ?? name },
+    entities: {
+      input: settings.entities.input.map(compileGenerationInputEntity),
+      output: settings.entities.output.map(compileGenerationInputEntity)
+    },
+    qualityCriteria: (settings.qualityCriteria ?? []).map((criterion) => ({
+      ...criterion,
+      targetEntity: criterion.targetEntity.id
+    })),
+    instruction: settings.instruction ?? '',
+    ui: settings.ui ?? {
+      code: '<></>',
+      data: '{}',
+      preprocess: 'return {}',
+      postprocess: 'return {};',
+      constants: '{}'
+    },
+    onboarding: settings.onboarding ?? {
+      enabled: true,
+      steps: [
+        {
+          id: 'step-1',
+          blocks: [
+            {
+              id: 'block-1',
+              type: 'text',
+              content: [{ type: 'markdown', value: 'Welcome to the onboarding!' }]
+            }
+          ]
+        }
+      ],
+      info: {
+        estimatedTime: '30',
+        role: 'Annotator',
+        goal: 'Successfully complete all onboarding steps',
+        successCriteria: 'Pass quiz, accept terms, and provide valid explanation'
+      }
+    },
+    ...(exam === undefined
+      ? {}
+      : {
+          exam: {
+            ...exam,
+            gradedEntities: exam.gradedEntities.map((entity) => ({
+              ...entity,
+              targetEntity: entity.targetEntity.id
+            }))
+          }
+        })
+  };
+}
+
+export function field<const Name extends string>(
+  name: Name,
+  jsonSchema: JsonSchema,
+  options: AuthoringIdOptions = {}
+): Field<Name> {
+  return {
+    id: options.id ?? mintedId('field', name),
+    name,
+    jsonSchema,
+    [FIELD_DEFINITION]: true
+  };
+}
+
+function createRoot(settings: RootAuthoringSettings, options: AuthoringIdOptions = {}): AuthoredRootNode {
+  const id = options.id ?? 'root';
+  const { started, completed, ...settingsWithoutFieldProxies } = settings;
+  return {
+    id,
+    type: 'root',
+    settings: {
+      ...settingsWithoutFieldProxies,
+      startedFieldProxies: { output: started.map(compileRootFieldProxy) },
+      completedFieldProxies: { input: completed.map(compileRootFieldProxy) }
+    },
+    started: outputPort(id, 'started'),
+    completed: inputPort(id, 'completed'),
+    [NODE_FIELD_REFERENCES]: referencedFields(settings)
+  };
+}
+
+export const root = Object.assign(createRoot, {
+  started: outputPort('root', 'started'),
+  completed: inputPort('root', 'completed')
+});
+
+export function code(
+  name: string,
+  settings: CodeAuthoringSettings,
+  options: AuthoringIdOptions = {}
+): AuthoredCodeNode {
+  const id = options.id ?? mintedId('code', name);
+  return {
+    id,
+    type: 'code',
+    settings: {
+      ...settings,
+      fieldProxies: {
+        input: settings.fieldProxies.input.map(compileFieldProxy),
+        output: settings.fieldProxies.output.map(compileFieldProxy)
+      }
+    },
+    input: inputPort(id, 'input'),
+    output: outputPort(id, 'output'),
+    [NODE_FIELD_REFERENCES]: referencedFields(settings)
+  };
+}
+
+export function generation(
+  name: string,
+  settings: GenerationAuthoringSettings,
+  options: AuthoringIdOptions = {}
+): AuthoredGenerationNode {
+  const id = options.id ?? mintedId('generation', name);
+  return {
+    id,
+    type: 'generation',
+    settings: compileGenerationSettings(name, settings),
+    input: inputPort(id, 'input'),
+    output: outputPort(id, 'output'),
+    [NODE_FIELD_REFERENCES]: referencedFields(settings)
+  };
+}
+
+export function match(
+  name: string,
+  settings: MatchAuthoringSettings,
+  options: AuthoringIdOptions = {}
+): AuthoredMatchNode {
+  const id = options.id ?? mintedId('match', name);
+  return {
+    id,
+    type: 'match',
+    settings: {
+      ...settings,
+      conditions: settings.conditions.map((condition) => ({
+        ...condition,
+        predicates: condition.predicates.map(({ field: referencedField, ...predicate }) => ({
+          ...predicate,
+          fieldProxyId: referencedField.id
+        }))
+      })),
+      fieldProxies: { input: settings.fieldProxies.input.map(compileFieldProxy) }
+    },
+    input: inputPort(id, 'input'),
+    default: outputPort(id, 'default'),
+    matched: (index) => outputPort(id, `matched_${index}`),
+    [NODE_FIELD_REFERENCES]: referencedFields(settings)
+  };
+}
+
+export function quorum(
+  name: string,
+  settings: QuorumAuthoringSettings,
+  options: AuthoringIdOptions = {}
+): AuthoredQuorumNode {
+  const id = options.id ?? mintedId('quorum', name);
+  const { exam, ...settingsWithoutExam } = settings;
+  return {
+    id,
+    type: 'quorum',
+    settings: {
+      ...settingsWithoutExam,
+      entities: {
+        input: settings.entities.input.map(compileGenerationInputEntity),
+        output: settings.entities.output.map(compileGenerationInputEntity)
+      },
+      qualityCriteria: settings.qualityCriteria.map((criterion) => ({
+        ...criterion,
+        targetEntity: criterion.targetEntity.id
+      })),
+      ...(exam === undefined
+        ? {}
+        : {
+            exam: {
+              ...exam,
+              gradedEntities: exam.gradedEntities.map((entity) => ({
+                ...entity,
+                targetEntity: entity.targetEntity.id
+              }))
+            }
+          })
+    },
+    input: inputPort(id, 'input'),
+    output: outputPort(id, 'output'),
+    [NODE_FIELD_REFERENCES]: referencedFields(settings)
+  };
+}
+
+export function connect(
+  from: OutputPort,
+  to: InputPort,
+  settings: PipelineGraphV1['connections'][number]['settings'] = {}
+): Connection {
+  return { from, to, settings };
+}
+
+export function definePipeline<const DatasetName extends string>(
+  definition: PipelineDefinitionInput<DatasetName>
+): PipelineDefinition<DatasetName> {
+  assert(definition.dataset.length > 0, 'Dataset name must not be empty');
+  const declaredFields = new Set(definition.fields);
+  const declaredFieldIds = new Set<string>();
+  for (const declaredField of definition.fields) {
+    assert(!declaredFieldIds.has(declaredField.id), `Field id "${declaredField.id}" is declared more than once`);
+    declaredFieldIds.add(declaredField.id);
+  }
+
+  const declaredNodeIds = new Set<string>();
+  for (const node of definition.nodes) {
+    assert(!declaredNodeIds.has(node.id), `Node id "${node.id}" is declared more than once`);
+    declaredNodeIds.add(node.id);
+    for (const referencedField of node[NODE_FIELD_REFERENCES]) {
+      assert(
+        declaredFields.has(referencedField),
+        `Field "${referencedField.name}" (${referencedField.id}) is referenced by node "${node.id}" but is not declared`
+      );
+    }
+  }
+
+  for (const connection of definition.connections) {
+    assert(declaredNodeIds.has(connection.from.node), `Connection source node "${connection.from.node}" is not declared`);
+    assert(declaredNodeIds.has(connection.to.node), `Connection target node "${connection.to.node}" is not declared`);
+  }
+
+  return {
+    dataset: definition.dataset,
+    [PIPELINE_DEFINITION]: true,
+    graph: {
+      version: 1,
+      fields: definition.fields.map(({ id, name, jsonSchema }) => ({ id, name, jsonSchema })),
+      nodes: definition.nodes.map((node) => {
+        switch (node.type) {
+          case 'root':
+            return { id: node.id, type: node.type, settings: node.settings };
+          case 'code':
+            return { id: node.id, type: node.type, settings: node.settings };
+          case 'generation':
+            return { id: node.id, type: node.type, settings: node.settings };
+          case 'match':
+            return { id: node.id, type: node.type, settings: node.settings };
+          case 'quorum':
+            return { id: node.id, type: node.type, settings: node.settings };
+        }
+      }),
+      connections: definition.connections.map(({ from, to, settings }) => ({
+        from: { node: from.node, handle: from.handle },
+        to: { node: to.node, handle: to.handle },
+        settings
+      }))
+    }
+  };
+}
+
+export function isPipelineDefinition(value: unknown): value is PipelineDefinition {
+  return typeof value === 'object' && value !== null && PIPELINE_DEFINITION in value;
+}
+
+export function validatePipelineDefinition(value: unknown): asserts value is PipelineDefinition {
+  assert(isPipelineDefinition(value), 'Invalid pipeline definition: expected a value returned by definePipeline');
+  assert(value.dataset.length > 0, 'Dataset name must not be empty');
+  for (const node of value.graph.nodes) {
+    if (node.type !== 'root') continue;
+    assert(!('datasetId' in node.settings), 'An unresolved pipeline definition cannot contain a dataset id');
+    assert(!('itemFilter' in node.settings), 'An unresolved pipeline definition cannot contain a dataset item filter');
+  }
+  validate(value.graph);
+}
+
+export function resolvePipelineDefinition(
+  definition: PipelineDefinition,
+  bindings: PipelineDefinitionBindings
+): PipelineGraphV1 {
+  const graph: PipelineGraphV1 = {
+    version: definition.graph.version,
+    fields: definition.graph.fields.map((fieldDefinition) => ({ ...fieldDefinition })),
+    nodes: definition.graph.nodes.map((node) =>
+      node.type === 'root' ? { ...node, settings: { ...node.settings, datasetId: bindings.datasetId } } : node
+    ),
+    connections: definition.graph.connections.map((connection) => ({
+      from: { ...connection.from },
+      to: { ...connection.to },
+      settings: { ...connection.settings }
+    }))
+  };
+  validate(graph);
+  return graph;
+}