@synergenius/flow-weaver 0.2.0

package/dist/cli/templates/workflows/ai-react.js

@@ -0,0 +1,294 @@
+import { LLM_SIMPLE_TYPES } from '../shared/llm-types.js';
+export const aiReactTemplate = {
+    id: 'ai-react',
+    name: 'ReAct Agent',
+    description: 'Reasoning + Acting agent with explicit thought process',
+    category: 'ai',
+    generate: (opts) => {
+        const { workflowName } = opts;
+        return `
+// ============================================================
+// ReAct Agent — Thought → Action → Observation loop
+// ============================================================
+//
+// The agent follows the ReAct pattern (Yao et al., 2022):
+//   1. Think — reason about the current state
+//   2. Act — call a tool or FINISH
+//   3. Observe — receive tool output, feed back into next thought
+//
+// The reactLoop node manages iteration and message accumulation.
+// think + act run inside the loop's scoped iteration.
+
+// ============================================================
+// LLM TYPES
+// ============================================================
+
+${LLM_SIMPLE_TYPES}
+
+// Mock provider — replace with real provider
+const createMockReactProvider = (): LLMProvider => ({
+  async chat(messages) {
+    const lastMessage = messages[messages.length - 1];
+    return {
+      content: \`Thought: Processing the request\\nAction: FINISH\\nAction Input: [Mock answer to: \${lastMessage.content.slice(0, 30)}...]\`,
+      toolCalls: [],
+      finishReason: 'stop',
+    };
+  },
+});
+
+const llmProvider: LLMProvider = (globalThis as unknown as { __fw_llm_provider__?: LLMProvider }).__fw_llm_provider__ ?? createMockReactProvider();
+const MAX_STEPS = 10;
+
+const REACT_PROMPT = \`You are a ReAct (Reasoning + Acting) agent.
+
+For each step, you MUST respond in this exact format:
+Thought: [Your reasoning about what to do next]
+Action: [tool_name] or [FINISH]
+Action Input: [input for the tool, or final answer if FINISH]
+
+Available tools: search, calculate
+
+When you have the final answer:
+Thought: I now have enough information to answer
+Action: FINISH
+Action Input: [Your final answer here]\`;
+
+// Parse ReAct response format
+function parseReactResponse(content: string): {
+  thought: string;
+  action: string;
+  actionInput: string;
+} {
+  const thoughtMatch = content.match(/Thought:\\s*(.+?)(?=\\nAction:|$)/s);
+  const actionMatch = content.match(/Action:\\s*(.+?)(?=\\nAction Input:|$)/s);
+  const inputMatch = content.match(/Action Input:\\s*(.+?)$/s);
+
+  return {
+    thought: thoughtMatch?.[1]?.trim() ?? '',
+    action: actionMatch?.[1]?.trim() ?? 'FINISH',
+    actionInput: inputMatch?.[1]?.trim() ?? '',
+  };
+}
+
+// ============================================================
+// TOOL IMPLEMENTATIONS
+// ============================================================
+
+// Replace with real tools
+const TOOL_IMPLEMENTATIONS: Record<string, (input: string) => Promise<string>> = {
+  async search(input: string): Promise<string> {
+    return '[Search results for: ' + input + ']';
+  },
+  async calculate(input: string): Promise<string> {
+    return '[Calculation result for: ' + input + ']';
+  },
+};
+
+// ============================================================
+// NODES
+// ============================================================
+
+/**
+ * ReAct loop — manages Think→Act→Observe iterations.
+ * Accumulates messages and terminates when action is FINISH or max steps.
+ *
+ * @flowWeaver nodeType
+ * @label ReAct Loop
+ * @input execute [order:0] - Execute
+ * @input task [order:1] - Task for the agent
+ * @input success scope:step [order:0] - Iteration succeeded
+ * @input failure scope:step [order:1] - Iteration failed
+ * @input thought scope:step [order:2] - Agent's reasoning
+ * @input action scope:step [order:3] - Action name
+ * @input actionInput scope:step [order:4] - Action input / final answer
+ * @input observation scope:step [order:5] - Tool observation
+ * @output onSuccess [order:0] - On Success (finished)
+ * @output onFailure [order:1] - On Failure
+ * @output start scope:step [order:0] - Triggers iteration
+ * @output messages scope:step [order:1] - Current messages for LLM
+ * @output answer [order:2] - Final answer
+ */
+async function reactLoop(
+  execute: boolean,
+  task: string,
+  step: (start: boolean, messages: LLMMessage[]) => Promise<{
+    success: boolean;
+    failure: boolean;
+    thought: string;
+    action: string;
+    actionInput: string;
+    observation: string;
+  }>
+): Promise<{ onSuccess: boolean; onFailure: boolean; answer: string }> {
+  if (!execute) {
+    return { onSuccess: false, onFailure: false, answer: '' };
+  }
+
+  const messages: LLMMessage[] = [{ role: 'user', content: task }];
+
+  for (let i = 0; i < MAX_STEPS; i++) {
+    const result = await step(true, messages);
+
+    if (result.failure) {
+      return { onSuccess: false, onFailure: true, answer: '' };
+    }
+
+    // Append thought + action as assistant message
+    messages.push({
+      role: 'assistant',
+      content: \`Thought: \${result.thought}\\nAction: \${result.action}\\nAction Input: \${result.actionInput}\`,
+    });
+
+    // Check termination
+    if (result.action.toUpperCase() === 'FINISH') {
+      return { onSuccess: true, onFailure: false, answer: result.actionInput };
+    }
+
+    // Append observation
+    if (result.observation) {
+      messages.push({ role: 'user', content: \`Observation: \${result.observation}\` });
+    }
+  }
+
+  return { onSuccess: true, onFailure: false, answer: 'Max steps reached' };
+}
+
+/**
+ * ReAct reasoning step — calls LLM and parses Thought/Action/ActionInput
+ *
+ * @flowWeaver nodeType
+ * @label Think
+ * @input execute [order:0] - Execute
+ * @input messages [order:1] - Conversation history
+ * @output onSuccess [order:0] - On Success
+ * @output onFailure [order:1] - On Failure
+ * @output thought [order:2] - Agent's reasoning
+ * @output action [order:3] - Action to take (tool name or FINISH)
+ * @output actionInput [order:4] - Input for action or final answer
+ */
+async function think(
+  execute: boolean,
+  messages: LLMMessage[]
+): Promise<{
+  onSuccess: boolean;
+  onFailure: boolean;
+  thought: string;
+  action: string;
+  actionInput: string;
+}> {
+  if (!execute) {
+    return { onSuccess: false, onFailure: false, thought: '', action: '', actionInput: '' };
+  }
+
+  try {
+    const response = await llmProvider.chat(messages, { systemPrompt: REACT_PROMPT });
+    const parsed = parseReactResponse(response.content ?? '');
+
+    return {
+      onSuccess: true,
+      onFailure: false,
+      thought: parsed.thought,
+      action: parsed.action,
+      actionInput: parsed.actionInput,
+    };
+  } catch {
+    return { onSuccess: false, onFailure: true, thought: '', action: '', actionInput: '' };
+  }
+}
+
+/**
+ * Execute action and return observation
+ *
+ * @flowWeaver nodeType
+ * @label Act
+ * @input execute [order:0] - Execute
+ * @input action [order:1] - Tool name to execute
+ * @input actionInput [order:2] - Input for tool
+ * @output onSuccess [order:0] - On Success
+ * @output onFailure [order:1] - On Failure
+ * @output observation [order:2] - Tool observation result
+ */
+async function act(
+  execute: boolean,
+  action: string,
+  actionInput: string
+): Promise<{
+  onSuccess: boolean;
+  onFailure: boolean;
+  observation: string;
+}> {
+  if (!execute) {
+    return { onSuccess: false, onFailure: false, observation: '' };
+  }
+
+  const tool = TOOL_IMPLEMENTATIONS[action.toLowerCase()];
+  if (!tool) {
+    return {
+      onSuccess: true,
+      onFailure: false,
+      observation: 'Unknown tool: ' + action,
+    };
+  }
+
+  try {
+    const observation = await tool(actionInput);
+    return { onSuccess: true, onFailure: false, observation };
+  } catch (error) {
+    return { onSuccess: false, onFailure: true, observation: '' };
+  }
+}
+
+// ============================================================
+// WORKFLOW
+// ============================================================
+
+/**
+ * ReAct Agent — iterative Thought→Action→Observation loop
+ *
+ * @flowWeaver workflow
+ * @node loop reactLoop [size: 450 250]
+ * @node thinking think loop.step
+ * @node acting act loop.step
+ * @position Start -400 0
+ * @position loop -150 0
+ * @position thinking -80 30
+ * @position acting 130 30
+ * @position Exit 350 0
+ * @connect Start.execute -> loop.execute
+ * @connect Start.task -> loop.task
+ * @connect loop.start -> thinking.execute
+ * @connect loop.messages -> thinking.messages
+ * @connect thinking.onSuccess -> acting.execute
+ * @connect thinking.action -> acting.action
+ * @connect thinking.actionInput -> acting.actionInput
+ * @connect thinking.thought -> loop.thought
+ * @connect thinking.action -> loop.action
+ * @connect thinking.actionInput -> loop.actionInput
+ * @connect thinking.onFailure -> loop.failure
+ * @connect acting.observation -> loop.observation
+ * @connect acting.onSuccess -> loop.success
+ * @connect acting.onFailure -> loop.failure
+ * @connect loop.onSuccess -> Exit.onSuccess
+ * @connect loop.onFailure -> Exit.onFailure
+ * @connect loop.answer -> Exit.answer
+ * @param execute [order:0] - Execute
+ * @param task [order:1] - Task for the agent
+ * @returns onSuccess [order:0] - On Success
+ * @returns onFailure [order:1] - On Failure
+ * @returns answer [order:2] - Final answer
+ */
+export async function ${workflowName}(
+  execute: boolean,
+  params: { task: string }
+): Promise<{
+  onSuccess: boolean;
+  onFailure: boolean;
+  answer: string;
+}> {
+  throw new Error('Compile with: flow-weaver compile <file>');
+}
+`.trim();
+    },
+};
+//# sourceMappingURL=ai-react.js.map

package/dist/cli/templates/workflows/conditional.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Conditional Router Template
+ * Decision branching with success/failure paths
+ *
+ * Design: evaluateCondition uses onSuccess for "condition met" and
+ * onFailure for "condition not met". Error handling is done inside
+ * the function body via try/catch — errors route to Exit.onFailure
+ * via the handler chain.
+ */
+import type { WorkflowTemplate } from '../index.js';
+export declare const conditionalTemplate: WorkflowTemplate;
+//# sourceMappingURL=conditional.d.ts.map

package/dist/cli/templates/workflows/conditional.js

@@ -0,0 +1,142 @@
+/**
+ * Conditional Router Template
+ * Decision branching with success/failure paths
+ *
+ * Design: evaluateCondition uses onSuccess for "condition met" and
+ * onFailure for "condition not met". Error handling is done inside
+ * the function body via try/catch — errors route to Exit.onFailure
+ * via the handler chain.
+ */
+export const conditionalTemplate = {
+    id: 'conditional',
+    name: 'Conditional Router',
+    description: 'Route data based on conditions with branching paths',
+    category: 'automation',
+    generate: (opts) => {
+        const { workflowName, async: isAsync } = opts;
+        const asyncKeyword = isAsync ? 'async ' : '';
+        const returnType = isAsync
+            ? 'Promise<{ onSuccess: boolean; onFailure: boolean; successResult?: any; failureResult?: any }>'
+            : '{ onSuccess: boolean; onFailure: boolean; successResult?: any; failureResult?: any }';
+        return `
+/**
+ * Evaluates condition and routes data.
+ * onSuccess = condition met (true path), onFailure = condition not met (false path).
+ * Errors are caught internally and returned via the onFailure path.
+ *
+ * @flowWeaver nodeType
+ * @label Evaluate Condition
+ * @input data [order:1] - Data to evaluate
+ * @input execute [order:0] - Execute
+ * @output conditionTrue [order:2] - Data if condition passed
+ * @output conditionFalse [order:3] - Data if condition failed
+ * @output conditionMet [order:4] - Whether condition was met
+ * @output onSuccess [order:0] - Condition passed (routes to success handler)
+ * @output onFailure [order:1] - Condition not met (routes to failure handler)
+ */
+function evaluateCondition(
+  execute: boolean,
+  data: any
+): { onSuccess: boolean; onFailure: boolean; conditionTrue: any; conditionFalse: any; conditionMet: boolean } {
+  if (!execute) {
+    return { onSuccess: false, onFailure: false, conditionTrue: null, conditionFalse: null, conditionMet: false };
+  }
+
+  try {
+    // TODO: Define your condition logic
+    const conditionMet = Boolean(data && data.isValid);
+
+    if (conditionMet) {
+      return { onSuccess: true, onFailure: false, conditionTrue: data, conditionFalse: null, conditionMet: true };
+    } else {
+      return { onSuccess: false, onFailure: true, conditionTrue: null, conditionFalse: data, conditionMet: false };
+    }
+  } catch (err) {
+    // On error, route to failure path with the original data
+    return { onSuccess: false, onFailure: true, conditionTrue: null, conditionFalse: data, conditionMet: false };
+  }
+}
+
+/**
+ * Handles success path
+ *
+ * @flowWeaver nodeType
+ * @label Handle Success
+ * @input data [order:1] - Data from success path
+ * @input execute [order:0] - Execute
+ * @output result [order:2] - Success result
+ * @output onSuccess [order:0] - On Success
+ * @output onFailure [order:1] - On Failure
+ */
+function handleSuccess(
+  execute: boolean,
+  data: any
+): { onSuccess: boolean; onFailure: boolean; result: any } {
+  if (!execute) {
+    return { onSuccess: false, onFailure: false, result: null };
+  }
+
+  // TODO: Handle success case
+  return { onSuccess: true, onFailure: false, result: { status: "success", data } };
+}
+
+/**
+ * Handles failure path
+ *
+ * @flowWeaver nodeType
+ * @label Handle Failure
+ * @input data [order:1] - Data from failure path
+ * @input execute [order:0] - Execute
+ * @output result [order:2] - Failure result
+ * @output onSuccess [order:0] - On Success
+ * @output onFailure [order:1] - On Failure
+ */
+function handleFailure(
+  execute: boolean,
+  data: any
+): { onSuccess: boolean; onFailure: boolean; result: any } {
+  if (!execute) {
+    return { onSuccess: false, onFailure: false, result: null };
+  }
+
+  // TODO: Handle failure case
+  return { onSuccess: true, onFailure: false, result: { status: "failure", data } };
+}
+
+/**
+ * @flowWeaver workflow
+ * @node router evaluateCondition
+ * @node successHandler handleSuccess
+ * @node failureHandler handleFailure
+ * @position Start -450 0
+ * @position router -180 0
+ * @position successHandler 90 -90
+ * @position failureHandler 90 90
+ * @position Exit 360 0
+ * @connect Start.execute -> router.execute
+ * @connect Start.data -> router.data
+ * @connect router.onSuccess -> successHandler.execute
+ * @connect router.conditionTrue -> successHandler.data
+ * @connect router.onFailure -> failureHandler.execute
+ * @connect router.conditionFalse -> failureHandler.data
+ * @connect successHandler.result -> Exit.successResult
+ * @connect successHandler.onSuccess -> Exit.onSuccess
+ * @connect failureHandler.result -> Exit.failureResult
+ * @connect failureHandler.onSuccess -> Exit.onFailure
+ * @param execute [order:0] - Execute
+ * @param data [order:1] - Input data to route
+ * @returns onSuccess [order:0] - Success path completed
+ * @returns onFailure [order:1] - Failure path completed
+ * @returns successResult [order:2] - Result from success path
+ * @returns failureResult [order:3] - Result from failure path
+ */
+export ${asyncKeyword}function ${workflowName}(
+  execute: boolean,
+  params: { data: any }
+): ${returnType} {
+  throw new Error("Compile with: flow-weaver compile <file>");
+}
+`.trim();
+    },
+};
+//# sourceMappingURL=conditional.js.map

package/dist/cli/templates/workflows/error-handler.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Error Handler Template
+ * Try/catch/retry pattern for robust error handling
+ */
+import type { WorkflowTemplate } from '../index.js';
+export declare const errorHandlerTemplate: WorkflowTemplate;
+//# sourceMappingURL=error-handler.d.ts.map

package/dist/cli/templates/workflows/error-handler.js

@@ -0,0 +1,147 @@
+/**
+ * Error Handler Template
+ * Try/catch/retry pattern for robust error handling
+ */
+export const errorHandlerTemplate = {
+    id: 'error-handler',
+    name: 'Error Handler',
+    description: 'Try/catch/retry pattern with error recovery',
+    category: 'utility',
+    generate: (opts) => {
+        const { workflowName, async: isAsync } = opts;
+        const asyncKeyword = isAsync ? 'async ' : '';
+        const returnType = isAsync
+            ? 'Promise<{ onSuccess: boolean; onFailure: boolean; result: any; attempts: number; lastError?: string }>'
+            : '{ onSuccess: boolean; onFailure: boolean; result: any; attempts: number; lastError?: string }';
+        return `
+/**
+ * Retry loop that orchestrates operation attempts
+ * Uses scoped ports to handle retry iteration internally
+ *
+ * @flowWeaver nodeType
+ * @label Retry Loop
+ * @input data [order:1] - Input data to process
+ * @input maxRetries [order:2] - Maximum retry attempts
+ * @input success scope:attempt [order:0] - From operation onSuccess
+ * @input failure scope:attempt [order:1] - From operation onFailure
+ * @input result scope:attempt [order:2] - Operation result
+ * @input error scope:attempt [order:3] - Error from operation
+ * @input execute [order:0] - Execute
+ * @output start scope:attempt [order:0] - Triggers attempt
+ * @output attemptData scope:attempt [order:1] - Data for this attempt
+ * @output attemptNum scope:attempt [order:2] - Current attempt number
+ * @output finalResult [order:2] - Final result
+ * @output attempts [order:3] - Total attempts made
+ * @output lastError [order:4] - Last error if failed
+ * @output onSuccess [order:0] - On Success
+ * @output onFailure [order:1] - On Failure
+ */
+function retryLoop(
+  execute: boolean,
+  data: any,
+  maxRetries: number,
+  attempt: (start: boolean, attemptData: any, attemptNum: number) => {
+    success: boolean;
+    failure: boolean;
+    result: any;
+    error: string;
+  }
+): { onSuccess: boolean; onFailure: boolean; finalResult: any; attempts: number; lastError: string } {
+  if (!execute) {
+    return { onSuccess: false, onFailure: false, finalResult: null, attempts: 0, lastError: '' };
+  }
+
+  let lastError = '';
+  for (let attemptNum = 1; attemptNum <= maxRetries; attemptNum++) {
+    const result = attempt(true, data, attemptNum);
+
+    if (result.success) {
+      return { onSuccess: true, onFailure: false, finalResult: result.result, attempts: attemptNum, lastError: '' };
+    }
+
+    lastError = result.error;
+    console.log(\`[Retry] Attempt \${attemptNum} failed: \${lastError}. \${attemptNum < maxRetries ? 'Retrying...' : 'Max retries reached.'}\`);
+  }
+
+  return { onSuccess: false, onFailure: true, finalResult: null, attempts: maxRetries, lastError };
+}
+
+/**
+ * Attempts an operation that might fail
+ *
+ * @flowWeaver nodeType
+ * @label Try Operation
+ * @input data [order:1] - Input data
+ * @input attempt [order:2] - Current attempt number
+ * @input execute [order:0] - Execute
+ * @output result [order:2] - Operation result
+ * @output error [order:3] - Error message if failed
+ * @output onSuccess [order:0] - On Success
+ * @output onFailure [order:1] - On Failure
+ */
+function tryOperation(
+  execute: boolean,
+  data: any,
+  attempt: number
+): { onSuccess: boolean; onFailure: boolean; result: any; error: string } {
+  if (!execute) {
+    return { onSuccess: false, onFailure: false, result: null, error: '' };
+  }
+
+  try {
+    // TODO: Replace with your operation that might fail
+    // This is a placeholder that randomly fails for demonstration
+    if (Math.random() < 0.3) {
+      throw new Error('Simulated failure');
+    }
+
+    const result = { processed: data, attempt };
+    return { onSuccess: true, onFailure: false, result, error: '' };
+  } catch (err) {
+    const error = err instanceof Error ? err.message : String(err);
+    return { onSuccess: false, onFailure: true, result: null, error };
+  }
+}
+
+/**
+ * @flowWeaver workflow
+ * @node loop retryLoop [size: 300 200]
+ * @node tryOp tryOperation loop.attempt
+ * @position Start -450 0
+ * @position loop -90 0
+ * @position tryOp 90 0
+ * @position Exit 360 0
+ * @connect Start.execute -> loop.execute
+ * @connect Start.data -> loop.data
+ * @connect Start.maxRetries -> loop.maxRetries
+ * @connect loop.start:attempt -> tryOp.execute
+ * @connect loop.attemptData:attempt -> tryOp.data
+ * @connect loop.attemptNum:attempt -> tryOp.attempt
+ * @connect tryOp.result -> loop.result:attempt
+ * @connect tryOp.error -> loop.error:attempt
+ * @connect tryOp.onSuccess -> loop.success:attempt
+ * @connect tryOp.onFailure -> loop.failure:attempt
+ * @connect loop.finalResult -> Exit.result
+ * @connect loop.attempts -> Exit.attempts
+ * @connect loop.lastError -> Exit.lastError
+ * @connect loop.onSuccess -> Exit.onSuccess
+ * @connect loop.onFailure -> Exit.onFailure
+ * @param execute [order:0] - Execute
+ * @param data [order:1] - Input data to process
+ * @param [maxRetries=3] [order:2] - Maximum retry attempts
+ * @returns onSuccess [order:0] - Operation succeeded
+ * @returns onFailure [order:1] - All retries exhausted
+ * @returns result [order:2] - Operation result
+ * @returns attempts [order:3] - Number of attempts made
+ * @returns lastError [order:4] - Last error message if failed
+ */
+export ${asyncKeyword}function ${workflowName}(
+  execute: boolean,
+  params: { data: any; maxRetries?: number }
+): ${returnType} {
+  throw new Error("Compile with: flow-weaver compile <file>");
+}
+`.trim();
+    },
+};
+//# sourceMappingURL=error-handler.js.map

package/dist/cli/templates/workflows/foreach.d.ts

@@ -0,0 +1,7 @@
+/**
+ * ForEach Batch Processing Template
+ * Iterate over array items with scoped ports
+ */
+import type { WorkflowTemplate } from '../index.js';
+export declare const foreachTemplate: WorkflowTemplate;
+//# sourceMappingURL=foreach.d.ts.map