@codemation/core-nodes 0.0.15 → 0.0.18

package/src/workflowAuthoring/WorkflowAgentNodeFactory.types.ts

@@ -0,0 +1,34 @@
+import { z } from "zod";
+import { AIAgent } from "../nodes/AIAgentConfig";
+import type { WorkflowAgentOptions } from "./WorkflowAuthoringOptions.types";
+import { WorkflowChatModelFactory } from "./WorkflowChatModelFactory.types";
+
+export class WorkflowAgentNodeFactory {
+  static create<TCurrentJson, TOutputSchema extends z.ZodTypeAny | undefined>(
+    nameOrOptions: string | WorkflowAgentOptions<TCurrentJson, TOutputSchema>,
+    optionsOrUndefined?: WorkflowAgentOptions<TCurrentJson, TOutputSchema>,
+  ): AIAgent<TCurrentJson, TOutputSchema extends z.ZodTypeAny ? z.output<TOutputSchema> : Record<string, unknown>> {
+    const options = typeof nameOrOptions === "string" ? optionsOrUndefined! : nameOrOptions;
+    const name = typeof nameOrOptions === "string" ? nameOrOptions : "AI agent";
+    const prompt = options.prompt;
+    const messages = [
+      {
+        role: "user" as const,
+        content:
+          typeof prompt === "function" ? ({ item }: { item: { json: TCurrentJson } }) => prompt(item.json) : prompt,
+      },
+    ] as const;
+    return new AIAgent<
+      TCurrentJson,
+      TOutputSchema extends z.ZodTypeAny ? z.output<TOutputSchema> : Record<string, unknown>
+    >({
+      name,
+      messages,
+      chatModel: WorkflowChatModelFactory.create(options.model),
+      tools: options.tools,
+      id: options.id,
+      retryPolicy: options.retryPolicy,
+      guardrails: options.guardrails,
+    });
+  }
+}

package/src/workflowAuthoring/WorkflowAuthoringBuilder.types.ts

@@ -0,0 +1,43 @@
+import { ChainCursor } from "@codemation/core";
+import { ManualTrigger } from "../nodes/ManualTriggerFactory";
+import { createWorkflowBuilder } from "../workflowBuilder.types";
+import { WorkflowChain } from "./WorkflowChain.types";
+
+export class WorkflowAuthoringBuilder {
+  constructor(
+    private readonly id: string,
+    private readonly workflowName: string = id,
+  ) {}
+
+  name(name: string): WorkflowAuthoringBuilder {
+    return new WorkflowAuthoringBuilder(this.id, name);
+  }
+
+  manualTrigger<TOutputJson>(defaultItems: TOutputJson | ReadonlyArray<TOutputJson>): WorkflowChain<TOutputJson>;
+  manualTrigger<TOutputJson>(
+    name: string,
+    defaultItems?: TOutputJson | ReadonlyArray<TOutputJson>,
+    id?: string,
+  ): WorkflowChain<TOutputJson>;
+  manualTrigger<TOutputJson>(
+    nameOrDefaultItems: string | TOutputJson | ReadonlyArray<TOutputJson>,
+    defaultItemsOrUndefined?: TOutputJson | ReadonlyArray<TOutputJson>,
+    id?: string,
+  ): WorkflowChain<TOutputJson> {
+    const builder = createWorkflowBuilder({ id: this.id, name: this.workflowName });
+    if (typeof nameOrDefaultItems === "string") {
+      return new WorkflowChain(
+        builder.trigger(
+          new ManualTrigger<TOutputJson>(
+            nameOrDefaultItems,
+            defaultItemsOrUndefined as TOutputJson | ReadonlyArray<TOutputJson>,
+            id,
+          ),
+        ) as ChainCursor<TOutputJson>,
+      );
+    }
+    return new WorkflowChain(
+      builder.trigger(new ManualTrigger<TOutputJson>("Manual trigger", nameOrDefaultItems)) as ChainCursor<TOutputJson>,
+    );
+  }
+}

package/src/workflowAuthoring/WorkflowAuthoringOptions.types.ts

@@ -0,0 +1,14 @@
+import type { AgentGuardrailConfig, ChatModelConfig, RunnableNodeConfig, ToolConfig } from "@codemation/core";
+import { z } from "zod";
+
+export type WorkflowAgentPrompt<TCurrentJson> = string | ((item: TCurrentJson) => string);
+
+export interface WorkflowAgentOptions<TCurrentJson, TOutputSchema extends z.ZodTypeAny | undefined = undefined> {
+  readonly prompt: WorkflowAgentPrompt<TCurrentJson>;
+  readonly model: string | ChatModelConfig;
+  readonly tools?: ReadonlyArray<ToolConfig>;
+  readonly outputSchema?: TOutputSchema;
+  readonly retryPolicy?: RunnableNodeConfig["retryPolicy"];
+  readonly guardrails?: AgentGuardrailConfig;
+  readonly id?: string;
+}

package/src/workflowAuthoring/WorkflowBranchBuilder.types.ts

@@ -0,0 +1,85 @@
+import type { AnyRunnableNodeConfig, DefinedNode, RunnableNodeConfig, RunnableNodeOutputJson } from "@codemation/core";
+import { z } from "zod";
+import { MapData } from "../nodes/mapData";
+import { Wait } from "../nodes/wait";
+import type { WorkflowAgentOptions } from "./WorkflowAuthoringOptions.types";
+import { WorkflowAgentNodeFactory } from "./WorkflowAgentNodeFactory.types";
+import { WorkflowDefinedNodeResolver } from "./WorkflowDefinedNodeResolver.types";
+import { WorkflowDurationParser } from "./WorkflowDurationParser.types";
+
+export class WorkflowBranchBuilder<TCurrentJson> {
+  constructor(private readonly steps: ReadonlyArray<AnyRunnableNodeConfig> = []) {}
+
+  then<TConfig extends RunnableNodeConfig<TCurrentJson, any>>(
+    config: TConfig,
+  ): WorkflowBranchBuilder<RunnableNodeOutputJson<TConfig>> {
+    return new WorkflowBranchBuilder<RunnableNodeOutputJson<TConfig>>([...this.steps, config]);
+  }
+
+  map<TNextJson>(mapper: (item: TCurrentJson) => TNextJson): WorkflowBranchBuilder<TNextJson>;
+  map<TNextJson>(
+    name: string,
+    mapper: (item: TCurrentJson) => TNextJson,
+    id?: string,
+  ): WorkflowBranchBuilder<TNextJson>;
+  map<TNextJson>(
+    nameOrMapper: string | ((item: TCurrentJson) => TNextJson),
+    mapperOrUndefined?: (item: TCurrentJson) => TNextJson,
+    id?: string,
+  ): WorkflowBranchBuilder<TNextJson> {
+    const name = typeof nameOrMapper === "string" ? nameOrMapper : "Map data";
+    const mapper = typeof nameOrMapper === "string" ? mapperOrUndefined! : nameOrMapper;
+    return this.then(
+      new MapData<TCurrentJson, TNextJson>(name, (item) => mapper(item.json as TCurrentJson), id),
+    ) as WorkflowBranchBuilder<TNextJson>;
+  }
+
+  wait(duration: number | string): WorkflowBranchBuilder<TCurrentJson>;
+  wait(name: string, duration: number | string, id?: string): WorkflowBranchBuilder<TCurrentJson>;
+  wait(
+    nameOrDuration: string | number,
+    durationOrUndefined?: string | number,
+    id?: string,
+  ): WorkflowBranchBuilder<TCurrentJson> {
+    const name = typeof nameOrDuration === "string" && durationOrUndefined !== undefined ? nameOrDuration : "Wait";
+    const duration = durationOrUndefined ?? nameOrDuration;
+    return this.then(
+      new Wait<TCurrentJson>(name, WorkflowDurationParser.parse(duration), id),
+    ) as WorkflowBranchBuilder<TCurrentJson>;
+  }
+
+  agent<TOutputSchema extends z.ZodTypeAny>(
+    options: WorkflowAgentOptions<TCurrentJson, TOutputSchema>,
+  ): WorkflowBranchBuilder<z.output<TOutputSchema>>;
+  agent(options: WorkflowAgentOptions<TCurrentJson, undefined>): WorkflowBranchBuilder<Record<string, unknown>>;
+  agent<TOutputSchema extends z.ZodTypeAny>(
+    name: string,
+    options: WorkflowAgentOptions<TCurrentJson, TOutputSchema | undefined>,
+  ): WorkflowBranchBuilder<TOutputSchema extends z.ZodTypeAny ? z.output<TOutputSchema> : Record<string, unknown>>;
+  agent<TOutputSchema extends z.ZodTypeAny>(
+    nameOrOptions: string | WorkflowAgentOptions<TCurrentJson, TOutputSchema | undefined>,
+    optionsOrUndefined?: WorkflowAgentOptions<TCurrentJson, TOutputSchema | undefined>,
+  ): WorkflowBranchBuilder<TOutputSchema extends z.ZodTypeAny ? z.output<TOutputSchema> : Record<string, unknown>> {
+    return this.then(WorkflowAgentNodeFactory.create(nameOrOptions, optionsOrUndefined)) as WorkflowBranchBuilder<
+      TOutputSchema extends z.ZodTypeAny ? z.output<TOutputSchema> : Record<string, unknown>
+    >;
+  }
+
+  node<TConfig extends Record<string, unknown>, TOutputJson>(
+    definitionOrKey: DefinedNode<string, TConfig, TCurrentJson, TOutputJson> | string,
+    config: TConfig,
+    name?: string,
+    id?: string,
+  ): WorkflowBranchBuilder<TOutputJson> {
+    const definition = WorkflowDefinedNodeResolver.resolve(
+      definitionOrKey as DefinedNode<string, Record<string, unknown>, unknown, unknown> | string,
+    ) as DefinedNode<string, TConfig, TCurrentJson, TOutputJson>;
+    return this.then(
+      definition.create(config, name, id) as RunnableNodeConfig<TCurrentJson, TOutputJson>,
+    ) as WorkflowBranchBuilder<TOutputJson>;
+  }
+
+  getSteps(): ReadonlyArray<AnyRunnableNodeConfig> {
+    return this.steps;
+  }
+}

package/src/workflowAuthoring/WorkflowChain.types.ts

@@ -0,0 +1,132 @@
+import type { DefinedNode, RunnableNodeConfig, RunnableNodeOutputJson, WorkflowDefinition } from "@codemation/core";
+import { ChainCursor } from "@codemation/core";
+import { z } from "zod";
+import { If } from "../nodes/if";
+import { MapData } from "../nodes/mapData";
+import { Wait } from "../nodes/wait";
+import type { WorkflowAgentOptions } from "./WorkflowAuthoringOptions.types";
+import { WorkflowAgentNodeFactory } from "./WorkflowAgentNodeFactory.types";
+import { WorkflowBranchBuilder } from "./WorkflowBranchBuilder.types";
+import { WorkflowDefinedNodeResolver } from "./WorkflowDefinedNodeResolver.types";
+import { WorkflowDurationParser } from "./WorkflowDurationParser.types";
+
+type BranchCallback<TCurrentJson, TNextJson> = (
+  branch: WorkflowBranchBuilder<TCurrentJson>,
+) => WorkflowBranchBuilder<TNextJson>;
+type BranchOutputMatch<TLeft, TRight> = [TLeft] extends [TRight] ? ([TRight] extends [TLeft] ? true : false) : false;
+
+export class WorkflowChain<TCurrentJson> {
+  constructor(private readonly chain: ChainCursor<TCurrentJson>) {}
+
+  then<TConfig extends RunnableNodeConfig<TCurrentJson, any>>(
+    config: TConfig,
+  ): WorkflowChain<RunnableNodeOutputJson<TConfig>> {
+    return new WorkflowChain(this.chain.then(config));
+  }
+
+  map<TNextJson>(mapper: (item: TCurrentJson) => TNextJson): WorkflowChain<TNextJson>;
+  map<TNextJson>(name: string, mapper: (item: TCurrentJson) => TNextJson, id?: string): WorkflowChain<TNextJson>;
+  map<TNextJson>(
+    nameOrMapper: string | ((item: TCurrentJson) => TNextJson),
+    mapperOrUndefined?: (item: TCurrentJson) => TNextJson,
+    id?: string,
+  ): WorkflowChain<TNextJson> {
+    const name = typeof nameOrMapper === "string" ? nameOrMapper : "Map data";
+    const mapper = typeof nameOrMapper === "string" ? mapperOrUndefined! : nameOrMapper;
+    return this.then(
+      new MapData<TCurrentJson, TNextJson>(name, (item) => mapper(item.json as TCurrentJson), id),
+    ) as WorkflowChain<TNextJson>;
+  }
+
+  wait(duration: number | string): WorkflowChain<TCurrentJson>;
+  wait(name: string, duration: number | string, id?: string): WorkflowChain<TCurrentJson>;
+  wait(
+    nameOrDuration: string | number,
+    durationOrUndefined?: string | number,
+    id?: string,
+  ): WorkflowChain<TCurrentJson> {
+    const name = typeof nameOrDuration === "string" && durationOrUndefined !== undefined ? nameOrDuration : "Wait";
+    const duration = durationOrUndefined ?? nameOrDuration;
+    return this.then(
+      new Wait<TCurrentJson>(name, WorkflowDurationParser.parse(duration), id),
+    ) as WorkflowChain<TCurrentJson>;
+  }
+
+  if<TBranchJson>(
+    predicate: (item: TCurrentJson) => boolean,
+    branches: Readonly<{
+      true?: BranchCallback<TCurrentJson, TBranchJson>;
+      false?: BranchCallback<TCurrentJson, TBranchJson>;
+    }>,
+  ): WorkflowChain<TBranchJson>;
+  if<TBranchJson>(
+    name: string,
+    predicate: (item: TCurrentJson) => boolean,
+    branches: Readonly<{
+      true?: BranchCallback<TCurrentJson, TBranchJson>;
+      false?: BranchCallback<TCurrentJson, TBranchJson>;
+    }>,
+  ): WorkflowChain<TBranchJson>;
+  if<TTrueJson, TFalseJson>(
+    nameOrPredicate: string | ((item: TCurrentJson) => boolean),
+    predicateOrBranches:
+      | ((item: TCurrentJson) => boolean)
+      | Readonly<{ true?: BranchCallback<TCurrentJson, TTrueJson>; false?: BranchCallback<TCurrentJson, TFalseJson> }>,
+    branchesOrUndefined?: Readonly<{
+      true?: BranchCallback<TCurrentJson, TTrueJson>;
+      false?: BranchCallback<TCurrentJson, TFalseJson>;
+    }>,
+  ): WorkflowChain<BranchOutputMatch<TTrueJson, TFalseJson> extends true ? TTrueJson : never> {
+    const name = typeof nameOrPredicate === "string" ? nameOrPredicate : "If";
+    const predicate =
+      typeof nameOrPredicate === "string" ? (predicateOrBranches as (item: TCurrentJson) => boolean) : nameOrPredicate;
+    const branches = (typeof nameOrPredicate === "string" ? branchesOrUndefined : predicateOrBranches) as Readonly<{
+      true?: BranchCallback<TCurrentJson, TTrueJson>;
+      false?: BranchCallback<TCurrentJson, TFalseJson>;
+    }>;
+    const cursor = this.chain.then(new If<TCurrentJson>(name, (item) => predicate(item.json as TCurrentJson)));
+    const trueSteps = branches.true?.(new WorkflowBranchBuilder<TCurrentJson>()).getSteps();
+    const falseSteps = branches.false?.(new WorkflowBranchBuilder<TCurrentJson>()).getSteps();
+    return new WorkflowChain(
+      cursor.when({
+        true: trueSteps,
+        false: falseSteps,
+      }),
+    ) as WorkflowChain<BranchOutputMatch<TTrueJson, TFalseJson> extends true ? TTrueJson : never>;
+  }
+
+  agent<TOutputSchema extends z.ZodTypeAny>(
+    options: WorkflowAgentOptions<TCurrentJson, TOutputSchema>,
+  ): WorkflowChain<z.output<TOutputSchema>>;
+  agent(options: WorkflowAgentOptions<TCurrentJson, undefined>): WorkflowChain<Record<string, unknown>>;
+  agent<TOutputSchema extends z.ZodTypeAny>(
+    name: string,
+    options: WorkflowAgentOptions<TCurrentJson, TOutputSchema | undefined>,
+  ): WorkflowChain<TOutputSchema extends z.ZodTypeAny ? z.output<TOutputSchema> : Record<string, unknown>>;
+  agent<TOutputSchema extends z.ZodTypeAny>(
+    nameOrOptions: string | WorkflowAgentOptions<TCurrentJson, TOutputSchema | undefined>,
+    optionsOrUndefined?: WorkflowAgentOptions<TCurrentJson, TOutputSchema | undefined>,
+  ): WorkflowChain<TOutputSchema extends z.ZodTypeAny ? z.output<TOutputSchema> : Record<string, unknown>> {
+    return this.then(WorkflowAgentNodeFactory.create(nameOrOptions, optionsOrUndefined)) as WorkflowChain<
+      TOutputSchema extends z.ZodTypeAny ? z.output<TOutputSchema> : Record<string, unknown>
+    >;
+  }
+
+  node<TConfig extends Record<string, unknown>, TOutputJson>(
+    definitionOrKey: DefinedNode<string, TConfig, TCurrentJson, TOutputJson> | string,
+    config: TConfig,
+    name?: string,
+    id?: string,
+  ): WorkflowChain<TOutputJson> {
+    const definition = WorkflowDefinedNodeResolver.resolve(
+      definitionOrKey as DefinedNode<string, Record<string, unknown>, unknown, unknown> | string,
+    ) as DefinedNode<string, TConfig, TCurrentJson, TOutputJson>;
+    return this.then(
+      definition.create(config, name, id) as RunnableNodeConfig<TCurrentJson, TOutputJson>,
+    ) as WorkflowChain<TOutputJson>;
+  }
+
+  build(): WorkflowDefinition {
+    return this.chain.build();
+  }
+}

package/src/workflowAuthoring/WorkflowChatModelFactory.types.ts

@@ -0,0 +1,15 @@
+import type { ChatModelConfig } from "@codemation/core";
+import { OpenAIChatModelConfig } from "../chatModels/openAiChatModelConfig";
+
+export class WorkflowChatModelFactory {
+  static create(model: string | ChatModelConfig): ChatModelConfig {
+    if (typeof model !== "string") {
+      return model;
+    }
+    const [provider, resolvedModel] = model.includes(":") ? model.split(":", 2) : ["openai", model];
+    if (provider !== "openai") {
+      throw new Error(`Unsupported workflow().agent() model provider "${provider}".`);
+    }
+    return new OpenAIChatModelConfig("OpenAI", resolvedModel);
+  }
+}

package/src/workflowAuthoring/WorkflowDefinedNodeResolver.types.ts

@@ -0,0 +1,16 @@
+import { DefinedNodeRegistry, type DefinedNode } from "@codemation/core";
+
+export class WorkflowDefinedNodeResolver {
+  static resolve(
+    definitionOrKey: DefinedNode<string, Record<string, unknown>, unknown, unknown> | string,
+  ): DefinedNode<string, Record<string, unknown>, unknown, unknown> {
+    if (typeof definitionOrKey !== "string") {
+      return definitionOrKey;
+    }
+    const definition = DefinedNodeRegistry.resolve(definitionOrKey);
+    if (!definition) {
+      throw new Error(`No helper-defined node with key "${definitionOrKey}" is registered in this module graph.`);
+    }
+    return definition;
+  }
+}

package/src/workflowAuthoring/WorkflowDurationParser.types.ts

@@ -0,0 +1,26 @@
+export class WorkflowDurationParser {
+  static parse(duration: number | string): number {
+    if (typeof duration === "number") {
+      return Number.isFinite(duration) && duration > 0 ? Math.floor(duration) : 0;
+    }
+    const normalized = duration.trim().toLowerCase();
+    const match = normalized.match(/^(\d+)(ms|s|m|h)$/);
+    if (!match) {
+      throw new Error(
+        `Unsupported wait duration "${duration}". Use a number of milliseconds or values like "500ms", "2s", "5m".`,
+      );
+    }
+    const value = Number(match[1]);
+    const unit = match[2];
+    if (unit === "ms") {
+      return value;
+    }
+    if (unit === "s") {
+      return value * 1000;
+    }
+    if (unit === "m") {
+      return value * 60_000;
+    }
+    return value * 3_600_000;
+  }
+}

package/src/workflowAuthoring.types.ts

@@ -0,0 +1,10 @@
+export type { WorkflowAgentOptions } from "./workflowAuthoring/WorkflowAuthoringOptions.types";
+export { WorkflowAuthoringBuilder } from "./workflowAuthoring/WorkflowAuthoringBuilder.types";
+export { WorkflowBranchBuilder } from "./workflowAuthoring/WorkflowBranchBuilder.types";
+export { WorkflowChain } from "./workflowAuthoring/WorkflowChain.types";
+
+import { WorkflowAuthoringBuilder } from "./workflowAuthoring/WorkflowAuthoringBuilder.types";
+
+export function workflow(id: string): WorkflowAuthoringBuilder {
+  return new WorkflowAuthoringBuilder(id);
+}