ultravisor 1.0.3 → 1.0.8

package/docs/features/tasks-file-system.md

@@ -0,0 +1,203 @@
+# File System Tasks
+
+Tasks for reading, writing, copying, and listing files on the local file system.
+
+---
+
+## Read File
+
+Reads a file from the local file system into operation state.
+
+### Settings
+
+- **FilePath** — Path to the file to read. Supports Pict template expressions for dynamic paths.
+- **Encoding** — Character encoding (default `utf8`). Use `binary` for non-text files.
+- **MaxBytes** — Maximum bytes to read. Set to `0` for unlimited.
+
+### Outputs
+
+- **FileContent** — The full text content of the file.
+- **BytesRead** — Number of bytes that were read.
+- **FileName** — The base name of the file (no directory).
+
+### Events
+
+- **ReadComplete** — Fires after a successful read.
+- **Error** — Fires if the file cannot be found or read.
+
+### Tips
+
+For very large files, use **Read File Buffered** instead to process content in chunks. Use MaxBytes as a safety limit to avoid loading unexpectedly large files into memory.
+
+---
+
+## Read File Buffered
+
+Reads a file in chunks up to a maximum buffer size, splitting on a preferred character boundary. Ideal for processing large files that should not be loaded entirely into memory.
+
+### Settings
+
+- **FilePath** — Path to the file to read.
+- **Encoding** — Character encoding (default `utf8`).
+- **MaxBufferSize** — Maximum bytes per chunk (default `65536`).
+- **SplitCharacter** — Preferred character to split on (default newline). The chunk is trimmed to the last occurrence of this character within the buffer so records are not broken mid-line.
+- **ByteOffset** — Byte offset to start reading from. Use `0` for the first chunk and feed the output ByteOffset back for continuation.
+
+### Outputs
+
+- **FileContent** — Content of the current chunk.
+- **BytesRead** — Bytes in this chunk.
+- **ByteOffset** — Updated byte offset for the next read.
+- **IsComplete** — `true` when the entire file has been read.
+- **FileName** — Base name of the file.
+- **TotalFileSize** — Total size of the file in bytes.
+
+### Events
+
+- **ReadComplete** — Fires when a chunk is read successfully.
+- **Error** — Fires on read failure.
+
+### Tips
+
+Wire the ByteOffset output back to the ByteOffset setting input and use an **If Conditional** on IsComplete to create a read loop. This pattern lets you process files of any size line-by-line or paragraph-by-paragraph.
+
+---
+
+## Read JSON
+
+Reads a JSON file from disk, parses it, and stores the resulting object in operation state.
+
+### Settings
+
+- **FilePath** — Path to the JSON file.
+- **Destination** — State address to store the parsed data. If empty, data is stored at the default output address.
+
+### Outputs
+
+- **Data** — The parsed JSON object or array.
+
+### Events
+
+- **Complete** — Fires after successful read and parse.
+- **Error** — Fires if the file is missing or contains invalid JSON.
+
+### Tips
+
+Pair with **Write JSON** to round-trip configuration or intermediate data. Use the Destination setting to place the parsed data at a specific location in your operation state for downstream tasks.
+
+---
+
+## Write File
+
+Writes text content to a file on disk.
+
+### Settings
+
+- **FilePath** — Path to the output file. Intermediate directories are created automatically.
+- **Content** — The text content to write. Supports Pict template expressions.
+- **Encoding** — Character encoding (default `utf8`).
+- **Append** — When `true`, appends to an existing file instead of overwriting it.
+- **LineEnding** — Force a line ending style: `lf`, `crlf`, or leave empty for no conversion.
+
+### Outputs
+
+- **FileLocation** — The path as specified (may be relative).
+- **FileName** — The base file name only.
+- **FilePath** — The fully resolved absolute path.
+- **BytesWritten** — Number of bytes written.
+
+### Events
+
+- **WriteComplete** — Fires on success.
+- **Error** — Fires on write failure.
+
+### Tips
+
+Use Append mode with a **String Appender** to build log files or accumulate output across loop iterations.
+
+---
+
+## Write JSON
+
+Serializes a state object to JSON and writes it to a file on disk.
+
+### Settings
+
+- **FilePath** — Path to the output JSON file.
+- **DataAddress** — State address of the data to serialize. If empty, uses the full operation state.
+- **PrettyFormat** — Pretty-print with indentation (default `true`).
+- **IndentType** — Indent character: `tab` or `space` (default `tab`).
+- **IndentCount** — Number of indent characters per level (default `1`).
+- **SortKeys** — Alphabetically sort object keys for deterministic output.
+
+### Outputs
+
+- **FileLocation** — The path as specified.
+- **FileName** — The base file name only.
+- **FilePath** — The fully resolved absolute path.
+- **BytesWritten** — Number of bytes written.
+
+### Events
+
+- **Done** — Fires on success.
+- **Error** — Fires on write failure.
+
+### Tips
+
+Enable SortKeys for config files that will be compared across versions or stored in version control.
+
+---
+
+## Copy File
+
+Copies a file from a source path to a target path.
+
+### Settings
+
+- **Source** — Source file path.
+- **TargetFile** — Destination file path.
+- **Overwrite** — Allow overwriting an existing target file (default `true`).
+
+### Outputs
+
+- **FileLocation** — The target path as specified.
+- **FileName** — The target file name only.
+- **FilePath** — The fully resolved absolute target path.
+- **BytesCopied** — Size of the copied file in bytes.
+
+### Events
+
+- **Done** — Fires on successful copy.
+- **Error** — Fires if the source is missing or the target cannot be written.
+
+### Tips
+
+Set Overwrite to `false` to protect existing files from accidental replacement. Both Source and TargetFile support Pict template expressions for dynamic paths.
+
+---
+
+## List Files
+
+Lists files in a directory with optional glob pattern filtering.
+
+### Settings
+
+- **Folder** — Directory path to list.
+- **Pattern** — Glob pattern filter (e.g. `*.txt`, `*.json`). Default `*` matches all files.
+- **Destination** — State address to store the resulting file list.
+- **Recursive** — When `true`, includes files in subdirectories.
+- **IncludeDirectories** — When `true`, includes directory entries in the results.
+
+### Outputs
+
+- **Files** — Array of file name strings matching the pattern.
+- **FileCount** — Number of entries found.
+
+### Events
+
+- **Complete** — Fires after listing is complete.
+- **Error** — Fires if the directory cannot be read.
+
+### Tips
+
+Use with **Split Execute** to iterate over the file list and process each file individually. Combine Recursive mode with a specific Pattern to find files deep in a directory tree.

package/docs/features/tasks-flow-control.md

@@ -0,0 +1,125 @@
+# Flow Control Tasks
+
+Tasks for branching, looping, launching sub-operations, and executing shell commands to control the flow of execution.
+
+---
+
+## If Conditional
+
+Evaluates a condition and branches execution to the True or False output. This is the primary decision-making card in a flow.
+
+### Settings
+
+- **DataAddress** — State address of the value to test.
+- **CompareValue** — Value to compare against.
+- **Operator** — Comparison operator: `==`, `!=`, `>`, `<`, `>=`, `<=`, `contains`, `startsWith`, `endsWith`. Default `==`.
+- **Expression** — A full expression string. When set, DataAddress/CompareValue/Operator are ignored and the expression is evaluated directly.
+
+### Outputs
+
+- **Result** — Boolean result of the evaluation.
+
+### Events
+
+- **True** — Fires when the condition is true.
+- **False** — Fires when the condition is false.
+
+### Tips
+
+Use Expression for complex conditions that combine multiple state values. For simple equality checks, DataAddress + CompareValue + Operator is more readable. The False output is positioned at the bottom of the card for visual clarity in flow diagrams.
+
+---
+
+## Split Execute
+
+Splits a string by a delimiter and processes each token through a sub-graph, acting as a loop iterator within the flow.
+
+### Settings
+
+- **InputString** — The string to split. Supports Pict template expressions.
+- **SplitDelimiter** — Delimiter to split on (default newline `\n`).
+- **SkipEmpty** — When `true`, skips empty tokens after splitting.
+- **TrimTokens** — When `true`, trims whitespace from each token.
+
+### Outputs
+
+- **CurrentToken** — The current token being processed.
+- **TokenIndex** — Zero-based index of the current token.
+- **TokenCount** — Total number of tokens.
+- **CompletedCount** — Number of tokens processed so far.
+
+### Events
+
+- **TokenDataSent** — Fires for each token, sending it through the sub-graph.
+- **CompletedAllSubtasks** — Fires after all tokens have been processed.
+- **Error** — Fires on failure.
+
+### How It Works
+
+1. The input string is split into tokens by the delimiter.
+2. For each token, **TokenDataSent** fires with the token data in state.
+3. Connect the downstream processing graph to TokenDataSent.
+4. Wire the end of your processing graph back to the **StepComplete** event input to advance to the next token.
+5. After all tokens are processed, **CompletedAllSubtasks** fires.
+
+### Tips
+
+Split Execute is the primary looping mechanism in Ultravisor flows. Use it with **List Files** output to process each file, or with newline-delimited text to process line-by-line.
+
+---
+
+## Launch Operation
+
+Executes a child operation by its hash, with isolated operation state. This enables modular flow composition by calling one operation from within another.
+
+### Settings
+
+- **OperationHash** — The hash identifier of the operation to launch.
+- **InputData** — JSON data to pass as input to the child operation.
+- **TimeoutMs** — Maximum execution time in milliseconds. Set to `0` for unlimited.
+- **InheritGlobalState** — When `true` (default), copies the parent's GlobalState into the child operation.
+
+### Outputs
+
+- **Result** — The result data returned by the child operation.
+- **Status** — Final status of the child operation.
+- **ElapsedMs** — Execution time of the child operation in milliseconds.
+
+### Events
+
+- **Completed** — Fires when the child operation finishes.
+- **Error** — Fires if the child operation fails or times out.
+
+### Tips
+
+Use Launch Operation to break complex workflows into reusable sub-operations. The child operation runs with its own isolated state, so it cannot accidentally modify the parent's local state. Use InheritGlobalState to share configuration and credentials.
+
+---
+
+## Command
+
+Executes a shell command on the server and captures its output.
+
+### Settings
+
+- **Command** — The shell command to execute (e.g. `ls`, `git`, `python3`).
+- **Parameters** — Command-line arguments as a single string.
+- **Description** — Human-readable description of what this command does (for documentation only).
+- **WorkingDirectory** — Working directory for the command.
+- **TimeoutMs** — Command timeout in milliseconds (default `300000` — 5 minutes).
+- **Environment** — JSON object of environment variables to set for the command.
+
+### Outputs
+
+- **StdOut** — Standard output from the command.
+- **StdErr** — Standard error output from the command.
+- **ExitCode** — Exit code (0 typically indicates success).
+
+### Events
+
+- **Complete** — Fires when the command finishes.
+- **Error** — Fires if the command fails to start or times out.
+
+### Tips
+
+Use an **If Conditional** on ExitCode to handle success vs failure. Both Command and Parameters support Pict template expressions, so you can build dynamic commands from state values. Set Environment to inject secrets or configuration without hardcoding them.

package/docs/features/tasks-http-client.md

@@ -0,0 +1,119 @@
+# HTTP Client Tasks
+
+Tasks for making HTTP requests to external APIs and web services, from simple GET operations to fully configurable REST calls.
+
+---
+
+## Get JSON
+
+Performs an HTTP GET request and parses the response body as JSON.
+
+### Settings
+
+- **URL** — The URL to request. Supports Pict template expressions for dynamic URLs.
+- **Headers** — JSON string of additional request headers (e.g. `{"Authorization": "Bearer ..."}`).
+- **Destination** — State address to store the parsed response data.
+- **TimeoutMs** — Request timeout in milliseconds (default `30000`).
+
+### Outputs
+
+- **Data** — The parsed JSON response object.
+- **StatusCode** — HTTP response status code.
+
+### Events
+
+- **Complete** — Fires on a successful response.
+- **Error** — Fires on network failure, timeout, or non-2xx status.
+
+### Tips
+
+For APIs requiring authentication, use **Set Values** to build the Headers JSON from stored credentials before connecting to the Headers setting input. Use the StatusCode output with an **If Conditional** to handle different HTTP response codes.
+
+---
+
+## Get Text
+
+Performs an HTTP GET request and returns the response body as plain text.
+
+### Settings
+
+- **URL** — The URL to request.
+- **Destination** — State address to store the response text.
+- **Headers** — JSON string of additional request headers.
+- **TimeoutMs** — Request timeout in milliseconds (default `30000`).
+
+### Outputs
+
+- **Data** — The response body as a string.
+- **StatusCode** — HTTP response status code.
+
+### Events
+
+- **Complete** — Fires on a successful response.
+- **Error** — Fires on network failure or timeout.
+
+### Tips
+
+Use Get Text for non-JSON responses: HTML pages, CSV downloads, plain text APIs, or XML feeds. Pipe the output into **Parse CSV** for CSV data or **Replace String** for text processing.
+
+---
+
+## Send JSON
+
+Sends JSON data to a URL via HTTP POST or PUT.
+
+### Settings
+
+- **URL** — The URL to send data to.
+- **Method** — HTTP method: `POST` or `PUT` (default `POST`).
+- **DataAddress** — State address of the object to send as the request body.
+- **Headers** — JSON string of additional request headers.
+- **Destination** — State address to store the response data.
+- **TimeoutMs** — Request timeout in milliseconds (default `30000`).
+
+### Outputs
+
+- **Response** — The parsed response data.
+- **StatusCode** — HTTP response status code.
+
+### Events
+
+- **Complete** — Fires on success.
+- **Error** — Fires on failure.
+
+### Tips
+
+Use Send JSON for creating or updating resources via REST APIs. For more control over the request (custom Content-Type, DELETE method, retries), use **REST Request** instead.
+
+---
+
+## REST Request
+
+Performs a fully configurable HTTP request with support for any method, custom content types, request bodies, retries, and timeout control.
+
+### Settings
+
+- **URL** — The URL to request.
+- **Method** — HTTP method: `GET`, `POST`, `PUT`, `DELETE`, `PATCH`, etc. (default `GET`).
+- **ContentType** — Content-Type header value (default `application/json`).
+- **Headers** — JSON string of additional request headers.
+- **Body** — Request body as a JSON string or raw text.
+- **Destination** — State address to store the response.
+- **Retries** — Number of retries on failure (default `0`).
+- **TimeoutMs** — Request timeout in milliseconds (default `30000`).
+- **RetryDelayMs** — Delay between retry attempts in milliseconds (default `1000`).
+
+### Outputs
+
+- **Response** — The response data.
+- **StatusCode** — HTTP response status code.
+- **ResponseHeaders** — JSON string of response headers.
+
+### Events
+
+- **Complete** — Fires on success.
+- **Error** — Fires on failure after all retries are exhausted.
+
+### Tips
+
+REST Request is the most flexible HTTP card. Use it for DELETE operations, form-encoded POST bodies, XML APIs, or any case where Get JSON / Send JSON are too restrictive. The Retries setting with RetryDelayMs provides built-in resilience for flaky endpoints.

package/docs/features/tasks-llm.md

@@ -0,0 +1,118 @@
+# LLM Tasks
+
+Tasks for integrating with large language models, including chat completions, embeddings, and tool use. These tasks dispatch work to Beacon workers with LLM capability.
+
+---
+
+## LLM Chat Completion
+
+Sends messages to a large language model and returns the completion. Supports multi-turn conversation history with persistence across operation runs.
+
+### Settings
+
+- **SystemPrompt** — System prompt text that sets the LLM's behavior and context.
+- **UserPrompt** — User prompt text for the current turn.
+- **Messages** — JSON array of message objects `[{role, content}]` for direct control over the conversation. Overrides SystemPrompt/UserPrompt when set.
+- **Model** — Override the default model name.
+- **Temperature** — Sampling temperature (0–2). Lower values are more deterministic.
+- **MaxTokens** — Maximum tokens to generate (default `4096`).
+- **TopP** — Nucleus sampling parameter.
+- **StopSequences** — JSON array of sequences that stop generation.
+- **ResponseFormat** — Set to `json_object` to force JSON output.
+- **InputAddress** — State address to read additional context data from (appended to UserPrompt).
+- **Destination** — State address to write the completion text to.
+
+### Conversation History
+
+- **ConversationAddress** — State address to store message history for multi-turn conversations.
+- **AppendToConversation** — Append this exchange to history (default `true` when ConversationAddress is set).
+- **ConversationMaxMessages** — Sliding window: maximum non-system messages to keep.
+- **ConversationMaxTokens** — Token budget for history (approximate, trims oldest messages).
+- **PersistConversation** — Copy conversation history to GlobalState for cross-operation persistence.
+- **ConversationPersistAddress** — GlobalState address for persistence.
+
+### Dispatch
+
+- **AffinityKey** — Route to a specific Beacon worker for consistent model access.
+- **TimeoutMs** — Timeout in milliseconds (default `120000`).
+
+### Outputs
+
+- **Content** — The LLM's response text.
+- **Model** — Model that generated the response.
+- **PromptTokens** / **CompletionTokens** / **TotalTokens** — Token usage statistics.
+- **FinishReason** — Why the completion ended (`stop`, `length`, etc.).
+- **BeaconID** — ID of the Beacon worker that executed the request.
+
+### Tips
+
+Use ConversationAddress with PersistConversation to build chatbots that maintain context across multiple operation runs. Set ResponseFormat to `json_object` when you need structured output that downstream cards can parse. Use Temperature `0` for deterministic, reproducible results.
+
+---
+
+## LLM Embedding
+
+Generates vector embeddings for text input using an LLM provider. Dispatches the work to a Beacon with LLM capability.
+
+### Settings
+
+- **Text** — The text to embed. Supports Pict template expressions.
+- **Model** — Override the default embedding model.
+- **Dimensions** — Requested embedding dimensions (model-dependent).
+- **InputAddress** — State address to read text from (alternative to Text setting).
+- **Destination** — State address to write the embedding vector to.
+- **AffinityKey** — Route to a specific Beacon worker.
+- **TimeoutMs** — Timeout in milliseconds (default `60000`).
+
+### Outputs
+
+- **Embedding** — JSON array of floating-point numbers representing the embedding vector.
+- **Dimensions** — Number of dimensions in the embedding.
+- **Model** — Model used for embedding.
+- **BeaconID** — ID of the Beacon that executed the work.
+
+### Tips
+
+Use embeddings for semantic search, clustering, or similarity comparisons. Store embeddings in a database via **Meadow Create** for later retrieval. Combine with **Expression Solver** or downstream processing to compute cosine similarity between vectors.
+
+---
+
+## LLM Tool Use
+
+Sends messages to a large language model with tool (function) definitions, enabling the LLM to request tool calls that your flow can execute.
+
+### Settings
+
+- **SystemPrompt** — System prompt text.
+- **UserPrompt** — User prompt text.
+- **Messages** — JSON array of messages for direct conversation control.
+- **Tools** — JSON array of tool definitions describing available functions the LLM can call.
+- **Model** — Override model name.
+- **ToolChoice** — `auto` (LLM decides), `none` (no tools), or a specific tool name (default `auto`).
+- **Temperature** — Sampling temperature.
+- **MaxTokens** — Maximum tokens to generate.
+- **ConversationAddress** — State address for multi-turn history.
+- **AppendToConversation** — Append this exchange to history.
+- **InputAddress** — State address to read context data from.
+- **Destination** — State address to write completion content.
+- **AffinityKey** — Route to a specific Beacon worker.
+- **TimeoutMs** — Timeout in milliseconds (default `120000`).
+
+### Outputs
+
+- **Content** — The LLM's text response (may be empty if tool calls were made).
+- **ToolCalls** — JSON array of tool call objects with function names and arguments.
+- **Model** — Model that generated the response.
+- **FinishReason** — `stop` for normal completion, `tool_calls` when tools were invoked.
+- **PromptTokens** / **CompletionTokens** — Token usage.
+- **BeaconID** — Beacon worker ID.
+
+### Events
+
+- **Complete** — Fires when the LLM responds.
+- **ToolCall** — Fires when the LLM requests a tool call.
+- **Error** — Fires on failure.
+
+### Tips
+
+Use the ToolCall event to route tool invocations to the appropriate processing cards, then feed results back for another LLM turn. This enables agent-style workflows where the LLM can gather information and take actions through your defined tools.