@zerowidth/workbench-sdk 2.2.0 → 2.3.0

package/README.md

@@ -48,7 +48,7 @@ import Workbench from '@zerowidth/workbench-sdk';
 // Create engine instance by passing the location of your configured flow
 const engine = await Workbench.create('./path/to/myflow.zwf', {
   keys: {
-    openrouter: process.env.OPENROUTER_API_KEY
+    inference: process.env.INFERENCE_API_KEY  // your LLM endpoint's key
   }
 });
 
@@ -281,14 +281,36 @@ The engine supports secure API key management for nodes that require external se
 ```javascript
 const engine = await Workbench.create(flow, {
   keys: {
-    openrouter: "sk-...",  // OpenRouter API key
+    inference: "sk-...",  // key for the LLM endpoint (default: OpenRouter)
   }
 });
 ```
 
+### Pointing at your own LLM
+
+Every OpenAI-compatible LLM node runs against a single inference endpoint.
+By default that's OpenRouter, but you can point it at **your own**
+OpenAI-compatible endpoint (vLLM, Ollama, TGI, a LiteLLM proxy, or any
+gateway) — nothing leaves your infrastructure:
+
+```javascript
+const engine = await Workbench.create(flow, {
+  keys: { inference: process.env.MY_LLM_KEY },
+  inferenceBaseURL: "https://llm.my-internal-host/v1",
+});
+```
+
+The model ids in the flow (e.g. `openai/gpt-4o`) must be ones your endpoint
+serves — a LiteLLM `model_list` mapping is the usual way to line these up.
+A custom `inferenceBaseURL` sends plain OpenAI-shaped requests (the
+OpenRouter-only payload fields are dropped automatically).
+
+> **Aliases:** `keys.openrouter` and `openrouterBaseURL` are still accepted
+> as backward-compatible aliases for `keys.inference` and `inferenceBaseURL`.
+
 ### Node Key Requirements
 
-Nodes specify their key requirements in their configuration. All LLMs are configured by default to use OpenRouter, but this can be overridden.
+Nodes specify their key requirements in their configuration. All LLMs are configured by default to use the inference endpoint (OpenRouter unless overridden), but this can be overridden.
 
 ```json
 {

package/nodes/custom-inference/custom-inference.config.json

@@ -0,0 +1,158 @@
+{
+  "display_name": "Custom Inference",
+  "tagline": "Generate text on a bring-your-own endpoint",
+  "description": "Runs a chat completion against a host-registered custom inference provider (an OpenAI-compatible or Azure OpenAI endpoint). The host resolves `settings.provider` to a `custom:<provider>` integration and sends `settings.model` as the model. Used by ZeroWidth's BYO inference endpoints (ADR 0048 Phase 3); the host rewrites a `byo:<provider>:<model>` node into this one at run time.",
+  "category": "llm",
+  "accepts_plugins": true,
+  "settings": [
+    {
+      "name": "provider",
+      "display_name": "Provider",
+      "type": "string",
+      "description": "Name of the host-registered custom inference provider.",
+      "default": null
+    },
+    {
+      "name": "model",
+      "display_name": "Model",
+      "type": "string",
+      "description": "Model / deployment id the endpoint serves.",
+      "default": null
+    }
+  ],
+  "inputs": [
+    {
+      "name": "messages",
+      "display_name": "Conversation",
+      "type": "conversation or message or string",
+      "description": "Array of chat messages that make up the conversation",
+      "required": true
+    },
+    {
+      "name": "system_prompt",
+      "display_name": "System Message",
+      "type": "message or string",
+      "description": "System prompt to instruct the model",
+      "default": null
+    },
+    {
+      "name": "tools",
+      "display_name": "Tools",
+      "type": "tool or array of tools",
+      "description": "Array of tools to use",
+      "default": null,
+      "allow_multiple": true
+    },
+    {
+      "name": "tool_choice",
+      "display_name": "Tool Choice",
+      "type": "string",
+      "description": "Tool selection control",
+      "default": null
+    },
+    {
+      "name": "response_format",
+      "display_name": "Response Format",
+      "type": "object",
+      "description": "Output format specification",
+      "default": null
+    },
+    {
+      "name": "stop",
+      "display_name": "Stop",
+      "type": "string or array",
+      "description": "Custom stop sequences",
+      "default": null
+    },
+    {
+      "name": "temperature",
+      "display_name": "Temperature",
+      "type": "number",
+      "description": "Controls randomness (0-2)",
+      "default": null
+    },
+    {
+      "name": "top_p",
+      "display_name": "Top P",
+      "type": "number",
+      "description": "Controls diversity via nucleus sampling",
+      "default": null
+    },
+    {
+      "name": "max_tokens",
+      "display_name": "Max Tokens",
+      "type": "number",
+      "description": "Maximum tokens to generate",
+      "default": null
+    },
+    {
+      "name": "frequency_penalty",
+      "display_name": "Frequency Penalty",
+      "type": "number",
+      "description": "Reduces repetition (-2 to 2)",
+      "default": null
+    },
+    {
+      "name": "presence_penalty",
+      "display_name": "Presence Penalty",
+      "type": "number",
+      "description": "Encourages new topics (-2 to 2)",
+      "default": null
+    },
+    {
+      "name": "seed",
+      "display_name": "Seed",
+      "type": "number",
+      "description": "Deterministic outputs",
+      "default": null
+    }
+  ],
+  "outputs": [
+    {
+      "name": "conversation",
+      "display_name": "Conversation",
+      "type": "conversation",
+      "can_stream": true,
+      "description": "An array of messages including any tool call & response messages as well as the final generated output."
+    },
+    {
+      "name": "content",
+      "display_name": "Content",
+      "can_stream": true,
+      "type": "string",
+      "description": "The content portion of the final generated response message."
+    },
+    {
+      "name": "message",
+      "display_name": "Final Message",
+      "type": "message",
+      "can_stream": true,
+      "description": "The final generated response message."
+    },
+    {
+      "name": "role",
+      "display_name": "Role",
+      "can_stream": true,
+      "type": "string",
+      "description": "Role of the response (usually 'assistant')"
+    },
+    {
+      "name": "tool_calls",
+      "display_name": "Tool Calls",
+      "type": "array of tools",
+      "description": "Tool calls made by the model"
+    },
+    {
+      "name": "usage",
+      "display_name": "Token Usage",
+      "type": "object",
+      "description": "Token usage statistics"
+    },
+    {
+      "name": "finish_reason",
+      "display_name": "Finish Reason",
+      "type": "string",
+      "description": "Why the completion finished"
+    }
+  ]
+}

package/nodes/custom-inference/custom-inference.process.js

@@ -0,0 +1,117 @@
+export default async ({inputs, settings, config, nodeConfig}) => {
+    try {
+        // Resolve the host-registered custom inference provider (ADR 0048
+        // Phase 3). `settings.provider` names it; the host built a
+        // `custom:<provider>` integration in loadIntegrations from
+        // config.customInferenceProviders. `settings.model` is the model /
+        // Azure deployment the endpoint serves.
+        const providerName = settings?.provider;
+        const model = settings?.model;
+        if (!providerName || !model) {
+            throw new Error("Custom Inference node requires provider + model settings");
+        }
+        const integration = config.integrations?.['custom:' + providerName];
+        if (!integration) {
+            throw new Error(`Custom inference provider "${providerName}" is not configured`);
+        }
+
+        let messages = inputs.messages;
+
+        if(typeof messages === 'string') {
+            messages = [{ role: 'user', content: messages }];
+        }
+
+        if(typeof messages === 'object' && !Array.isArray(messages)) {
+            messages = [messages];
+        }
+
+        if(inputs.system_prompt) {
+            let systemPrompt = inputs.system_prompt;
+            if(typeof systemPrompt === 'string') {
+                systemPrompt = { role: 'system', content: systemPrompt };
+            }
+            messages = [systemPrompt, ...messages];
+        }
+
+        // Build parameters object from the wired inputs (everything but the
+        // conversation itself), mirroring the platform LLM nodes.
+        const params = {};
+        for (const input of (nodeConfig?.inputs || [])) {
+            if (input.name === 'messages') continue;
+            const value = inputs[input.name];
+            if (value !== null && value !== undefined) {
+                if (input.name === 'tools' && Array.isArray(value)) {
+                    params.tools = value.flat();
+                } else {
+                    params[input.name] = value;
+                }
+            }
+        }
+
+        const response = await integration.chatCompletion({
+            model,
+            messages,
+            ...params
+        }, nodeConfig, config);
+
+        // Conversation output: keep only internal-tool history + the fresh
+        // response — identical to the platform chat nodes.
+        const hasInternalToolTracking = config.internal_tool_names !== undefined;
+        const internalToolNames = new Set(config.internal_tool_names || []);
+
+        let conversationMessages = [];
+        if (Array.isArray(messages) && messages.length > 0) {
+            for (let i = messages.length - 1; i >= 0; i--) {
+                const msg = messages[i];
+                if (!msg || typeof msg !== 'object') continue;
+                const isTool = msg.role === 'tool';
+                const hasToolCalls = msg.tool_calls && Array.isArray(msg.tool_calls) && msg.tool_calls.length > 0;
+                if (isTool) {
+                    const toolName = msg.name;
+                    if (!hasInternalToolTracking || internalToolNames.has(toolName)) {
+                        conversationMessages.unshift(msg);
+                    }
+                } else if (hasToolCalls) {
+                    const internalCalls = !hasInternalToolTracking
+                        ? msg.tool_calls
+                        : msg.tool_calls.filter(tc => internalToolNames.has(tc.function?.name));
+                    if (internalCalls.length > 0) {
+                        conversationMessages.unshift({ ...msg, tool_calls: internalCalls });
+                    }
+                } else {
+                    break;
+                }
+            }
+        }
+
+        const finalMessage = { content: response.content, role: response.role };
+        if (response.tool_calls && Array.isArray(response.tool_calls) && response.tool_calls.length > 0) {
+            finalMessage.tool_calls = response.tool_calls;
+        }
+        if (response.images) {
+            finalMessage.images = response.images;
+        }
+        conversationMessages.push(finalMessage);
+
+        return {
+            conversation: conversationMessages,
+            message: {
+                content: response.content,
+                role: response.role,
+                tool_calls: response.tool_calls
+            },
+            content: response.content,
+            role: response.role,
+            tool_calls: response.tool_calls,
+            annotations: response.annotations,
+            citations: response.citations,
+            logprobs: response.logprobs,
+            finish_reason: response.finish_reason,
+            usage: response.usage,
+            cost_total: response.cost_total,
+            cost_itemized: response.cost_itemized
+        };
+    } catch (error) {
+        throw new Error(`Custom Inference node error: ${error.message}`);
+    }
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zerowidth/workbench-sdk",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "dependencies": {
     "adm-zip": "^0.5.16",
     "ajv": "^8.17.1",
@@ -11,7 +11,11 @@
     "tiktoken": "^1.0.22",
     "uuid": "^11.1.0"
   },
-  "repository": "https://github.com/zerowidth-ai/workbench-sdk",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/zerowidth-ai/workbench-sdk.git",
+    "directory": "sdks/nodejs"
+  },
   "description": "Workbench SDK \u2014 execute Workbench-authored flows in production. Successor to the zv1 package; see https://zerowidth.ai for the design surface.",
   "main": "./src/index.js",
   "files": [
@@ -34,7 +38,8 @@
     "test-nodes": "node tests/test.all-nodes.js",
     "test-flows": "node tests/test.flows.js",
     "test-flow": "node tests/test.flows.js",
-    "test-kb": "node tests/test.kb-search.js && node tests/test.kb-graph.js"
+    "test-kb": "node tests/test.kb-search.js && node tests/test.kb-graph.js",
+    "test-custom-inference": "node tests/test.custom-inference.js"
   },
   "author": "Peter Binggeser @ ZeroWidth, LLC",
   "license": "Apache-2.0",

package/src/integrations/openrouter.js

@@ -1,18 +1,38 @@
-import OpenAI from 'openai';
+import OpenAI, { AzureOpenAI } from 'openai';
 import { emitAPICallEvent } from '../utilities/sanitizeAPICall.js';
 
 export default class OpenRouterIntegration {
     constructor(apiKey, options = {}) {
-        
-        this.client = new OpenAI({
-            baseURL: options.baseURL || 'https://openrouter.ai/api/v1',
-            apiKey: apiKey,
-            defaultHeaders: {
-                'Content-Type': 'application/json',
-                'HTTP-Referer': options.referer || 'https://workbench.zerowidth.ai',
-                'X-Title': options.title || 'Workbench by ZeroWidth'
-            }
-        });
+        // dialect: 'openrouter' (default — the platform endpoint, which
+        // accepts OpenRouter-specific payload extensions), or a custom
+        // OpenAI-compatible endpoint: 'openai' (vLLM/Ollama/TGI/gateways)
+        // or 'azure' (Azure OpenAI — deployment routing + api-version).
+        // See ADR 0048 Phase 3 in the zerowidth monorepo.
+        this.dialect = options.dialect || 'openrouter';
+
+        const defaultHeaders = {
+            'Content-Type': 'application/json',
+            'HTTP-Referer': options.referer || 'https://workbench.zerowidth.ai',
+            'X-Title': options.title || 'Workbench by ZeroWidth'
+        };
+
+        if (this.dialect === 'azure') {
+            // Azure OpenAI: the model name is the deployment; auth is the
+            // `api-key` header + a required `api-version`. AzureOpenAI wires
+            // all three from these options.
+            this.client = new AzureOpenAI({
+                endpoint: options.baseURL,
+                apiKey: apiKey,
+                apiVersion: options.apiVersion || '2024-10-21',
+                defaultHeaders
+            });
+        } else {
+            this.client = new OpenAI({
+                baseURL: options.baseURL || 'https://openrouter.ai/api/v1',
+                apiKey: apiKey,
+                defaultHeaders
+            });
+        }
     }
 
     async chatCompletion(params, nodeConfig = null, engineConfig = null) {
@@ -24,16 +44,20 @@ export default class OpenRouterIntegration {
         } = params;
 
         // Base payload with required fields
-        const payload = {
-            model,
-            provider: {
+        const payload = { model };
+        // OpenRouter-only extensions: the `provider` routing directive and
+        // usage accounting. A custom OpenAI-compatible / Azure endpoint
+        // doesn't understand these and strict servers (Azure) reject
+        // unknown fields — so only send them to the platform endpoint.
+        if (this.dialect === 'openrouter') {
+            payload.provider = {
                 data_collection: "deny",
                 require_parameters: true,
-            },
+            };
             // Request OpenRouter usage accounting so the response carries the
             // authoritative cost (usage.cost). buildCostData prefers it.
-            usage: { include: true }
-        };
+            payload.usage = { include: true };
+        }
 
         // Add messages or prompt (required)
         if (messages) {

package/src/utilities/loaders.js

@@ -112,13 +112,27 @@ export async function loadNodes(flow) {
 export async function loadIntegrations(config, flow = null) {
   const integrations = {};
   
-  // Load OpenRouter integration if API key is provided
-  if (config.keys?.openrouter) {
+  // Load the primary LLM integration (OpenAI-compatible chat/completions).
+  // Public config is provider-agnostic — `inferenceBaseURL` + `keys.inference`
+  // — so a self-hosted host can point the engine at its own endpoint without
+  // any "openrouter" branding. `openrouterBaseURL` + `keys.openrouter` remain
+  // as backward-compatible aliases (the platform default endpoint stays
+  // OpenRouter). The integration is still registered under `openrouter` for
+  // the LLM nodes that look it up by that name.
+  const inferenceKey = config.keys?.inference ?? config.keys?.openrouter;
+  if (inferenceKey) {
       const openrouterPath = path.join(getDirname(import.meta.url), '../integrations', 'openrouter.js');
+      const inferenceBaseURL = config.inferenceBaseURL || config.openrouterBaseURL || 'https://openrouter.ai/api/v1';
+      // Only the real OpenRouter endpoint understands the OpenRouter-only
+      // payload extensions (provider routing, usage accounting). A custom
+      // base URL is a plain OpenAI-compatible endpoint, so use the 'openai'
+      // dialect there and don't send those fields (see openrouter.js).
+      const isOpenRouterEndpoint = /^https?:\/\/openrouter\.ai(\/|$)/i.test(inferenceBaseURL);
       try {
           const OpenRouterIntegration = await import(openrouterPath).then(module => module.default);
-          integrations.openrouter = new OpenRouterIntegration(config.keys.openrouter, {
-              baseURL: config.openrouterBaseURL || 'https://openrouter.ai/api/v1',
+          integrations.openrouter = new OpenRouterIntegration(inferenceKey, {
+              baseURL: inferenceBaseURL,
+              dialect: isOpenRouterEndpoint ? 'openrouter' : 'openai',
               referer: 'https://workbench.zerowidth.ai',
               title: 'Workbench by ZeroWidth'
           });
@@ -126,7 +140,28 @@ export async function loadIntegrations(config, flow = null) {
           throw error;
       }
   }
-  
+
+  // Bring-your-own inference endpoints (ADR 0048 Phase 3). The host passes
+  // `customInferenceProviders: { <name>: { baseURL, apiKey, dialect,
+  // apiVersion?, models? } }`. Each becomes an integration keyed
+  // `custom:<name>`, reusing the OpenRouter integration's completion logic
+  // with a custom destination + dialect. The `custom-inference` node
+  // resolves `custom:<provider>` by its settings.
+  if (config.customInferenceProviders && typeof config.customInferenceProviders === 'object') {
+      const openrouterPath = path.join(getDirname(import.meta.url), '../integrations', 'openrouter.js');
+      const OpenRouterIntegration = await import(openrouterPath).then(module => module.default);
+      for (const [name, provider] of Object.entries(config.customInferenceProviders)) {
+          if (!provider?.baseURL || !provider?.apiKey) continue;
+          integrations['custom:' + name] = new OpenRouterIntegration(provider.apiKey, {
+              baseURL: provider.baseURL,
+              dialect: provider.dialect === 'azure' ? 'azure' : 'openai',
+              apiVersion: provider.apiVersion,
+              referer: 'https://workbench.zerowidth.ai',
+              title: 'Workbench by ZeroWidth'
+          });
+      }
+  }
+
   // Load knowledge base integration if available
   const knowledgeBaseType = config.knowledgeBase?.type || 'sqlite';
   const knowledgeBaseConfig = config.knowledgeBase || {};