zv1

https://github.com/zerowidth-ai/zv1
Admin
zv1 is a collaborative platform for designing and orchestrating AI behaviors visually, with...
Tokens:39,538
Snippets:386
Trust Score:3.1
License:Apache-2.0
Update:5 months ago
Show doc for...
Tokens:
Raw
### Run Node.js Example

Source: https://github.com/zerowidth-ai/zv1/blob/main/sdks/nodejs/examples/02-input-output-types/README.md

Navigate to the example directory and execute the main script using Node.js.

```bash
cd zv1/sdk/engines/nodejs/examples/02-input-output-types
node run.js
```

--------------------------------

### Run Basic Flow Example

Source: https://github.com/zerowidth-ai/zv1/blob/main/sdks/nodejs/examples/01-basic-flow/README.md

Navigate to the example directory and execute the run.js script to see the basic flow in action.

```bash
cd zv1/sdk/engines/nodejs/examples/01-basic-flow
node run.js
```

--------------------------------

### Install Node.js SDK Dependencies and Test

Source: https://github.com/zerowidth-ai/zv1/blob/main/README.md

Navigate to the Node.js SDK directory, install its dependencies using npm, and run its tests. This is part of the development setup for the Node.js SDK.

```bash
cd sdks/nodejs
npm install
npm test
```

--------------------------------

### Node.js SDK: Install and Test

Source: https://github.com/zerowidth-ai/zv1/blob/main/CLAUDE.md

Commands for setting up and testing the Node.js SDK. Includes installing dependencies, running all tests, and executing specific flow or node tests.

```bash
cd sdks/nodejs
npm install
npm test
node tests/test.flows.js
node tests/test.flows.js flow.addition.zv1
node tests/test.all-nodes.js
node tests/test.all-nodes.js --node add
```

--------------------------------

### Install Node.js SDK

Source: https://github.com/zerowidth-ai/zv1/blob/main/README.md

Install the zv1 Node.js SDK using npm. This is the first step to using the SDK in your project.

```bash
npm install zv1
```

--------------------------------

### Install zv1 Python SDK

Source: https://github.com/zerowidth-ai/zv1/blob/main/sdks/python/README.md

Install the zv1 Python SDK using pip. Alternatively, install from source by cloning the repository and performing a local installation.

```bash
pip install zv1
```

```bash
git clone https://github.com/zerowidth/zv1.git
cd zv1/sdks/python
pip install -e .
```

--------------------------------

### Python SDK: Install and Test

Source: https://github.com/zerowidth-ai/zv1/blob/main/CLAUDE.md

Commands for setting up and testing the Python SDK. Includes installing the SDK in editable mode and running flow or specific flow tests.

```bash
cd sdks/python
pip install -e .
python tests/test_flows.py
python tests/test_flows.py flow.addition.zv1
```

--------------------------------

### Install .NET SDK on macOS

Source: https://github.com/zerowidth-ai/zv1/blob/main/sdks/dotnet/DEVELOPMENT_STATUS.md

Provides the Homebrew command to install the .NET SDK on macOS. Ensure you have Homebrew installed first.

```bash
# Install .NET SDK (macOS)
brew install dotnet
```

--------------------------------

### Creating Instances

Source: https://github.com/zerowidth-ai/zv1/blob/main/sdks/nodejs/README.md

Examples of how to create a new zv1 instance using the static `create` method.

```APIDOC
## Creating Instances

### Recommended: Use the static `create` method

**Loading from various sources:**

```javascript
// Load from .zv1 file (new format)
const engine = await zv1.create('./myflow.zv1', config);

// Load from legacy JSON file
const engine = await zv1.create('./legacy.json', config);

// Load from flow object
const engine = await zv1.create(flowObject, config);

// Load from ZIP data in memory (Buffer)
const zipBuffer = fs.readFileSync('./myflow.zv1');
const engine = await zv1.create(zipBuffer, config);
```

**Important: Clean up resources when done**

```javascript
// Always call cleanup when the engine is no longer needed
await engine.cleanup();
```

**`create` method features:**
- **Auto-detects format**: Supports `.zv1` files, `.json` files, flow objects, and ZIP data (Buffer).
- **Handles imports**: Loads hierarchical imports automatically.
- **Validates structure**: Ensures flow integrity before execution.
- **Loads dependencies**: Node definitions, custom types, and integrations.
- **Memory efficient**: Can load `.zv1` files directly from memory without writing to disk.
- **Returns ready instance**: Fully initialized and ready to run.
```

--------------------------------

### Install Dependencies

Source: https://github.com/zerowidth-ai/zv1/blob/main/scripts/README.md

Installs project dependencies for the scripts. Run this command in the scripts directory.

```bash
cd scripts
npm install
```

--------------------------------

### Complete Node Example: Config File

Source: https://github.com/zerowidth-ai/zv1/blob/main/NODE_GUIDELINES.md

Configuration file for an example data processing node, defining its inputs, outputs, and metadata.

```json
{
  "display_name": "Example Data Processor",
  "description": "Process and transform input data with validation and filtering",
  "category": "data",
  "provider": "internal",
  "is_plugin": false,
  "inputs": [
    {
      "name": "input_data",
      "display_name": "Input Data",
      "type": "array of objects",
      "description": "Array of data objects to process",
      "required": true
    },
    {
      "name": "filter_field",
      "display_name": "Filter Field",
      "type": "string",
      "description": "Field name to filter by",
      "suggestion": {
        "type": "string",
        "name": "value"
      }
    },
    {
      "name": "max_items",
      "display_name": "Maximum Items",
      "type": "number",
      "description": "Maximum number of items to return",
      "default": 100
    }
  ],
  "outputs": [
    {
      "name": "processed_data",
      "display_name": "Processed Data",
      "type": "array of objects",
      "description": "Filtered and processed data objects"
    },
    {
      "name": "total_count",
      "display_name": "Total Count",
      "type": "number",
      "description": "Total number of processed items"
    }
  ],
  "settings": []
}
```

--------------------------------

### Chat with LLM Example

Source: https://github.com/zerowidth-ai/zv1/blob/main/sdks/dotnet/README.md

Shows how to configure the engine with API keys and run a chat flow, passing a list of messages as input.

```csharp
using ZeroWidth.Zv1;

await using var engine = await Zv1Engine.CreateAsync("./chat-flow.zv1", new Zv1Config
{
    Keys = new Dictionary<string, object?>
    {
        ["openrouter"] = Environment.GetEnvironmentVariable("OPENROUTER_API_KEY")
    }
});

var result = await engine.RunAsync(new Dictionary<string, object?>
{
    ["chat"] = new List<object>
    {
        new Dictionary<string, object?>
        {
            ["role"] = "user",
            ["content"] = "What is the capital of France?"
        }
    }
});

var chat = result.Outputs?["chat"] as List<object>;
Console.WriteLine(chat);
```

--------------------------------

### Create Zv1Engine Instance

Source: https://github.com/zerowidth-ai/zv1/blob/main/sdks/dotnet/README.md

Demonstrates how to create a new Zv1Engine instance, which is the recommended way to start using the SDK. It takes a flow definition and optional configuration.

```APIDOC
## Create Zv1Engine Instance

### Description
Create a new Zv1Engine instance (recommended).

### Method
`static Task<Zv1Engine> CreateAsync(object flow, Zv1Config? config = null)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **flow** (object) - Required - File path (.zv1 or .json), flow definition, or stream
- **config** (Zv1Config?) - Optional - Configuration options and context for the engine

### Request Example
```csharp
var engine = await Zv1Engine.CreateAsync(flow, new Zv1Config
{
    Mcp = new McpConfig
    {
        Tools = new List<McpTool>
        {
            new McpTool
            {
                Name = "getTime",
                Description = "Get current time",
                Url = "http://localhost:3000/mcp"
            }
        }
    }
});
```

### Response
#### Success Response (200)
- **Zv1Engine** - Fully initialized Zv1Engine instance

#### Response Example
None provided.
```

--------------------------------

### Node Description Example

Source: https://github.com/zerowidth-ai/zv1/blob/main/NODE_GUIDELINES.md

Example of a node description, starting with an action verb and detailing its functionality.

```json
{
  "description": "Fetch latest headlines from the last 48 hours with rich filtering options including keywords, countries, regions, categories, and more"
}
```

--------------------------------

### Verify .NET SDK Installation

Source: https://github.com/zerowidth-ai/zv1/blob/main/sdks/dotnet/DEVELOPMENT_STATUS.md

Command to check the installed .NET SDK version. Requires .NET SDK 8.0 or higher.

```bash
# Verify installation
dotnet --version  # Should be 8.0+
```

--------------------------------

### Install zv1 NuGet Package

Source: https://github.com/zerowidth-ai/zv1/blob/main/sdks/dotnet/README.md

Use the dotnet CLI to add the ZeroWidth.Zv1 package to your project.

```bash
dotnet add package ZeroWidth.Zv1
```

--------------------------------

### Install zv1 via Package Manager Console

Source: https://github.com/zerowidth-ai/zv1/blob/main/sdks/dotnet/README.md

Alternatively, install the ZeroWidth.Zv1 package using the Package Manager Console in Visual Studio.

```powershell
Install-Package ZeroWidth.Zv1
```

--------------------------------

### Basic Data Flow Example

Source: https://github.com/zerowidth-ai/zv1/blob/main/sdks/dotnet/README.md

Demonstrates how to define a simple data flow with input, processing, and output nodes, and then execute it.

```csharp
using ZeroWidth.Zv1;

var flow = new Dictionary<string, object?>
{
    ["nodes"] = new List<object>
    {
        new Dictionary<string, object?>
        {
            ["id"] = "input1",
            ["type"] = "input-data",
            ["settings"] = new Dictionary<string, object?> { ["key"] = "text" }
        },
        new Dictionary<string, object?>
        {
            ["id"] = "process1",
            ["type"] = "text-transform",
            ["settings"] = new Dictionary<string, object?> { ["operation"] = "uppercase" }
        },
        new Dictionary<string, object?>
        {
            ["id"] = "output1",
            ["type"] = "output-data"
        }
    },
    ["links"] = new List<object>
    {
        new Dictionary<string, object?>
        {
            ["from"] = new Dictionary<string, object?> { ["node_id"] = "input1", ["port_name"] = "value" },
            ["to"] = new Dictionary<string, object?> { ["node_id"] = "process1", ["port_name"] = "input" }
        },
        new Dictionary<string, object?>
        {
            ["from"] = new Dictionary<string, object?> { ["node_id"] = "process1", ["port_name"] = "output" },
            ["to"] = new Dictionary<string, object?> { ["node_id"] = "output1", ["port_name"] = "value" }
        }
    }
};

await using var engine = await Zv1Engine.CreateAsync(flow);
var result = await engine.RunAsync(new Dictionary<string, object?> { ["text"] = "hello world" });
Console.WriteLine(result.Outputs?["data"]);  // "HELLO WORLD"
```

--------------------------------

### Quick Start: Execute a Flow

Source: https://github.com/zerowidth-ai/zv1/blob/main/sdks/dotnet/README.md

Instantiate the Zv1Engine, configure API keys, and run a flow with input data. The result contains the flow's outputs.

```csharp
using ZeroWidth.Zv1;

// Create engine instance by passing the location of your configured flow
await using var engine = await Zv1Engine.CreateAsync("./path/to/myflow.zv1", new Zv1Config
{
    Keys = new Dictionary<string, object?>
    {
        ["openrouter"] = "your-api-key"
    }
});

// Run the flow
var result = await engine.RunAsync(new Dictionary<string, object?>
{
    ["chat"] = new List<object>
    {
        new Dictionary<string, object?>
        {
            ["role"] = "user",
            ["content"] = "Hello, world!"
        }
    }
});

Console.WriteLine(result.Outputs);
```

--------------------------------

### Complete Node Example: Process File

Source: https://github.com/zerowidth-ai/zv1/blob/main/NODE_GUIDELINES.md

The main processing logic for an example data processing node, handling filtering and item limits.

```javascript
export default async ({inputs, settings, config, nodeConfig}) => {
  // Remember, input validation has already taken place at this point

  // Process data
  let processedData = inputs.input_data;

  // Apply filter if specified
  if (inputs.filter_field) {
    processedData = processedData.filter(item => 
      item[inputs.filter_field] !== undefined && 
      item[inputs.filter_field] !== null
    );
  }

  // Apply max items limit
  const maxItems = inputs.max_items || 100;
  if (processedData.length > maxItems) {
    processedData = processedData.slice(0, maxItems);
  }

  return {
    processed_data: processedData,
    total_count: processedData.length
  };
};
```

--------------------------------

### Output Type Description Example

Source: https://github.com/zerowidth-ai/zv1/blob/main/NODE_GUIDELINES.md

Example of an output type description, detailing an array of objects.

```json
{
  "name": "articles",
  "display_name": "Articles",
  "type": "array of objects",
  "description": "Array of article objects with metadata including title, content, author, and publication date"
}
```

--------------------------------

### Quick Start: Execute a zv1 Flow

Source: https://github.com/zerowidth-ai/zv1/blob/main/sdks/python/README.md

Initialize the Zv1 engine with a flow file and API keys, then run the flow with input data. Ensure to clean up resources after execution.

```python
import asyncio
from zv1 import Zv1

async def main():
    # Create engine instance by passing the location of your configured flow
    engine = await Zv1.create('./path/to/myflow.zv1', {
        'keys': {
            'openrouter': 'your-api-key'
        }
    })

    # Run the flow
    result = await engine.run({
        'chat': [
            {
                'role': 'user',
                'content': 'Hello, world!'
            }
        ]
    })

    print(result['outputs'])

    # Clean up resources
    await engine.cleanup()

asyncio.run(main())
```

--------------------------------

### Engine Creation with API Key Configuration

Source: https://github.com/zerowidth-ai/zv1/blob/main/sdks/nodejs/README.md

Demonstrates how to create an engine instance, providing API keys for external service authentication. This example shows configuring the OpenRouter API key.

```javascript
const engine = await zv1.create(flow, {
  keys: {
    openrouter: "sk-...",  // OpenRouter API key
  }
});
```

--------------------------------

### Example Flow Structure

Source: https://github.com/zerowidth-ai/zv1/blob/main/sdks/nodejs/examples/02-input-output-types/README.md

Visual representation of the data flow between different input and output nodes in the zv1 example.

```text
input-data ──────────→ output-data (user_name_output)

input-prompt ─────────→ output-data (system_prompt_output)

input-chat ───────────→ output-chat (most recent message → formatted chat)
```

--------------------------------

### Quick Start: Create and Run a zv1 Flow

Source: https://github.com/zerowidth-ai/zv1/blob/main/sdks/nodejs/README.md

Initialize the zv1 engine with a flow file and API keys, then execute the flow with initial input. Requires a flow file at './path/to/myflow.zv1' and an OPENROUTER_API_KEY environment variable.

```javascript
import zv1 from 'zv1';

// Create engine instance by passing the location of your configured flow
const engine = await zv1.create('./path/to/myflow.zv1', {
  keys: {
    openrouter: process.env.OPENROUTER_API_KEY
  }
});

// Run the flow
const result = await engine.run({
  chat: [
    {
      role: 'user',
      content: "Hello, world!"
    }
  ]
});
```

--------------------------------

### Node File Structure Example

Source: https://github.com/zerowidth-ai/zv1/blob/main/NODE_GUIDELINES.md

Defines the standard file organization for a zv1 node, including configuration, process logic, and test files.

```text
nodes/your-node-name/
├── your-node-name.config.json    # Node configuration and schema
├── your-node-name.process.js     # Node execution logic
└── your-node-name.tests.json     # Test cases (optional but recommended)
```

--------------------------------

### Input Field Description Example

Source: https://github.com/zerowidth-ai/zv1/blob/main/NODE_GUIDELINES.md

Example of an input field description, specifying its name, type, and requirements.

```json
{
  "name": "from_date",
  "display_name": "From Date",
  "type": "string",
  "description": "Start date in YYYY-MM-DD format",
  "required": true
}
```

--------------------------------

### Chat with LLM using Zv1

Source: https://github.com/zerowidth-ai/zv1/blob/main/sdks/python/README.md

Shows how to set up and run a chat flow with an LLM using the Zv1 SDK. This example includes providing API keys and interacting with a chat model.

```python
import asyncio
from zv1 import Zv1

async def main():
    engine = await Zv1.create('./chat-flow.zv1', {
        'keys': {
            'openrouter': 'your-api-key'
        }
    })

    result = await engine.run({
        'chat': [
            {'role': 'user', 'content': 'What is the capital of France?'}
        ]
    })

    print(result['outputs']['chat'])
    await engine.cleanup()

asyncio.run(main())
```

--------------------------------

### Basic Data Flow with Zv1

Source: https://github.com/zerowidth-ai/zv1/blob/main/sdks/python/README.md

Demonstrates how to define a simple data processing flow using Python dictionaries and execute it with the Zv1 engine. This example transforms input text to uppercase.

```python
import asyncio
from zv1 import Zv1

async def main():
    flow = {
        'nodes': [
            {
                'id': 'input1',
                'type': 'input-data',
                'settings': {'key': 'text'}
            },
            {
                'id': 'process1',
                'type': 'text-transform',
                'settings': {'operation': 'uppercase'}
            },
            {
                'id': 'output1',
                'type': 'output-data'
            }
        ],
        'links': [
            {
                'from': {'node_id': 'input1', 'port_name': 'value'},
                'to': {'node_id': 'process1', 'port_name': 'input'}
            },
            {
                'from': {'node_id': 'process1', 'port_name': 'output'},
                'to': {'node_id': 'output1', 'port_name': 'value'}
            }
        ]
    }

    engine = await Zv1.create(flow)
    result = await engine.run({'text': 'hello world'})
    print(result['outputs'])  # {'data': 'HELLO WORLD'}

asyncio.run(main())
```

--------------------------------

### Node Naming Convention Example

Source: https://github.com/zerowidth-ai/zv1/blob/main/NODE_GUIDELINES.md

Illustrates naming conventions for node properties, using snake_case for internal names and Title Case for display names.

```json
{
  "name": "total_results",           // snake_case
  "display_name": "Total Results",   // Title Case
  "type": "number"
}
```

--------------------------------

### Example .NET SDK Test Output

Source: https://github.com/zerowidth-ai/zv1/blob/main/sdks/dotnet/DEVELOPMENT_STATUS.md

Shows the expected output format when running flow tests successfully. Indicates which flows are being tested, their inputs, and the PASS/FAIL result.

```text
[INFO] Running all flow tests (X files)
[INFO] Testing flow: flow.addition.json with inputs: {"a":3,"b":2}
  [RESULT] {"outputs":{"data":5}}
  [PASS] flow.addition.json
[INFO] Testing flow: flow.addition.zv1 with inputs: {"a":2,"b":3}
  [RESULT] {"outputs":{"data":5}}
  [PASS] flow.addition.zv1
...
```

--------------------------------

### Run LLM Flow and Get Results

Source: https://context7.com/zerowidth-ai/zv1/llms.txt

Initializes the AI engine with an LLM flow configuration and executes a chat interaction, logging the review output and cost summary.

```javascript
const engine = await zv1.create(llmFlow, { keys: { openrouter: process.env.OPENROUTER_API_KEY } });
const result = await engine.run({
  chat: [{ role: 'user', content: 'Review this function:\n\nfunction add(a,b){return a+b}' }]
});
console.log(result.outputs.review);         // full conversation with assistant review
console.log(result.cost_summary.total);     // total USD cost
```

--------------------------------

### engine.run(inputs, timeout?)

Source: https://context7.com/zerowidth-ai/zv1/llms.txt

Executes the loaded flow from start to finish. It injects provided inputs into matching input nodes and returns a comprehensive result object including outputs, execution timeline, cost summary, and status.

```APIDOC
## engine.run(inputs, timeout?)

### Description
Executes the loaded flow from start to finish. It injects provided inputs into matching input nodes and returns a comprehensive result object including outputs, execution timeline, cost summary, and status. Nodes execute in parallel up to `maxConcurrency`.

### Parameters
#### inputs
- **inputs** (object) - Required - An object containing key-value pairs to be used as inputs for the flow. Keys should match the input node identifiers.
#### timeout
- **timeout** (number) - Optional - The maximum time in milliseconds to allow the flow execution. Defaults to 60000 ms (60 seconds).

### Returns
- **Promise<RunResult>** - A Promise that resolves to an object containing:
  - **outputs** (object) - Named outputs from the flow's output nodes.
  - **cost_summary** (object) - Summary of costs incurred during execution.
  - **message** (string) - Status message of the execution (e.g., "Completed.").
  - **timeline** (array) - An array detailing the execution steps of each node.
  - **inputsMissingValues** (array) - List of inputs that were not satisfied.
  - **partial** (boolean) - Indicates if the result is partial (true) or complete (false).
  - **terminalNodes** (object) - Outputs of the last executed nodes if the result is partial.
```

--------------------------------

### Build zv1 from Source

Source: https://github.com/zerowidth-ai/zv1/blob/main/sdks/dotnet/README.md

Clone the zv1 repository and build the .NET SDK locally.

```bash
git clone https://github.com/zerowidth/zv1.git
cd zv1/sdks/dotnet
dotnet build
```

--------------------------------

### Build and Run .NET SDK Tests

Source: https://github.com/zerowidth-ai/zv1/blob/main/sdks/dotnet/README.md

Navigate to the SDK directory, restore dependencies, build the project, and run tests using the `dotnet` CLI.

```bash
cd sdks/dotnet
dotnet restore
dotnet build
dotnet test
```

--------------------------------

### Configure Engine with API Keys

Source: https://github.com/zerowidth-ai/zv1/blob/main/sdks/dotnet/README.md

Demonstrates how to initialize the Zv1Engine with API keys for external service authentication, using a configuration object.

```csharp
var engine = await Zv1Engine.CreateAsync(flow, new Zv1Config
{
    Keys = new Dictionary<string, object?>
    {
        ["openrouter"] = "sk-..."  // OpenRouter API key
    }
});
```

--------------------------------

### Terminal Node Handling Example

Source: https://github.com/zerowidth-ai/zv1/blob/main/sdks/dotnet/README.md

Illustrates the structure of the ExecutionResult when a flow completes without explicit output nodes.

```csharp
new ExecutionResult
{
    Partial = true,
    Message = "Flow completed without output nodes",
    TerminalNodes = new List<TerminalNode>
    {
        new TerminalNode
        {
            NodeId = "node1",
            Type = "processor",
            Outputs = { ... }
        }
    }
}
```

--------------------------------

### Initialize and Run Node.js SDK

Source: https://github.com/zerowidth-ai/zv1/blob/main/README.md

Initialize the zv1 engine with your AI orchestration and API keys, then execute it with chat inputs. Ensure your OPENROUTER_API_KEY is set in the environment.

```javascript
import zv1 from 'zv1';

// Load your AI orchestration designed at zv1.ai
const engine = await zv1.create('./myflow.zv1', {
  keys: {
    openrouter: process.env.OPENROUTER_API_KEY
  }
});

// Execute your AI behavior in production
const result = await engine.run({
  chat: [{ role: 'user', content: 'Hello, world!' }]
});

console.log(result.outputs);
```

--------------------------------

### Define Tool Schema for LLM Plugins

Source: https://github.com/zerowidth-ai/zv1/blob/main/sdks/nodejs/README.md

Example of a JSON schema definition for a calculator tool, used for LLM plugins.

```json
{
  "name": "calculator",
  "description": "Performs calculations",
  "parameters": {
    "type": "object",
    "properties": {
      "operation": { "type": "string" },
      "numbers": { "type": "array" }
    }
  }
}
```

--------------------------------

### Output Data Node Example

Source: https://github.com/zerowidth-ai/zv1/blob/main/sdks/nodejs/README.md

Defines an output node for returning structured data. It specifies a key under which the data will be returned.

```json
{
  "id": "output1",
  "type": "output-data",
  "settings": {
    "key": "result"
  }
}
```

--------------------------------

### Convert Content to String

Source: https://github.com/zerowidth-ai/zv1/blob/main/sdks/nodejs/src/types/README.md

Convert a content object or array to a string. This example shows converting an array of text content objects.

```javascript
const content = [
  { type: 'text', text: 'First paragraph' },
  { type: 'text', text: 'Second paragraph' }
];

const text = engine.convertType(content, 'content');
// Returns: "First paragraphSecond paragraph"
```

--------------------------------

### Run Specific Node Tests

Source: https://github.com/zerowidth-ai/zv1/blob/main/sdks/dotnet/README.md

Execute tests for a specific node by its name, or run tests starting from a particular node in the flow.

```csharp
// Test a specific node
var summary = await runner.RunNodeTestsAsync("add");

// Test starting from a specific node
var summary = await runner.RunTestsStartingFromAsync("array-map");
```

--------------------------------

### Input Data Node Example

Source: https://github.com/zerowidth-ai/zv1/blob/main/sdks/nodejs/README.md

Defines an input node for structured data entry. It specifies a key for the input and an optional default value.

```json
{
  "id": "input1",
  "type": "input-data",
  "settings": {
    "key": "userInput",
    "default_value": "Hello"
  }
}
```

--------------------------------

### Legacy JSON Flow File Structure

Source: https://github.com/zerowidth-ai/zv1/blob/main/sdks/nodejs/README.md

Example of the legacy JSON flow file format, which can include an optional 'imports' array for modularity.

```json
{
  "nodes": [...],
  "links": [...],
  "imports": [
    {
      "id": "import-123",
      "display_name": "My Import",
      "nodes": [...],
      "links": [...] 
    }
  ]
}
```

--------------------------------

### Build .NET SDK Project

Source: https://github.com/zerowidth-ai/zv1/blob/main/sdks/dotnet/DEVELOPMENT_STATUS.md

Command to compile the .NET SDK project. This step is necessary before running tests or building executables.

```bash
# Build
dotnet build
```

--------------------------------

### Good Error Messages

Source: https://github.com/zerowidth-ai/zv1/blob/main/NODE_GUIDELINES.md

Examples of descriptive and actionable error messages that include field names or specific details, avoiding generic failure statements.

```javascript
// ✅ Good error messages
throw new Error("API key is required for this service");
throw new Error("Invalid date format. Expected YYYY-MM-DD");
throw new Error("Maximum 5 countries allowed, received 8");
```

--------------------------------

### Initialize and Run Node Tests

Source: https://github.com/zerowidth-ai/zv1/blob/main/sdks/dotnet/README.md

Initialize a NodeTestRunner with the path to the node definitions and run all tests. The results are then printed to the console.

```csharp
using ZeroWidth.Zv1.Testing;

var runner = new NodeTestRunner("./nodes");
var summary = await runner.RunAllTestsAsync();

NodeTestRunner.PrintResults(summary);
```

--------------------------------

### Create zv1 Instance

Source: https://github.com/zerowidth-ai/zv1/blob/main/sdks/nodejs/README.md

Use the static `create` method to initialize a zv1 engine instance. It supports loading flows from various sources like files, objects, or buffers.

```javascript
const engine = await zv1.create('./myflow.zv1', config);
```

```javascript
const engine = await zv1.create('./legacy.json', config);
```

```javascript
const engine = await zv1.create(flowObject, config);
```

```javascript
const zipBuffer = fs.readFileSync('./myflow.zv1');
const engine = await zv1.create(zipBuffer, config);
```

--------------------------------

### Define Test Flow Structure

Source: https://github.com/zerowidth-ai/zv1/blob/main/sdks/nodejs/README.md

Example JSON structure for defining test flows, including nodes, links, inputs, expected outputs, and expected errors.

```json
{
  "flow": {
    "nodes": [...],
    "links": [...] 
  },
  "inputs": { ... },
  "expected": { ... },
  "expectedSchema": { ... },
  "expectedError": {
    "type": "node",
    "message": "Expected error message",
    "nodeId": "node-1",
    "nodeType": "custom-node"
  }
}
```

--------------------------------

### Streaming with Event Handlers

Source: https://github.com/zerowidth-ai/zv1/blob/main/sdks/dotnet/README.md

Illustrates how to set up event handlers for node updates, specifically to stream content as it becomes available during execution.

```csharp
await using var engine = await Zv1Engine.CreateAsync("./streaming-flow.zv1", new Zv1Config
{
    Keys = new Dictionary<string, object?> { ["openrouter"] = apiKey },
    OnNodeUpdate = async (update) =>
    {
        if (update.Data?.TryGetValue("content", out var content) == true)
        {
            Console.Write(content);  // Stream tokens as they arrive
        }
    }
});

var result = await engine.RunAsync(inputs);
Console.WriteLine();  // Final newline after streaming
```

--------------------------------

### Node Key Requirements Configuration

Source: https://github.com/zerowidth-ai/zv1/blob/main/sdks/python/README.md

Nodes specify their key requirements in their configuration. This JSON snippet shows an example of how a node might define its key needs.

```json
{
  "config": {
    "needs_key_from": ["openai"],
    "display_name": "GPT-4 Node",
    "description": "Processes text with GPT-4"
  }
}
```

--------------------------------

### Configuration Options

Source: https://github.com/zerowidth-ai/zv1/blob/main/sdks/python/README.md

Details on the configuration options available when creating a Zv1 instance.

```APIDOC
## Configuration Options

**`config`** (dict, optional)

Configuration options and context for the engine. Example structure:

```python
{
    # Optional: API keys for external services
    'keys': {
        'openai': 'sk-...',
        'gemini': '...',
        # ... other service keys
    },

    # Optional: Node execution event handlers
    'on_node_start': async_callback,      # (event) -> None
    'on_node_complete': async_callback,   # (event) -> None
    'on_node_update': async_callback,     # (event) -> None

    # Optional: Error event handler
    'on_error': async_callback,           # (error_event) -> None

    # Optional: Maximum number of plugin calls per LLM node (default: 10)
    'max_plugin_calls': 10,

    # Optional: Execution ID for tracking (auto-generated if not provided)
    'execution_id': 'custom-execution-id',

    # Optional: Enable debug logging
    'debug': True
}
```
```

--------------------------------

### Registering Event Handlers

Source: https://github.com/zerowidth-ai/zv1/blob/main/sdks/dotnet/README.md

Shows how to configure event handlers (OnNodeStart, OnNodeComplete, OnNodeUpdate, OnError) during engine creation to monitor and interact with flow execution.

```csharp
var engine = await Zv1Engine.CreateAsync(flow, new Zv1Config
{
    OnNodeStart = async (node) =>
    {
        Console.WriteLine($"Node {node.NodeId} starting execution");
    },

    OnNodeComplete = async (node) =>
    {
        Console.WriteLine($"Node {node.NodeId} completed execution");
    },

    OnNodeUpdate = async (update) =>
    {
        Console.WriteLine($"Node {update.NodeId} sent update: {update.Data}");
    },

    OnError = async (error) =>
    {
        Console.WriteLine($"Error occurred: {error.Message}");
    }
});
```

--------------------------------

### Zv1 Class Methods

Source: https://github.com/zerowidth-ai/zv1/blob/main/sdks/python/README.md

Provides documentation for the core Zv1 class methods: `create`, `run`, and `cleanup`.

```APIDOC
## Zv1 Class

### `create(flow, config: dict = None)`

**Description**: Create a new Zv1 instance (recommended).

**Parameters**:
- `flow`: File path (.zv1 or .json), flow definition dict, or bytes
- `config` (dict, optional): Configuration options and context for the engine

**Returns**:
- `'Zv1'`: Fully initialized Zv1 instance

### `run(inputs: dict, timeout: int = 60000)`

**Description**: Run the flow and return the final output.

**Parameters**:
- `inputs` (dict): Data to inject into input nodes
- `timeout` (int, optional): Maximum execution time in milliseconds (default: 60000)

**Returns**:
- `dict`: The final output from output nodes

### `cleanup()`

**Description**: Clean up resources including knowledge databases and temporary files. Call this when the engine is no longer needed to free up memory.

**Returns**:
- `None`
```

--------------------------------

### Manual Resource Cleanup

Source: https://github.com/zerowidth-ai/zv1/blob/main/sdks/dotnet/README.md

Demonstrates manual cleanup of Zv1Engine resources using a try-finally block and calling `DisposeAsync()`.

```csharp
var engine = await Zv1Engine.CreateAsync("./myflow.zv1", config);

try
{
    var result = await engine.RunAsync(inputs);
    Console.WriteLine(result);
}
finally
{
    await engine.DisposeAsync();
}
```

--------------------------------

### Get and Execute Node Processor in C#

Source: https://github.com/zerowidth-ai/zv1/blob/main/sdks/dotnet/DEVELOPMENT_STATUS.md

Shows how to retrieve a registered node processor function from the registry and execute it. This usage pattern is found in the main Zv1.cs engine.

```csharp
// Usage (in Zv1.cs)
var processFunc = NodeProcessorRegistry.GetProcessor(nodeType);
var outputs = await processFunc(context);
```

--------------------------------

### Automatic Resource Cleanup with IAsyncDisposable

Source: https://github.com/zerowidth-ai/zv1/blob/main/sdks/dotnet/README.md

Shows how to use `await using` to ensure the Zv1Engine's resources are automatically disposed of upon exiting the scope.

```csharp
await using var engine = await Zv1Engine.CreateAsync("./myflow.zv1", config);

var result = await engine.RunAsync(inputs);
Console.WriteLine(result);
// Resources are automatically cleaned up when leaving the using block
```

--------------------------------

### Run Auto-Sync Watcher

Source: https://github.com/zerowidth-ai/zv1/blob/main/README.md

Start the auto-sync watcher script in the 'scripts' directory. This tool monitors changes in shared asset directories and automatically syncs them to language-specific SDKs during development.

```bash
cd scripts
npm install
npm run dev
```

--------------------------------

### Run All .NET SDK Tests

Source: https://github.com/zerowidth-ai/zv1/blob/main/sdks/dotnet/DEVELOPMENT_STATUS.md

Executes all unit and integration tests defined in the test project. This command helps verify the integrity of the SDK.

```bash
# Run tests
dotnet test
```

--------------------------------

### Input Validation: Automagic Type Conversion

Source: https://github.com/zerowidth-ai/zv1/blob/main/NODE_GUIDELINES.md

Example of automatically converting an input string to an array if it's expected to be an array of strings. Assumes required inputs and defaults are handled before this function.

```javascript
// ✅ DO: Automagically convert input types
export default async ({inputs, settings, config, nodeConfig}) => {
  if (typeof inputs.array_of_strings_field === 'string) {
    inputs.array_of_strings_field = [inputs.array_of_strings_field]
  }

  // All required inputs and default values are handled PRIOR to the process function being called
  
  // Process inputs...
  
};
```

--------------------------------

### zv1 Flow File Structure (.zv1 format)

Source: https://github.com/zerowidth-ai/zv1/blob/main/sdks/nodejs/README.md

Illustrates the recommended .zv1 flow file format, which is a ZIP archive containing the main orchestration JSON and optional imports.

```tree
myflow.zv1
├── orchestration.json          # Main flow definition
├── imports/                    # Optional imports folder
│   └── a1b2c3d4-e5f6-7890-abcd-ef1234567890/   # Import folder (importId only)
│       ├── orchestration.json  # Import's flow definition
│       ├── README.md           # Optional documentation
│       └── imports/            # Optional nested imports
│           └── b2c3d4e5-f6g7-8901-bcde-f12345678901/
│               └── orchestration.json
```

--------------------------------

### Import Resolution with Imports Object

Source: https://github.com/zerowidth-ai/zv1/blob/main/sdks/nodejs/README.md

Demonstrates the recommended 'imports' object in the main orchestration.json for specifying dependencies with version ranges.

```json
{
  "metadata": {
    "name": "My Flow",
    "version": "1.0.0"
  },
  "nodes": [...],
  "links": [...],
  "imports": {
    "a1b2c3d4-e5f6-7890-abcd-ef1234567890": "^1.2.3",
    "b2c3d4e5-f6g7-8901-bcde-f12345678901": "~1.0.0",
    "c3d4e5f6-g7h8-9012-cdef-123456789012": "2.1.0",
    "d4e5f6g7-h8i9-0123-defg-234567890123": "latest"
  }
}
```

--------------------------------

### zv1.create(flow, config)

Source: https://context7.com/zerowidth-ai/zv1/llms.txt

Creates a Flow Engine instance by loading a flow file or object. It initializes node definitions, validates API keys, and prepares the engine for execution. Supports various flow formats including .zv1 archives, JSON files, and in-memory objects.

```APIDOC
## zv1.create(flow, config)

### Description
Creates a Flow Engine instance by loading a flow file or object. It initializes node definitions, validates API keys, and prepares the engine for execution. Supports various flow formats including .zv1 archives, JSON files, and in-memory objects.

### Parameters
#### flow
- **flow** (string | object | Buffer) - Required - Path to a .zv1 archive, legacy JSON file, ZIP Buffer, or a plain flow object.
#### config
- **config** (object) - Required - Configuration object for the engine.
  - **keys** (object) - Required - API keys for LLM providers.
    - **openrouter** (string) - Required - OpenRouter API key. Defaults to OpenRouter if not overridden.
    - **openai** (string) - Optional - OpenAI API key override.
    - **anthropic** (string) - Optional - Anthropic API key override.
  - **debug** (boolean) - Optional - Enable verbose logging. Defaults to false.
  - **maxConcurrency** (number) - Optional - Maximum number of nodes to execute in parallel. Defaults to 5.
  - **maxPluginCalls** (number) - Optional - Maximum tool-call rounds per LLM. Defaults to 10.
  - **executionId** (string) - Optional - An identifier for the current run.

### Returns
- **Promise<Engine>** - A Promise that resolves to a ready-to-run engine instance.
```

--------------------------------

### Event Handlers for Node Lifecycle

Source: https://github.com/zerowidth-ai/zv1/blob/main/sdks/nodejs/README.md

Shows how to register event handlers for node lifecycle events such as start, completion, and updates. These handlers can be used for monitoring, logging, and integrating with external systems.

```javascript
const engine = await zv1.create(flow, {
  onNodeStart: async ({ nodeId, nodeType, timestamp, inputs, settings }) => {
    console.log(`Node ${nodeId} starting execution`);
    // Example: Track metrics in your own system
    // await yourMetricsService.recordNodeStart(nodeId, timestamp);
  },
  
  onNodeComplete: async ({ nodeId, nodeType, timestamp, inputs, outputs, settings }) => { 
    console.log(`Node ${nodeId} completed execution`);
    // Example: Calculate and track execution duration
    // const duration = timestamp - startTime;
    // await yourMetricsService.recordNodeComplete(nodeId, duration);
  },

  onNodeUpdate: async ({ nodeId, nodeType, timestamp, data }) => {
    console.log(`Node ${nodeId} sent update:`, data);
    // Example: Handle real-time updates from nodes
  },
  
  onError: async (errorEvent) => {
    console.log('Error occurred:', errorEvent);
    // Example: Send to your error tracking service
    // await yourErrorTracker.recordError(errorEvent);
  }
});
```

--------------------------------

### Airtable Environment Variables Setup

Source: https://github.com/zerowidth-ai/zv1/blob/main/sdks/python/src/integrations/AIRTABLE_TEST_SETUP.md

Configure these environment variables in your .env file to enable Airtable integration tests. Ensure you replace placeholder values with your actual Airtable credentials and IDs.

```bash
# Airtable API Key
AIRTABLE_API_KEY=patXXXXXXXXXXXXXXXXXXXXXX

# Test table configuration
AIRTABLE_TEST_BASE_ID=appXXXXXXXXXXXXXX
AIRTABLE_TEST_TABLE_NAME=TestTable

# For get/update tests - ID of an existing record
AIRTABLE_TEST_RECORD_ID=recXXXXXXXXXXXXXX

# For delete test - create a throwaway record and put its ID here
AIRTABLE_TEST_RECORD_TO_DELETE=recYYYYYYYYYYYYYY
```

--------------------------------

### zv1 Class Methods

Source: https://github.com/zerowidth-ai/zv1/blob/main/sdks/nodejs/README.md

Documentation for the zv1 class and its static and instance methods.

```APIDOC
## zv1 Class

### `static async create(flow, config)`

**Description**: Creates a new zv1 instance. This is the recommended way to initialize the engine.

**Parameters**:
- `flow` (string|Object|Buffer): File path to a .zv1 or .json file, a flow definition object, or ZIP data as a Buffer.
- `config` (Object): Configuration options and context for the engine.

**Returns**: A Promise that resolves to a fully initialized zv1 instance.

### `async run(inputs, timeout)`

**Description**: Runs the flow with the provided inputs and returns the final output.

**Parameters**:
- `inputs` (Object): Data to inject into input nodes.
- `timeout` (number): Maximum execution time in milliseconds. Defaults to 60000.

**Returns**: A Promise that resolves to the final output from the output nodes.

### `async cleanup()`

**Description**: Cleans up resources, including knowledge databases and temporary files. This should be called when the engine is no longer needed to free up memory.

**Returns**: A Promise that resolves when cleanup is complete.
```

--------------------------------

### Error Context with Verbose Mode

Source: https://github.com/zerowidth-ai/zv1/blob/main/sdks/nodejs/README.md

An example of the detailed error context provided when verbose mode is enabled. It includes error type, message, execution ID, node details, and a cost summary.

```javascript
{
  errorType: "node",
  message: "Node execution failed: Custom error message",
  executionId: "uuid-1234",
  nodeId: "node-1",
  nodeType: "custom-node",
  errorDetails: {
    timeline: [...],
    nodeCount: 5,
    nodesExecuted: 3,
    cost_summary: { total: 0.05, itemized: [...] }
  }
}
```

--------------------------------

### Create Custom Message Converter

Source: https://github.com/zerowidth-ai/zv1/blob/main/sdks/nodejs/src/types/README.md

Define custom conversion logic for the 'message' type in a `<typeName>.converters.js` file. This example shows how to extract text content from a message's content field.

```javascript
/**
 * Type converters for the 'message' type
 * Converts message objects to strings by extracting all text content
 */

/**
 * Extract text content from a message's content field
 */
function extractTextFromContent(content) {
  if (typeof content === 'string') {
    return content;
  }
  
  if (content === null || content === undefined) {
    return '';
  }
  
  if (Array.isArray(content)) {
    let text = '';
    for (const item of content) {
      if (item && typeof item === 'object' && item.type === 'text' && item.text) {
        text += item.text;
      }
    }
    return text;
  }
  
  return String(content || '');
}

/**
 * Convert a message object to a string
 */
export function toString(message, separator) {
  if (!message || typeof message !== 'object') {
    return String(message || '');
  }
  
  return extractTextFromContent(message.content);
}

export default {
  toString
};
```

--------------------------------

### Create Engine with Custom Tools

Source: https://github.com/zerowidth-ai/zv1/blob/main/NODE_GUIDELINES.md

Initialize the zv1 engine, providing API keys and defining custom tools with their schemas and processing logic. This allows LLMs to access external functionalities.

```javascript
const engine = await zv1.create('./myflow.zv1', {
  keys: { openai: 'sk-...' },
  tools: {
    // Full definition: schema + implementation
    'get_weather': {
      schema: {
        name: 'get_weather',
        description: 'Get current weather for a city',
        parameters: {
          type: 'object',
          properties: {
            city: { type: 'string', description: 'City name' },
            units: { type: 'string', enum: ['celsius', 'fahrenheit'] }
          },
          required: ['city']
        }
      },
      process: async (args) => {
        // Your custom tool implementation
        const weather = await fetchWeather(args.city, args.units);
        return { temperature: weather.temp, conditions: weather.conditions };
      }
    },
    
    // Process only: uses schema from flow's tool node
    'lookup_customer': {
      process: async (args) => {
        // Flow already defines the schema via a tool node
        // You just provide the implementation
        return await db.customers.findOne({ id: args.customer_id });
      }
    }
  }
});
```

--------------------------------

### Run zv1 Flow and Get Results

Source: https://github.com/zerowidth-ai/zv1/blob/main/sdks/nodejs/README.md

Execute a zv1 flow using the `run` method with optional inputs. The result object contains flow outputs, execution timeline, and cost summaries.

```javascript
const result = await engine.run(inputs);

// Example result structure:
{
  // Flow outputs (from output nodes)
  outputs: {
    data: "processed result",
    chat: [{ role: "assistant", content: "response" }]
  },
  
  // Execution timeline with detailed node information
  timeline: [
    {
      nodeId: "node-1",
      nodeType: "input-data", 
      inputs: { /* node inputs */ },
      outputs: { /* node outputs */ },
      settings: { /* node settings */ },
      startTime: "2024-01-01T10:00:00.000Z",
      endTime: "2024-01-01T10:00:00.100Z", 
      durationMs: 100,
      status: "success" // or "error"
      // errorMessage: "error details" (if status is "error")
    }
    // ... more timeline entries
  ],
  
  // Cost tracking information
  cost_summary: {
    total: 0.05,
    itemized: [
      {
        node_id: "llm-1",
        node_type: "openai-gpt-4",
        total: 0.05,
        itemized: { /* detailed cost breakdown */ }
      }
    ]
  },
  
  // Any missing input values for partial executions
  inputsMissingValues: [],
  
  // Completion message, which is also used to communicate partial runs 
  message: "Completed."
}
```

--------------------------------

### Zv1 Configuration Options

Source: https://github.com/zerowidth-ai/zv1/blob/main/sdks/python/README.md

Illustrates the structure of the configuration dictionary for Zv1. It includes settings for API keys, node event handlers, error handling, and execution parameters.

```python
config = {
    # Optional: API keys for external services
    'keys': {
        'openai': 'sk-...',
        'gemini': '...',
        # ... other service keys
    },

    # Optional: Node execution event handlers
    'on_node_start': async_callback,      # (event) -> None
    'on_node_complete': async_callback,   # (event) -> None
    'on_node_update': async_callback,     # (event) -> None

    # Optional: Error event handler
    'on_error': async_callback,           # (error_event) -> None

    # Optional: Maximum number of plugin calls per LLM node (default: 10)
    'max_plugin_calls': 10,

    # Optional: Execution ID for tracking (auto-generated if not provided)
    'execution_id': 'custom-execution-id',

    # Optional: Enable debug logging
    'debug': True
}
```
Tokens:
Raw