@foresthubai/workflow-core 0.3.0

package/src/api/workflow.ts

@@ -0,0 +1,607 @@
+/**
+ * This file was auto-generated by openapi-typescript.
+ * Do not make direct changes to the file.
+ */
+
+export type paths = Record<string, never>;
+export type webhooks = Record<string, never>;
+export interface components {
+    schemas: {
+        /** @enum {string} */
+        DataType: "int" | "float" | "bool" | "string";
+        /** @enum {string} */
+        SignalType: "digital" | "analog";
+        /** @enum {string} */
+        EdgeType: "control" | "tool" | "agentTask" | "agentChoice" | "agentDelegate";
+        NodePosition: {
+            x: number;
+            y: number;
+        };
+        /** @description Workflow represents the deployment format of a project, passed to agents. */
+        Workflow: {
+            /**
+             * Format: int32
+             * @description Monotonic version of the persisted workflow format, bumped when the serialized shape changes.
+             */
+            schemaVersion: number;
+            nodes: components["schemas"]["Node"][];
+            edges: components["schemas"]["Edge"][];
+            functions: components["schemas"]["Function"][];
+            declaredVariables: components["schemas"]["Variable"][];
+            channels: components["schemas"]["Channel"][];
+            memory: components["schemas"]["Memory"][];
+            /** @description Declared custom/self-hosted models; referenced from nodes by id. Static catalog models need no declaration. */
+            models: components["schemas"]["Model"][];
+        };
+        Edge: {
+            id: string;
+            type: components["schemas"]["EdgeType"];
+            from: components["schemas"]["Vertex"];
+            to: components["schemas"]["Vertex"];
+            /** @description Prompt expression sent to the agent. Present on `agentTask` (required) and `agentDelegate` (optional). */
+            prompt?: components["schemas"]["Expression"];
+            /** @description LLM-readable explanation of when the edge should fire. Present on `agentChoice` and `agentDelegate`. */
+            description?: string;
+        };
+        Vertex: {
+            nodeId: string;
+            port: string;
+        };
+        Function: {
+            functionInfo: components["schemas"]["FunctionInfo"];
+            /** @description Maps return variable uid to its Expression */
+            outputAssignments: {
+                [key: string]: components["schemas"]["Expression"];
+            };
+            nodes: components["schemas"]["Node"][];
+            edges: components["schemas"]["Edge"][];
+            declaredVariables: components["schemas"]["Variable"][];
+        };
+        FunctionInfo: {
+            id: string;
+            /** Format: int32 */
+            version: number;
+            name: string;
+            arguments: components["schemas"]["Variable"][];
+            returns: components["schemas"]["Variable"][];
+        };
+        /** @description A named, typed variable with a stable uid that can be referenced throughout the workflow. */
+        Variable: {
+            /** @description Stable identifier that survives renames */
+            uid: string;
+            name: string;
+            dataType: components["schemas"]["DataType"];
+            /** @description Initial value matching the dataType (number, boolean, or string). Only used by declared variables. */
+            initialValue?: unknown;
+        };
+        Expression: {
+            expression: string;
+            /** @description A list of referenced variable IDs used in the expression */
+            references: components["schemas"]["Reference"][];
+            dataType: components["schemas"]["DataType"];
+        };
+        Reference: {
+            srcId: string;
+            varId: string;
+        };
+        OutputBinding: {
+            /** @description Discard the output if false; route it according to `mode` if true */
+            active: boolean;
+            /** @enum {string} */
+            mode: "emit" | "assign";
+            /** @description Variable name (when mode=emit) */
+            name?: string;
+            /** @description Existing variable to route to (when mode=assign) */
+            target?: components["schemas"]["Reference"];
+        };
+        OutputDeclaration: {
+            /** @enum {string} */
+            mode: "emit" | "assign";
+            /** @description JSON property name of the declared output */
+            name: string;
+            dataType: components["schemas"]["DataType"];
+            /** @description New variable uid (when mode=emit) */
+            uid?: string;
+            /** @description Existing variable to route to (when mode=assign) */
+            target?: components["schemas"]["Reference"];
+        };
+        Memory: components["schemas"]["MemoryFile"] | components["schemas"]["VectorDatabase"];
+        /** @description One .md file that agent nodes can read and write to. */
+        MemoryFile: {
+            /**
+             * @description discriminator enum property added by openapi-typescript
+             * @enum {string}
+             */
+            type: "MemoryFile";
+            /** @description Stable identifier that survives renames; referenced from MemoryRef. */
+            id: string;
+            /** @description Display name. Unique per agent (LLM tool enums use it). */
+            label: string;
+            description: string;
+            content: string;
+            /** @description Byte cap; null means unlimited. */
+            maxSizeBytes?: number | null;
+        };
+        /** @description A vector database for retrieval-augmented generation (RAG). */
+        VectorDatabase: {
+            /**
+             * @description discriminator enum property added by openapi-typescript
+             * @enum {string}
+             */
+            type: "VectorDatabase";
+            /** @description Stable identifier; referenced from Retriever nodes. */
+            id: string;
+            /** @description Display name. */
+            label: string;
+            description?: string;
+        };
+        /** @description Reference from an LLM agent node to a declared MemoryFile with an access mode. */
+        MemoryRef: {
+            /** @description id of the referenced MemoryFile. */
+            id: string;
+            /**
+             * @description r = read-only; rw = read + write.
+             * @enum {string}
+             */
+            mode: "r" | "rw";
+        };
+        /** @enum {string} */
+        ModelCapability: "chat" | "embedding" | "function_call" | "vision" | "fine_tuning" | "reasoning" | "classification" | "code";
+        Model: components["schemas"]["LLMModel"];
+        /** @description A custom or self-hosted language model that agent nodes can reference. */
+        LLMModel: {
+            /**
+             * @description discriminator enum property added by openapi-typescript
+             * @enum {string}
+             */
+            type: "LLMModel";
+            /** @description Stable identifier; this is the ModelID nodes reference. */
+            id: string;
+            /** @description Display name. */
+            label: string;
+            /** @description Capabilities this model supports (used to filter model pickers). */
+            capabilities: components["schemas"]["ModelCapability"][];
+        };
+        Node: components["schemas"]["ReadPinNode"] | components["schemas"]["WritePinNode"] | components["schemas"]["AgentNode"] | components["schemas"]["IfNode"] | components["schemas"]["SerialReadNode"] | components["schemas"]["SerialWriteNode"] | components["schemas"]["RetrieverNode"] | components["schemas"]["WebFetchNode"] | components["schemas"]["FunctionCallNode"] | components["schemas"]["OnFunctionCallNode"] | components["schemas"]["DelayNode"] | components["schemas"]["TickerNode"] | components["schemas"]["AlarmNode"] | components["schemas"]["WebSearchToolNode"] | components["schemas"]["OnStartupNode"] | components["schemas"]["OnPinEdgeNode"] | components["schemas"]["OnSerialReceiveNode"] | components["schemas"]["OnThresholdNode"] | components["schemas"]["SetVariableNode"] | components["schemas"]["MqttPublishNode"] | components["schemas"]["OnMqttMessageNode"];
+        WebSearchToolNode: {
+            id: string;
+            /**
+             * @description discriminator enum property added by openapi-typescript
+             * @enum {string}
+             */
+            type: "WebSearchTool";
+            label?: string;
+            position: components["schemas"]["NodePosition"];
+            arguments: {
+                /** @description Maximum number of search results to return per call. Defaults to 5 when omitted or non-positive. Capped at 20. */
+                maxResults?: number;
+            };
+        };
+        DelayNode: {
+            id: string;
+            /**
+             * @description discriminator enum property added by openapi-typescript
+             * @enum {string}
+             */
+            type: "Delay";
+            label?: string;
+            position: components["schemas"]["NodePosition"];
+            arguments: {
+                /** @description Time in milliseconds to pause execution */
+                delayMs?: number;
+            };
+        };
+        TickerNode: {
+            id: string;
+            /**
+             * @description discriminator enum property added by openapi-typescript
+             * @enum {string}
+             */
+            type: "Ticker";
+            label?: string;
+            position: components["schemas"]["NodePosition"];
+            arguments: {
+                /** @description How many units between ticks */
+                intervalValue?: number;
+                /**
+                 * @description Time unit for the interval
+                 * @enum {string}
+                 */
+                intervalUnit: "milliseconds" | "seconds" | "minutes" | "hours";
+            };
+        };
+        AlarmNode: {
+            id: string;
+            /**
+             * @description discriminator enum property added by openapi-typescript
+             * @enum {string}
+             */
+            type: "Alarm";
+            label?: string;
+            position: components["schemas"]["NodePosition"];
+            arguments: {
+                /** @description Time of day to fire (HH:MM, 24h format) */
+                time?: string;
+                /** @description Days of the week to fire on (empty = every day) */
+                days: string[];
+            };
+        };
+        FunctionCallNode: {
+            id: string;
+            /**
+             * @description discriminator enum property added by openapi-typescript
+             * @enum {string}
+             */
+            type: "FunctionCall";
+            label?: string;
+            position: components["schemas"]["NodePosition"];
+            /** @description Id of the function this node calls. The signature is resolved from the workflow's functions table. */
+            functionId: string;
+            arguments: {
+                inputBindings?: {
+                    [key: string]: components["schemas"]["Expression"];
+                };
+                outputBindings?: {
+                    [key: string]: components["schemas"]["OutputBinding"];
+                };
+                /** @description Description exposed to the LLM when this function is wired as a tool. Ignored in exec mode. */
+                toolDescription?: string;
+            };
+        };
+        OnFunctionCallNode: {
+            id: string;
+            /**
+             * @description discriminator enum property added by openapi-typescript
+             * @enum {string}
+             */
+            type: "OnFunctionCall";
+            label?: string;
+            position: components["schemas"]["NodePosition"];
+        };
+        OnStartupNode: {
+            id: string;
+            /**
+             * @description discriminator enum property added by openapi-typescript
+             * @enum {string}
+             */
+            type: "OnStartup";
+            label?: string;
+            position: components["schemas"]["NodePosition"];
+        };
+        OnPinEdgeNode: {
+            id: string;
+            /**
+             * @description discriminator enum property added by openapi-typescript
+             * @enum {string}
+             */
+            type: "OnPinEdge";
+            label?: string;
+            position: components["schemas"]["NodePosition"];
+            arguments: {
+                /** @description IO variable ID of the digital pin to watch */
+                pinReference?: string;
+                /**
+                 * @description Edge transition that fires the trigger
+                 * @enum {string}
+                 */
+                edge: "rising" | "falling" | "both";
+            };
+        };
+        OnSerialReceiveNode: {
+            id: string;
+            /**
+             * @description discriminator enum property added by openapi-typescript
+             * @enum {string}
+             */
+            type: "OnSerialReceive";
+            label?: string;
+            position: components["schemas"]["NodePosition"];
+            arguments: {
+                /** @description Reference to an IO variable ID (the serial port to listen on) */
+                portReference?: string;
+                output: components["schemas"]["OutputBinding"];
+            };
+        };
+        OnThresholdNode: {
+            id: string;
+            /**
+             * @description discriminator enum property added by openapi-typescript
+             * @enum {string}
+             */
+            type: "OnThreshold";
+            label?: string;
+            position: components["schemas"]["NodePosition"];
+            arguments: {
+                /** @description Numeric variable to watch for threshold crossings */
+                variable?: components["schemas"]["Reference"];
+                /** @description Value the variable crosses to fire the trigger */
+                threshold?: number;
+                /**
+                 * @description Crossing direction to fire on (default both)
+                 * @enum {string}
+                 */
+                direction: "rising" | "falling" | "both";
+                /** @description Hysteresis band width around threshold; 0 disables (default 0) */
+                deadband?: number;
+                /** @description Optional binding for the triggering value */
+                output: components["schemas"]["OutputBinding"];
+            };
+        };
+        RetrieverNode: {
+            id: string;
+            /**
+             * @description discriminator enum property added by openapi-typescript
+             * @enum {string}
+             */
+            type: "Retriever";
+            label?: string;
+            position: components["schemas"]["NodePosition"];
+            arguments: {
+                /** @description Reference to a declared VectorDatabase memory id */
+                memoryReference?: string;
+                /** @description Number of results to return */
+                topK?: number;
+                /** @description Search query expression */
+                query: components["schemas"]["Expression"];
+                output: components["schemas"]["OutputBinding"];
+                /** @description Description exposed to the LLM when this node is wired as a tool. Ignored in exec mode. */
+                toolDescription?: string;
+            };
+        };
+        WebFetchNode: {
+            id: string;
+            /**
+             * @description discriminator enum property added by openapi-typescript
+             * @enum {string}
+             */
+            type: "WebFetch";
+            label?: string;
+            position: components["schemas"]["NodePosition"];
+            arguments: {
+                /** @description URL expression to fetch (http or https) */
+                url: components["schemas"]["Expression"];
+                /** @description Maximum characters of extracted text to return. Defaults to 50000 when omitted or non-positive. */
+                maxChars?: number;
+                output: components["schemas"]["OutputBinding"];
+            };
+        };
+        ReadPinNode: {
+            id: string;
+            /**
+             * @description discriminator enum property added by openapi-typescript
+             * @enum {string}
+             */
+            type: "ReadPin";
+            label?: string;
+            position: components["schemas"]["NodePosition"];
+            arguments: {
+                /** @description Reference to an IO variable ID */
+                pinReference?: string;
+                signalType: components["schemas"]["SignalType"];
+                output: components["schemas"]["OutputBinding"];
+                /** @description Description exposed to the LLM when this node is wired as a tool. Ignored in exec mode. */
+                toolDescription?: string;
+            };
+        };
+        WritePinNode: {
+            id: string;
+            /**
+             * @description discriminator enum property added by openapi-typescript
+             * @enum {string}
+             */
+            type: "WritePin";
+            label?: string;
+            position: components["schemas"]["NodePosition"];
+            arguments: {
+                /** @description Reference to an IO variable ID */
+                pinReference?: string;
+                signalType: components["schemas"]["SignalType"];
+                value: components["schemas"]["Expression"];
+            };
+        };
+        AgentNode: {
+            id: string;
+            /**
+             * @description discriminator enum property added by openapi-typescript
+             * @enum {string}
+             */
+            type: "Agent";
+            label?: string;
+            position: components["schemas"]["NodePosition"];
+            arguments: {
+                /** @description Name of the agent */
+                name?: string;
+                model?: string;
+                instructions?: string;
+                /** @description Maximum number of agent runner turns */
+                maxTurns?: number;
+                answer: components["schemas"]["OutputBinding"];
+                /** @description Ordered list of structured-output declarations. Names must be unique within this list */
+                outputDeclarations: components["schemas"]["OutputDeclaration"][];
+                /** @description Memory files this agent can access, each with an access mode. */
+                memoryRefs: components["schemas"]["MemoryRef"][];
+                /** @description Description exposed to the LLM when this node is wired as a tool. Ignored in exec mode. */
+                toolDescription?: string;
+            };
+        };
+        IfNode: {
+            id: string;
+            /**
+             * @description discriminator enum property added by openapi-typescript
+             * @enum {string}
+             */
+            type: "If";
+            label?: string;
+            position: components["schemas"]["NodePosition"];
+            arguments: {
+                condition: components["schemas"]["Expression"];
+            };
+        };
+        SerialReadNode: {
+            id: string;
+            /**
+             * @description discriminator enum property added by openapi-typescript
+             * @enum {string}
+             */
+            type: "SerialRead";
+            label?: string;
+            position: components["schemas"]["NodePosition"];
+            arguments: {
+                /** @description Reference to an UART ID (the serial port to read from) */
+                portReference?: string;
+                prompt?: string;
+                output: components["schemas"]["OutputBinding"];
+            };
+        };
+        SerialWriteNode: {
+            id: string;
+            /**
+             * @description discriminator enum property added by openapi-typescript
+             * @enum {string}
+             */
+            type: "SerialWrite";
+            label?: string;
+            position: components["schemas"]["NodePosition"];
+            arguments: {
+                /** @description Reference to a UART channel ID (the serial port to write to) */
+                portReference?: string;
+                value: components["schemas"]["Expression"];
+            };
+        };
+        SetVariableNode: {
+            id: string;
+            /**
+             * @description discriminator enum property added by openapi-typescript
+             * @enum {string}
+             */
+            type: "SetVariable";
+            label?: string;
+            position: components["schemas"]["NodePosition"];
+            arguments: {
+                variable?: components["schemas"]["Reference"];
+                value: components["schemas"]["Expression"];
+            };
+        };
+        MqttPublishNode: {
+            id: string;
+            /**
+             * @description discriminator enum property added by openapi-typescript
+             * @enum {string}
+             */
+            type: "MqttPublish";
+            label?: string;
+            position: components["schemas"]["NodePosition"];
+            arguments: {
+                /** @description Reference to an MQTT channel ID (the channel carries the topic; resolved to a broker at deploy time) */
+                channelReference?: string;
+                dataType: components["schemas"]["DataType"];
+                value: components["schemas"]["Expression"];
+                /**
+                 * @description MQTT Quality of Service level
+                 * @enum {integer}
+                 */
+                qos: 0 | 1 | 2;
+                /** @description Whether the broker should retain the message */
+                retain: boolean;
+            };
+        };
+        OnMqttMessageNode: {
+            id: string;
+            /**
+             * @description discriminator enum property added by openapi-typescript
+             * @enum {string}
+             */
+            type: "OnMqttMessage";
+            label?: string;
+            position: components["schemas"]["NodePosition"];
+            arguments: {
+                /** @description Reference to an MQTT channel ID (the channel carries the topic filter; resolved to a broker at deploy time) */
+                channelReference?: string;
+                dataType: components["schemas"]["DataType"];
+                output: components["schemas"]["OutputBinding"];
+            };
+        };
+        Channel: components["schemas"]["GPIOINChannel"] | components["schemas"]["GPIOOUTChannel"] | components["schemas"]["ADCChannel"] | components["schemas"]["PWMChannel"] | components["schemas"]["DACChannel"] | components["schemas"]["UARTChannel"] | components["schemas"]["MQTTChannel"];
+        GPIOINChannel: {
+            /**
+             * @description discriminator enum property added by openapi-typescript
+             * @enum {string}
+             */
+            type: "GPIOIN";
+            id: string;
+            label: string;
+            /**
+             * @description Pin bias configuration
+             * @enum {string}
+             */
+            bias: "none" | "pullup" | "pulldown";
+            /** @description Debounce window in milliseconds */
+            debounceMs: number;
+        };
+        GPIOOUTChannel: {
+            /**
+             * @description discriminator enum property added by openapi-typescript
+             * @enum {string}
+             */
+            type: "GPIOOUT";
+            id: string;
+            label: string;
+        };
+        ADCChannel: {
+            /**
+             * @description discriminator enum property added by openapi-typescript
+             * @enum {string}
+             */
+            type: "ADC";
+            id: string;
+            label: string;
+        };
+        PWMChannel: {
+            /**
+             * @description discriminator enum property added by openapi-typescript
+             * @enum {string}
+             */
+            type: "PWM";
+            id: string;
+            label: string;
+            /** @description PWM frequency in Hz */
+            frequency: number;
+        };
+        DACChannel: {
+            /**
+             * @description discriminator enum property added by openapi-typescript
+             * @enum {string}
+             */
+            type: "DAC";
+            id: string;
+            label: string;
+        };
+        UARTChannel: {
+            /**
+             * @description discriminator enum property added by openapi-typescript
+             * @enum {string}
+             */
+            type: "UART";
+            id: string;
+            label: string;
+        };
+        MQTTChannel: {
+            /**
+             * @description discriminator enum property added by openapi-typescript
+             * @enum {string}
+             */
+            type: "MQTT";
+            id: string;
+            label: string;
+            /** @description Topic this channel publishes to / subscribes on. The engine wraps it with the bound broker's prefix at runtime. */
+            topic: string;
+        };
+    };
+    responses: never;
+    parameters: never;
+    requestBodies: never;
+    headers: never;
+    pathItems: never;
+}
+export type $defs = Record<string, never>;
+export type operations = Record<string, never>;

package/src/channel/Channel.ts

@@ -0,0 +1,11 @@
+export type ChannelType = "GPIOIN" | "GPIOOUT" | "ADC" | "PWM" | "DAC" | "UART" | "MQTT";
+
+export const ALL_CHANNEL_TYPES: ChannelType[] = ["GPIOIN", "GPIOOUT", "ADC", "PWM", "DAC", "UART", "MQTT"];
+
+/** Interface for a channel instance in the workflow */
+export interface Channel {
+  id: string;
+  label: string;
+  type: ChannelType;
+  arguments: Record<string, unknown>;
+}