Ami Graph Builder

---
name: ami-graph-builder
description: Domain tips and workflow guidance for building AMI computation graphs via MCP tools. Load when creating/connecting nodes, working with sources or subgraphs, or diagnosing graph issues.
---

# AMI Graph Builder

You are building computation graphs for AMI (Analysis Monitoring Interface), the LCLS-II online data analysis system. You interact with AMI via MCP tools — NOT by generating Python code.

## Workflow (follow this order)

1. Read `ami://graph/sources` — see what data is available from the experiment
2. Read `ami://subgraph-templates` — check if a template already does what's needed
3. If template exists → `import_subgraph`, connect source to boundary inputs, done
4. If not → build incrementally: `ensure_source` → `create_node` → `connect_nodes`
5. Always finish with: `validate_graph` → `apply_graph` → `get_graph_errors` → `auto_layout`

## Verification (MANDATORY — never skip)

After all nodes are connected, always run this sequence before responding to the user:

### 1. Structural check
Call `validate_graph()`. It returns:
- `{"ok": true, "issues": []}` → no problems, continue
- `{"ok": false, "issues": ["Node 'X' has disconnected required input 'Y'"]}` → fix each issue, then call `validate_graph()` again

### 2. Submit to workers
Call `apply_graph()`. This submits the graph to AMI workers for execution. It is fire-and-forget and returns `{"status": "applied"}`.

### 3. Check runtime errors
Call `get_graph_errors()`. It returns:
- `{"ok": true, "errors": []}` → graph is running cleanly
- `{"ok": false, "errors": [...]}` → runtime issues (type mismatches, missing data, node exceptions). Fix and re-apply.

### 4. Arrange layout
Call `auto_layout()` to arrange nodes neatly in the GUI.

### 5. Report to user
Tell the user:
- Which nodes were created (name + type)
- Which connections were made
- Any manual steps required (e.g., ROI drawing, PythonEditor code)
- Any warnings from `get_graph_errors`

### Optional: Confirm graph structure
For complex graphs (3+ nodes), call `get_graph_state()` to confirm expected nodes and connections exist before reporting done. It returns `{"nodes": [...], "connections": [...], "sources": {...}}`.

### Optional: Confirm data is flowing
Call `list_features()` to see what outputs have live data, then `fetch_data("FeatureName")` to sample a value. Use this if the user wants to verify the graph is producing results, or if `get_graph_errors` reported issues.

## Source Terminal Naming (CRITICAL)

Source node terminals are always named "Out".

    WRONG:   connect_nodes("cspad", "cspad", "Mean.0", "In")
    CORRECT: connect_nodes("cspad", "Out", "Mean.0", "In")

Source nodes always have a single output terminal named "Out", regardless of the source name.

## Node Naming

AMI assigns unique names: BinningNode.0, BinningNode.1, ScatterPlot.0, etc.
Always use the `node_name` returned by `create_node` — never assume the suffix.

## Sources Are Self-Displaying

SourceNodes have built-in viewers. When a user clicks a source node in the GUI:
- Scalar → ScalarWidget
- 1D array → WaveformWidget
- 2D array → ImageWidget

DO NOT create display nodes just to view raw source data.
Only create display nodes for PROCESSED results (after Mean, Sum, ROI, etc.).

If user says "show me the detector" — just `ensure_source("detector_name")` and tell them to click it.

## When to Use Which Node

| User wants... | Use this node | Key inputs |
|---|---|---|
| X vs Y correlation | ScatterPlot | X, Y (both float or Array1d) |
| Value over time | ScalarPlot | In (float) |
| 1D spectrum/profile | LinePlot | X, Y (both Array1d) |
| 2D image of processed data | ImageViewer | In (Array2d) |
| Simple arithmetic (x*2+5, a/b) | Calculator | In (float/Array1d/Array2d) |
| Boolean filter (x > 100) | Filter | In (Any) |
| Histogram | Binning | In (float/Array1d/Array2d) |
| ROI on 2D detector | Roi2D | In (Array2d) |
| Mean of signal | Average0D / Average1D / Average2D | In (match dimensionality) |
| Scan analysis (mean vs step) | MeanVsScan | Bin (float), Value (float) |
| Numpy/scipy transforms, custom logic | PythonEditor | (user writes code in GUI) |

When unsure which node to use, query `ami://node-types` for the full list with terminal specs.

## Display Nodes Are Self-Viewing

ScatterPlot, LinePlot, ScalarPlot, Histogram, Histogram2D, ImageViewer —
these all open their own plot window automatically. No extra viewer needed after them.

## ROI Workflow

ROI nodes (Roi2D, Roi1D) require manual interaction after creation:
1. Create the ROI node and connect the detector source to it
2. Tell the user they MUST click the source node and draw the ROI rectangle in the GUI
3. Only after the ROI is drawn will data flow through the ROI output

Always warn the user about this step — it's not something the agent can do remotely.

## Common Patterns

### Scalar monitoring
```
ensure_source("laser_power") → create_node("ScalarPlot") → connect(source→In)
```

### X vs Y correlation
```
ensure_source(A) + ensure_source(B) → create_node("ScatterPlot") → connect(A→X, B→Y)
```

### ROI intensity tracking
```
ensure_source("detector") → create_node("Roi2D") → create_node("Sum") → create_node("ScalarPlot")
connect: detector→Roi2D.In, Roi2D.Out→Sum.In, Sum.Out→ScalarPlot.In
```

### Azimuthal integration
```
ensure_source("detector") → create_node("RoiArch") → create_node("LinePlot")
connect: detector→RoiArch.In, RoiArch.Bins→LinePlot.X, RoiArch.Counts→LinePlot.Y
(RoiArch geometry must be configured in GUI)
```

### Scan analysis
```
ensure_source("motor") + ensure_source("signal")
→ create_node("MeanVsScan")
connect: motor→MeanVsScan.Bin, signal→MeanVsScan.Value
→ create_node("LinePlot")
connect: MeanVsScan.Bins→LinePlot.X, MeanVsScan.Counts→LinePlot.Y
```

## Labels

Use descriptive Title Case labels when creating nodes:
- Good: "Laser Vs Detector Correlation", "CSPAD Signal Region", "ROI Total Counts"
- Bad: "node1", "my_plot", "ScatterPlot for data"

## Type Compatibility

Check `ami://node-types` for terminal types before connecting. Common rules:
- float sources → float inputs (ScalarPlot.In, Calculator.In, MeanVsScan.Value)
- Array2d sources → Array2d inputs (Roi2D.In, ImageViewer.In, Projection.In)
- Array1d → Array1d inputs (LinePlot.Y, FFT.In, Average1D.In)
- ScatterPlot accepts float or Array1d on both X and Y

If types don't match, you need a conversion node in between.

## Subgraph Boundaries

When you import a subgraph template:
- It has **boundary inputs** — connect external sources to these
- It has **boundary outputs** — connect these to display nodes or downstream processing
- The `import_subgraph` tool returns the boundary terminal names

## Configuring Calculator and Filter

These nodes require expressions/conditions set AFTER connecting inputs.
Expression variables are the **connected wire names** (e.g., `cspad.Out`), NOT terminal names.

### Calculator Workflow
1. Create Calculator node and connect inputs
2. Call `get_node_inputs("Calculator.0")` to see available variable names
3. Call `set_calculator_expression("Calculator.0", "cspad.Out * 2 + 5")`

Expression examples (simple arithmetic only):
- Single input: `"cspad.Out * 2 + 5"`
- Two inputs: `"cspad.Out / laser.Out"` (need `add_node_terminal` for second input)

For numpy/scipy operations (np.sqrt, np.mean, etc.) use PythonEditor instead — it is more reliable and readable for complex expressions.

### Filter Workflow (Event Code Filtering)
1. Create Filter node
2. Add extra input terminal if needed: `add_node_terminal("Filter.0", "In.1", "in", "Any")`
3. Connect sources (e.g., laser event code + detector)
4. Call `get_node_inputs("Filter.0")` to see variable names and output terminals
5. Call `set_filter_conditions("Filter.0", conditions)` with JSON:

```json
{
  "If": {
    "condition": "laser.Out == 1",
    "Filter.0.Out": "cspad.Out"
  },
  "Else": {
    "Filter.0.Out": "None"
  }
}
```

This passes cspad images through only when laser is on (event code == 1).

### Adding Extra Terminals
```
add_node_terminal("Calculator.0", "In.1", "in", "float")  # extra Calculator input
add_node_terminal("Filter.0", "In.1", "in", "Any")        # extra Filter input
add_node_terminal("Filter.0", "Out.1", "out", "Any")      # extra Filter output
```

## Common Pitfalls

### Stack Nodes Need Sequence Inputs
Stack1d and Stack2d expect list/tuple inputs, not single scalars. Connect them to collection nodes:
- `timestamp → PickN (N=5) → Stack1d` ✓
- `timestamp → Stack1d` ✗ (will fail: "arrays to stack must be passed as a sequence type")

### CurveFit Variables Must Include Independent Variable
When using CurveFit, include the independent variable first in the `variables` parameter:
- `variables="x,a,b"` for function `f="a*x+b"` ✓
- `variables="a,b"` ✗ (will fail: lambdify argument mismatch)

### Calculator/Filter Must Be Connected Before Configuring
Expression variables are the connected wire names (e.g., `cspad.Out`), not terminal
names (`In`). Always: connect inputs → call `get_node_inputs()` → then set expression/conditions.

### Accumulator/PythonEditor Nodes
These nodes work out-of-the-box with default templates for MCP usage. Custom code requires GUI editor interaction.

### Calculator Is for Simple Arithmetic Only
Use Calculator for basic math (addition, subtraction, multiplication, division, comparisons).
For numpy or scipy functions, use PythonEditor — it handles complex expressions more reliably.
- `"cspad.Out * 2 + offset.Out"` ✓ Calculator
- `"np.sqrt(cspad.Out)"` ✗ Calculator → use PythonEditor

## Node Configuration

Most nodes have configurable parameters (bin counts, sigma values, axis settings, etc.).

### Reading current parameters
```
get_node_parameters("GaussianFilter1D.0")
# Returns: {"node": "GaussianFilter1D.0", "parameters": {"sigma": 1.0, "axis": -1}}
```

### Setting parameters
```
set_node_parameters("GaussianFilter1D.0", {"sigma": 2.0, "axis": 0})
# Returns: {"node": "GaussianFilter1D.0", "parameters": {"sigma": 2.0, "axis": 0}}
```

Use `get_node_parameters` first to see what parameters are available and their current values before making changes. After `set_node_parameters`, call `apply_graph()` for the change to take effect.

Calculator and Filter nodes have dedicated tools (`set_calculator_expression`, `set_filter_conditions`) — use those instead for expression/condition changes.

## Graph Management

### Save and load
```
save_graph("/path/to/graph.fc")   # save current graph to file
load_graph("/path/to/graph.fc")   # load graph from file (replaces current)
clear_graph()                      # remove all nodes (use with caution)
```

### Creating subgraphs
To group existing nodes into a visual subgraph container:
```
create_subgraph(["PythonEditor.0", "Average2D.0"], "Jungfrau Processing", "Description here")
# Returns: {"subgraph_name": "Jungfrau Processing", "terminals": {...}}
```

Source nodes are automatically excluded. Boundary terminals are auto-detected from existing cross-boundary connections.

To inspect an existing subgraph's terminals:
```
list_subgraphs()                              # list all subgraphs with child nodes
list_subgraph_terminals("Jungfrau Processing") # detailed boundary terminal info
```

To save a subgraph as a reusable template:
```
export_subgraph("Jungfrau Processing", "/path/to/template.fc")
```

## Error Recovery

All MCP tools return helpful error context:
- Wrong node type → response includes available types
- Wrong terminal name → response includes available terminals for that node
- Source doesn't exist → response includes available sources

Use this feedback to self-correct. Don't guess — read the error response.

### Removing nodes and connections
If a node was created incorrectly or a connection is wrong:
```
delete_node("BinningNode.0")              # removes node and all its connections
disconnect_nodes("cspad", "Out", "Mean.0", "In")  # removes a single connection
remove_node_terminal("Calculator.0", "In.1")      # removes a user-added terminal
```

Always `validate_graph()` after making corrections to confirm the issue is resolved.

## Performance Monitoring

If a graph change causes performance degradation (GUI updates slowing, latency growing,
high processing time), refer to the AMI Performance Monitor skill for Grafana MCP tool
patterns — diagnosing whether graph execution time, send backpressure, or worker
starvation is the bottleneck using Prometheus metrics and Tempo distributed traces.
That guidance is available via the `ami-performance-monitor` skill.

Key signal after `apply_graph`: if `ami_event_time_secs{type="Datagram"}` or
`ami_heartbeat_latency_seconds` increases significantly, the new graph operations may
be too expensive.