Pipelines
Multi-stage, multi-step processing chains with a visual editor. The core execution unit of MechaMental.
Pipelines (formally called Augmentations) are the primary way to orchestrate AI workflows in MechaMental. A pipeline defines a sequence of stages, where each stage contains one or more steps that execute in order.
Pipeline Editor
The pipeline editor provides a visual canvas for building and configuring your workflows.
- Stages are displayed horizontally from left to right, each rendered as a card (280px wide)
- Steps within each stage are listed vertically inside the stage card
- Steps are draggable — reorder them within a stage or move them between stages
- The editor top bar provides actions for creating endpoints and managing pipeline settings
Pipeline Structure
Pipeline (Augmentation)
├── Stage 1 ──────────► Stage 2 ──────────► Stage 3
│ ├── Step A ├── Step D ├── Step F
│ ├── Step B └── Step E └── Step G
│ └── Step C- Pipeline — the top-level container, associated with an app
- Stage — a group of related steps that execute as a unit
- Step — an individual operation (inference, tool call, memory query, etc.)
Creating a Stage
Click Add Stage on the pipeline canvas to open the Create Stage dialog:
- Name (required) — a descriptive name for the stage
- Description (optional) — explain the purpose of this stage
Stage Detail Dialog
Click on a stage header to open the stage detail dialog with these tabs:
| Tab | Contents |
|---|---|
| General | Name, description, and execution mode (Sequential or Parallel) |
| Advanced | Stage Gate configuration — conditions that must be met before the stage executes |
Execution Modes
Each stage can run its steps in one of two modes:
- Sequential — steps execute one after another, in the order they appear
- Parallel — all steps in the stage execute simultaneously
Step Types
Each step performs a specific operation. When adding a step, choose from the dropdown which displays each type with a descriptive icon.
| Step Type | Description |
|---|---|
inference | Call an LLM with a system prompt, tools, and execution context |
tool_call | Invoke a registered tool or MCP server directly |
source_ingest | Add new documents to a knowledge source programmatically |
source_query | Retrieve source data by semantic or keyword query |
source_get | Fetch a specific source document by ID |
memory_update | Store facts, preferences, or instructions in semantic memory |
memory_query | Retrieve relevant memory entries by semantic search |
artifact_create | Generate and persist an artifact (code, document, image) |
artifact_query | Search for existing artifacts |
artifact_get | Fetch a specific artifact by ID |
thread_update | Save messages to a conversation thread |
thread_query | Retrieve messages from a thread |
approval | Pause execution and wait for human approval before continuing |
transform | Transform data between steps using Jinja2 templates |
Step Detail Dialog
Click on any step to open the step detail dialog. The available tabs depend on the step type:
| Tab | Available For | Contents |
|---|---|---|
| General | All steps | Name, step type, model selection, and basic configuration |
| Config | All steps | Step-specific settings (query templates, document IDs, transform logic, etc.) |
| Prompt | inference only | System prompt editor with Jinja2 template support |
| Tools | inference only | Select which tools the model can call during this inference step |
| Conditions | All steps | Conditional expressions that determine whether the step executes |
| Advanced | All steps | Event action, timeout, error handling, and other advanced settings |
Execution Context
As a pipeline runs, each step's output is stored in an execution context. Subsequent steps can reference previous outputs using Jinja2 template syntax.
Available Context Variables
{# Endpoint request data #}
{{ endpoint.payload.query }}
{{ endpoint.payload.user_id }}
{# Previous step outputs #}
{{ steps.my_inference_step.output }}
{{ steps.source_lookup.results }}
{# Stage-level outputs #}
{{ stages.preprocessing.output }}The context includes:
endpoint.payload— the incoming request bodysteps.<name>— output from any previously executed step (referenced by step name)stages.<name>— aggregated output from a completed stage- Injected knowledge — source data, memory entries, and thread messages loaded by earlier steps
Jinja2 Templates
Prompts, transform steps, and configuration fields all support Jinja2 template syntax. This lets you dynamically compose content based on the execution context.
You are a customer support agent for {{ endpoint.payload.company_name }}.
{% if steps.memory_lookup.results %}
Relevant context from memory:
{% for entry in steps.memory_lookup.results %}
- {{ entry.content }}
{% endfor %}
{% endif %}
User question: {{ endpoint.payload.query }}Template Syntax
MechaMental uses standard Jinja2 syntax. Use {{ }} for variable interpolation, {% %} for control flow (if/for), and {# #} for comments.
Step Conditions
Steps can have conditions configured in the Conditions tab of the step detail dialog. Conditions are expressions evaluated against the execution context that determine whether the step should execute.
Use conditions to skip steps based on:
- Input values from the endpoint payload
- Results from previous steps
- Environment variables or configuration
Keep It Simple
Step conditions let you build conditional logic without complex branching. Instead of creating parallel pipeline paths, use conditions to skip or include steps within a linear pipeline structure.
Stage Gates
Stages support Stage Gate configuration in the Advanced tab of the stage detail dialog. A stage gate defines conditions that must be satisfied before the stage begins execution. This is useful for pipelines where later stages should only run if earlier stages produced valid results.
Events and Streaming
Steps can publish Server-Sent Events (SSE) during execution. The Advanced tab of the step detail dialog includes an event_action setting:
primary— the step emits main response content, streamed to the callersecondary— the step emits cognitive chain / reasoning events, visible in the Cortex chat UI
Version Control
Every change to a pipeline is tracked as a commit with field-level diffs. You can view the full change history, compare versions, and understand exactly what changed between any two points in time. See Releases for how pipelines are packaged for deployment.