microsoft/amplifier-tool-leverage-patterns

Amplifier Tool Leverage Levels

The Pattern

Problem: You've built a workflow/automation tool on Amplifier. Different consumers want to use it different ways — an attractor pipeline wants to compose it, a web app wants to import it, an agent wants to call it as a tool, a human wants a CLI. You don't want four copies of the logic.

Approach: Pick ONE home for the logic, then expose up to four leverage levels as thin adapters over that home. Build only the levels a real consumer demands.

| Level | Surface | Consumer | What it is | |-------|---------|----------|------------| | L1 | .dot attractor pipelines | Other pipelines / Resolve | One .dot per command + a shared subgraph (folder-shape), run on the loop-pipeline engine (amplifier-bundle-attractor) | | L2 | Python lib | Other codebases | Each command an importable method; clean public API in __init__.py | | L3 | Amplifier tool modules | Agents | bundle.md + modules/tool-<name>/ wrapping each command as an agent-callable tool | | L4 | CLI | Humans / scripts | Thin click/argparse wrapper over the lib |

The four levels, concretely

L1 — Standalone .dot attractor pipelines. One .dot per command, plus a shared subgraph factored out via a folder-shape node. Runs on the loop-pipeline engine anywhere — including inside the Amplifier Resolve dot-graph resolver: register a <name>.dot + <name>.resolver.yaml in the resolver's pipelines/ dir. Inside the graph, parallelogram nodes shell out to the tool's CLI (deterministic steps); box nodes are full LLM agents (synthesis steps). This is the level that lets your tool compose into larger attractor flows.

L2 — Python lib. Each command is an importable method. Export a deliberate public API from __init__.py. This is what lets another codebase embed the tool directly — e.g. a web app importing it rather than shelling out.

L3 — Amplifier tool modules. A bundle.md plus modules/tool-<name>/ exposing each command as an agent-callable tool. Obey the mount() Iron Law; keep each tool a thin wrapper over the lib (run blocking work via asyncio.to_thread). This is what lets an agent call your tool as a tool.

L4 — CLI. A thin click/argparse surface over the lib. Almost always worth it — it's the cheapest level and it's what L1's parallelogram nodes shell out to.

The DRY rule (load-bearing)

The logic lives in ONE place; every level is a thin adapter over it. Where "one place" is depends on the nature of the work:

• LLM-logic tools → the home is the .dot files. The prompts and graph are the logic. L2/L3/L4 orchestrate runs of those graphs.
• Deterministic tools (e.g. git plumbing) → the home is the lib. The .dot files are thin orchestration that shells out to the CLI/lib.

Two failure modes to refuse:

1. Don't re-implement logic in the .dot. If the core is deterministic, the .dot calls it — it does not reproduce it.
2. Don't fold a dependency's private engine into your .dot. Keep dependencies behind their public CLI/subprocess boundary. Low coupling beats a fast path that reaches into someone else's internals.

Sharing across repos without vendoring

When one leverage-repo builds on another (repo-weaver on wiki-weaver), you'll reuse something across a repo boundary. Split the decision by cost and coupling:

• Heavy / stateful / LLM engine → keep it behind the public boundary. Shell the other tool's CLI (L4) or compose its .dot as a subgraph (L1). Never import its internals — this is failure mode #2 above.
• Cheap / structural / deterministic facts (paths, layout constants, schemas) → a direct import beats duplication. Copied constants drift silently; a single source of truth doesn't. Make the upstream a real dependency and import them — this does NOT violate the DRY rule, it honors it across the repo boundary.

To import across repos without vendoring:

1. Declare the upstream as a git dependency — upstream @ git+https://…@main (companion repos usually aren't on PyPI). Hatchling needs [tool.hatch.metadata] allow-direct-references = true to build a wheel with a direct-URL dep.
2. Guard against drift with a contract test that asserts your expected values equal the upstream's exported constants — CI fails the moment they diverge.
3. Merge order follows the dependency — the upstream change lands on main first (so @main resolves the new symbols), then the downstream flips its pin and merges. Same producer→consumer ordering as any cross-repo change.

Evidence: repo-weaver imports wiki-weaver's WIKI_DIR / _sources / path-helper constants exactly this way (single source of truth for corpus layout), while keeping the synthesis engine behind the subprocess boundary.

The judgment: which levels do I actually need?

Do NOT build all four by default. Build the level a real consumer demands:

| Build... | When a real consumer needs... | |----------|-------------------------------| | L1 | Resolve / attractor composition | | L2 | an app that will import it | | L3 | an agent that will call it as a tool | | L4 | almost always (cheapest; L1 shells out to it) |

Building a level "to complete the set" is over-engineering. Prove each level with a real consumer: L1 is proven by being registered and RUN in the resolver; L2 by an actual import; L3 by an agent invocation. A level that is never run by its consumer is ceremony — delete it or don't build it yet.

When this pattern is the WRONG answer

• A plain library or CLI does the job and nothing composes/embeds/agent-calls it → just ship L4 (and maybe L2). Don't reach for attractor pipelines or tool modules to "be thorough." See cli-packaging-patterns.
• The tool isn't Amplifier/LLM-powered at all → the leverage levels add an Amplifier dependency for no gain. Use ordinary packaging.
• You can't name the consumer for a level → that's the signal not to build it. Levels follow demand, not symmetry.

Worked exemplar: repo-weaver

repo-weaver demonstrates all four levels, each proven:

• L1 — its .dot pipeline ran end-to-end in the Resolve dot-graph resolver inside a DTU.
• L2 — exports a public API for direct import.
• L3 — ships tool-repo-weaver (3 tools), proven to return real cited output.
• L4 — its CLI ran across 30 repos.

repo-weaver crosses into wiki-weaver at two deliberately different boundaries. Its deterministic git→docs core lives in the lib; the heavy LLM synthesis engine stays behind wiki-weaver's CLI/subprocess boundary (never imported — low coupling). But the cheap, structural corpus-layout constants are a direct Python import from wiki-weaver's lib (wiki-weaver @ git+…@main), so layout has one source of truth instead of duplicated literals — guarded by a contract test that fails if the two drift. See "Sharing across repos without vendoring" above, and its ARCHITECTURE.md, for the boundary in detail.

Future levels (extensions, not part of the core four)

MCP/REST service wrappers and self-hosted web UIs are natural further leverage levels over the same lib. Add them when a consumer needs them — same rule: prove the consumer first.

Related skills

• cli-packaging-patterns — how to build L4 (and the L2 packaging) cleanly.
• plugin-discovery-patterns — entry-point discovery for L3 tool modules and resolver pipelines.
• creating-amplifier-modules — the mount() Iron Law and module structure for L3.
• dot-patterns / dot-syntax — authoring the L1 .dot graphs (folder-shape subgraphs, parallelogram vs box nodes).