Custom transforms
Define transform parameters, bindings, runtime behavior and source lineage.
A transform capability processes named pipeline inputs and returns declared outputs. Start with a small operation and specify exactly how it changes rows and evidence.
Define the capability
Declare kind: transform, a stable capability key, runtimeEntrypoint, deterministic, top-level lineage.mode, and the transform_params, transform_inputs and transform_outputs contracts. Use named bindings that agree with the runtime input handles and returned outputs.
The runtime exports a plugin declaration and executable tool capability. Its execute(params, context) receives parameters and runtime data handles. Use the supported runtime data interfaces for those handles; a hand-written array callback is not sufficient when the execution path expects file-backed inputs.
Choose lineage
| Mode | Use |
|---|---|
row_preserving | Exactly one output row per input row, in the same order |
explicit | Filtering, deduplication, joins, unions, aggregation, pivoting or other row shaping |
dropped | The implementation deliberately cannot preserve source-row lineage |
Lineage is evidence about contribution. Do not assign row-preserving mode to a transform that changes row membership, or fabricate source IDs when combining records.
Specify an AI transform
Explain the requested AI behavior, accepted output schema, allowed changes, review fields and ambiguous cases. Set deterministic: false for a capability whose results depend on model reasoning. Keep that behavior in the actual execution path; a deterministic heuristic is not a substitute for the requested AI operation.
For example, a custom classification capability should declare labels, input fields and confidence/rationale outputs, then test valid labels, uncertain cases and malformed model responses. See the classification reference for the internal capability’s contract.
Test and install
Generate the package through custom creation. Review the implementation and validation commands, publish, install and bind it to a transform node.
Test a small input, empty input, missing fields and any row-shaping cases. Compare values, row count, output bindings and evidence. Validate the saved pipeline before execution and inspect its actual output afterward.
FAQ
Can I copy the internal transform’s parameters?
Use them as a design reference only when the runtime implements the same semantics. A declared parameter schema must match your own code.
Is a test that only checks compilation enough?
No. Compilation checks package structure; behavior tests must verify outputs and lineage. A bounded real run checks installation and runtime integration.