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)
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 node and follows the white wires through your logic.
- Data flow (colored circle ports) — Passes values between nodes. Like variables being read by expressions. Data nodes compute on demand when a downstream node reads their output.
Node Categories
Nodes are split into core nodes (available in all modules) andmodule nodes (framework-specific). Core nodes include:
| Category | Examples | Description |
|---|---|---|
| Flow Control | Branch, Sequence, ForEach, Gate | Conditionals, loops, execution ordering |
| Math | Add, Subtract, Multiply, Divide, Modulo | Arithmetic operations |
| Compare | Equal, Greater Than, Less Than | Comparisons returning true/false |
| Logic | And, Or, Not | Boolean logic |
| Values | Literal, Random Int, Random Float | Constants and random values |
| Properties | Get Property, Set Property | Read/write data on objects |
Module nodes appear in the context menu under the module name. Each module defines a coreWhitelist that controls which core nodes appear in its palette — only whitelisted core nodes with codegen support for that module are shown. 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