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…

Что это такое?Мультиагентный каркас, который автономно оптимизирует инференс LLM на GPU AMD Instinct: он профилирует вашу нагрузку, ищет оптимизации на уровне фреймворков и GPU-ядер, сквозь проверяет каждого кандидата и сохраняет подтверждённые результаты в базу знаний рецептов.
Это библиотека, которую я импортирую, или инструмент, который я запускаю для своего сервера инференса?Это Python CLI-каркас, который вы запускаете для своего сервера инференса — python -m hyperloom.inferenceoptimizer.cli optimize — плюс скрипты для операторов в scripts/ для проверки платформы.
Как его запустить?Начните с руководства Quickstart — там описаны установка Hyperloom и запуск демо; второе руководство рассказывает, как запустить оптимизацию и следить за ней, а полная документация находится в документации ROCm.
Оптимизацию делает AI-модель, и какая именно?Да, в качестве LLM-бэкенда используется Claude, так что нужен доступ к ней. Hyperloom также вызывает сторонние инструменты вроде Cursor, Visual Studio и Claude Code, у которых свои отдельные лицензии.
Агенты могут править исходники серверного фреймворка — как убедиться, что ничего не сломается?Рискованные правки проходят через изолированный worktree, проверку unified-diff, проверку политик, одобрение Критика и запуск бенчмарка, который выполняет координатор, а не сама модель. Всё, что не проходит валидацию, откатывается.
Можно ли свободно использовать в коммерческих целях?Да — лицензия MIT, так что коммерческое использование, изменение и распространение разрешены. Вызываемые инструменты вроде Cursor и Claude Code, а также несколько сторонних файлов ядер в комплекте, имеют собственные лицензии, которые нужно соблюдать отдельно.
Нужно ли для этого специальное железо?Да — GPU AMD Instinct: MI300X, MI325X или MI355X. Нагрузки на NVIDIA и других ускорителях он не оптимизирует.
Что именно происходит за одну сессию оптимизации?Сессия — это замкнутый цикл «вход, оптимизация, проверка, обучение» из шести фаз: Prelude (базовые замеры, профилирование, roofline-анализ), Enablement, оптимизация фреймворка, оптимизация ядер, Sweep по точкам конкурентности и Close, с жёстким лимитом циклов, чтобы процесс не зацикливался навсегда.
Какие фреймворки и нагрузки он поддерживает?Он оптимизирует генерацию текста, генерацию изображений и свои или скриптуемые пайплайны, обслуживаемые на vLLM, SGLang или xDiT. Работа с ядрами делегируется бэкендам GEAK или KernelForge и ведётся на HIP, Triton или FlyDSL.
Что такое база знаний рецептов?Каждая сессия читает её перед запуском и дописывает по завершении. Строка хранит победившую конфигурацию, измеренную пропускную способность, выводы и запомнившиеся неудачи; поиск ослабляет совпадение по одному полю за раз, чтобы близкий рецепт мог «прогреть» следующий запуск.
Почему лучше отдать это каркасу, а не позволить LLM тюнить свободно?Реальный запуск — это сотни шагов, многократные перезапуски серверов инференса и правки исходников фреймворка — без контроля модель уходит в сторону, заново наступает на те же грабли и может применить небезопасные патчи. Hyperloom удерживает задачу на основе сохранённого состояния и ограничивает, что агенты могут менять.
Почему без него тюнинг обычно занимает недели?Потому что тюнинг затрагивает конфигурацию сервера инференса, исходники фреймворка и GPU-ядра, а традиционно требует времени дефицитных специалистов — причём заново для каждой новой модели, релиза фреймворка и поколения ускорителей. Hyperloom автоматизирует этот цикл без ручной подстройки под каждую модель.
Что делают операторские скрипты в scripts/?partitionmodesweep.py бенчмаркаит каждый режим партиций AMD (SPX/DPX/QPX/CPX), чтобы понять, какая конфигурация подходит нагрузке; platformaudit.py проверяет тюнинг CPU EPYC по руководству AMD; platformauditbmc.py проверяет параметры, доступные только через BIOS, по BMC.
Creator
AMD-AGI
Size
83.8 MB
Stars
241
Age
6mo
Commits · 90 Days