Hyperloom README

The project's README from github.com/AMD-AGI/Hyperloom. As one markdown file: README.md.

ROCm Hyperloom

Tests Lint Version License: MIT Python

ROCm™ Hyperloom is a multi-agent harness that autonomously optimizes inference on AMD Instinct™ GPUs. It profiles each workload, searches framework and kernel optimizations, validates every candidate end to end, and carries proven results into a recipe knowledge base — without per-model human tuning.

It supports text generation, image generation, and custom pipelines on vLLM, SGLang, and xDiT.

Hyperloom architecture

Why Hyperloom

Serving efficiency determines hardware capacity, latency, and operating cost. Tuning a workload across serving configuration, framework source, and GPU kernels has traditionally taken weeks from a scarce specialist pool, and that work repeats for every new model, framework release, and accelerator generation.

Handing the same loop to an LLM is not enough. A real session runs for hundreds of turns, starts and stops many inference servers, and edits a serving framework's source tree. Left as the only source of truth, the model drifts from the original goal, rediscovers the same dead ends on every run, and can apply unsafe patches. Hyperloom is the harness around that loop: it keeps the mission grounded, reuses what earlier sessions already learned, and bounds what an agent is allowed to change.

How it works

A session is a closed loop: input → optimize → validate → learn.

PRELUDE → ENABLEMENT → FRAMEWORK_AGENT → KERNEL_AGENT → SWEEP → CLOSE

After Sweep, the coordinator either closes or starts another cycle when budget remains, the run has not converged, and roofline analysis still shows headroom. A hard cycle ceiling prevents unbounded looping. A new cycle resumes at the framework layer from the established baseline, rather than starting over.

Phase What it does
Prelude Measures a stock baseline (the anchor for every later comparison), optionally replays the closest recipe from the knowledge base, then profiles and builds a roofline so later phases know where the headroom is.
Enablement Makes the model run at all (serving flags through targeted rebuilds), graded on runnability and accuracy. Only entered when a baseline fails; skipped on healthy runs.
Framework optimization Searches serving flags, precision, attention, batching, and ranked upstream diffs.
Kernel optimization Delegates hot kernels to one AMD backend — GEAK or KernelForge — then re-measures every accepted change end to end. Only one backend runs per phase.
Sweep Re-measures the accumulated stack across concurrency and sequence-length operating points. Skips itself when the validated gain has not moved.
Close Records why the run stopped, writes the recipe knowledge base, final report, and machine-readable session artifacts.

Benchmarks are run by the coordinator, not by the model. A gain an agent predicts is logged for calibration and never decides a keep. A kernel backend's claimed speedup is held as unverified until Hyperloom re-measures it under the session protocol. Changes that fail validation are reverted; successful changes become the new baseline.

See the optimization loop for the runtime contracts, enablement ladder, and phase allowlists.

Multi-agent harness

The Coordinator runs Orchestration and Critic turns and dispatches specialists when needed. Each turn is grounded in persisted session state rather than an automatic supervision or recovery loop:

Role When it runs How it keeps the run on-goal
Orchestration Every tick Continuous planner; mission and progress are re-seeded from the state file, not from the transcript
Critic Every keep-or-revert Rules on whether a change served the mission; the learning record is written from that verdict
Specialist Authoring only Ephemeral. Returns a reviewed diff, not a decision

Risky source edits go through an isolated worktree, a unified-diff gate, a policy check, a Critic sign-off, and a coordinator benchmark. A rejection names the rule it broke so the next attempt is a fix, not a repeat.

Recipe knowledge base

Every session reads the recipe knowledge base (Recipe KB) before it starts and writes back when it finishes. A row stores the winning configuration, measured throughput, useful lessons, and failures worth remembering. Lookup relaxes one field at a time (model, hardware, framework, model type, architecture, framework version, precision) so a close match can warm-start the next run. Past failures are evidence in prompt context, not hard disqualifiers; what enters the KB is strict, because a bad entry outlives the run that created it.

Profiling and bottleneck analysis are backed by TraceLens, with trace collection from Magpie and low-level GPU tooling from IntelliKit. Long-horizon search and the knowledge base are described further in Arbor.

Supported features

Feature Options
Workload Text generation, image generation, and custom / scriptable pipelines
Platform MI300X, MI325X, MI355X
Framework SGLang, vLLM, xDiT
Kernel language HIP, Triton, FlyDSL
Kernel backends GEAK, KernelForge
LLM backend Claude

Get started

Goal Guide
Set up Hyperloom and run a demo Quickstart
Launch and monitor an optimization Run an optimization
Understand the algorithm Optimization loop
python -m hyperloom.inference_optimizer.cli optimize

Documentation

Topic Link
ROCm Docs Hyperloom
Authentication and credentials Authentication & credentials
Environment variables Environment variables
Components Components
Compatibility Compatibility matrix
Troubleshooting Troubleshooting
Operations Operations & self-hosting
Session output schema session_breakdown.json

File issues and feedback

If you encounter problems or bugs while running Hyperloom, open an issue, or send feedback through the beta survey.


Developer entry points

For contribution workflow, testing, and linting, see CONTRIBUTING.md.


Licensing

Hyperloom is released under the MIT License. The full license text is in LICENSE.

You may use Hyperloom commercially, modify it, and distribute it under the terms of the MIT license, provided the copyright notice and the permission notice are retained in all copies or substantial portions of the software.

Third-party tools and agents (Cursor, Visual Studio, and Claude Code) that Hyperloom invokes are governed by their own separate license terms and are NOT covered by the MIT license above — see the "Third-Party Tools and Agents" section in LICENSE. You are responsible for reviewing and complying with each tool's individual license.

A few files distributed inside Hyperloom are also third-party — reference kernels and a Triton oracle carried in forge's knowledge base and examples. They keep their own licences; THIRD_PARTY.md lists them and REUSE.toml carries the machine-readable form.

For security-relevant issues, see SECURITY.md. For contribution conventions, see CONTRIBUTING.md.

Hyperloom (AMD-AGI/Hyperloom)

Searching Database…

What is this?A multi-agent harness that autonomously optimizes LLM inference on AMD Instinct GPUs: it profiles your workload, searches framework and GPU-kernel optimizations, validates every candidate end to end, and saves proven results into a recipe knowledge base.
Is it a library I import, or a tool I run against my serving stack?It's a Python CLI harness you run against your serving stack — python -m hyperloom.inferenceoptimizer.cli optimize — plus operator scripts under scripts/ for platform checks.
How do I get it running?Start with the Quickstart guide, which covers setting Hyperloom up and running a demo; a second guide covers launching and monitoring an optimization, and the full docs live in the ROCm documentation.
Does it use an AI model to do the optimizing, and which one?Yes, the LLM backend is Claude, so you need access to it. Hyperloom also invokes third-party tools like Cursor, Visual Studio, and Claude Code, which keep their own separate licenses.
It lets agents edit serving-framework source — how do I know it won't break my setup?Risky edits pass through an isolated worktree, a unified-diff gate, a policy check, a Critic sign-off, and a benchmark run by the coordinator rather than the model. Anything that fails validation is reverted.
Is it free to use commercially?Yes — MIT licensed, so commercial use, modification, and distribution are fine. Invoked tools like Cursor and Claude Code, plus a few bundled third-party kernel files, carry their own licenses you must comply with separately.
Do I need special hardware for this?Yes — an AMD Instinct GPU: MI300X, MI325X, or MI355X. It does not optimize workloads on NVIDIA or other accelerators.
What does one optimization session actually do?A session is a closed loop — input, optimize, validate, learn — over six phases: Prelude (stock baseline, profiling, roofline), Enablement, framework optimization, kernel optimization, Sweep across concurrency points, and Close, with a hard cycle ceiling so it never loops forever.
What frameworks and workloads does it support?It optimizes text generation, image generation, and custom or scriptable pipelines served on vLLM, SGLang, or xDiT. Kernel work is delegated to the GEAK or KernelForge backends and written in HIP, Triton, or FlyDSL.
What is the recipe knowledge base?Every session reads it before starting and writes back when it finishes. A row stores the winning configuration, measured throughput, lessons, and failures worth remembering; lookup relaxes one field at a time so a close match can warm-start the next run.
Why hand this to a harness instead of letting the LLM tune freely?A real run spans hundreds of turns, restarts many inference servers, and edits framework source — left alone the model drifts, rediscovers dead ends, and can apply unsafe patches. Hyperloom keeps the mission grounded in persisted state and bounds what agents may change.
Why does tuning usually take weeks without it?Because tuning spans serving configuration, framework source, and GPU kernels, and traditionally needs scarce specialist time — repeated for every new model, framework release, and accelerator generation. Hyperloom automates that loop without per-model human tuning.
What do the operator scripts in scripts/ do?partitionmodesweep.py benchmarks each AMD partition mode (SPX/DPX/QPX/CPX) to find which shape a workload wants; platformaudit.py checks EPYC CPU tuning against AMD's guide; platformauditbmc.py audits BIOS-only knobs over the BMC.
Creator
AMD-AGI
Size
83 MB
Stars
239
Age
6mo
Commits · 90 Days