@uipath/skills 1.201.0-preview.621 → 1.202.0-preview.635

package/skills/uipath-maestro-flow/references/author/references/plugins/switch/planning.md

@@ -1,38 +0,0 @@
-# Switch Node — Planning
-
-## Node Type
-
-`core.logic.switch`
-
-## When to Use
-
-Use a Switch node for multi-way branching (3+ paths) based on ordered case expressions. Cases are evaluated in order; the first `true` case is taken.
-
-### Selection Heuristics
-
-| Situation | Use Switch? |
-| --- | --- |
-| Three or more paths based on different conditions | Yes |
-| Simple true/false branch | No — use [Decision](../decision/planning.md) |
-| Branch on HTTP response status codes | No — use [HTTP](../http/planning.md) built-in branches |
-| Branch requires reasoning on ambiguous input | No — use [Agent](../agent/planning.md) |
-
-## Ports
-
-| Input Port | Output Port(s) |
-| --- | --- |
-| `input` | `case-{id}` (dynamic per case), `default` |
-
-## Key Inputs
-
-| Input | Required | Description |
-| --- | --- | --- |
-| `cases` | Yes | Array of `{ id, label, expression }` (min 1 item) |
-
-Each case creates a dynamic output port: `case-{item.id}`. An optional `default` port handles unmatched cases.
-
-## Wiring Rules
-
-- Switch nodes produce one outgoing edge per case + optionally one from `default`
-- Each case edge uses `sourcePort: "case-{id}"` where `{id}` matches the case's `id` field
-- Every case branch must lead to a downstream node

package/skills/uipath-maestro-flow/references/author/references/plugins/terminate/impl.md

@@ -1,48 +0,0 @@
-# Terminate Node — Implementation
-
-## Node Type
-
-`core.logic.terminate`
-
-## Registry Validation
-
-```bash
-uip maestro flow registry get core.logic.terminate --output json
-```
-
-Confirm: input port `input`, no output ports. Set the node instance `typeVersion` to the `version` field from this response — do not hardcode it.
-
-## JSON Structure
-
-```json
-{
-  "id": "abortOnError",
-  "type": "core.logic.terminate",
-  "typeVersion": "<DEFINITION_VERSION>",
-  "display": { "label": "Abort" },
-  "inputs": {}
-}
-```
-
-## Adding / Editing
-
-For step-by-step add, delete, and wiring procedures, see [editing-operations.md](../../editing-operations.md). Use the JSON structure above for the node-specific `inputs`.
-
-## Common Pattern — Error Handler
-
-```text
-HTTP Request
-  |-- default -> Process -> End
-  |-- error   -> Log Error (Script) -> Terminate
-```
-
-Wire the action node's implicit `error` source port straight to the handler; the Script logs `$vars.httpCall.error`, then Terminate aborts the flow. Do **not** put a Decision downstream to test for an error — a failing node has already faulted the flow before execution reaches it.
-
-Add this pattern only when the requirements state what a failure should do. With no error edge the failure faults the flow on its own, which is the correct default — and never set `inputs.errorHandlingEnabled: true` without the edge. See [file-format.md — Implicit error port on action nodes](../../../../shared/file-format.md#implicit-error-port-on-action-nodes).
-
-## Debug
-
-| Error | Cause | Fix |
-| --- | --- | --- |
-| Terminate has outgoing edges | Wired an edge from Terminate to another node | Remove — Terminate has no output ports |
-| Workflow outputs missing | Expected outputs but hit Terminate | Terminate does not produce outputs — use End for paths that need output mapping |

package/skills/uipath-maestro-flow/references/author/references/plugins/transform/impl.md

@@ -1,287 +0,0 @@
-# Transform Node — Implementation
-
-## Node Types
-
-- `core.action.transform` — generic (chains multiple operations)
-- `core.action.transform.filter` — filter only
-- `core.action.transform.map` — map only
-- `core.action.transform.group-by` — group-by only
-
-## Registry Validation
-
-```bash
-uip maestro flow registry get core.action.transform --output json
-uip maestro flow registry get core.action.transform.filter --output json
-uip maestro flow registry get core.action.transform.map --output json
-uip maestro flow registry get core.action.transform.group-by --output json
-```
-
-Confirm: input port `input`, output ports `output` and `error`, required inputs `collection` and `operations`. Set each node instance's `typeVersion` to the `version` field from the matching response — do not hardcode it.
-
-## Adding / Editing
-
-For step-by-step add, delete, and wiring procedures, see [editing-operations.md](../../editing-operations.md). Use the JSON structures below for the node-specific `inputs` and `model` fields.
-
-## Collection Input Contract
-
-`inputs.collection` is a transform-specific path field, not a general `=js:` value field. Set it to the variable path that contains the array:
-
-```json
-"collection": "$vars.orders.output.items"
-```
-
-**NEVER** wrap transform `collection` in `=js:`. **NEVER** set it to an inline array literal. Both forms below are wrong:
-
-```json
-"collection": "=js:$vars.orders.output.items"
-```
-
-```json
-"collection": "=js:[{\"title\":\"Example\"}]"
-```
-
-The transform runtime turns the path string into a lookup such as `vars.orders.output.items`. If the string starts with `=js:` or contains an inline JSON/JS literal, that lookup resolves to an empty collection.
-
-For static data, store the array in a workflow variable `defaultValue` or emit it from an upstream static-data/script node, then point `collection` at that variable or node output. Filtering, mapping, and grouping still belong in transform nodes.
-
-## Output Shape
-
-`$vars.<transformNode>.output` is a **bare array** — no `.items`, `.body`, `.response`. filter → surviving elements; map → mapped elements; group-by → group objects (`{<groupByField>, <alias>…}`).
-
-Chain transforms off the bare array. `.output.items` on a transform → `undefined` → empty, silently (no fault). `.items`/`.body.items` in the examples below is HTTP-body/variable shape, never a transform's own output.
-
-```json
-"collection": "$vars.filterHighViewDays.output"
-```
-
-Read an element field in a Script node: `$vars.groupByNode.output[0].totalViews`.
-
----
-
-## Generic Transform (`core.action.transform`)
-
-Chains multiple operations (filter -> map -> groupBy) in a single node. Operations execute in order; each feeds into the next.
-
-```json
-{
-  "id": "transformChain",
-  "type": "core.action.transform",
-  "typeVersion": "<DEFINITION_VERSION>",
-  "display": { "label": "Process Employees" },
-  "inputs": {
-    "collection": "$vars.fetchData.output.body.employees",
-    "operations": [
-      {
-        "id": "op1",
-        "type": "filter",
-        "config": {
-          "operation": "and",
-          "filters": [
-            { "id": "f1", "field": "active", "condition": "equals", "value": true }
-          ]
-        }
-      },
-      {
-        "id": "op2",
-        "type": "map",
-        "config": {
-          "keepOriginalFields": false,
-          "mappings": [
-            { "id": "m1", "field": "name", "transformation": "uppercase", "renameTo": "fullName" },
-            { "id": "m2", "field": "salary", "transformation": "copy", "renameTo": "" }
-          ]
-        }
-      }
-    ]
-  },
-  "outputs": {
-    "output": {
-      "type": "object",
-      "description": "The return value of the transform",
-      "source": "=result.response",
-      "var": "output"
-    },
-    "error": {
-      "type": "object",
-      "description": "Error information if the transform fails",
-      "source": "=Error",
-      "var": "error"
-    }
-  }
-}
-```
-
----
-
-## Filter (`core.action.transform.filter`)
-
-```json
-{
-  "id": "filterActive",
-  "type": "core.action.transform.filter",
-  "typeVersion": "<DEFINITION_VERSION>",
-  "display": { "label": "Filter Active Orders" },
-  "inputs": {
-    "collection": "$vars.orders.output.items",
-    "operations": [
-      {
-        "id": "op1",
-        "type": "filter",
-        "config": {
-          "operation": "and",
-          "filters": [
-            { "id": "f1", "field": "status", "condition": "equals", "value": "active" },
-            { "id": "f2", "field": "amount", "condition": "greater_equal", "value": 100 }
-          ]
-        }
-      }
-    ]
-  },
-  "outputs": {
-    "output": {
-      "type": "object",
-      "description": "The return value of the transform",
-      "source": "=result.response",
-      "var": "output"
-    },
-    "error": {
-      "type": "object",
-      "description": "Error information if the transform fails",
-      "source": "=Error",
-      "var": "error"
-    }
-  }
-}
-```
-
-**Filter conditions:** `equals`, `not_equals`, `greater_than`, `less_than`, `greater_equal`, `less_equal`, `contains`, `starts_with`, `ends_with`, `is_null`, `is_not_null`
-
-**Filter operations:** `and` (all conditions must match), `or` (any condition matches)
-
-> **Filter `value` is literal-only — no `$vars`, no `=js:`, no brace-templates.** The Transform runtime reads `value` as-is and does not evaluate expressions. Setting `"value": "$vars.threshold"`, `"value": "=js:$vars.threshold"`, or `"value": "{$vars.threshold}"` silently produces an empty filtered array — the filter is comparing each item's field against the literal string `$vars.threshold` (or `=js:...`), never against the intended number. Only literal scalars work: `"value": 500`, `"value": "active"`, `"value": true`. If you need a dynamic threshold, compute the filter inside a [Script](../script/impl.md) node instead, or hoist the literal into the flow design and keep the Transform filter for demo-time thresholds.
-
-**`field` accepts dot-paths** for nested object fields (e.g., `"field": "order.amount"`). Applies to `collection` elements.
-
----
-
-## Map (`core.action.transform.map`)
-
-```json
-{
-  "id": "mapFields",
-  "type": "core.action.transform.map",
-  "typeVersion": "<DEFINITION_VERSION>",
-  "display": { "label": "Normalize Names" },
-  "inputs": {
-    "collection": "$vars.rawData.output.items",
-    "operations": [
-      {
-        "id": "op1",
-        "type": "map",
-        "config": {
-          "keepOriginalFields": false,
-          "mappings": [
-            { "id": "m1", "field": "firstName", "transformation": "uppercase", "renameTo": "name" },
-            { "id": "m2", "field": "email", "transformation": "lowercase", "renameTo": "" },
-            { "id": "m3", "field": "dept", "transformation": "copy", "renameTo": "department" }
-          ]
-        }
-      }
-    ]
-  },
-  "outputs": {
-    "output": {
-      "type": "object",
-      "description": "The return value of the transform",
-      "source": "=result.response",
-      "var": "output"
-    },
-    "error": {
-      "type": "object",
-      "description": "Error information if the transform fails",
-      "source": "=Error",
-      "var": "error"
-    }
-  }
-}
-```
-
-**Transformations:** `copy` (no change), `uppercase`, `lowercase`, `trim` (remove leading/trailing whitespace).
-
-**`keepOriginalFields`:** When `false`, only mapped fields appear in output. When `true`, unmapped fields pass through.
-
-**`renameTo`:** New field name. Empty string (`""`) keeps the original name.
-
----
-
-## Group By (`core.action.transform.group-by`)
-
-```json
-{
-  "id": "groupByDept",
-  "type": "core.action.transform.group-by",
-  "typeVersion": "<DEFINITION_VERSION>",
-  "display": { "label": "Group by Department" },
-  "inputs": {
-    "collection": "$vars.employees.output.items",
-    "operations": [
-      {
-        "id": "op1",
-        "type": "groupBy",
-        "config": {
-          "groupByField": "department",
-          "aggregations": [
-            { "id": "a1", "field": "", "operation": "count", "alias": "headcount" },
-            { "id": "a2", "field": "salary", "operation": "sum", "alias": "totalSalary" },
-            { "id": "a3", "field": "salary", "operation": "average", "alias": "avgSalary" },
-            { "id": "a4", "field": "salary", "operation": "min", "alias": "minSalary" },
-            { "id": "a5", "field": "salary", "operation": "max", "alias": "maxSalary" },
-            { "id": "a6", "field": "name", "operation": "collect", "alias": "names" },
-            { "id": "a7", "field": "name", "operation": "first", "alias": "firstHire" }
-          ]
-        }
-      }
-    ]
-  },
-  "outputs": {
-    "output": {
-      "type": "object",
-      "description": "The return value of the transform",
-      "source": "=result.response",
-      "var": "output"
-    },
-    "error": {
-      "type": "object",
-      "description": "Error information if the transform fails",
-      "source": "=Error",
-      "var": "error"
-    }
-  }
-}
-```
-
-**Aggregation operations:**
-
-| Operation | Description | `field` required |
-| --- | --- | --- |
-| `count` | Number of items in group | No |
-| `sum` | Sum of numeric field | Yes |
-| `average` | Average of numeric field | Yes |
-| `min` | Minimum value | Yes |
-| `max` | Maximum value | Yes |
-| `collect` | Array of all field values | Yes |
-| `first` | First item's field value | Yes |
-| `last` | Last item's field value | Yes |
-
----
-
-## Debug
-
-| Error | Cause | Fix |
-| --- | --- | --- |
-| Filter passes all items through | Wrong condition name (e.g. `greater` instead of `greater_than`) | Use exact names: `equals`, `not_equals`, `greater_than`, `less_than`, `greater_equal`, `less_equal`, `contains`, `starts_with`, `ends_with`, `is_null`, `is_not_null` |
-| Filter silently returns empty array | Filter `value` holds an unresolved expression (`"$vars.x"`, `"=js:..."`, `"{$vars.x}"`) — Transform compares each item against that string literal | Replace with a literal scalar (`"value": 500`); expressions are not evaluated in filter `value`. If the threshold must be dynamic, do the filter in a Script node |
-| Collection is null/empty | `collection` was wrapped in `=js:` or set to an inline array literal instead of a plain variable path | Use a path such as `"$vars.loadCatalog.output.catalog"` or `"$vars.catalog"`; keep static arrays in a variable default or upstream node |
-| Map output missing fields | `keepOriginalFields: false` and field not in mappings | Add the field to mappings or set `keepOriginalFields: true` |
-| GroupBy produces empty groups | No items match the group field | Check `groupByField` matches actual field names in the data |
-| Chained transform gets empty input, upstream had rows | `collection` used `$vars.<transform>.output.items`; transform output is a bare array (`.items` → `undefined`) | Use `$vars.<transform>.output` — see [Output Shape](#output-shape) |

package/skills/uipath-maestro-flow/references/evaluate/references/eval-sets-guide.md

@@ -1,226 +0,0 @@
-# Eval Sets and Data Points
-
-An eval set is a JSON file that bundles test cases (data points) with the evaluators that score them. Each Flow project can have multiple eval sets — typically one per scenario (smoke, regression, edge cases).
-
-## Eval Set Lifecycle
-
-```bash
-# Create
-uip maestro flow eval set add "<set_name>" \
-  [--evaluators <ref1>,<ref2>] \
-  [--entry-point <node_id>] \
-  --path <flow_project> --output json
-
-# List
-uip maestro flow eval set list --path <flow_project> --output json
-
-# Remove
-uip maestro flow eval set remove "<id_or_name>" --path <flow_project> --output json
-```
-
-### `--evaluators`
-
-Comma-separated list of evaluator IDs or generated file base names. When omitted, the new eval set links to **all evaluators** present in the project at creation time and writes the generated evaluator file refs (for example, `greeting-match-62c0793a.json`). Prefer omission when the eval set should use every current evaluator.
-
-Do **not** pass an evaluator display name such as `greeting-match` to `--evaluators`; that writes the display name into `evaluatorRefs`, and Studio Web eval runs will not resolve it. If you need an explicit list, get the generated id/file ref from `uip maestro flow eval evaluator add/list --output json` and pass that value instead.
-
-Subsequent evaluators added to the project do NOT auto-attach — link them by re-running `set add` with explicit generated refs, or carefully repair the eval set's `evaluatorRefs` array using the evaluator file refs the CLI created.
-
-### `--entry-point`
-
-Stored as `selectedEntrypoint` on the eval set. Accepts either:
-
-- A flow path: `/Main.bpmn#start`
-- A start node ID: `start_a1b2c3d4`
-
-The eval set's entry point is used by `eval run start` unless `--entry-point` is overridden at run time. Pin one explicitly when the flow has multiple entry points; otherwise the first start node found is used and may not be the one you intend.
-
-## Data Point Lifecycle
-
-Data points (test cases) live **inline** inside the eval set JSON, not as separate files. CRUD via `uip maestro flow eval add/list/remove`:
-
-```bash
-# Add a data point
-uip maestro flow eval add "<data_point_name>" \
-  --set "<set_name>" \
-  --inputs '{"...":"..."}' \
-  [--expected '{"...":"..."}'] \
-  [--criteria '{"<evaluator_id>": {...}}'] \
-  [--input-file <key>=<path>] \
-  [--search-text "<text>"] \
-  --path <flow_project> --output json
-
-# List
-uip maestro flow eval list --set "<set_name>" --path <flow_project> --output json
-
-# Remove
-uip maestro flow eval remove "<id_or_name>" --set "<set_name>" --path <flow_project> --output json
-```
-
-### `--inputs`
-
-JSON object whose keys must match the flow's declared input variables for the chosen entry point. `eval add` validates these keys and fails fast when an input key is not declared in the `.flow` file. Add missing variables first, or change the data point input JSON to match the Flow schema.
-
-For a simple string input named `name`:
-
-```bash
-uip maestro flow variable add ./MySolution/MyFlow/MyFlow.flow name \
-  --direction in --type string --output json
-```
-
-### `--expected`
-
-JSON object representing the expected output. How it is consumed depends on the evaluator type:
-
-| Evaluator type | Reads `--expected` how |
-|----------------|-----------------------|
-| `exact-match` | Compares the output against `expected` verbatim (or `expected[targetKey]` if `--target-key` is set on the evaluator) |
-| `json-similarity` | Tree-compared with tolerance |
-| `contains` | Not used directly — see `--search-text` |
-| `llm-judge-output` | Substituted into `{{ExpectedOutput}}` |
-| `llm-judge-strict-json` | Substituted per-key into `{{ExpectedOutput}}` |
-| `llm-judge-trajectory` | Used along with `--expected-agent-behavior` (set via `--criteria`) |
-| `llm-judge-trajectory-simulation` | Same as `trajectory` plus simulation context |
-
-### `--criteria`
-
-Per-evaluator overrides keyed by evaluator ID. Use this when one eval set contains multiple evaluators and you want each to score against different criteria for the same data point. Most common shape:
-
-```json
-{
-  "<evaluator_ref_for_trajectory>": {
-    "expectedAgentBehavior": "Agent calls the weather tool with the user's location, then returns a one-sentence summary."
-  },
-  "<evaluator_ref_for_output>": {
-    "expectedOutput": {"summary": "Sunny in NYC, 72°F"}
-  }
-}
-```
-
-If `--criteria` is omitted, evaluators fall back to `--expected` (for output evaluators) and to defaults (for trajectory evaluators). Always pass an explicit `expectedAgentBehavior` for trajectory evaluators — the LLM's score against an empty `{{ExpectedAgentBehavior}}` is meaningless.
-
-### `--input-file <key>=<path>`
-
-Repeatable. Attach a file as input under the given key. The CLI stages the file alongside the eval set so the runtime can read it during evaluation. Useful when the flow accepts file inputs (PDFs, CSVs, images) rather than JSON only.
-
-```bash
-uip maestro flow eval add invoice-test \
-  --set "Smoke Tests" \
-  --inputs '{"orderId":"ORD-123"}' \
-  --input-file invoice=./fixtures/invoice-123.pdf \
-  --input-file receipt=./fixtures/receipt-123.png \
-  --expected '{"total": 142.50}' \
-  --path ./MySolution/MyFlow --output json
-```
-
-The file content is referenced from the eval set; do not delete the source file before the run completes.
-
-### `--search-text`
-
-Convenience flag for `contains` evaluators only. Attaches the search string to the data point so the contains evaluator knows what substring to test for. Equivalent to writing `criteria` for the contains evaluator.
-
-```bash
-uip maestro flow eval add success-keyword \
-  --set "Smoke Tests" \
-  --inputs '{"task":"deploy"}' \
-  --search-text "deployment succeeded" \
-  --path ./MySolution/MyFlow --output json
-```
-
-## Eval Set JSON Shape
-
-A typical eval set JSON file (created by `set add`):
-
-```json
-{
-  "id": "<uuid>",
-  "name": "Smoke Tests",
-  "version": "1.0",
-  "evaluatorRefs": ["<evaluator-file-ref-1>.json", "<evaluator-file-ref-2>.json"],
-  "selectedEntrypoint": "/Main.bpmn#start",
-  "evaluations": [
-    {
-      "id": "<uuid>",
-      "name": "hello-test",
-      "inputs": {"message": "hello"},
-      "expectedOutput": {"reply": "Hello! How can I help you?"},
-      "evaluationCriterias": {
-        "<evaluator-ref-2>": {
-          "expectedAgentBehavior": "Agent responds with a friendly greeting."
-        }
-      }
-    }
-  ]
-}
-```
-
-Key fields:
-
-- `version: "1.0"` distinguishes the new eval format from any legacy variants. Keep this. <!-- version-check-skip --> (eval-set file schema version, CLI-emitted by `eval set add` — not a `.flow` version)
-- `evaluatorRefs` references evaluator files generated by the CLI. Prefer CLI commands over hand-editing these refs.
-- `selectedEntrypoint` is the eval set's pinned entry point. Override per-run with `eval run start --entry-point`.
-- `evaluations[]` is the inline list of data points. Order is informational, not significant.
-- `evaluationCriterias` (note plural) is the per-data-point per-evaluator override map.
-
-## Aligning Inputs with the Flow Schema
-
-The data point's `inputs` JSON must match the flow's input schema at the chosen entry point. Mismatches produce `eval add` errors such as `Input "name" is not declared as an input variable in the flow`. Two ways to verify before adding data points:
-
-1. Inspect `<flow>.flow` in the project for `variables` entries with `direction: "in"`.
-2. Run `uip maestro flow variable list <flow_file> --output json`.
-
-## Simulations on Data Points
-
-Simulations replace selected nodes during an eval run with controlled outputs, so the flow is evaluated without calling real external services. Each simulation targets one component by its node `id` from the `.flow` file.
-
-```bash
-# Add an LLM simulation (non-deterministic, prompt-guided)
-uip maestro flow eval simulation add <component-id> \
-  --set "<set_name>" \
-  --data-point "<data_point_name>" \
-  --strategy Llm \
-  --component-type connector \
-  --simulation-instructions "Pretend to send the email and return success." \
-  --output-schema '{"type":"object","properties":{"status":{"type":"string"},"messageId":{"type":"string"}}}' \
-  --path <flow_project> --output json
-
-# Add a Static simulation (fixed JSON output)
-uip maestro flow eval simulation add <component-id> \
-  --set "<set_name>" \
-  --data-point "<data_point_name>" \
-  --strategy Static \
-  --component-type agent \
-  --mock-value '{"status":"ok"}' \
-  --path <flow_project> --output json
-
-# List simulations on a data point
-uip maestro flow eval simulation list \
-  --set "<set_name>" \
-  --data-point "<data_point_name>" \
-  --path <flow_project> --output json
-
-# Remove a simulation
-uip maestro flow eval simulation remove <component-id> \
-  --set "<set_name>" \
-  --data-point "<data_point_name>" \
-  --path <flow_project> --output json
-```
-
-**Strategy selection:**
-
-| Strategy | Use when | Key flags |
-|----------|----------|-----------|
-| `Llm` | Output should be plausible but non-deterministic | `--simulation-instructions`, `--output-schema` (auto-resolved) |
-| `Static` | Output must be identical every run | `--mock-value <json>` |
-
-For `Llm` simulations, `--output-schema` is **auto-resolved from the `.flow` file** — the CLI reads the node's output definition (connector `outputJsonSchema`, agent `agentOutputVariables`, or `node.outputs`) and injects it automatically. Pass `--output-schema` explicitly only when you need to override the derived schema or the node has no declared outputs.
-
-Simulations are stored inline in the data point's `simulations` array within the eval set JSON. Running `simulation add` twice for the same `<component-id>` on the same data point replaces the existing simulation.
-
-## Anti-patterns
-
-- **Don't hand-write `id` UUIDs on data points.** Use `uip maestro flow eval add` so the CLI generates fresh UUIDs and keeps `evalSetId` consistent with the parent set.
-- **Don't pass `--inputs` keys that aren't in the flow's input schema.** The CLI rejects unknown keys before writing the data point.
-- **Don't set `--expected '{}'` and skip `--criteria` for trajectory evaluators.** Both placeholders end up empty; scoring is meaningless.
-- **Don't delete attached input files before the run completes.** The CLI references them by path until upload to Studio Web finishes.
-- **Don't expect `--evaluators` on `set add` to auto-update.** Adding new evaluators later does not retroactively link them to existing eval sets.