Core Concepts
Projects
A project is your workspace. Each framework defines its own project types:
- Mesa — Model (agent-based model) and Simulation (federate multiple models)
- Weave AI — Agent (conversational AI agent) and Server Graph (MCP server with tools and imported agents)
- Full Stack — Full Stack App (compose multiple projects into one deployable application)
Projects auto-save as you work. Each project belongs to one framework, but you can enable any number of libraries (e.g., NetworkX, ChromaDB, SQLAlchemy) to add composable nodes to your canvas.
The Graph Editor
The graph editor is where you build logic visually. It uses a node-and-wire paradigm:
- Nodes — Operations like "Branch", "Add", "Compare", or module-specific actions
- Edges — Wires connecting node ports together
- Ports — Input/output connection points on nodes
Right-click the canvas to open the context menu and browse available nodes. You can also drag from a pin and release on empty canvas to open a filtered context menu showing only compatible nodes — selecting one auto-wires the connection.
Flow Types
There are two types of connections:
- Exec flow (white arrow ports) — Controls the order operations happen. Like lines of code executing top-to-bottom. Every graph starts with an entry-point node (Trigger in Mesa, Entry in Weave AI) and follows the white wires through your logic.
- Data flow (colored shaped ports) — Passes values between nodes. Like variables being read by expressions. Data nodes compute on demand when a downstream node reads their output. Port color indicates the data type passing through the wire. Port shape indicates whether the type is a primitive or a compound (collection) type.
Pin Colors
Every data port is colored by its type. Exec ports are always white.
Primitive Types
| Type | Color | Hex |
|---|---|---|
| int | Cyan | #00cccc |
| float | Green | #00cc00 |
| str | Magenta | #cc00cc |
| bool | Red | #cc0000 |
| any | Gray | #888888 |
| none | Dark gray | #666666 |
Collection Types
| Type | Color | Hex |
|---|---|---|
| list | Orange-yellow | #ffaa00 |
| dict | Pink | #ff88ff |
| tuple | Teal | #00ff88 |
| set | Orange-yellow | #ffaa00 |
Advanced Types
| Type | Color | Hex |
|---|---|---|
| object | Gray | #888888 |
| callable | Purple | #aa00ff |
| generic | Light gray | #cccccc |
Domain Types
Frameworks define their own semantic types that resolve to specific colors:
| Type | Color | Framework |
|---|---|---|
| Agent | Orange #cc8800 |
Mesa |
| AgentSet | Yellow #cccc00 |
Mesa |
| Position | Teal #00ff88 |
Mesa |
| Cell | Blue #00aaff |
Mesa |
| DataFrame | Purple #aa00ff |
Mesa |
| Graph | Blue #3b82f6 |
NetworkX |
| Message | Blue #3b82f6 |
Weave AI |
| Response | Purple #a855f7 |
Weave AI |
| ToolCall | Yellow #eab308 |
Weave AI |
| ToolResult | Amber #f59e0b |
Weave AI |
| ToolInput | Cyan #06b6d4 |
Weave AI (MCP) |
| ToolOutput | Teal #14b8a6 |
Weave AI (MCP) |
Pin Shapes
Port shape tells you whether the data is a single value or a collection. Color and shape are orthogonal — a list[int] port is cyan (int) with a diamond shape (list).
| Shape | Meaning | Example |
|---|---|---|
| Circle | Primitive or object | int, str, bool, Agent |
| Diamond | List | list[int], list[str] |
| Rounded square | Dict | dict[str, float] |
| Triangle | Tuple | tuple[int, int] |
| Hexagon | Set | set[str] |
Exec ports always render as white arrows regardless of shape rules.
Node Categories
Nodes are split into core nodes (available in all modules) and module nodes (framework-specific). Core nodes include:
| Category | Examples | Description |
|---|---|---|
| Flow Control | Branch, Sequence, ForEach, Switch, TryCatch, Parallel | Conditionals, loops, error handling, execution ordering |
| Math | Add, Subtract, Multiply, Divide, Modulo | Arithmetic operations |
| Compare | Equal, Greater Than, Less Than | Comparisons returning true/false |
| Logic | And, Or, Not, Negate | Boolean and numeric logic |
| String Ops | Concat, Split, Replace, Format, Contains | String manipulation |
| Collection Ops | List Length, List Get, List Append, Dict Get | List and dictionary operations |
| Type Conversion | Cast | Convert between types (str, int, float, bool, list, dict) |
| Values | Literal, Get Variable, Set Variable | Constants and named variables |
| Properties | Get Property, Set Property | Read/write data on objects |
Module nodes appear in the context menu under the module name. Modules can also define optional extensions (e.g., Mesa Geo) that add specialized node sets, toggled per project in settings. See the module-specific documentation for details on what nodes are available.
Statement vs Expression Nodes
There are two kinds of nodes:
- Statement nodes — Have exec ports (white arrows) and a solid border. They do things: set a property, move an agent, branch execution. They participate in exec flow.
- Expression nodes — Have no exec ports and a dashed border. They compute values: add two numbers, compare values, read a property. They're evaluated when their output is needed.
Code Generation
When you click Generate, Loom walks your graph and produces Python code. The output files depend on the module, but the generated code always:
- Uses the framework's native API directly
- Has no dependency on Loom
- Can be modified by hand after export