Documentation

Morflow Engine & Syntax Reference

Section 1

1. CLI Reference

Use the Morflow CLI to find actions and plugins, prepare their binaries, and check a pipeline before running it. Actions and plugins have separate caches, while prep prepares both from the declarations in your .morf file.

1.1. Installation

Install the standalone morflow command-line interface globally via cURL, npm, or pip:

CLI InstallationShell
# Install standalone native binary via cURL
curl -fsSL https://morflow.org/install.sh | bash

# Or install via NPM (Global CLI)
npm install -g morflow

# Or install via Pip (Python CLI)
pip install morflow

1.2. Core CLI Commands

CommandSyntaxDescription
checkmorflow check <file.morf> [-p <dir>] [--plugins-path <dir>]Validates syntax and Single Static Assignment (SSA), checks action dependencies and declared types, and infers shapes from action contracts.
prepmorflow prep <file.morf> [-p <dir>] [--plugins-path <dir>] [-f]Prepares imported actions and declared plugins, and verifies checksums for offline execution.
searchmorflow search <query> [-l <limit>]Searches the actions published in the repository’s GitHub releases by name and returns paths you can install or import.
catalogmorflow catalog [<pack>]Lists every action pack published in the repository’s GitHub releases with its latest version, or every action in one pack with its import path.
specmorflow spec <pkg>/<ver>/<action>Inspects argument schemas, types, and action documentation.
installmorflow install <action> [-p <dir>] [-f]Installs a versioned action or an entire pack into the action cache. Use prep to prepare all pipeline dependencies.
listmorflow list [-p <dir>]Lists installed action versions and the concrete release behind latest.
cleanmorflow clean [-p <dir>]Removes cached action binaries from the action path.
plugins listmorflow plugins list [--path <dir>]Lists verified installed plugins, including requested and concrete versions.
plugins searchmorflow plugins search <query> [-l <limit>]Searches the shipped plugin catalog by name and returns paths with explicit latest versions. Works offline.
plugins installmorflow plugins install <name>/<version> [-p <dir>] [-f]Installs an exact plugin version or an explicitly requested latest release.
plugins cleanmorflow plugins clean [--path <dir>]Removes prepared plugin entries. Loaded pipelines retain their selected plugins.

1.3. Pipeline Verification (check)

The check command performs static analysis, type checking, and shape inference on your .morf pipeline without requiring live input data. It checks syntax, Single Static Assignment (SSA) rules, action dependencies, declared payload types, and available shape information before deployment:

  • Type & Parameter Validation: Verifies all declared parameter types, ensuring argument types (e.g. IntArg) are not piped as flow heads (preventing E007) and that actions receive matching inputs.
  • Shape Checking: Checks how types and shapes flow between actions, including rank, partially known dimensions (such as Tensor[*, *, 3]), and channel counts. Each action is checked again with its actual input dimensions before execution, and its output is checked against the predicted shape.
  • Reducer Axis Bounds Checking: Statically proves that reduction operations (e.g. sum, mean, max, min, norm, argmax) do not specify out-of-bounds axes against pinned tensor ranks (preventing E010).
Pipeline Static Analysis & Shape VerificationBash
# Verify pipeline syntax, action binaries, type safety, and tensor shapes
morflow check ./pipeline.morf

# Check with a custom action cache directory
morflow check ./pipeline.morf --path ./actions_cache

Run prep first so the required actions and plugins are available locally. Checking verifies their receipts, checksums, and version requirements without network access. It does not load external libraries such as OpenCV, so checking can succeed on a development machine without those system libraries installed.

The check report shows a shape safety percentage and a Verified, Runtime check, or Invalid result for every action in all flows and branches. See Shapes & Shape Checking for the calculation and concrete versus dynamic examples.

1.4. Offline Prep (prep)

Run prep after writing your action imports and plugin declarations. It resolves their releases, checks that the declared plugins satisfy the actions’ requirements, and downloads and verifies the required binaries. You can do this while building a container image or before moving the pipeline to an offline machine.

Prepare Actions and PluginsBash
# Prepare all declared actions and plugins
morflow prep ./pipeline.morf

# Download again, even when the cached checksums match
morflow prep ./pipeline.morf --force

# Use separate custom caches for actions and plugins
morflow prep ./pipeline.morf --path ./actions_cache --plugins-path ./plugins_cache
morflow check ./pipeline.morf --path ./actions_cache --plugins-path ./plugins_cache

Use an exact version or write latest explicitly in every import and plugin declaration. Each preparation refreshes the selected stable release for latest and reuses cached binaries when their checksums match. Preparation reports an error if any required dependency cannot be prepared.

Plugins can depend on external shared libraries. Install compatible system libraries on the execution machine separately; preparation downloads the Morflow plugin, not its system dependencies. Once prepared, pipeline loading and execution use local artifacts without network requests. See Use a Plugin in a Pipeline for the OpenCV setup.

Action Versions & Verified Cache

Imports select an exact release, such as image_basics/0.3.3, or a refreshable latest entry. Exact binaries include their version in the filename; latest binaries use the word latest. Both can coexist in the same cache.

Each prep or install resolves the newest stable release for latest imports, verifies published SHA-256 checksums, and replaces cached bytes when the checksum changes. A receipt beside each binary records its concrete version and verified checksum. Pipeline loading verifies these artifacts locally, and loaded pipelines retain their actions until reloaded.

File and string APIs use the same prepared cache. Import aliases select multiple versions of one pack, while morflow list shows installed versions and the release behind latest. Actions resolve through imports or fully qualified pack/version/action calls.

1.5. Catalog, Search & Spec

This documentation does not list every action. Browse the full suite, search for actions, and view their parameters and supported dtypes directly in your terminal:

Action DiscoveryBash
# List every pack, then every action in one pack
morflow catalog
morflow catalog audio_basics

# Search for color or audio transformation actions
morflow search color
morflow search biquad

# Inspect argument schemas and SPEC.md docs
morflow spec image_basics/latest/color_adjust
morflow spec audio_basics/latest/biquad_filter

1.6. Plugin Commands

Use plugins search to find a plugin, and plugins install to prepare one independently of a pipeline. For a complete pipeline, prep is the usual starting point: it installs the declared plugins together with the imported actions and checks their compatibility.

Discover and Install PluginsShell
# Search the shipped catalog; no network request is needed
morflow plugins search opencv --limit 5

# Install an exact version, or explicitly request latest
morflow plugins install opencv-bridge/0.1.3
morflow plugins install opencv-bridge/latest

# Choose a cache and force a fresh download
morflow plugins install opencv-bridge/0.1.3 --path ./plugins_cache --force

# Inspect verified entries in that cache
morflow plugins list --path ./plugins_cache

plugins search matches names without regard to letter case and returns up to five results by default. Its results include an explicit latest version, such as opencv-bridge/latest. Installation downloads the platform-specific binary and verifies its published checksum.

plugins list shows both the requested version and its concrete release. For example, a latest entry can point to release 0.1.0. Refreshing it with preparation or installation affects newly loaded pipelines; existing pipelines keep the plugin snapshot they selected when loaded.

Clean the Plugin CacheShell
morflow plugins clean --path ./plugins_cache

Cleaning removes prepared plugin entries and catalogs from the chosen cache. Already loaded pipelines retain their selected snapshots. Run preparation again before loading another pipeline that needs the removed entries. morflow clean manages the separate action cache.

Add --help to any command for its options and examples. For the plugin declaration syntax and full lifecycle, see Plugins.

1.7. Environment Variables

VariableDefaultDescription
MORFLOW_ACTIONS_PATH~/.morflow/actionsDirectory where Morflow caches versioned action binaries, release catalogs, and checksum receipts (.so, .dylib, .dll).
MORFLOW_PLUGINS_PATH~/.morflow/pluginsSets the verified plugin cache directory. Local builds are also discovered in target/release/plugins.
MORFLOW_REPOJiraPit/MorflowTarget GitHub repository used by the CLI to query releases and download precompiled action and plugin binaries.

Section 2

2. .morf Syntax Guide

Learn .morf syntax from the ground up: starting from the smallest building block (an Action), to chaining them into a Flow, producing results with Emit, and composing Multiple Flows in a single file.

2.1. Anatomy of an Action

An Action is the fundamental atomic unit of computation in Morflow. It represents an isolated, high-performance compiled operation (e.g. image resizing, Gaussian blur, audio biquad filtering, tensor normalization).

Actions can be invoked in three main forms:

Action Invocation Formsmorf
# Form 1: Zero-argument actions (parentheses are optional)
to_image
to_wav
identity

# Form 2: Keyword arguments (key=value)
resize(width=512, height=512, filter="bilinear")
color_adjust(contrast=1.15, saturation=1.05, brightness=0.02)
biquad_filter(type="highpass", freq=30.0, sample_rate=48000)

# Form 3: Variable arguments (passing pipeline parameters to action parameters)
resize(width=$target_width, height=$target_height)
resample(to_rate=$target_sample_rate)

Before using actions, import their parent Action Pack at the top of your .morf file:

Importing Actionsmorf
# Package-level import (brings actions into scope or under an alias)
import base/latest
import audio_basics/latest as audio

# Item import (brings specific actions into local scope)
from base/latest import to_tensor
from image_basics/latest import resize, color_adjust, gaussian_blur, to_image

2.2. Inputs & Constructing a Flow

A Flow connects an input variable through a sequence of actions using the >> dataflow operator. Each action receives the output payload of the previous action. Tensor views share backing storage, enabling zero-copy slicing and axis permutations.

Inputs and configurable parameters are declared using accept at the top of the file (see Section 3: Data Types and Shape for all supported flowable payload and configuration argument types):

Declaring Pipeline Inputsmorf
# Declare flowable input payload
accept Image $img_in

# Declare configuration arguments with defaults
accept IntArg $target_width = 512
accept IntArg $target_height = 512
accept BoolArg $normalize = true
Data Types & Dimensions: Morflow pipelines enforce an explicit type system (Tensor, Image, Audio, Scalar, Bytes, and *Arg). For a complete walkthrough of every data type, dimension declaration syntax, and component structures, see Section 3: Data Types and Shape.

Once inputs and parameters are declared, chain actions into a continuous dataflow stream:

A Sequential Flow Chainmorf
# The flow starts with the flowable input $img_in and passes data step-by-step
$img_in
    >> to_tensor(color="rgb", dtype="f32", layout="hwc", normalize=$normalize)
    >> resize(width=$target_width, height=$target_height, filter="bilinear")
    >> color_adjust(contrast=1.15, saturation=1.05)
    >> gaussian_blur(sigma=1.2)
    >> to_image(color="rgba", dtype="u8")

2.3. Emitting Output & Intermediate Emission (emit)

The emit keyword collects outputs for the calling host application. emit is a passthrough operation: it captures the current payload as a pipeline output and lets subsequent actions continue processing the flow.

This enables intermediate emission, allowing a single continuous flow to collect checkpoints, previews, or multi-scale outputs without duplicating upstream work or branching into separate pipelines:

Intermediate Emission & Chainingmorf
# Form A: Single primary emission
import base/latest
from base/latest import to_tensor
from image_basics/latest import resize

accept Image $img_in
$img_in >> to_tensor >> resize(width=512, height=512) >> emit

# Form B: Named stream emission
import audio_basics/latest

accept Bytes $audio_in
$audio_in >> to_audio >> normalize >> emit("normalized_audio")

# Form C: Intermediate emission with chained downstream processing
import base/latest
from base/latest import to_tensor
from image_basics/latest import resize, color_adjust

accept Image $img_in
$img_in
    >> to_tensor(color="rgb", normalize=true)
    >> resize(width=1024, height=1024)
    >> emit("high_res")               # Emits intermediate 1024x1024 tensor to host
    >> resize(width=256, height=256)   # Continues stream without re-ingesting $img_in
    >> color_adjust(contrast=1.2)
    >> emit("preview")                # Emits downstream preview thumbnail
Host Return Type & Multi-Emission: Collected outputs are returned when pipeline execution completes. Python returns a single value for one output and a dictionary for multiple outputs. Node.js and Java provide methods for retrieving all named outputs, and Rust returns PipelineOutputs.

2.4. Multiple Flows in One File

A single .morf file can contain multiple flows. You can capture intermediate states mid-stream into a tapped variable using >> $var_name, and then spawn independent branch flows from that variable.

Morflow automatically discovers dependencies between flows and schedules independent branches concurrently across CPU worker threads:

Multi-Flow Audio Split Pipelinemorf
import audio_basics/latest

accept Bytes $input_audio

# FLOW 1: Ingest input audio, convert to structured stream, and tap into $decoded
$input_audio >> to_audio >> $decoded

# FLOW 2: Extract channel 0 (Left), apply low-pass filtering, convert to WAV, and emit
$decoded[0] >> biquad_filter(type="lowpass", freq=1200.0) >> to_wav >> emit("left_filtered")

# FLOW 3: Extract channel 1 (Right), apply high-pass filtering, convert to WAV, and emit
$decoded[1] >> biquad_filter(type="highpass", freq=800.0) >> to_wav >> emit("right_filtered")

In this pipeline, Flow 2 and Flow 3 run concurrently in parallel immediately after Flow 1 finishes. Because both downstream branches depend solely on the shared output of Flow 1 ($decoded) but have no dependency on each other, Morflow's runtime schedules both branches concurrently across CPU worker threads.

Static Single Assignment (SSA) Rule: Each tapped variable identifier (e.g. $decoded) is assigned once within its scope. This rule gives each tapped variable a single producer, helping the scheduler resolve dependencies while tensor views share backing storage across branches.

2.5. Advanced Control Flow (Loops & Conditionals)

Morflow includes built-in constructs for parallel loops, conditional branching, and pattern routing within flows:

Parallel Map Loop (each): The each block applies a transformation sub-flow across elements of a higher-rank collection, batch, or multi-channel audio/image payload (see Section 3.9: Deep Dive: Slicing & Restacking with each for type-specific slicing rules). Each iteration is executed concurrently in parallel across multi-threaded CPU workers. The general rule for each is that the result is always stacked back to the same data type as the input, so the result of each sub-flow must be able to be combined back to the original higher-rank type. Once all parallel iterations complete, their resulting outputs are automatically stacked back together in sequence order and passed directly to the next action in the stream.

Parallel Map Loop (each)morf
import audio_basics/latest

accept Bytes $input_audio

# Iterates each channel concurrently in parallel, transforms, and stacks back together
$input_audio
    >> to_audio(sample_rate=44100)
    >> each ($channel) {
        $channel
            >> biquad_filter(type="highpass", freq=30.0, sample_rate=48000)
            >> compressor(threshold_db=-12.0, ratio=3.0)
    }
    >> stereo_widen(width=1.2)   # Receives the stacked multi-channel stream
    >> to_wav
    >> emit
The Higher-Rank Restacking Rule: In Morflow, each always stacks results back to the exact same data type as the loop input. Thus, the result of each parallel sub-flow must be able to be combined back into the original higher-rank type (e.g. multi-channel Audio → mono Audio slices → restacked multi-channel Audio). Changing the payload kind inside the loop (e.g. returning a Tensor or Scalar from an Image channel loop) violates static rule E009. Outputs from an each block are emitted after its parallel results have been restacked. For an in-depth breakdown of slicing dimensions, type derivation, and restacking contracts for every higher-rank type, see Section 3.9: Deep Dive: Slicing & Restacking with each.

Choosing the Loop Axis (each(axis=N)): A Tensor loop goes over axis 0 by default. Write each(axis=N) to loop over another axis; negative values count from the end, so axis=-1 is the last axis. Each iteration receives the tensor with that axis removed, and the results are stacked back along the same axis. Only Tensors take an axis: each(axis=N) on an Image or Audio is an error, and morflow check rejects an axis that cannot exist for the declared rank, such as each(axis=2) on Tensor[*, 3].

Looping Over a Chosen Axismorf
import tensor_stats/latest

accept Tensor[*, 3] $readings

# Loop over the columns (axis 1): each $column is one sensor over time
$readings >> each(axis=1) ($column) {
    $column >> cumsum
} >> emit

Conditionals & Dynamic Routing: Branch pipelines conditionally based on runtime metadata or route streams dynamically:

Conditionals & Dynamic Routingmorf
import audio_basics/latest
from base/latest import identity

accept Bytes $input_audio
accept IntArg $sample_rate = 44100
accept IntArg $channels = 2

# 1. If / Else branching
$input_audio >> to_audio(sample_rate=$sample_rate, channels=$channels) >> if ($sample_rate != 48000) {
    resample(to_rate=48000)
} else {
    identity
} >> $prepared

# 2. Dynamic route pattern matching
$prepared >> route {
    $channels == 1 => biquad_filter(type="lowpass", freq=1000.0)
    $channels == 2 => stereo_widen(width=1.4)
    else => identity
} >> to_wav >> emit

Condition Rules: Both sides of a comparison (==, !=, <, <=, >, >=) must be numbers. An operand can be a number, a numeric argument, a Scalar, an element picked by index such as $readings[0, 0] (negative indexes count from the end), or one of these fields:

  • sample_rate (rate), duration (duration_seconds), and num_samples (samples) of an Audio.
  • height, width, and channels of an Image, or axes 0, 1, and 2 of a Tensor; channels also works on an Audio.
  • peak (peak_abs), rms, mean, and len (length, the element count) of a Tensor, Scalar, Image, or Audio; len also gives the size of Bytes.

A condition that cannot be evaluated is an error rather than being treated as true. This covers a misspelled field such as $readings.widht, a field the value does not have, a string, and a value that is not a single number. morflow check reports the ones it can tell from the declared types before the pipeline runs. Comparisons are exact for every dtype, so large integers are never rounded.

Conditions on Tensor Valuesmorf
import math_basics/latest

accept Tensor[*, 3] $readings

# Flip every sign if the first reading is below zero
$readings >> if ($readings[0, 0] < 0) {
    neg
} else {
    abs
} >> emit("aligned")

# Take the first arm whose condition holds
$readings >> route {
    $readings.height > 100 => clamp(max=10.0)
    $readings[-1, 2] > 10 => clamp(min=0.0)
    else => abs
} >> emit("checked")

2.6. Complete End-to-End Examples

Here are two complete, production-ready .morf pipeline definitions:

Complete Vision Pipelinemorf
# Morflow Image Processing Pipeline (.morf)

import base/latest
from base/latest import to_tensor
from image_basics/latest import resize, color_adjust, gaussian_blur, to_image

accept Image $img_in
accept IntArg $target_width = 512
accept IntArg $target_height = 512

# Direct chained dataflow from host image input to emitted output
$img_in
    >> to_tensor(color="rgb", dtype="f32", layout="hwc", normalize=true)
    >> resize(width=$target_width, height=$target_height, filter="bilinear")
    >> color_adjust(contrast=1.15, saturation=1.05, brightness=0.02)
    >> gaussian_blur(sigma=1.2)
    >> to_image(color="rgba", dtype="u8")
    >> emit
Complete Audio DSP Pipelinemorf
# Morflow Audio DSP Pipeline (.morf)

import audio_basics/latest

accept Bytes $input_audio
accept IntArg $sample_rate = 44100

# Direct chained DSP processing with inline multi-channel loop
$input_audio
    >> to_audio(sample_rate=$sample_rate)
    >> resample(to_rate=48000)
    >> normalize(target_peak=0.95)
    >> each ($channel) {
        $channel
            >> biquad_filter(type="highpass", freq=30.0, sample_rate=48000)
            >> compressor(threshold_db=-12.0, ratio=3.0)
    }
    >> stereo_widen(width=1.2)
    >> limiter(ceiling_db=-0.1)
    >> to_wav
    >> emit

Section 3

3. Data Types and Shape

Morflow provides an explicit type system and shape algebra. Input declarations describe payload kinds and optional rank and dimension constraints. The checker uses these declarations and action shape contracts to validate flows, and the runtime verifies supplied inputs against their declared types.

3.1. Type Hierarchy & Architecture

Types in Morflow are fundamentally divided into two distinct classes:

  • Flowable Payloads: High-performance multi-dimensional arrays, signals, images, or byte buffers that stream through >> dataflow chains, participate in parallel each loops, and can be yielded to the host via emit.
  • Configuration Arguments (*Arg): Parameter values passed from host applications to configure action arguments (such as image resolutions, filter cutoffs, or sample rates). Arguments cannot be piped as the head of a flow (preventing compile error E007).
TypeClassificationDefault / Shape SyntaxIterated by each
TensorFlowable PayloadTensor, Tensor[rank=N], Tensor[*, *]Yes (Axis 0 / Batch, or any axis with each(axis=N))
ImageFlowable PayloadImage, Image[*, *, C] (HWC), Image[C, *, *] (CHW)Yes (Channel Axis)
AudioFlowable PayloadAudio, Audio[C, *] (Planar), Audio[*, C] (Interleaved)Yes (Channel or Sample)
ScalarFlowable PayloadScalar (Rank-0 numerical value)Does not work with each
BytesFlowable PayloadBytes (Opaque linear buffer)Does not work with each
CompositeFlowable PayloadComposite (Tuple of payloads)Does not work with each
IntArgConfiguration ArgIntArg (Integer scalar parameter)Does not work with each
FloatArgConfiguration ArgFloatArg (Float scalar parameter)Does not work with each
StrArgConfiguration ArgStrArg (String scalar parameter)Does not work with each
BoolArgConfiguration ArgBoolArg (Boolean scalar parameter)Does not work with each

3.2. Tensor

Components

ComponentTypeDescription
bufferDense MemoryContiguous multi-dimensional buffer holding element values
shapeList of dimension lengthsDimension array [D_0, D_1, ..., D_k] defining tensor geometry
dtypeDTypeNumeric types: f32, f64, u8, u32, u64, i8, i16, i32, i64

Defining Shapes & Dimensions: You can constrain tensor inputs with precise shapes or wildcard dimensions:

Tensor Shape Annotationsmorf
# 1. Unconstrained: Any rank and shape accepted
accept Tensor $data

# 2. Fixed Rank: Enforces exactly rank 2 (matrix), dynamic dimensions
accept Tensor[rank=2] $matrix

# 3. Dynamic Wildcard Dimensions: 2D tensor where both dimensions are dynamic
accept Tensor[*, *] $table

# 4. Partial Fixed Dimensions: Dynamic batch size with fixed 512-dim embedding vector
accept Tensor[*, 512] $embeddings

# 5. Static Fixed Shape: Exact 3x224x224 tensor dimensions
accept Tensor[3, 224, 224] $batch

How Tensor Works with each:

  • Iteration Axis: Iterates along Axis 0 (the leading dimension / batch axis) by default; each(axis=N) picks another axis (see Section 2.5).
  • Iteration Count: One parallel iteration per position along the loop axis (shape[0] for Axis 0).
  • Loop Variable Derivation:
    • If rank ≥ 2: Each iteration produces an independent Tensor with rank reduced by one (rank N − 1). Slicing Tensor[32, 128] yields 32 parallel sub-flows each receiving a Tensor[128].
    • If rank 1: Iterating a 1D tensor slices single elements, binding each iteration to a Scalar (rank-0 numeric value).
    • If rank 0: A rank-0 scalar tensor has no dimensions to slice and is rejected at compile time.
  • Restacking: Outputs from all iterations are collected and restacked along the loop axis back into the parent tensor shape. In accordance with the higher-rank restacking rule, sub-flows must yield rank-(N − 1) tensors so that slices can be reassembled back into the original higher-rank Tensor[rank=N].

3.3. Image

Components

ComponentTypeDescription
pixel bufferDense MemoryMulti-channel contiguous raster pixel buffer
dimensions(H, W)Spatial height H and width W in pixels
channelsInteger (C)Color channel count (e.g. 1 for Grayscale, 3 for RGB, 4 for RGBA)
color_spaceColorSpaceSupported variants: rgb, rgba, bgr, bgra, grayscale, grayscale_alpha, ycbcr, hsv, lab, cmyk
layoutImageLayoutExact memory arrangement: hwc (channels-last, default) or chw (channels-first)

Defining Shapes & Dimensions:

Image Shape Declarationsmorf
# 1. Unconstrained: Any resolution, channel count, or memory layout accepted
accept Image $img_in

# 2. 3-channel RGB/BGR in HWC format (or Image[3, *, *] for planar CHW format)
accept Image[*, *, 3] $rgb_in

# 3. Grayscale image with 1 channel in HWC (or Image[1, *, *] for CHW, or 2D Image[*, *])
accept Image[*, *, 1] $gray_in

# 4. Fixed static resolution and channel count in HWC (or Image[3, 1080, 1920] for CHW)
accept Image[1080, 1920, 3] $frame

How Image Works with each (Channel Slicing):

  • Iteration Axis: Crucially, each on an Image slices along the Color Channel Axis (C), not spatial rows or columns!
    • In hwc layout: slices along Axis 2.
    • In chw layout: slices along Axis 0.
  • Iteration Count: Exactly C parallel workers (e.g. 3 for RGB, 4 for RGBA).
  • Loop Variable Derivation: Each parallel iteration receives an independent rank-2 Image in ColorSpace::Grayscale, preserving the full H × W spatial resolution. This allows applying filters, equalizations, or thresholding to individual channels simultaneously.
  • Payload Kind Preservation (E009): The sub-flow inside each must preserve the payload kind. You cannot convert the channel slice into a Tensor or Audio mid-loop without causing static error E009.
  • Restacking: The transformed grayscale channel slices are reassembled along the channel axis back into the parent's original color space and layout. Because the slices are recombined into the higher-rank Image, all iterations must produce compatible single-channel Image payloads.

3.4. Audio

Components

ComponentTypeDescription
sample bufferDense MemoryLinear PCM floating-point audio sample buffer
channelsInteger (C)Number of independent audio channels (e.g. 1 for Mono, 2 for Stereo)
samplesInteger (S)Number of audio sample frames per channel
sample_rateu32Sampling frequency in Hz (e.g. 44100, 48000)
channel_layoutAudioChannelLayoutExplicit layout variants: Mono (1 ch), Stereo (2 ch), Stereo2_1 (3 ch), Quad (4 ch), Surround5_1 (6 ch), Surround7_1 (8 ch), AmbisonicOrder1 (4 ch), AmbisonicOrder2 (9 ch), AmbisonicOrder3 (16 ch), Custom
layoutAudioLayoutExact memory arrangement: Planar [channels, samples] or Interleaved [samples, channels]

Defining Shapes & Dimensions:

Audio Declarationsmorf
# 1. Unconstrained: Any channel count, sample length, or memory layout accepted
accept Audio $audio_in

# 2. Dynamic 2D audio signal in Planar layout (or Audio[*, *] for Interleaved)
accept Audio[*, *] $stream

# 3. Stereo audio (2 channels) in Planar format (or Audio[*, 2] for Interleaved format)
accept Audio[2, *] $stereo

# 4. Mono audio signal in Planar format (or Audio[*, 1] for Interleaved, or 1D Audio[*])
accept Audio[1, *] $mono

How Audio Works with each:

  • Multi-Channel Audio (C > 1): Slices along the channel axis (Axis 0 in Planar, Axis 1 in Interleaved). Each parallel worker receives an independent single-channel Audio (mono) payload with the parent's sample rate intact. Slices are processed concurrently and restacked along the channel axis back into the higher-rank multi-channel Audio.
  • Mono Audio (C = 1, rank-1 [samples]): Slices along the sample axis. Each iteration receives a single sample as a Scalar float. Slices are restacked along the sample axis back into the higher-rank mono audio container.

3.5. Scalar

Components

ComponentTypeDescription
valueRank-0 Float / IntSingle numeric value with rank 0

Defining Shape: Scalar has no dimensions (rank 0). It is declared simply as accept Scalar $name [= default].

Behavior with each: Does not work with each.

3.6. Bytes

Components

ComponentTypeDescription
bytesByte bufferOpaque contiguous linear byte buffer holding raw file or network stream data

Defining Shape: Bytes has no shape or dimension concepts. It is declared as accept Bytes $data.

Behavior with each: Does not work with each.

3.7. Composite

Components

ComponentTypeDescription
payloadsTuple of PayloadsHeterogeneous collection combining multiple distinct flowable payloads

Behavior with each: Does not work with each.

Two-Tensor Arithmetic: Besides the scalar-argument form (add(value=1.5)), add, sub, mul, div, and pow accept a two-component Composite [a, b] and compute a + b, a - b, a * b, a / b, or a ** b element by element. The two tensors broadcast like NumPy: dimensions are matched from the last axis, and an axis of length 1, or a missing axis, stretches to fit. Either side can be a Scalar, and the result is a Scalar only if both are. A Composite with any other number of components, or a Composite together with a scalar argument, is an error.

two_tensor.morfmorf
import math_basics/latest

accept Composite[Tensor[*, 3], Tensor[3]] $pair

# a + b, broadcasting b across every row of a
$pair >> add >> emit

morflow check predicts the broadcast shape when it can, and rejects shapes that can never broadcast. For example, Composite[Tensor[2, 3], Tensor[4]] fails with operands could not be broadcast together with shapes [2, 3] and [4]. A Composite reaches these actions either from an action that returns one, such as qr, or from the host (see Section 5.5). The dtype of the result follows the promotion rules in Section 4.3.

3.8. Configuration Arguments (IntArg, FloatArg, StrArg, BoolArg)

Components

Argument TypeNative TypeDescription
IntArg64-bit integerInteger parameters (resolutions, axis indices, sample rates)
FloatArg64-bit floatFloating-point parameters (thresholds, gain, cutoff frequencies, sigma)
StrArgUTF-8 stringString parameters (interpolation modes, filter names, file paths)
BoolArgBooleanFlag parameters (normalization toggles, channel invert flags)

Behavior with each: Does not work with each.

Configuration Argument Typesmorf
# Integer parameter (dimensions, sample rates, axis indices)
accept IntArg $target_w = 512

# Floating-point parameter (contrast, gain, threshold, sigma)
accept FloatArg $contrast = 1.15

# String parameter (color space formats, interpolation modes)
accept StrArg $filter = "bilinear"

# Boolean flag (normalization, channel swapping)
accept BoolArg $normalize = true
Non-Flowable Guarantee (E007): Configuration arguments cannot initiate a dataflow stream (e.g. $target_w >> ... raises E007: cannot pipe from non-flowable argument type). They are strictly passed to action calls (e.g. resize(width=$target_w)) and can be accessed as parameters inside each sub-flows.

3.9. Deep Dive: Slicing & Restacking with each

The each operator is Morflow's parallel map-and-restack construct. It dynamically slices a multi-dimensional payload across a specific axis, dispatches each slice independently across CPU workers, and deterministically restacks the transformed slices back together in original sequence order.

The Cardinal Rule of each: Higher-Rank Type Restacking

The foundational invariant governing each is: the result is always stacked back to the exact same data type as the input. Because Morflow automatically reassembles the aggregated slices into the original higher-rank container, the result of each sub-flow must be able to be combined back into the original higher-rank type.

Slicing & Restacking Semantics by Type

Incoming Higher-Rank PayloadIteration AxisSub-Flow Slice ($var)Required Sub-Flow OutputRestacked Result
Tensor[rank=N] (N ≥ 2)Axis 0 (Batch / Leading), or the axis chosen with each(axis=N)Tensor[rank=N-1]Tensor[rank=N-1]Tensor[rank=N]
Tensor[rank=1] (1D Vector)Axis 0 (Elements)ScalarScalarTensor[rank=1]
Image[H, W, C] (HWC layout)Axis 2 (Channel Axis)Image[H, W, 1] (Grayscale)Image[H, W, 1]Image[H, W, C]
Image[C, H, W] (CHW layout)Axis 0 (Channel Axis)Image[1, H, W] (Grayscale)Image[1, H, W]Image[C, H, W]
Audio[C, S] (C > 1, Planar)Axis 0 (Channel Axis)Audio[1, S] (Mono Audio)Audio[1, S] (Mono Audio)Audio[C, S]
Audio[1, S] (Mono Audio)Axis 0 (Sample Axis)Scalar (Float sample)ScalarAudio[1, S]

Higher-Rank Restacking Contracts

Morflow's execution engine enforces strict type and dimension symmetry when reassembling sub-flow results:

  • Higher-Rank Images (Channel Reassembly): When looping over a multi-channel Image, each parallel iteration receives a single grayscale channel. The sub-flow must output a single-channel Image preserving spatial height and width (H × W). When all channel sub-flows conclude, the engine stacks them along the channel axis (Axis 2 in HWC, Axis 0 in CHW) and restores the original ColorSpace (e.g. RGB) and layout. The checker validates payload-kind compatibility, and the runtime verifies channel shapes during reassembly.
  • Higher-Rank Audio (Multi-Channel Synchronization): Slicing a multi-channel Audio yields mono Audio streams. Each branch must produce a mono Audio with identical sample rates and layouts. Morflow stacks the processed mono streams along the channel axis back into the original multi-channel higher-rank Audio container (transposing planar buffers into interleaved buffers if the parent audio used interleaved layout). When mono Audio is sliced per-sample, single Scalar float samples are processed and stacked back into mono Audio.
  • Higher-Rank Tensors (Loop-Axis Concatenation): Slicing a rank-N Tensor along its loop axis (Axis 0 unless each(axis=N) picks another) produces rank-(N − 1) slices. Every parallel branch must yield a rank-(N − 1) Tensor with identical inner dimension sizes. The runtime stacks them back along the same axis to recreate the higher-rank rank-N Tensor.

The Core Rules of each

  • 1. The Higher-Rank Restacking Contract (E009): The sub-flow inside each must preserve the payload kind of the loop variable. Because the engine restacks outputs back into the higher-rank container of the input, the result of each sub-flow must be combinable back into the original higher-rank type. If an Image channel loop yields a Tensor or Scalar, or an Audio loop yields non-audio data, compilation halts with E009: 'each' body changes the payload kind.
  • 2. Emitting Loop Results: Slices execute concurrently across CPU worker threads. Their results are collected in iteration order, restacked, and emitted by the enclosing top-level flow.
  • 3. Single Static Assignment (SSA) Safety: The loop variable (e.g. $channel) is immutable within its iteration scope. Intermediate variables tapped inside an each loop cannot conflict with external flows.
  • 4. External Parameter Access: Sub-flows inside each can freely reference external variables and configuration arguments declared in the outer scope (e.g. $channel >> biquad_filter(freq=$cutoff)).
Valid vs Invalid each Sub-flowsmorf
# ❌ COMPILE ERROR E009: Sub-flow changes payload kind
# The loop input is an Image, so each sub-flow must produce an Image.
# Here, 'relu' returns a Tensor, which cannot be restacked back into the higher-rank Image!
$rgb_image
    >> each ($channel) {
        $channel
            >> to_tensor
            >> relu  # Error E009: body produces Tensor, expected Image
    }

# ✅ VALID: Sub-flow produces compatible Image slices
# Every slice remains an Image and restacks cleanly back into RGB Image
$rgb_image
    >> each ($channel) {
        $channel
            >> gaussian_blur(sigma=1.2)
            >> threshold(cutoff=128)
    }
    >> emit
Parallel Multi-Channel Audio Loopmorf
import audio_basics/latest

accept Audio $stereo_audio
accept FloatArg $cutoff_freq = 120.0

# Stereo audio ($stereo_audio has 2 channels)
# 'each' slices the channel axis, processing 2 channels in parallel
$stereo_audio
    >> each ($channel) {
        # $channel is a mono Audio payload
        $channel
            >> biquad_filter(type="highpass", freq=$cutoff_freq)
            >> compressor(threshold_db=-12.0, ratio=3.0)
    }
    # Processed channels are restacked into stereo Audio
    >> stereo_widen(width=1.2)
    >> to_wav
    >> emit

3.10. Shapes & Shape Checking

Morflow can catch incompatible shapes before you run a pipeline. For example, a tensor with 2 rows and 3 columns has six elements, so reshaping it to 3 rows and 2 columns is valid. Reshaping it to 4 rows and 2 columns is an error.

Tell Morflow what to expect by adding a shape to your input declaration. You can specify every dimension, leave some dimensions flexible, or omit the shape entirely:

Input declarationWhat it accepts
accept Tensor $xA tensor of any shape.
accept Tensor[rank=2] $xA matrix with any number of rows and columns.
accept Tensor[*,3] $xA matrix with any number of rows and exactly 3 columns.
accept Tensor[2,3] $xA matrix with exactly 2 rows and 3 columns.

Use * for a dimension whose size can change between runs. A size of 0 means that dimension is empty.

When you run morflow check, Morflow follows the shape through each action and checks whether the next action can accept it. The more dimensions you specify, the more Morflow can verify ahead of time. Flexible dimensions still carry useful information: with Tensor[*,3], Morflow knows that every row passed to each contains 3 elements.

The same checking applies to Image and Audio dimensions. For a Composite, Morflow tracks each payload separately and in order. For example, Composite[Tensor[2,3], Tensor[3,4]] gives matmul a 2×3 left matrix and a 3×4 right matrix. Selecting $parts[0] gives you the first matrix, with its 2×3 shape.

Check resultMeaningCLI behavior
VerifiedThe action can accept the specified type, shape, and arguments.Counts as verified.
Runtime checkMore information is needed, such as the actual input size or an argument supplied when the pipeline runs.Shows which action needs more information and why.
InvalidThe specified input or arguments do not meet the action’s requirements.Reports an error.

Run morflow check pipeline.morf to see how much of your pipeline’s shape compatibility can be verified before execution. If 8 of 10 actions are verified, the report shows 80% shape safety. It also shows the input and output shapes for each action and explains what is still needed for any action marked Runtime check.

Actions in every flow, branch, and loop are included. Each action written in the pipeline counts once, even if a loop runs it many times. emit does not count. If there are no processing actions, the percentage is N/A.

Concrete versus dynamic shapesmorf
from tensor_basics/latest import reshape
accept Tensor[2,3] $fixed
accept Tensor[*,3] $dynamic
$fixed >> reshape("3,2") >> emit("fixed")
$dynamic >> reshape("3,2") >> emit("dynamic")

# Shape safety: 50.0% (1/2 actions verified)
# Flow 1: Verified — six input elements match six output elements.
# Flow 2: Runtime check — the wildcard length is resolved at runtime.

In this example, the first reshape is verified because the input has exactly six elements. The second needs the actual row count before Morflow can know whether the reshape will work. You can keep that flexibility or specify the row count to make the check more precise. Arguments supplied by the caller also remain flexible, even when they have defaults.

When you run the pipeline, Morflow checks each action using the actual input dimensions and arguments, then verifies the shape of its output. A 100% report means every action’s shape requirements have been verified for your input declarations. Requirements that depend on the data itself, such as whether a matrix can be inverted, are checked during execution.

Section 4

4. Tensor DTypes

Every Tensor has a dtype, the type of its elements. The numeric packs (math_basics, tensor_stats, and nn_basics) accept all nine dtypes, follow NumPy's rules for the dtype of each result, and can combine two tensors with NumPy broadcasting.

4.1. Supported DTypes

DTypeElementsNumPy Equivalent
f32, f6432-bit and 64-bit floatsfloat32, float64
i8, i16, i32, i64Signed integersint8, int16, int32, int64
u8, u32, u64Unsigned integersuint8, uint32, uint64

Packs differ in which dtypes they accept. Every action lists them on the Supported DTypes line of its SPEC; find actions with morflow catalog (see Section 1.5) and read the line with morflow spec:

Checking an Action's DTypesBash
morflow spec image_basics/latest/resize

To feed a tensor into an action that does not accept its dtype, convert it first with cast from tensor_basics, for example cast(dtype="f32").

4.2. DTypes of Numeric Actions

The dtype of a result depends on the action. These are the common rules, with examples; each numeric action's SPEC has a DTypes section with its exact rule, for example morflow spec tensor_stats/latest/mean:

Result DTypeExamples
Same as the inputabs, clamp, relu, and add with a scalar argument
f64 for integer input; floats keep their dtypesqrt, mean, softmax, and div with a scalar argument
i64 for signed integers, u64 for unsigned; floats keep their dtypesum, cumsum
i32 (index of the first match)argmin, argmax
Promoted from both inputs (see Section 4.3)add on two tensors, cosine_similarity
  • Floats: f32 is computed in single precision and f64 in double precision. NaN values in the input behave like NumPy: they propagate through the result, and argmin / argmax return the index of the first NaN.
  • Integer overflow wraps like NumPy. For example, abs of -128 as i8 is -128.
  • Integer statistics (mean, var, std, norm) are computed exactly, and only the result is rounded to f64.
  • Arguments on integer tensors: value, exponent, min, and max must be whole numbers that fit the dtype; anything else is an error. div accepts any value, because its result is f64. A negative exponent on an integer pow is an error.
Result DTypes from Integer Inputmorf
import tensor_stats/latest

accept Tensor[*, 3] $counts

$counts >> sum(axis=0) >> emit("totals")     # i32 counts give i64 totals
$counts >> mean(axis=0) >> emit("averages")  # and f64 averages

4.3. Promotion Between Two Tensors

When add, sub, mul, div, or pow combine two tensors (see Section 3.7), and in cosine_similarity, the result dtype is promoted from both inputs:

InputsResult DType
The same dtypeThat dtype
At least one floatf64 if either side is f64, otherwise f32
Two integers of the same signednessThe wider one (i8 and i32 give i32)
A signed and an unsigned integerThe smallest signed type that holds both (u8 and i8 give i16), or i64 if none does

div and cosine_similarity turn an integer result into f64. Integer overflow in add, sub, mul, and pow wraps like NumPy.

Section 5

5. Pipeline Execution

Execute the same .morf pipelines and native actions across training and production serving. Morflow provides host SDKs for Python, JavaScript/Node.js, Java, and Rust, converting host tensors, image arrays, and raw bytes into engine payloads.

5.1. Python

The Python SDK (morflow) converts NumPy arrays and raw bytes into engine payloads and executes pipelines in Rust with the Python GIL released. Payloads can be passed as typed wrappers (morflow.Image, morflow.Audio, morflow.Tensor), or plain NumPy arrays and bytes matching declared accept types.

InstallationShell
pip install morflow
Typed Execution & Positional Arguments in Pythonpython
import numpy as np
from PIL import Image
import morflow

# 1. Load pipeline from file
pipeline = morflow.load("image_pipeline.morf")

# 2. Pass NumPy array wrapped as morflow.Image
img = Image.open("input.png").convert("RGB")
np_img = np.array(img, dtype=np.uint8)

# 3. Execute with positional arguments (payload, target_w, target_h)
# Declared defaults (512, 512) apply if arguments are omitted: pipeline.run(payload)
result_np = pipeline.run(morflow.Image(np_img, color="rgb"), 512, 512)

# 4. Save result
out_img = Image.fromarray(result_np)
out_img.save("output.png")

# ----------------------------------------------------
# Audio Processing (Pass and receive raw WAV bytes)
# ----------------------------------------------------
audio_pipe = morflow.load("audio_pipeline.morf")
with open("input.wav", "rb") as f:
    input_bytes = f.read()

# Pass raw bytes (bound to accept Bytes) and custom sample rate IntArg
output_wav_bytes = audio_pipe.run(input_bytes, 44100)
with open("output.wav", "wb") as f:
    f.write(output_wav_bytes)

5.2. JavaScript / Node.js

The Node.js SDK provides asynchronous execution (via pipeline.run() or pipeline.runArgs() offloading work to a background worker pool) and synchronous execution (via pipeline.runSync() / pipeline.runSyncArgs()). Positional arguments matching declared accept statements can be passed directly as heterogeneous arguments (numbers, booleans, strings, Buffers, or TensorInput).

InstallationShell
npm install morflow
Async Pipeline Execution with Arguments in Node.jsjavascript
import fs from 'node:fs';
import morflow from 'morflow';

// 1. Load pipeline from file
const pipeline = morflow.load('image_pipeline.morf');

// 2. Construct TensorInput with explicit payloadType
const inputBuffer = fs.readFileSync('input_raw_rgb.bin');
const tensorInput = {
  data: inputBuffer,
  shape: [1080, 1920, 3],
  dtype: 'u8',
  payloadType: 'image',
  colorSpace: 'rgb'
};

// 3. Run asynchronously on worker pool with positional arguments (runArgs)
const outputTensor = await pipeline.runArgs(tensorInput, 512, 512);

console.log(`Shape: ${outputTensor.shape}, Dtype: ${outputTensor.dtype}`);
const outBuffer = outputTensor.toBuffer();
fs.writeFileSync('output_raw_rgba.bin', outBuffer);

// ----------------------------------------------------
// Audio DSP Execution (Direct Buffer & Argument I/O)
// ----------------------------------------------------
const audioPipe = morflow.load('audio_pipeline.morf');
const wavBuffer = fs.readFileSync('input.wav');

// Execute asynchronously with buffer and sample rate argument
const outWav = await audioPipe.runArgs(wavBuffer, 44100);
fs.writeFileSync('output.wav', outWav.toBuffer());

5.3. Java

The Java SDK wraps native JNI bindings with type-safe classes, automatic memory cleanup, and direct tensor buffers for high-throughput enterprise JVM backends. Positional parameters are bound using pipeline.runArgs(...).

Maven Dependency (pom.xml)XML
<dependency>
    <groupId>org.morflow</groupId>
    <artifactId>morflow</artifactId>
    <version>0.3.2</version>
</dependency>
Pipeline Execution in Javajava
import org.morflow.Morflow;
import org.morflow.Pipeline;
import org.morflow.MorflowTensor;
import java.nio.file.Files;
import java.nio.file.Path;

public class MorflowRunner {
    public static void main(String[] args) throws Exception {
        // 1. Load pipeline
        try (Pipeline pipeline = Morflow.load("image_pipeline.morf")) {
            // 2. Wrap image bytes into MorflowTensor [H, W, C]
            byte[] rgbBytes = Files.readAllBytes(Path.of("input_rgb.raw"));
            MorflowTensor inputTensor = MorflowTensor.fromByteArray(
                rgbBytes,
                new int[]{1080, 1920, 3}
            );

            // 3. Execute pipeline with positional arguments (runArgs)
            MorflowTensor outputTensor = pipeline.runArgs(inputTensor, 512, 512);
            int[] outShape = outputTensor.getShape();
            byte[] outBytes = outputTensor.toByteArray();
            Files.write(Path.of("output.raw"), outBytes);
        }

        // Audio WAV execution with raw byte array and sample rate argument
        try (Pipeline audioPipe = Morflow.load("audio_pipeline.morf")) {
            byte[] inputWav = Files.readAllBytes(Path.of("input.wav"));
            MorflowTensor audioOut = audioPipe.runArgs(inputWav, 44100);
            Files.write(Path.of("output.wav"), audioOut.toByteArray());
        }
    }
}

5.4. Rust

The native Rust engine crate (morflow) provides direct access to Payload variants (Image, Audio, Tensor, Data, Scalar) for native pipeline integration.

Cargo DependenciesShell
cargo install morflow
cargo add morflow
Native Pipeline Execution in Rustrust
use core_types::{ColorSpace, Image, Payload, RVec};
use morflow::Morflow;
use std::fs;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 1. Load pipeline from file
    let mut pipeline = Morflow::load("image_pipeline.morf")?;

    // 2. Wrap image buffer into a Morflow Image payload
    let img = image::open("input.png")?.to_rgb8();
    let input = Image::from_u8_hwc(
        &img,
        img.width() as usize,
        img.height() as usize,
        ColorSpace::Rgb,
    ).map_err(|e| e.to_string())?;

    // 3. Execute Morflow pipeline with declared payload
    let outputs = pipeline.run(Payload::Image(input))?;

    // 4. Extract emitted payload and save output
    if let Payload::Image(out) = outputs.into_single()? {
        let bytes = out.to_contiguous_bytes();
        image::save_buffer(
            "output.png",
            bytes.as_slice(),
            out.width() as u32,
            out.height() as u32,
            image::ColorType::Rgba8,
        )?;
    }

    // ----------------------------------------------------
    // Audio DSP Execution (Direct Data Payload)
    // ----------------------------------------------------
    let mut audio_pipe = Morflow::load("audio_pipeline.morf")?;
    let wav_bytes = fs::read("input.wav")?;

    let audio_out = audio_pipe.run(Payload::Data {
        buffer: RVec::from(wav_bytes),
    })?;

    if let Payload::Data { buffer } = audio_out.into_single()? {
        fs::write("output.wav", buffer.as_slice())?;
    }

    Ok(())
}

5.5. DTypes in the Host SDKs

Every SDK passes tensors of all nine dtypes in and returns results with their dtype, and each can send and receive a Composite:

SDKTensor of a DTypeComposite
PythonA NumPy array of that dtype, returned as an array of the same dtype. A float64 array stays f64; morflow.Image and morflow.Audio convert it to f32.Pass a list or tuple, such as pipeline.run([a, b]); a Composite result is a list.
JavaScriptA typed array carries its dtype (Float64Array is f64, BigInt64Array is i64); a Buffer needs { data, shape, dtype }. Results have a dtype and toTypedArray(), toFloat64Array(), toBigInt64Array(), and similar getters.Pass an array, such as pipeline.run([a, b]); a Composite result is an array (in TypeScript, run<MorflowTensor[]>(…)).
JavaMorflowTensor.fromDoubleArray, fromLongArray, fromIntArray, fromShortArray, fromFloatArray, fromByteArray, or fromDirectBuffer(buffer, shape, "u32") for the others. Read results with getDtype() and toDoubleArray(), toLongArray(), and similar.Pass MorflowTensor.composite(a, b); a Composite result has isComposite() and getItems().
RustTensor::from_vec_of(values, shape) for any element type; read with to_vec_of::<T>() and dtype.name().Payload::Composite(RVec::from(vec![...]))

An unknown dtype name is an error. In Python, a plain list of numbers is a Composite of numbers rather than a tensor, so build tensors with np.array. Each example below runs two_tensor.morf from Section 3.7 on two i32 tensors:

Two-Tensor Arithmetic in Pythonpython
import numpy as np
import morflow

pipeline = morflow.load("two_tensor.morf")
a = np.array([[1, 2, 3], [4, 5, 6]], dtype=np.int32)
b = np.array([10, 20, 30], dtype=np.int32)

# A list is sent as a Composite, so [a, b] feeds add
total = pipeline.run([a, b])
print(total.dtype, total)  # int32 [[11 22 33] [14 25 36]]
Two-Tensor Arithmetic in Node.jsjavascript
import morflow from 'morflow';

const pipeline = morflow.load('two_tensor.morf');
const a = { data: new Int32Array([1, 2, 3, 4, 5, 6]), shape: [2, 3] };
const b = new Int32Array([10, 20, 30]);  // a typed array carries its dtype

// An array is sent as a Composite
const total = await pipeline.run([a, b]);
console.log(total.dtype, total.toInt32Array());  // i32 Int32Array(6) [11, 22, 33, 14, 25, 36]
Two-Tensor Arithmetic in Javajava
try (Pipeline pipeline = Morflow.load("two_tensor.morf")) {
    MorflowTensor pair = MorflowTensor.composite(
        MorflowTensor.fromIntArray(new int[]{1, 2, 3, 4, 5, 6}, new int[]{2, 3}),
        MorflowTensor.fromIntArray(new int[]{10, 20, 30}, new int[]{3}));
    MorflowTensor total = pipeline.run(pair);
    System.out.println(total.getDtype() + " " + Arrays.toString(total.toIntArray()));  // i32 [11, 22, 33, 14, 25, 36]
}
Two-Tensor Arithmetic in Rustrust
use morflow::{Morflow, Payload, RVec, Tensor};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut pipeline = Morflow::load("two_tensor.morf")?;
    let a = Tensor::from_vec_of(vec![1i32, 2, 3, 4, 5, 6], vec![2, 3]).map_err(|e| e.to_string())?;
    let b = Tensor::from_vec_of(vec![10i32, 20, 30], vec![3]).map_err(|e| e.to_string())?;

    // A Composite holds the two tensors in order
    let pair = Payload::Composite(RVec::from(vec![Payload::Tensor(a), Payload::Tensor(b)]));
    if let Payload::Tensor(total) = pipeline.run(pair)?.into_single()? {
        println!("{} {:?}", total.dtype.name(), total.to_vec_of::<i32>());  // i32 Some([11, 22, 33, 14, 25, 36])
    }
    Ok(())
}

Section 6

6. Plugins

Most Morflow actions include all the code they need to run, so you can use them without installing a plugin. However, when several actions need the same functionality, they can share it through a plugin rather than include a separate copy in every action binary.

6.1. What a Plugin Does

A plugin is a shared binary that provides functionality to the actions that depend on it. When those actions run, they call the plugin's functions, which may perform the work directly or use an external library installed on your machine. You still call the actions in your .morf pipeline as usual, while the actions handle their interaction with the plugin.

Because plugins are installed separately from actions, your pipeline must declare which plugin version to use. Each action specifies the versions it supports, and Morflow checks your selection against those requirements to ensure that the plugin is compatible with every action that needs it.

6.2. Use a Plugin in a Pipeline

Add a plugin declaration before your flows, then import the actions you want to use. The example below selects a plugin and calls an action that depends on it:

Declare a pluginmorf
plugin opencv-bridge/0.1.3
from image_opencv/0.1.3 import resize

accept Tensor[480,640,3] $image
$image >> resize(320,240) >> emit

Always include a version in both the plugin declaration and the action import. You can select an exact release, such as 0.1.0, or explicitly write latest. A pipeline selects one version of each plugin. Morflow checks that version against the requirements of the imported actions.

Run prep to download the published plugin and action binaries for your platform. Then run check to inspect the pipeline before executing it:

Prepare and check the pipelineshell
morflow prep pipeline.morf
morflow check pipeline.morf

After preparation, load and run the pipeline through your usual Morflow binding. The published binaries are ready to use; you do not need to build them yourself.

System dependencies

Some plugins need additional shared libraries on the machine that runs the pipeline. For example, the openblas plugin shares numerical routines across the BLAS action packs and loads a system OpenBLAS installation. Follow that plugin’s installation instructions to choose compatible versions for your operating system. Morflow preparation installs the plugin binary; install any required system libraries separately. Missing or incompatible libraries are reported when the action tries to use the plugin during execution.

The opencv-bridge plugin works the same way, but each published binary loads one specific OpenCV version, because OpenCV's shared libraries change name with every minor release. Version 0.1.3 needs OpenCV 4.6 on Linux (as shipped by Ubuntu 24.04), and OpenCV 4.14 from Homebrew on macOS or from vcpkg on Windows. With any other OpenCV version, such as on Fedora or Arch, build the plugin from source against your installation. The plugin guide lists the exact packages and build steps.

6.3. Preparation, Checking & Execution

During preparation

morflow prep reads your declarations and finds the requested releases. It checks that the plugin versions are compatible with the actions, downloads the binaries, and verifies their checksums before saving them locally. If a required dependency cannot be prepared, the command reports an error.

During checking and loading

morflow check and pipeline loading use those saved binaries without network requests. They verify the files and select the versions the pipeline will use. Shape checking does not load the plugin or its external libraries. You can therefore check and load a prepared pipeline on a machine without those external libraries installed.

During execution

During processing, actions access the plugin version selected when the pipeline was loaded. The engine loads that binary when an action first requests one of its functions. Later calls reuse the loaded binary and function.

6.4. Manage Plugins and Versions

Find, install, and inspect pluginsshell
morflow plugins search opencv
morflow plugins install opencv-bridge/0.1.3
morflow plugins list
morflow plugins clean

Use plugins search to find a plugin in the shipped catalog. Use plugins install when you want to install one without preparing a pipeline. plugins list shows what is installed, and plugins clean removes prepared entries. The CLI reference explains the options for each command.

Plugins are saved in ~/.morflow/plugins by default, separately from actions. Set MORFLOW_PLUGINS_PATH to use another directory. You can also pass --plugins-path to prep and check.

An exact version stays tied to that release. Each time you prepare or install latest, Morflow checks for the newest stable release. Reload a pipeline to use the refreshed version; an already loaded pipeline keeps its selected binary, even after the prepared cache entry is cleaned.

Section 7

7. Custom Action

A custom action is a Rust shared library that you import and call from a .morf pipeline. You describe which payloads it accepts, check the input shape and arguments, and implement the transformation. Morflow calls these functions for you, including the shape check before each execution.

7.1. Create an Action

In a Morflow checkout, create actions/custom_pack/custom_action/Cargo.toml and actions/custom_pack/custom_action/src/lib.rs. The folder custom_pack is the pack name; the Cargo package name custom_action is the action name. The Cargo version is the version you will import.

Cargo.tomltoml
[package]
name = "custom_action"
version = "0.1.0"
edition = "2021"

[lib]
crate-type = ["cdylib"]

[dependencies]
core_types = { package = "morflow-core-types", version = "0.4.3" }

Add "actions/custom_pack/custom_action" to the root Cargo workspace’s members list. cdylib tells Cargo to build a library that Morflow can load. The dependency above uses the published morflow-core-types package under the name core_types, which is also used by the Rust code below.

Start with this complete pass-through action. It accepts a Tensor and returns it with the same shape. The four exported functions are the action’s public interface; dimensions is an ordinary Rust helper:

src/lib.rsrust
// actions/custom_pack/custom_action/src/lib.rs
use core_types::{ActionArgs, DataType, InputDescriptor, Payload, PreparedData,
                 Shape, ShapeCheckResult, ShapeResult};
use core_types::shapecheck::{self, PreparedArgs};

#[no_mangle]
pub extern "C" fn get_input_type() -> DataType { DataType::Tensor }
#[no_mangle]
pub extern "C" fn get_output_type() -> DataType { DataType::Tensor }

fn dimensions(input: Shape, _: PreparedArgs) -> ShapeResult {
    ShapeResult::Ok(input)
}

#[no_mangle]
pub extern "C" fn shapecheck(input: InputDescriptor, args: ActionArgs) -> ShapeCheckResult {
    shapecheck::analyze(input, args, "custom_action", get_input_type(),
                        get_output_type(), Some(dimensions), None)
}

#[no_mangle]
pub extern "C" fn process(payload: Payload, _prepared: PreparedData) -> Payload {
    // Pass-through example; replace with a transformation of the same shape.
    payload
}

The engine requires all four exports: get_input_type, get_output_type, shapecheck, and process. Keep the shown signatures and #[no_mangle] attributes. To accept several payload kinds, combine their DataType values with |.

7.2. How the Engine Runs an Action

Static checking — each action

Check declared shapes and available arguments without running process.

Static shapecheck flowchartDeclared input enters shapecheck. Ready marks the action Verified; Deferred marks Runtime check and records unresolved reasons. Both carry predicted output to the next action. Invalid reports an error and fails static checking.ReadyDeferredInvalidDeclared input shapeor predicted outputshapecheckResult?Mark VerifiedMark Runtime checkRecord unresolvedreasonsStatic check failsReport errorUse predicted outputto check next action

Repeat for every action. The report includes each result and the overall shape safety percentage.

Runtime — each action call

Check actual input before processing, then verify the returned output.

Runtime shapecheck flowchartActual input enters shapecheck. Ready calls process with payload and prepared data. Deferred or Invalid returns an error without calling process. Processing failure returns a processing error. Successful processing verifies output against the predicted type and shape. A match continues to the next action; a mismatch returns an output contract error.ReadyDeferred / InvalidSuccessFailureYesNoActual inputshapecheckResult?processPayload +prepared dataVerify outputType +predicted shapeMatches?Next actionReturn errorProcess is not calledProcessing errorOutput contract error

Repeat for every action execution, including every loop iteration.

FunctionWhen calledResponsibility
get_input_type
get_output_type
When the action is loaded.Declare accepted and produced payload kinds.
shapecheck(input, args)During CLI checking with declared shapes; again before every execution with actual dimensions and metadata.Check the input type, shape, and arguments. Describe the output shape and provide any data needed by processing.
process(payload, prepared)At runtime, only after a Ready result.Read and transform the payload. Return the output promised by shapecheck, or Payload::Error with a useful message.

During morflow check, shapecheck receives the declared shapes and available arguments. It predicts the output so Morflow can check the next action. process is not called at this stage.

When the pipeline runs, Morflow calls shapecheck again with the actual input dimensions, metadata, and resolved arguments. A Ready result allows process to run. An Invalid or Deferred result stops that call and reports an error. After processing, Morflow checks that the returned payload matches the predicted type, shape, and Composite structure.

The engine passes prepared automatically. Pipeline authors still write a normal call such as custom_action or custom_action(axis=1). Prepared data from static checking is discarded; each runtime call gets fresh data, including calls inside parallel loops.

7.3. Write the Shape Check

shapecheck receives two arguments. InputDescriptor describes the input’s type and shape, plus properties such as tensor dtype, image layout, and audio sample rate when available. ActionArgs contains positional and named arguments. The descriptor does not contain tensor elements, image pixels, audio samples, or encoded file contents.

Use the same rules for static and runtime checking. Check ranks, compatible dimensions, component counts, axis bounds, and arguments that affect the operation. If a dimension or argument is unknown, preserve whatever output information you can still determine.

Return valueWhen to use itWhat Morflow does
ShapeCheckResult::ReadyThe available input information and arguments establish that the call is valid. Supply its output shape and prepared data.Counts the static call as Verified. At runtime, passes the prepared data to processing.
ShapeCheckResult::DeferredThe call may be valid, but needs dimensions, metadata, or argument values that are not available yet. Supply the predicted output and unresolved reasons.Shows Runtime check in the static report and carries the partial output shape forward.
ShapeCheckResult::InvalidThe known inputs or arguments are incompatible. Supply a specific reason.Fails static checking or stops the runtime call before processing.

For example, reshaping Tensor[2,3] to Tensor[3,2] has matching element counts. Reshaping it to Tensor[4,2] is invalid. With Tensor[*,3], the input element count must be checked at runtime, but the requested output can still be described as Tensor[3,2].

In the pass-through example, shapecheck::analyze checks the accepted payload kind, calls dimensions, and creates the result and prepared data. Pass a single-shape helper as its Some(dimensions) argument, or a helper for a full Composite shape tree as its final argument. This helper suits actions whose validity depends on dimensions and arguments. Write a custom shapecheck body when you also need metadata or additional checks.

Keep this function free of processing and side effects: it may run while a pipeline is only being inspected, and it may run concurrently. Give errors concrete explanations, such as “axis 3 is outside a rank-2 tensor” or “left columns 3 do not match right rows 4.”

7.4. Pass Checked Data to Processing

process(payload, prepared) receives the actual payload and the data returned by that call’s successful shape check. Put shape compatibility rules in shapecheck, then use the checked results here to perform the transformation.

Prepared dataUse
prepared.outputThe predicted output shape, including ordered Composite components.
prepared.output_dims()Get concrete dimensions for a single output when allocating or reshaping it.
prepared.argsRead positional or named arguments and reuse cached numeric parsing through parse and usize_list.
prepared.fieldsStore action-specific results of checking, such as a normalized axis. Fields are named PreparedValue values; read them with field, unsigned, or float.

A custom shape check returns Ready with a PreparedData containing the output prediction, PreparedArgs::from(args), and any named fields. Initialize its runtime field with None.into(); the engine supplies the runtime context before processing. Use the same output prediction in both the result and the prepared data. PreparedValue supports integers, floating-point values, booleans, text, lists, and nested named fields.

For an action with an axis argument, resolve negative indices and check bounds once in shapecheck, store the normalized axis in a field, and use that field in process. The pipeline author does not have to supply or manage this data.

Checks that depend on actual contents still belong in processing: decoding a file, checking a numerical domain, or detecting a singular matrix. Return Payload::Error("useful explanation".into()) if processing fails. Shape verification describes the call’s type and shape compatibility; it does not promise that every possible data value will succeed.

7.5. Handle Composite Inputs and Outputs

A Composite holds an ordered list of payloads. Its shape description is also an ordered list, and can contain nested Composites. An action that accepts Composite inputs should declare DataType::Composite, check the component count and each component’s kind, then read their shapes in order.

Use input.value.get(0) for the first component and input.value.get(1) for the second. These return optional references so you can report a missing component clearly. Metadata uses the same ordering through input.metadata.get(index). In processing, match Payload::Composite(items) and use the corresponding indices.

For matrix multiplication, component 0 is the left operand and component 1 is the right operand. Check their shared inner dimension and predict the result’s outer dimensions. For an action that returns several results, return ValueShape::Composite from checking and Payload::Composite from processing in the same order.

For example, QR returns Q first and R second. Describing both output shapes lets a pipeline select $parts[0] or $parts[1] and have downstream actions checked against the selected component’s shape.

7.6. Build, Package & Import

Build the action and package the resulting library into an action cache. The packaging tool reads the action name and version from Cargo.toml and the pack name from its parent folder. Run these commands from the Morflow repository root on Linux:

Local action installationshell
cargo build --release -p custom_action
python3 scripts/package_action.py actions/custom_pack/custom_action/Cargo.toml \
  target/release/libcustom_action.so --cache ./actions_cache
export MORFLOW_ACTIONS_PATH="$PWD/actions_cache"
Use your custom actionmorf
from custom_pack/0.1.0 import custom_action
accept Tensor[2,3] $input
$input >> custom_action >> emit

On macOS, use target/release/libcustom_action.dylib; on Windows, use target/release/custom_action.dll and set MORFLOW_ACTIONS_PATH using your shell’s environment-variable syntax. Packaging creates the versioned binary, checksum receipt, and offline action catalog. If you add a SPEC.md beside Cargo.toml, it is packaged with the action too. Packaging also writes <action>_METADATA.json with its plugin requirements. Publish that metadata file and its checksum alongside the binary, including for actions whose plugin list is empty.

The Linux cache entry is actions_cache/custom_pack/custom_action_action-0.1.0-linux-x86_64.so, with its receipt at the same path plus .json. Import the packaged version explicitly, as above. Morflow loads from the local cache without network access. After changing the action, rebuild and package it, then reload the pipeline to use the new binary.

7.7. Test the Action

Save the import example as custom_pipeline.morf. Check it with the same action cache you will use for execution:

Check your pipelineshell
cargo test -p custom_action
cargo run -p morflow -- check custom_pipeline.morf

For runtime unit tests, call core_types::shapecheck::execute("custom_action", shapecheck, process, payload). This runs the same shape-check, processing, and output-verification sequence as the engine. Calling process directly only tests processing and requires you to supply prepared data yourself.

Cover valid concrete shapes, incompatible shapes, and dynamic declarations. Check that invalid inputs are rejected before processing, that partial shapes retain any known rank and dimensions, and that runtime outputs match the prediction. For Composite actions, also test missing components, incorrect kinds, and component ordering.

Finally, load the example pipeline through a binding and run it with a matching Tensor. Try Tensor[*,3] in the declaration as well: the static report should identify unresolved dimensions, while execution checks the actual dimensions supplied by the host.

7.8. Declare Plugin Requirements

If your action uses a plugin, declare the dependency in both its packaging metadata and its exported interface. Pipeline authors then select a compatible plugin version with a plugin name/version declaration. Actions that do not use plugins need no additional export.

Declare the dependency in Cargo.toml

Add one entry per required plugin. The version here is a supported semantic version range, rather than the exact version selected by the pipeline. For example, ^0.1.0 accepts compatible releases from 0.1.0 up to, but excluding, 0.2.0.

Cargo.toml — plugin requirementtoml
[[package.metadata.morflow.plugins]]
name = "opencv-bridge"
version = "^0.1.0"

Export the same requirement from the action

The engine reads get_required_plugins when it loads the action and verifies that its requirements match the packaged receipt. Keep the exported names and ranges identical to Cargo.toml. Define this export inside each action that requires the plugin.

src/lib.rs — additional exportrust
#[no_mangle]
pub extern "C" fn get_required_plugins()
    -> core_types::RVec<core_types::plugins::PluginRequirement> {
    vec![core_types::plugins::PluginRequirement {
        name: "opencv-bridge".into(),
        version: "^0.1.0".into(),
    }].into()
}

Access the plugin during processing

After a successful runtime shape check, the engine provides the selected plugins through prepared.runtime. Call the plugin through a private, typed wrapper inside the action’s process implementation. For example, an OpenCV action’s processing code requests morflow_opencv_process from the declared opencv-bridge plugin and calls it using the agreed native signature. The action and plugin compile the same plugin-owned interface definition, which specifies the operation identifiers, parameter layout, and function signature.

At the lower level, RuntimeContext::symbol(plugin_name, function_name) returns a native function address or an error. Converting that address into a callable function is unsafe and must use the plugin’s exact documented signature. Keep this conversion and buffer handling in a private wrapper inside the action, then return a useful Payload::Error if plugin access or processing fails.

Keep plugin lookup and external-library checks out of shapecheck. That function checks the input description and arguments; it must work on a machine without the external library. Initialize PreparedData.runtime with None.into() when constructing checked data. The engine fills it before processing, so pipeline authors do not pass this context themselves.

Package and test the dependency

The action packaging script includes the Cargo plugin requirements in the artifact receipt and <action>_METADATA.json. Publish the metadata and its checksum with the action binary. Preparation uses it to reject missing declarations or incompatible plugin versions before installing the required artifacts.

Test the action through a pipeline that declares its plugin. Cover a valid installed plugin, a missing declaration, and an incompatible version. Also verify that checking and loading succeed with a verified plugin artifact but no system library, while execution reports the missing library clearly. Run processing tests with compatible system dependencies and check that outputs match the shape prediction. For plugin-backed actions, the plain shapecheck::execute helper does not supply a runtime context; pipeline integration tests exercise the engine’s plugin setup.