microsoft/amplifier-bundle-attractor

microsoft/amplifier-bundle-attractor

Description: Attractor bundle for the Amplifier project

Language: Python

License: MIT

Stars: 6

Forks: 1

Open issues: 0

Created: 2026-02-13T16:55:39Z

Pushed: 2026-06-11T05:33:58Z

Default branch: main

Fork: no

Archived: no

README:

Attractor

Multi-stage AI pipelines for code. Plan, implement, test, review — orchestrated as directed graphs.

Upstream Attribution and Layering

This bundle implements the attractor nlspec defined at github.com/strongdm/attractor. Community .dot files written against the canonical spec should work without modification.

We extend the spec selectively where high-value additions warrant it. Every extension is backward-compatible and documented in [specs/EXTENSIONS.md](specs/EXTENSIONS.md). If you find behavior that diverges from the canonical spec without an entry in that file, treat it as a bug.

Dependency awareness. Per the Amplifier ecosystem REPOSITORY_RULES.md: this bundle's declared code dependencies are amplifier-core and its own internal modules. It does not reference downstream consumers (resolvers, orchestration platforms, or application bundles). The one documented lineage exception is amplifier-bundle-recipes: attractor is a follow-up to that recipe-bundle work, and specific recipe patterns may be cited as prior-art inspiration where useful.

Documentation

| Guide | Description | |-------|-------------| | [Getting Started](docs/GETTING-STARTED.md) | Installation, first pipeline run, provider selection, common gotchas | | [DOT Authoring Guide](docs/DOT-AUTHORING-GUIDE.md) | How to design effective pipelines -- patterns, attributes, fidelity, stylesheets | | [DOT Syntax Reference](docs/DOT-SYNTAX.md) | Quick reference tables and copy-paste patterns | | [Routing Reference](docs/ROUTING-REFERENCE.md) | Edge selection algorithm, report_outcome tool, condition expressions, common pitfalls | | [App Integration Guide](docs/APP-INTEGRATION-GUIDE.md) | Using pipelines from Python applications (DirectProvider vs AmplifierSession) | | [Pipeline Design Principles](docs/PIPELINE_DESIGN_PRINCIPLES.md) | Six framework-agnostic design principles: tier discipline, validation patterns, loop convergence, LLM output protocols, parameterization, verdict-bearing nodes |

Quick Start

1. Add to your Amplifier config:

# .amplifier/config.yaml (or any bundle that includes this)
includes:
- bundle: git+https://github.com/microsoft/amplifier-bundle-attractor@main#subdirectory=profiles/attractor-profile-anthropic

Pick your provider: attractor-profile-anthropic, attractor-profile-openai, or attractor-profile-gemini.

2. Run a pipeline from the CLI:

amplifier run --agent attractor-profile-anthropic \
--goal "Add input validation to the login endpoint" \
--dot-file examples/pipelines/02-plan-implement-test.dot

3. Or just ask conversationally:

> "Run the plan-implement-test pipeline to add input validation to the login endpoint"

> "Build a test suite for the auth module using a parallel pipeline"

The agent can generate pipelines on-the-fly or use any of the included examples.

What Can It Do?

Fix a bug systematically -- reproduce, diagnose, fix, regression test, verify:

amplifier run --dot-file examples/pipelines/practical/bug-fix.dot \
--goal "Fix the NullPointerError in UserService.getProfile()"

Review a PR in parallel -- analyze diff, then simultaneously check bugs, security, performance, and style -- then synthesize review comments:

amplifier run --dot-file examples/pipelines/practical/pr-review.dot \
--goal "Review PR #142"

Build a feature safely -- parse spec, parallel implement (core, API, tests), integration test, human review gate:

amplifier run --dot-file examples/pipelines/practical/feature-build.dot \
--goal "Add user avatar upload with S3 storage"

Pipeline Gallery

| Pipeline | Pattern | Use Case | |----------|---------|----------| | [Simple Linear](examples/pipelines/01-simple-linear.dot) | A -> B -> C | Quick single-task | | [Plan-Implement-Test](examples/pipelines/02-plan-implement-test.dot) | plan -> impl -> test | Standard dev workflow | | [Conditional Routing](examples/pipelines/03-conditional-routing.dot) | if/else branches | Outcome-based flow | | [Retry with Fallback](examples/pipelines/04-retry-with-fallback.dot) | Retry loop | Resilient execution | | [Parallel Fan-Out](examples/pipelines/05-parallel-fan-out.dot) | Fork/join | Concurrent work | | [Model Stylesheet](examples/pipelines/06-model-stylesheet.dot) | CSS-like config | Multi-provider | | [Fidelity Modes](examples/pipelines/07-fidelity-modes.dot) | Context control | Execution fidelity | | [Human Gate](examples/pipelines/08-human-gate.dot) | Approval gate | Human-in-the-loop | | [Manager-Supervisor](examples/pipelines/09-manager-supervisor.dot) | Hierarchical | Agent supervision | | [Full Attractor](examples/pipelines/10-full-attractor.dot) | All features | Complete pipeline | | [PR Review](examples/pipelines/practical/pr-review.dot) | Parallel analysis | Code review | | [Test Generation](examples/pipelines/practical/test-gen.dot) | Retry loop | Test authoring | | [Bug Fix](examples/pipelines/practical/bug-fix.dot) | Diagnose + verify | Debugging | | [Feature Build](examples/pipelines/practical/feature-build.dot) | Parallel + gate | Feature development | | [Refactoring](examples/pipelines/practical/refactor.dot) | Snapshot safety | Code improvement |

How It Works

The loop-pipeline orchestrator walks a Graphviz DOT digraph. Each node is an AI task (or control node like fork/join/gate), and edges define the flow between them. For each LLM node, the orchestrator spawns a loop-agent sub-session that runs an agentic tool loop -- call LLM, execute tools, feed results back -- until the node's task completes. Results flow forward along edges to the next node.

Provider Profiles

Each profile wires a provider, an agent loop, provider-aligned tools, and a system prompt. All profiles include attractor-core (shared hooks and the tool-report-outcome tool).

| Profile | Provider | Tools | Env Var | |---------|----------|-------|---------| | attractor-profile-anthropic | Anthropic Claude | tool-filesystem (read/write/edit), tool-bash (120s timeout), tool-search |...