@graph-compose/client 1.0.0

package/README.md

@@ -0,0 +1,646 @@
+# @graph-compose/client
+
+Welcome! 👋 This is the Graph Compose client SDK, designed to help you build, validate, and execute workflow graphs using a fluent, type-safe builder pattern in TypeScript.
+
+This package works hand-in-hand with `@graph-compose/core`, which defines the underlying structure and validation schemas for workflows. You'll use `@graph-compose/client` to programmatically construct these workflow graphs, starting with basic HTTP operations and dependencies.
+
+
+## Features
+
+*   🏗️ **Fluent Builder API:** Easily define nodes (like `http` requests) and their configurations using method chaining.
+*   🔗 **Dependency Management:** Explicitly define dependencies between nodes.
+*   ✅ **Built-in Validation:** Leverages `@graph-compose/core` schemas to validate your graph definition locally.
+*   🚀 **Workflow Execution:** Provides methods to run your defined workflows asynchronously (`execute`, recommended) or synchronously (`executeSync`).
+*   🔒 **Type Safety:** Full TypeScript support for confidence in your workflow definitions.
+*   🔄 **Expression Support:** Utilize `{{ }}` expressions within node configurations (e.g., URLs, headers), powered by `@graph-compose/core`.
+*   *(Support for Agents and Tools is also available - see advanced documentation)*
+*   ⏱️ **Timeouts & Retries:** Configure detailed retry policies and timeouts (`startToClose`, `scheduleToClose`) for nodes and tools.
+*   ⚙️ **Workflow Configuration:** Set global workflow settings like execution timeouts (`withWorkflowConfig`).
+*   🔀 **Conditional Execution:** Define complex branching logic for HTTP nodes (`withConditions`).
+*   🛡️ **Schema Validation:** Apply Zod-based input/output validation schemas to HTTP nodes (`withValidation`).
+
+## API Reference & Documentation
+
+> **Note:** This document focuses specifically on the `@graph-compose/client` SDK for building workflows programmatically. For broader platform documentation, conceptual guides, API schemas, and examples, please visit the main Graph Compose site: [graphcompose.io](https://graphcompose.io).
+
+*   **Guides & Overviews:** For conceptual guides, integration examples, and broader platform documentation, visit the main Graph Compose documentation site: [graphcompose.io/docs](https://graphcompose.io/docs).
+*   **Workflow API Schemas:** For the definitive source of truth on the backend Workflow API request/response schemas (based on Zod/OpenAPI), see: [graphcompose.io/workflows](https://graphcompose.io/workflows).
+
+## Table of Contents
+
+- [Features](#features)
+- [API Reference & Documentation](#api-reference--documentation)
+- [Installation](#installation)
+- [Quick Start: Building a Simple HTTP Workflow](#quick-start-building-a-simple-http-workflow)
+- [Method Summary](#method-summary)
+- [Core Concepts](#core-concepts)
+- [Defining Node Types](#defining-node-types)
+- [Defining Tool Types (for Agents)](#defining-tool-types-for-agents)
+- [Workflow Configuration](#workflow-configuration)
+- [Validation](#validation)
+- [Execution](#execution)
+- [Getting the Workflow Definition](#getting-the-workflow-definition)
+- [Interacting with Existing Workflows (API)](#interacting-with-existing-workflows-api)
+- [Full Example: Putting it Together](#full-example-putting-it-together)
+- [Contributing](#contributing)
+- [License](#license)
+
+## Installation
+
+```bash
+npm install @graph-compose/client @graph-compose/core
+# or
+yarn add @graph-compose/client @graph-compose/core
+```
+*(Note: `@graph-compose/core` is a required peer dependency.)*
+
+## Quick Start: Building a Simple HTTP Workflow
+
+```typescript
+import { GraphCompose } from '@graph-compose/client';
+import { z } from 'zod'; // Often used with core schemas
+
+// Initialize the client (token is required)
+// Reads from process.env.GRAPH_COMPOSE_TOKEN if not provided
+const graph = new GraphCompose({
+  token: process.env.GRAPH_COMPOSE_TOKEN || 'your-api-token',
+});
+
+// Define a simple workflow with three dependent HTTP steps
+try {
+  // Node 1: Fetch initial user data
+  graph.node('fetch_user')
+    .get('https://api.example.com/users/{{ context.userId }}')
+    .withHeaders({ 'X-Request-ID': '{{ $uuid() }}' })
+    .withStartToCloseTimeout('5s')
+    .end(); // <-- Required: Finalize the 'fetch_user' node definition
+
+  // Node 2: Fetch user's orders, depending on the first node
+  graph.node('fetch_orders')
+    .withDependencies(['fetch_user']) // This node runs after 'fetch_user' completes
+    .get('https://api.example.com/orders?userId={{ results.fetch_user.id }}')
+    .end(); // <-- Required: Finalize the 'fetch_orders' node definition
+
+  // Node 3: Post-process orders
+  graph.node('process_orders')
+    .withDependencies(['fetch_orders']) // Depends on 'fetch_orders'
+    .post('https://api.example.com/process')
+    .withBody({
+      orderData: '{{ results.fetch_orders }}',
+      processingTimestamp: '{{ $now() }}'
+    })
+    .end(); // <-- Required: Finalize the 'process_orders' node definition
+
+  // (Optional) Explicitly validate the workflow definition locally
+  // Requires all nodes/tools to be finalized with .end()
+  const validation = graph.validate();
+  if (!validation.isValid) {
+    console.error("Workflow validation failed:", validation.errors);
+    throw new Error("Invalid workflow definition");
+  } else {
+    console.log("Local validation successful!");
+  }
+
+  // Execute the workflow
+  // Requires all nodes/tools to be finalized with .end()
+  console.log('Executing workflow...');
+  const apiResponse = await graph.execute({
+    context: { // Initial data for the workflow run
+      userId: 'user-789'
+    },
+    // webhookUrl: 'https://my-service.com/updates' // Optional webhook
+  });
+
+  if (apiResponse.success && apiResponse.data) {
+    console.log('Workflow execution started successfully:', apiResponse.data);
+    // Access workflowId via apiResponse.data.workflowId
+  } else {
+    console.error(`Workflow execution failed: ${apiResponse.message}`);
+  }
+
+} catch (error) {
+  console.error('Error building or executing workflow:', error);
+  // Handle potential ZodErrors during build if schemas are used directly
+  if (error instanceof z.ZodError) {
+     console.error("Detailed Zod Errors:", error.errors);
+  }
+}
+```
+
+
+## Method Summary
+
+This section provides a quick overview of the primary methods available on the `GraphCompose` instance, grouped by purpose.
+
+### Initialization
+
+| Method                      | Purpose                                                |
+| :-------------------------- | :----------------------------------------------------- |
+| `new GraphCompose(options?)` | Creates a new workflow builder instance. Requires API token. |
+
+### Component Definition
+
+These methods start the definition of a new workflow component and return a **builder instance**. You **must** call `.end()` on the builder to finalize the component.
+
+| Method                              | Purpose                                           |
+| :---------------------------------- | :------------------------------------------------ |
+| `node(id)`                          | Starts defining a standard HTTP node.             |
+| `agent(id)`                         | Starts defining an Agent node, which orchestrates calls to your custom HTTP endpoint. |
+| `errorBoundary(id, protectedNodes)` | Starts defining an Error Boundary node.           |
+| `tool(id)`                          | Starts defining a Tool (HTTP or Graph based).     |
+
+### Node/Tool Configuration (on Builder)
+
+These are examples of methods called on the **builder instance** returned by the definition methods above to configure the specific component.
+
+| Method                        | Purpose                                                                      |
+| :---------------------------- | :--------------------------------------------------------------------------- |
+| `.get(url)`, `.post(url)`, etc. | Sets the HTTP method and URL (HTTP Nodes/Tools).                             |
+| `.withHeaders(headers)`       | Adds HTTP headers (HTTP Nodes/Tools).                                        |
+| `.withBody(body)`             | Sets the request body (HTTP Nodes/Tools).                                    |
+| `.withDependencies(ids)`      | Specifies prerequisite nodes (HTTP & Agent Nodes).                           |
+| `.withRetries(policy)`        | Configures automatic retry behavior (HTTP Nodes/Tools).                      |
+| `.withTools(ids)`             | (Agent builder) Declares tools available for the agent's logic to call.         |
+| `.addTool(tool)`              | (Agent builder) Adds a single tool available for the agent's logic to call. |
+| `.withMaxIterations(n)`       | (Agent builder) Sets the maximum number of agent iterations.                 |
+| `.graph(callback)`            | (Tool builder) Defines a sub-graph for a Graph tool.                         |
+| `.description(text)`          | (Tool builder) Sets the description used by agents to select the tool.       |
+| `.withConditions(conds)`      | (Node builder) Adds conditional execution logic (HTTP Nodes only).           |
+| `.withValidation(schema)`     | (Node builder) Adds input/output schema validation (HTTP Nodes only).        |
+| `.withStartToCloseTimeout(d)` | Sets max time for one execution attempt (HTTP Nodes/Tools).                  |
+| `.withScheduleToCloseTimeout(d)`| Sets max time from schedule to completion (incl. queue) (HTTP Nodes/Tools). |
+
+### Finalization (on Builder)
+
+This method is called on the **builder instance** to finalize the component's definition.
+
+| Method   | Purpose                                                               |
+| :------- | :-------------------------------------------------------------------- |
+| `.end()` | Finalizes the current node/tool definition and adds it to the graph. | 
+
+### Workflow Configuration
+
+These methods configure the overall workflow. They must be called when no node or tool builder is active.
+
+| Method                       | Purpose                                           |
+| :--------------------------- | :------------------------------------------------ |
+| `withContext(context)`       | Sets global context data accessible to all nodes. |
+| `withWebhookUrl(url)`        | Sets a webhook URL for workflow event updates.    |
+| `withWorkflowConfig(config)` | Sets global workflow settings (e.g., timeouts).   |
+
+### Validation
+
+These methods validate the workflow definition. They must be called when no node or tool builder is active.
+
+| Method          | Purpose                                                  |
+| :-------------- | :------------------------------------------------------- |
+| `validate()`    | Performs local, client-side validation of the structure. |
+| `validateApi()` | Sends the definition to the API for server-side validation. |
+
+### Execution
+
+These methods execute the workflow. They must be called when no node or tool builder is active.
+
+| Method                 | Purpose                                                               |
+| :--------------------- | :-------------------------------------------------------------------- |
+| `execute(options?)`    | Executes the workflow asynchronously, returning immediately.        |
+| `executeSync(options?)`| Executes the workflow synchronously, waiting for completion.        |
+
+### Retrieving Definition
+
+These methods retrieve the built workflow definition. They must be called when no node or tool builder is active.
+
+| Method          | Purpose                                                                   |
+| :-------------- | :------------------------------------------------------------------------ |
+| `getWorkflow()` | Returns the complete workflow definition object.                            |
+| `toJSON()`      | Alias for `getWorkflow()`; standard method for `JSON.stringify()`.          |
+
+### API Interaction
+
+These methods interact with existing workflow instances via the API.
+
+| Method                                | Purpose                                              |
+| :------------------------------------ | :--------------------------------------------------- |
+| `getWorkflowStatus(workflowId)`       | Retrieves the current status and details of a workflow. |
+| `terminateWorkflow(workflowId, opts?)`| Requests termination of a running workflow.         |
+
+## Core Concepts
+
+### The `GraphCompose` Builder
+
+This is the main class you'll instantiate. It holds the state of the workflow being built.
+
+```typescript
+import { GraphCompose } from '@graph-compose/client';
+
+// Reads from process.env.GRAPH_COMPOSE_TOKEN if not provided
+const graph = new GraphCompose({
+  token: process.env.GRAPH_COMPOSE_TOKEN || 'your-api-token',
+});
+```
+
+### Defining Nodes and Tools - The `.end()` Method
+
+You define the components of your workflow (nodes and tools) by chaining methods starting with `graph.node('node_id')`, `graph.agent('agent_id')`, `graph.errorBoundary('boundary_id', [...])`, or `graph.tool('tool_id')`.
+
+*   **Configuration:** Chain methods like `.get()`, `.post()`, `.withHeaders()`, `.withBody()`, `.withRetries()`, `.withDependencies()`, etc., to configure the node or tool.
+*   **Finalization:** **Crucially, you MUST call `.end()`** after configuring each node or tool. This finalizes its definition, adds it to the graph, and returns control to the main `GraphCompose` instance. Attempting to start defining a new component or perform graph-level operations (like `validate` or `execute`) before calling `.end()` on the *current* component builder will result in an error.
+
+```typescript
+// Correct usage with .end()
+graph
+  .node('fetch_data') // Start defining node 'fetch_data'
+    .get('https://api.example.com/data')
+    .withStartToCloseTimeout('10s')
+    .end(); // Finalize 'fetch_data' and return to the main graph builder
+
+graph
+  .node('process_data') // Start defining node 'process_data'
+    .withDependencies(['fetch_data']) // Depends on 'fetch_data'
+    .post('https://api.example.com/process')
+    .withBody({ input: '{{ results.fetch_data }}' })
+    .end(); // Finalize 'process_data'
+
+// Now it's safe to perform graph-level operations like validate or execute
+// const validation = graph.validate();
+// const result = await graph.execute();
+```
+
+## Defining Node Types
+
+Nodes represent the primary steps or actions within your workflow. Remember to always finish defining a node with `.end()`.
+
+### HTTP Nodes
+
+These are the most basic type, used for making HTTP requests.
+
+```typescript
+graph.node("fetch_user_data")
+  .description("Retrieves user details based on context ID.") // Optional description
+  .get("https://api.example.com/users/{{context.userId}}")
+  .withHeaders({ "Authorization": "Bearer YOUR_SERVICE_TOKEN" })
+  .withStartToCloseTimeout('5s') // Example timeout
+  .end(); // Required!
+```
+
+### Agent Nodes
+
+Agent nodes orchestrate iterative calls to a user-defined HTTP endpoint. This endpoint implements the agent's logic (which might involve AI models) to process inputs, make decisions, and determine which Tools (other workflow nodes) to use.
+
+```typescript
+graph.agent("process_user_request")
+  .description("Handles user queries using available tools.") // Optional
+  .withMaxIterations(5) // Limit the number of tool calls/LLM turns
+  .withTools(["search_web", "summarize_content"]) // Reference tool IDs (defined separately)
+  .post("https://ai.example.com/process") // The endpoint hosting the agent logic
+  .withBody({ query: "{{context.userInput}}" })
+  .withDependencies(["fetch_user_data"]) // Can depend on other nodes
+  .end(); // Required!
+```
+
+### Error Boundary Nodes
+
+These nodes execute *only* if one of the nodes they monitor fails. They are used for error handling and cleanup.
+
+```typescript
+graph.errorBoundary("api_error_handler", ["fetch_user_data", "process_user_request"]) // List of node IDs to monitor
+  .description("Logs errors from API calls.") // Optional
+  .post("https://my-service.com/log-error")
+  .withBody({
+    failedNodeId: '{{ error.nodeId }}',
+    errorMessage: '{{ error.message }}',
+    timestamp: '{{ $now() }}'
+   })
+  .end(); // Required!
+```
+
+## Defining Tool Types (for Agents)
+
+Tools are functions or services that Agent Nodes can call to perform specific actions. Remember to always finish defining a tool with `.end()`.
+
+### HTTP Tools
+
+These are simple tools that make an HTTP request when called by an agent.
+
+```typescript
+graph.tool("search_web")
+  .description("Searches the web for a given query.") // Crucial for the agent to understand the tool
+  .post("https://api.search-provider.com/search")
+  .withBody({ query: "{{input.query}}" }) // 'input' contains agent-provided parameters
+  .withScheduleToCloseTimeout('15s') // Example timeout
+  .end(); // Required!
+
+graph.tool("summarize_content")
+  .description("Summarizes a provided block of text.")
+  .post("https://ai.example.com/summarize")
+  .withBody({ text: "{{input.text_to_summarize}}" })
+  .end(); // Required!
+```
+
+### Graph Tools
+
+These allow encapsulating a *sub-graph* as a tool. This sub-graph can contain multiple HTTP nodes.
+
+```typescript
+graph.tool('data_processor')
+  .description('Validates and transforms input data using a multi-step process.')
+  .graph((subGraph) => { // Define the sub-graph structure
+    subGraph
+      .node('validate') // Nodes within the tool's sub-graph
+        .post('https://api.example.com/validate')
+        .withBody('{{ context.example_context }}') 
+        .end(); // End sub-graph node
+    subGraph
+      .node('transform')
+        .withDependencies(['validate']) // Dependencies within the sub-graph
+        .post('https://api.example.com/transform')
+        .withBody('{{ results.validate }}') // Results refer to nodes within the sub-graph
+        .end(); // End sub-graph node
+  }) // End of sub-graph definition
+  .end(); // <-- Required: Finalize the tool itself
+```
+
+**Graph Tool Validation Rules:**
+- Graph tools can only contain HTTP nodes.
+- Graph tools must have at least one node defined (and ended).
+- Each graph tool runs as an isolated sub-workflow when invoked by an agent.
+
+### Assigning Tools to Agents
+
+You declare which Tools (defined elsewhere in the workflow) are available for your agent logic to request by referencing their IDs when defining the agent node.
+
+```typescript
+graph.agent('assistant')
+  .withMaxIterations(5)
+  .withTools(['search_web', 'data_processor']) // Reference the tools by their defined IDs
+  .post('https://api.example.com/agent')
+  // ... other agent configurations ...
+  .end(); // Required!
+```
+
+## Workflow Configuration
+
+These methods modify the overall graph configuration and require that no node or tool builder is currently active (i.e., the previous builder must have called `.end()`).
+
+```typescript
+// Assuming previous node/tool builders have called .end()
+
+// Set initial data available to all nodes via 'context'
+graph.withContext({
+  userId: "user-123",
+  userInput: "Tell me about GraphCompose",
+});
+
+// Specify a URL to receive webhook updates about the workflow's progress
+graph.withWebhookUrl("https://my-app.com/graph-compose-webhook");
+
+// Set global workflow limits
+graph.withWorkflowConfig({
+  workflowExecutionTimeout: "1 hour" // Max total execution time
+  // workflowTaskTimeout: "1m" // Max time for a single step/task
+});
+```
+
+## Validation
+
+Ensuring your workflow definition is correct before execution is crucial.
+
+### Local Validation
+
+The client performs structural and configuration validation locally when you call `graph.validate()`. This includes checking for:
+*   Valid node/tool IDs and names.
+*   Dependency cycles.
+*   Correct agent configuration (like `max_iterations`).
+*   Valid JSONata expressions used in configurations.
+*   Graph Tool structure rules.
+
+This method requires all nodes and tools to have been finalized with `.end()`. Execution methods (`.execute()`, `.executeSync()`) also perform this validation internally.
+
+```typescript
+// Assuming all node/tool builders have called .end()
+const validationResult = graph.validate();
+if (!validationResult.isValid) {
+  console.error("Workflow validation failed locally:", validationResult.errors);
+} else {
+  console.log("Local validation successful!");
+}
+```
+
+### API Validation
+
+You can also send the *current* workflow definition to the Graph Compose API for validation. This might catch additional issues specific to the execution environment.
+
+```typescript
+// Assuming all node/tool builders have called .end()
+async function validateWithApi() {
+  try {
+    // validateApi returns ApiResponse<ApiValidationResult | null>
+    const apiResponse = await graph.validateApi();
+
+    if (apiResponse.success && apiResponse.data) {
+      // Check the validation result within the data field
+      if (apiResponse.data.isValid) {
+        console.log("API validation successful!");
+      } else {
+        console.error("API validation failed:", apiResponse.data.errors);
+      }
+    } else {
+      // Handle cases where the API call itself failed (e.g., network error, auth error)
+      console.error(`API validation request failed: ${apiResponse.message}`);
+    }
+  } catch (error) {
+    console.error("Failed to call validation API:", error);
+  }
+}
+validateWithApi();
+```
+
+## Execution
+
+Once defined and validated, you can run your workflow. Execution methods require all nodes and tools to have been finalized with `.end()`.
+
+*   **Asynchronous (`execute`)**: This is the recommended method. It starts the workflow on the Graph Compose platform and immediately returns a `workflowId`. You can monitor progress via webhooks or by polling the status API.
+
+    ```typescript
+    // Assuming all node/tool builders have called .end()
+    async function startWorkflowAsync() {
+      try {
+        // Pass any runtime context needed
+        // execute returns ApiResponse<WorkflowResponse | null>
+        const apiResponse = await graph.execute({ context: { batchId: "batch-789" } });
+
+        if (apiResponse.success && apiResponse.data) {
+          console.log("Workflow started successfully with ID:", apiResponse.data.workflowId);
+          // Use apiResponse.data.workflowId and apiResponse.data.runId
+        } else {
+          console.error(`Failed to start async workflow: ${apiResponse.message}`);
+        }
+        // Use workflowId to track status or receive webhook updates
+      } catch (error) {
+        console.error("Failed to start async workflow:", error);
+      }
+    }
+    startWorkflowAsync();
+    ```
+
+*   **Synchronous (`executeSync`)**: This method starts the workflow and *waits* for it to complete (or fail) before returning the final result or error. This is simpler for short-running workflows but can time out for longer processes.
+
+    ```typescript
+    // Assuming all node/tool builders have called .end()
+    async function runWorkflowAndWait() {
+      try {
+        // Pass any runtime context needed
+        // executeSync returns ApiResponse<WorkflowResponse | null>
+        const apiResponse = await graph.executeSync({ context: { overrideUserId: "new-user-456" } });
+
+        if (apiResponse.success && apiResponse.data) {
+          console.log("Workflow completed synchronously:", apiResponse.data);
+          // apiResponse.data contains status, executionState, error etc.
+        } else {
+          console.error(`Synchronous workflow execution failed: ${apiResponse.message}`);
+        }
+      } catch (error) {
+        console.error("Synchronous workflow execution failed:", error);
+      }
+    }
+    runWorkflowAndWait();
+    ```
+
+## Getting the Workflow Definition
+
+After finalizing all nodes and tools with `.end()`, you can retrieve the raw workflow definition object that the client has built. This is useful for debugging, saving, or inspecting the structure.
+
+*   `graph.getWorkflow()`: Returns the complete `WorkflowGraph` object.
+*   `graph.toJSON()`: An alias for `getWorkflow()`, providing the standard JavaScript method for serialization.
+
+Both methods will throw an error if any node or tool builder is still active (i.e., missing a final `.end()` call).
+
+```typescript
+// Assuming all builders are finalized
+
+const workflowDefinition = graph.getWorkflow();
+console.log("Raw Workflow Definition Object:", workflowDefinition);
+
+// Equivalent using toJSON() for easy serialization
+const workflowJsonString = JSON.stringify(graph.toJSON(), null, 2);
+console.log("Workflow JSON:", workflowJsonString);
+```
+
+## Interacting with Existing Workflows (API)
+
+These methods interact directly with the Graph Compose API using a workflow ID, and don't depend on the local builder state.
+
+*   **Get Workflow Status:** Check the current status (running, completed, failed, etc.) of a previously started workflow.
+    ```typescript
+    // Does not depend on local builder state
+    async function checkStatus(workflowId: string) {
+      try {
+        const statusResult = await graph.getWorkflowStatus(workflowId);
+        console.log(`Status for ${workflowId}:`, statusResult.status);
+        // Handle other details in statusResult like results or errors
+      } catch (error) {
+        console.error("Failed to get workflow status:", error);
+      }
+    }
+    checkStatus("existing-workflow-id-123");
+    ```
+
+*   **Terminate Workflow:** Stop a currently running workflow.
+    ```typescript
+    // Does not depend on local builder state
+    async function stopWorkflow(workflowId: string, reason?: string) {
+      try {
+        const terminateResult = await graph.terminateWorkflow(workflowId, { reason });
+        console.log(`Termination request for ${workflowId}:`, terminateResult);
+      } catch (error) {
+        console.error("Failed to terminate workflow:", error);
+      }
+    }
+    stopWorkflow("running-workflow-id-456", "User cancelled operation");
+    ```
+
+## Full Example: Putting it Together
+
+This example demonstrates defining nodes, setting context, validating, and executing.
+
+```typescript
+import { GraphCompose } from "@graph-compose/client";
+
+async function main() {
+  const graph = new GraphCompose({ token: process.env.GRAPH_COMPOSE_TOKEN || "" });
+
+  // Define Node 1
+  graph.node("get_ip")
+    .description("Fetches the public IP address of the caller.")
+    .get("https://httpbin.org/ip")
+    .end(); // Required!
+
+  // Define Node 2 (depends on Node 1)
+  graph.node("echo_ip")
+    .description("Echoes the IP address back.")
+    .post("https://httpbin.org/post")
+    .withBody({ theIpAddress: "{{results.get_ip.origin}}" }) // Access results from 'get_ip'
+    .withDependencies(["get_ip"])
+    .end(); // Required!
+
+  // Set context *after* ending the last node builder
+  graph.withContext({ requestSource: "client-example-readme" });
+
+  console.log("Validating workflow locally...");
+  // Validate *after* ending all node builders and setting context/config
+  const validation = graph.validate();
+  if (!validation.isValid) {
+    console.error("Local Validation Failed:", validation.errors);
+    return;
+  }
+  console.log("Local Validation Successful!");
+
+  console.log("Executing workflow asynchronously...");
+  // Execute *after* ending all node builders and setting context/config
+  try {
+    // execute returns ApiResponse<WorkflowResponse | null>
+    const apiResponse = await graph.execute(); // Using async execution
+
+    if (apiResponse.success && apiResponse.data) {
+      const workflowId = apiResponse.data.workflowId;
+      console.log("Workflow started with ID:", workflowId);
+      console.log("Monitor status using `getWorkflowStatus(workflowId)` or webhooks.");
+      // Example: Poll status after a short delay
+      // setTimeout(async () => {
+      //   await checkStatus(workflowId); // Assumes checkStatus function from above is defined
+      // }, 5000);
+    } else {
+      console.error(`Failed to start workflow: ${apiResponse.message}`);
+    }
+  } catch (error) {
+    console.error("Execution Failed:", error);
+  }
+}
+
+// Helper function for the example (copy from 'Interacting with Existing Workflows' section)
+async function checkStatus(workflowId: string) {
+  // Re-initialize graph object or ensure it's accessible in this scope
+  const graph = new GraphCompose({ token: process.env.GRAPH_COMPOSE_TOKEN || "" });
+  try {
+    const statusResult = await graph.getWorkflowStatus(workflowId);
+    console.log(`[Status Check] Status for ${workflowId}:`, statusResult.status);
+    if (statusResult.status === 'COMPLETED') {
+        console.log('[Status Check] Results:', statusResult.results);
+    } else if (statusResult.status === 'FAILED') {
+        console.error('[Status Check] Error:', statusResult.error);
+    }
+  } catch (error) {
+    console.error("[Status Check] Failed to get workflow status:", error);
+  }
+}
+
+main();
+```
+
+## Contributing
+
+Contributions are welcome! Please refer to the main repository's contribution guidelines.
+
+## License
+
+This project is licensed under the MIT License. See the LICENSE file in the main repository for details.