AttractorEx is the standalone pipeline engine embedded in this Phoenix project. It implements a practical, execution-oriented subset of the strongDM Attractor specification and extends it with an HTTP control plane, human-in-the-loop adapters, a unified LLM client layer, and a coding-agent session model.
What It Does
At a high level, AttractorEx turns DOT graphs into executable workflows:
- Parse a DOT graph into a normalized runtime model.
- Validate structural, routing, and handler-specific constraints.
- Execute nodes from
starttoexit. - Route across edges by condition, status, preferred labels, or suggested next IDs.
- Persist status artifacts, checkpoints, and per-stage outputs.
Architecture
The library is organized into a small set of focused layers:
| Layer | Main modules | Responsibility |
|---|---|---|
| Entry points | AttractorEx, AttractorEx.Engine | Public API and execution orchestration |
| DOT model | AttractorEx.Parser, AttractorEx.Graph, AttractorEx.Node, AttractorEx.Edge | Parse and normalize the graph |
| Validation | AttractorEx.Validator, AttractorEx.Condition, AttractorEx.ModelStylesheet | Linting, schema checks, and selector-based styling |
| Runtime handlers | AttractorEx.HandlerRegistry, AttractorEx.Handlers.* | Node execution semantics |
| Human gates | AttractorEx.HumanGate, AttractorEx.Interviewer, AttractorEx.Interviewers.* | wait.human workflows and answer normalization |
| HTTP service | AttractorEx.HTTP, AttractorEx.HTTP.Manager, AttractorEx.HTTP.Router | Remote pipeline execution and SSE updates |
| Phoenix adapter | AttractorExPhx, AttractorExPhx.Client, AttractorExPhx.HTTPServer | Phoenix-facing integration seam over the standalone engine |
| Unified LLM | AttractorEx.LLM.* | Provider-agnostic completion and streaming |
| Agent loop | AttractorEx.Agent.* | Spec-inspired coding-agent session primitives |
Core Execution Flow
AttractorEx.run/3 follows the same broad lifecycle documented in the upstream spec:
- Parse DOT input.
- Apply built-in and custom graph transforms.
- Validate the transformed graph.
- Create a run directory and manifest.
- Execute node handlers one step at a time.
- Write
status.jsonandcheckpoint.jsonartifacts. - Emit structured events for observers and the HTTP service.
Output Artifacts
Each run writes runtime artifacts under the configured logs root:
manifest.jsonfor run metadata.checkpoint.jsonfor resumable state.status.jsonfor per-stage and final outcome serialization.- Handler-specific files such as
prompt.md,response.md, and tool hook logs.
Reading The Docs
The rest of this documentation is structured to match how the code is used:
- Pipeline Engine for graph execution semantics.
- Human-in-the-Loop for
wait.humanflows. - HTTP API for service mode and transport contracts.
- Agent Loop for coding-agent session primitives.
- Spec Alignment for implementation status against the upstream documents.
For source-level details, browse the grouped module documentation in the sidebar.