Hyperloom

AMD-AGI活跃维护

在 AMD GPU 上自动调优 LLM 推理负载的智能体系统,通过自动搜索和优化 GPU kernel 提升大模型推理性能。

An agentic system that auto-optimizes LLM workloads on AMD GPUs.

v1.1.5发布于 2026-10-28 07:41 UTC266star +2 / 7 天81fork同步于 2026-11-10 12:03 UTC

怎么上手

由 README 提炼,执行前请确认
python -m hyperloom optimize
硬件要求按 README 说明

README 说明面向 AMD Instinct GPU,支持 MI300X、MI325X、MI355X;未给出具体显存要求,也未说明能否在 CPU 上运行。

支持 ROCm / AMD多卡 / 张量并行
下载:源码 zip·GitHub Releases(安装包)本站不镜像安装包

项目说明

由 README 自动翻译提炼

在 AMD Instinct GPU 上自动优化 LLM 推理负载的多智能体框架,免去逐模型人工调参

在 AMD GPU 上自动调优 LLM 推理负载的智能体系统,通过自动搜索和优化 GPU kernel 提升大模型推理性能。

核心能力

  • 按 Prelude→Enablement→Framework→Kernel→Sweep→Close 闭环自动优化
  • 由协调器统一跑基准,智能体预测的收益不直接决定保留
  • 内核优化接入 GEAK 或 KernelForge 后端并端到端复测
  • 用 Recipe 知识库跨会话复用配置与失败经验
  • 支持 vLLM、SGLang、xDiT 上的文本与图像生成负载

容易踩的坑

需要 Claude 或 Codex 作为 LLM 后端,并配置相应认证凭据;内核优化阶段需额外接入 GEAK 或 KernelForge 后端,且同一阶段只运行一个;分区扫描脚本 scripts/partition_mode_sweep.py 修改分区模式需要特权。

内容由模型根据 README 生成,可能不完整或不准确,以官方文档为准。看原文 README

最近发版

5 个版本v1.1.5
  1. v1.1.5Hyperloom v1.1.5最新正式版2026-10-28 · 2026-10-28 07:41 UTC

    Hyperloom v1.1.5

    This is a patch release on top of 1.1.4. AgentX optimization now runs on Magpie's native AgentX contract. New FRAMEWORK_AGENT and KERNEL_AGENT work must fit what is left of its phase budget, and a phase transition lets running work finish instead of cancelling it. The release adds GPU power budgets and opt-in power settings, an Experience KB you can operate with the hyperloom-kb command, a custom specialist the Coordinator runs itself, the PrimaTune predictor, Radeon AI PRO R9700 support with vLLM, a Claude–Codex relay for stalled forge-loop searches and a Claude subscription credential path. Explore also stops re-measuring launches the session already has an answer for.

    Sessions started by 1.1.4 or earlier cannot be resumed on this build. coordinator.db now records schema version 7 and has no in-place migration, so optimize --resume-from on an older session exits 2 before touching it (#1967), and kernelforge forge-loop --resume refuses a 1.1.4 checkpoint. Finish in-flight sessions under the build that started them. The workspace Experience KB also starts empty, the accuracy eval can no longer be turned off, and several options, environment variables and defaults move; see Breaking changes before upgrading. The per-change history lives in docs/release-notes.md.

    Highlights

    1. AgentX runs on Magpie's native AgentX contract

    Under HYPERLOOM_AGENTX=1, Hyperloom turns --model, --framework, --precision, --tp, --ep and --conc into a Magpie AgentX config, or takes one from --benchmark-config PATH (start from assets/configs/agentx_sglang.yaml). It archives the config as benchmark.yaml in the session and resumes from that copy. Magpie owns server start, trace replay, profiling and cleanup, and a KEEP needs a valid, unprofiled Magpie report for the session's own workload. Native AgentX is single-node SGLang or vLLM at one concurrency per session and exits 2 at launch on a flag it cannot honour. Hyperloom's own AIPerf client is removed, while the MLPerf backend keeps its entry point (#1922). A baseline measured with the prefix cache off is refused (#1884). A candidate can no longer change the speculative draft under simulated acceptance (#1885). GEAK serves the engine the baseline ran (#1792), and on interactivity-graded sessions the stack ledger measures adoptions on the graded axis (#2022).

    2. Phase budgets bind, running work finishes, and failures surface

    Work whose estimate does not fit what is left of the FRAMEWORK_AGENT or KERNEL_AGENT phase is refused with rule=phase_time_budget, and running work stops at the phase end. The LLM's extend_explore_budget and extend_kernel_budget hints no longer lengthen a phase (#1873). A phase transition waits for running tasks to finish and be booked instead of cancelling them, so a GEAK rebench still running when KERNEL ends is kept or settled (#1860). Orchestration can no longer run an action its phase does not offer (phase_incompatible), and once a gain is validated a higher re-baseline no longer replaces its baseline anchor (#1886). While a baseline is measured and the budget still funds another macro cycle, a skip_to_close is refused as skip_to_close_contradicted and the run keeps optimizing (#2185). Broad exception handlers across the optimizer and KernelForge now catch only the errors their code can raise, so failures 1.1.4 stepped past are recorded on the task, tick or CLOSE step above them (#1986, #2004, #2042, #2049).

    3. GPU power budgets and opt-in power settings

    --max-power-w N caps the summed measured-phase mean power of the serving GPUs, and --max-per-gpu-power-w GPU_ID W caps one card. Every KEEP path refuses a candidate over a budget or without a per-card reading, and a baseline that breaks a budget stops the run with baseline_over_power_budget (#1770). With --apply-gpu-power-settings, the s

  2. v1.1.4Hyperloom v1.1.42026-10-15 · 2026-10-15 09:37 UTC
    查看更新说明

    Hyperloom v1.1.4

    This is a patch release on top of 1.1.3. Every command now runs behind one hyperloom <command> entry point. A session lost with its container can be resumed elsewhere, and a failing LLM backend can no longer burn hours of a long run. Hyperloom now measures GPU power and scans server logs for runtime findings, and the validated SGLang stack moves to 0.5.21.

    Sessions recorded by 1.1.3 resume on this build. How Hyperloom is launched, installed and configured does change, and so do several report fields; see Breaking changes and the upgrade guide before upgrading. The per-change history lives in docs/release-notes.md.

    Highlights

    1. One hyperloom command, and no flags that do nothing

    hyperloom <command> (or python -m hyperloom <command>) is now the only entry point. setup, check, optimize, recover, quantize, session ... and multi-node ... replace about 50 console scripts and python -m paths, and hyperloom --help lists them all (#1736). Flags that were ignored or only advisory now fail at startup instead of being accepted (#1736, #1739, #1786). On resume, preflight checks the session's recorded framework instead of the SGLang default (#1753), and every --extra-env pin is exported so all readers resolve it alike (#1797, #1818).

    2. A session lost with its container can be resumed

    hyperloom recover --session-dir S --confirm-scope-gone OWNER_SCOPE --confirmation-reason TEXT cancels the unfinished tasks of a vanished execution environment and releases their execution and GPU leases, so optimize --resume-from can continue the session elsewhere. Owner scopes now include the start time of the namespace's PID 1, so a new container on the same node is not mistaken for the lost one. A session resumed in SWEEP re-dispatches its lost concurrency sweep, and a crashed integrate_patch whose tree went with the container rolls back while an accepted env-only candidate is replayed into the stack (#1874, carrying #1859, #1870, #1871 and #1879). A local Ray head without the serving_slot resource is restarted with it when that is safe, and unrecoverable baseline failures end the session early (#1816).

    3. Long runs stop burning hours on a broken LLM loop

    Prompt sections that grew with the session are now bounded; in the reported run this cut a 1.6M-character prompt that failed with Prompt is too long to about 109K (#1735). A failing LLM backend is retried with exponential backoff from 2 s up to 5 min, and an hour without a successful turn stops the session with stop_reason=backend_unhealthy while CLOSE still publishes the best validated stack (#1737). Every Claude SDK turn is bounded by INFERENCE_OPTIMIZER_CLAUDE_TURN_TIMEOUT_SEC (default 1500 s) and its CLI is killed past the bound (#1754). emit_intent is no longer silently hidden from the model, and 50 consecutive turns without an intent also end the session as backend_unhealthy (#1805).

    4. Specialists run beside the loop and draw on earlier sessions

    The dispatcher no longer waits on running CPU specialists before the tick advances, and the top untested specialist proposals are benched automatically as one explore grid (#1742). Each workspace runs a local Experience KB service: measured FRAMEWORK_AGENT attempts are published as Experiences and read back into prompts, with optional sync against a shared global KB (#1732). Operators can define their own specialist with --custom-specialist-prompt-file and --custom-specialist-description (#1804). The installer owns the single Claude CLI on PATH, and specialists always run as CLI subprocesses (#1775, #1786).

    5. Runtime findings from server logs, and verdicts that say why

    Every measured server log is scanned for runtime findings such as unknown vLLM enviro

  3. v1.1.3Hyperloom v1.1.32026-09-30 · 2026-09-30 09:58 UTC
    查看更新说明

    Hyperloom v1.1.3

    This is a patch release on top of 1.1.2. It adds targeted, repository-wide KernelForge fusion discovery, makes ATOM installable on bare metal, tightens AgentX grading, and hardens GPU ownership, phase transitions, recovery and reporting.

    Most 1.1.2 sessions resume on this build. A pre-1.1.3 AgentX session does not carry the median-interactivity anchor this release requires and should not be resumed. The command line, environment contract and several Python and report fields also move; see Breaking changes before upgrading.

    The full per-change history lives in docs/release-notes.md.

    Highlights

    1. KernelForge fusion gains targeted, repository-wide discovery

    forge-fuse --fuse-kernel anchors a fusion on an exact traced kernel and derives its neighbours from the trace; --repo-scope lets discovery and authoring inspect the whole framework repository when the chain is not in the resolved model file (#1678). Discovery avoids folding work into a tuned library GEMM's epilogue, validates harness alignment, and checks that a keeper reduces launch count. DeepSeek-V4 harnesses also derive the output groups from o_groups, with --attn-tp recording the attention shard independently of serving TP (#1709).

    2. ATOM becomes a first-class setup and optimization target

    Bare-metal setup accepts --install-framework atom, installs AITER and ATOM from source, and refuses environments where ATOM would interfere with SGLang or vLLM plugins (#1694). The shared 12-hour demos now cover ATOM in Docker and bare-metal modes. User-selected execution and kernel integration are preserved (#1615), and an unset KERNEL_OPT_BACKEND_ORDER resolves to GEAK for ATOM as it does for every other framework (#1693).

    3. AgentX grading uses median interactivity with explicit guards

    An AgentX KEEP now requires a 3% gain on e2e_norm_intvty_p50, while P90 interactivity, output throughput, measurement-window duration and request errors must hold (#1652). SBD V6 publishes and renders the objective, guards, comparability inputs and submission validity, so the report shows the axes on which the verdict was actually taken (#1687).

    4. GPU ownership and phase transitions fail closed

    KERNEL_AGENT work holds a GPU lane until its physical execution settles, and phase transitions wait for a GPU barrier (#1654). Ended holders are reclaimed, Ray waits are bounded without making a still-owned device available, and shutdown no longer waits on its own caller (#1595, #1682). Stack validation stops when it cannot undo its patches instead of continuing from an unknown tree (#1677).

    5. Workflow evidence becomes replayable

    Fresh sessions publish a versioned workflow-evaluation contract with replayable transition inputs, dispatch provenance and separate process and business outcomes (#1666, #1688). A per-process trajectory ledger records LLM requests, tool events and lifecycle transitions and projects them onto Langfuse spans (#1697). AIPerf KV-cache telemetry is recovered from the endpoint that actually serves it (#1698).

    6. AgentX and KernelForge use the remote knowledge store consistently

    AgentX gains its own remote Recipe identity, selection metric, evidence and warm-replay path (#1597). Experience rows are stored in the shape their producer writes (#1561), while KernelForge remote experience storage converges on KB Store and refuses the GBrain configuration that previously ran as a silent no-op (#1614).

    7. Measurement and publication stop inventing success

    Graph-capture fallbacks that changed the measured workload are removed (#1609). Fusion, GEMM tuning and the critic now report unavailable checks, missing measurements and outages as such rather than as PASS, 1.00x or ACCEPT (#1628, #1629, #1635, #1636, #1639). A failed JIT rebuild stops the loop instead of benchmarking a stale binary (#1634), and CLOSE

  4. v1.1.2Hyperloom v1.1.22026-09-23 · 2026-09-23 08:07 UTC
    查看更新说明

    Hyperloom v1.1.2

    This is a patch release on top of 1.1.1. The session record resumes across the upgrade: ensure_schema migrates a 1.1.1 coordinator.db on the way in.

    ROCm 10 becomes a validated stack, bring-up gets a phase of its own, and the automatic supervision layer is retired in favour of explicit resume and recovery. ATOM is supported end to end, KernelForge gains an assembly backend and stops losing work a killed campaign had already proven, and the Session Breakdown now says which axis a session was graded on.

    The command line, the environment contract, the installation prerequisites and several report fields do move. The ones that need a plan before upgrading are listed under Breaking changes. CHANGELOG.md is retired (#1589); the full per-change list now lives in docs/release-notes.md.

    Highlights

    1. ROCm 10 is a validated stack

    Docker runs SGLang 0.5.20 and vLLM on ROCm 10 user space, bare-metal vLLM builds from source on a ROCm 10 host, and rocprof-compute is installed and found on TheRock's pip-packaged ROCm (#1549, #1593, #1605). A prebuilt SGLang image whose torch fails under rocprofv3 is marked profiling-unavailable instead of hanging the round. SGLang >= 0.5.18 profiles through TraceLens kernel_shape_tool rather than git-applied roofline patches (#1486, #1593). The six-leg ROCm 10 run also surfaced scheduler stalls that are fixed here: KERNEL entry hooks no longer block the coordinator tick, conc-sweep boot rounds are no longer counted as measured variants, and a trace with zero GPU events stops repeat roofline scheduling with a recorded reason (#1605).

    2. ENABLEMENT is the sixth phase of the loop

    Bring-up leaves FRAMEWORK_AGENT and sits between PRELUDE and FRAMEWORK_AGENT with its own entry and exit, phase_history rows and report section (#1491). It gets no budget share: it is bounded by the wall clock and ENABLEMENT_MAX_ATTEMPTS, and runnability is decided from the measurement rather than a log scan. A KEEP now ships an ordered replay recipe (setup, build, patch) with a sufficient / insufficient verdict under enablement.recipe in session_breakdown.json (#1414), and a KB recipe carrying code overlays can be replayed into a pip-installed framework (#1563).

    3. Automatic supervision is retired; limits and recovery are explicit

    The Robustness agent, the runtime recover action and the Monitor/Supervisor auto-resume are removed (#1547). Each benchmark spawn has a hard deadline (INFERENCE_OPTIMIZER_BENCHMARK_TIMEOUT_SEC, default 7800) plus a silence limit (INFERENCE_OPTIMIZER_BENCHMARK_SILENCE_TIMEOUT_SEC, default 600) armed only once a ready marker is seen. Resume refuses ownership it cannot verify instead of guessing, and recover-session --confirm-stopped releases a stopped task's residue under the session lock. Inline MCP actions no longer block the coordinator's event loop (#1577).

    4. ATOM is supported end to end

    Its recovery workers are reaped, --framework atom defaults the kernel backend to forge, and it is published as supported (#1416). Detailed profiling adds --mark-trace and ATOM's annotation switches only when the installed build supports them (#1509).

    5. KernelForge gains an assembly backend and keeps more of its work

    forge-loop --kernel-backend assembly optimizes compiler-emitted AMDGPU assembly behind a numerical contract (#1426). Warm starts fall back to a fuzzy KB match across framework versions and GPUs (#1512). A lane's patch is merged against the KEEPs that landed before it instead of being dropped on stale context (#1528), Controller patches integrate in priority order with clean patch hygiene (#1583), and a Controller KEEP reaches the stack ledger in every benchmark mode (#1522). A killed campaign's proven fusions are salvaged instead of reported as REVERT (#1533, #1536), its leftovers no longer fail the next task

  5. v1.1.1Hyperloom v1.1.12026-09-16 · 2026-09-16 09:13 UTC
    查看更新说明

    Hyperloom v1.1.1

    This is a patch release on top of 1.1.0. The session record does not move, so a session recorded by 1.1.0 resumes on this build.

    Most of it is the Recipe knowledge base telling the truth: the prior work a session had actually earned was not reaching the model at all — an exact warm-start hit printed "first session for this workload/hw", and the lessons and pitfalls sections rendered (none) no matter how much a prior session had learned. The other corrections are in agent-backend selection, which three places answered differently, and in the supervisor watchdog, whose restarts are now resumable and bounded.

    The command line and the environment contract do move: one optimizer option, one console script and eight environment variables that 1.1.0 accepted are gone, one variable's accepted values narrow, and one option is added. The ones that need a plan before upgrading are listed under Breaking changes; the full per-change list is in CHANGELOG.md.

    Highlights

    1. The warm-start block, the KB's lessons, and its pitfalls reach the model again

    All three read field shapes no writer produces. An exact hit carrying a full config printed (no recipe text — first session for this workload/hw), and sections 5b and 5c rendered (none) regardless of what a prior session had recorded (#1466, #1464). The block now renders warm_start_context, the view recipe_kb_t0 already persists on every anchor, and a borrowed config is labelled with the model it came from. No recorded knowledge was lost; until now none of it was being shown. A losing operator's progress is also banked rather than discarded, and a warm start is picked by measurement (#1448).

    2. One rule picks the agent backend across both packages

    A configured credential first, then an installed SDK, with Claude ahead of Codex. Four places answered this and three disagreed, so forge-loop on an OpenAI-only host could resolve to Claude and then fail to authenticate (#1472). The Robustness Agent's RCA engine follows the same precedence instead of checking the OpenAI side unconditionally. One consequence worth naming: a deployment whose runtime is logged in by other means is no longer refused up front — forge-fuse dropped its --agent-backend auto usage error and forge-fusion dropped the llm_provider_unconfigured result, leaving the real authentication failure to the preflight that can see it.

    Forge also stops naming its own settings: it reads Hyperloom's environment contract (CLAUDE_MODEL / CODEX_MODEL) and nothing above it, and reasoning effort falls back to the project-wide HYPERLOOM_REASONING_EFFORT (#1442). One reasoning-effort ladder now covers both surfaces — see Breaking changes.

    3. Supervisor watchdog restarts are resumable and bounded

    A wedged coordinator takes SIGHUP and keeps its interrupted phase segment rather than recording a session outcome; three restart attempts, counted durably before the signal goes out, make the wedge terminal (#1462). Separately, the robustness monitor now reads the real stop-reason vocabulary — it had been importing a module that does not exist and silently falling back to a subset missing 16 terminal reasons, so a finished session could be relaunched. Long executor subprocesses also move off the event loop (#1471).

    4. --extend-hours grants a resumed session more budget

    Elapsed time is summed forward across every leg and never reset, so this is the only way to continue a run that has already spent its budget. The grant is applied on --resume-from and recorded in the session state with its reason; it defaults to 0.0, so an invocation that does not pass it behaves as before.

    5. The collective lane becomes part of the rewrite controller

    A communication operator and a dense operator are the same rewrite job; the only thing separating them was the measurement harness, which belon

用户点评

登录用户的真实使用记录,可按版本和硬件筛选
共 0 条

    还没有人点评。第一个说出真实体验的人最有价值。

    README 原文

    未翻译

    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.

    Merged upstream

    Hyperloom found each of these in a real optimization session on AMD Instinct GPUs, and vLLM or SGLang merged it. The numbers are quoted from the linked PR and were measured on the upstream revision it names; the PR also carries the benchmark commands, the accuracy checks, and the operating points where the gain does not apply.

    Upstream PRMergedModel / workloadGPUMeasured effect
    sglang#410712026-10-10Qwen3-32B-FP8, 1024 in / 512 out, concurrency 4MI300X+314 % output tok/s against the untuned Triton default; made the gfx942 default by sglang#43815
    sglang#438152026-10-27Qwen3-235B-A22B-Instruct-2507-FP8, 1024 in / 512 out, concurrency 4, TP=4MI325X+118 % output tok/s, and +28 % at concurrency 128
    vllm#585392026-09-30DeepSeek-V4.1-Flash, 307 in / 23 out, TP=2MI355X+53.9 % total tok/s, −37.0 % mean TTFT
    sglang#452952026-10-29Gemma 3 12B it, 12288 in / 2048 out, concurrency 128MI325X+14 % output tok/s, from more KV capacity for the full-attention layers
    vllm#588972026-10-14gpt-oss-120b, 1033 in / 523 out, concurrency 61MI355X+9.7 % total tok/s, −11.1 % median TPOT
    sglang#467312026-10-29gemma-4-26B-A4B-it, 8192 in / 1024 out, concurrency 256MI355X+9.0 % total tok/s, −15.9 % mean TTFT
    sglang#465282026-10-27fp8-KV checkpoints with calibrated KV scales, such as Llama-3.1-8B-Instruct-FP8-KVMI355X, MI325XCorrectness: the default aiter backend produced garbage with no flag set, GSM8K 0.000; now 0.760
    vllm#571082026-10-10Block-FP8 checkpoint missing a weight scaleMI300X, MI325XCorrectness: a checkpoint that had served garbage (GSM8K 0.00) now fails the load and names the parameter

    26 Hyperloom optimizations are merged upstream as of 2026-11-02, 12 for throughput and 14 for correctness; the eight with the largest measured effect are above. Upstream optimizations merged into vLLM and SGLang has the full list, the per-row caveats, and the rule for what enters it.

    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.

    PhaseWhat it does
    PreludeMeasures 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.
    EnablementMakes 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 optimizationSearches serving flags, precision, attention, batching, and ranked upstream diffs.
    Kernel optimizationDelegates hot kernels to one AMD backend — GEAK or KernelForge — then re-measures every accepted change end to end. Only one backend runs per phase.
    SweepRe-measures the accumulated stack across concurrency and sequence-length operating points. Skips itself when the validated gain has not moved.
    CloseRecords 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:

    RoleWhen it runsHow it keeps the run on-goal
    OrchestrationEvery tick; in KERNEL_AGENT only when kernel progress changes, or after 15 minutes without a turnContinuous planner; mission and progress are re-seeded from the state file, not from the transcript
    CriticEvery keep-or-revertRules on whether a change served the mission; the learning record is written from that verdict
    SpecialistAuthoring onlyEphemeral. 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

    FeatureOptions
    WorkloadText generation, image generation, and custom / scriptable pipelines
    PlatformMI300X, MI325X, MI355X
    FrameworkSGLang, vLLM, xDiT
    Kernel languageHIP, Triton, FlyDSL
    Kernel backendsGEAK, KernelForge
    LLM backendClaude, Codex

    Get started

    GoalGuide
    Set up Hyperloom and run a demoQuickstart
    Launch and monitor an optimizationRun an optimization
    Understand the algorithmOptimization loop
    python -m hyperloom optimize
    

    Documentation

    TopicLink
    ROCm DocsHyperloom
    Authentication and credentialsAuthentication & credentials
    Environment variablesEnvironment variables
    ComponentsComponents
    CompatibilityCompatibility matrix
    TroubleshootingTroubleshooting
    OperationsOperations & self-hosting
    Session output schemasession_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

    • Runtime package: src/hyperloom/
    • Contributor & AI authoring contract: AGENTS.md
    • Main agent instructions: src/hyperloom/inference_optimizer/SKILL.md
    • CLI entry point: hyperloom <command> (or python -m hyperloom <command>)
    • Operator tools: python -m hyperloom session <breakdown|report|backfill|events|state>
    • Compute-partition sweep: python3 scripts/partition_mode_sweep.py — sets each AMD partition mode (SPX/DPX/QPX/CPX) on one card in turn, runs the same benchmark on every partition that mode creates, sums the throughput and restores the entry mode. Answers which shape a workload wants before a session commits to one; optimize itself only ever reads the mode. Needs privilege for the set, so it is a script rather than part of the loop.
    • Platform tuning audit: python3 scripts/platform_audit.py — checks the host CPU tuning that silently changes benchmark results. Judges Core Performance Boost and the cpufreq governor against AMD's BIOS & Workload Tuning Guide for EPYC 9004; records determinism, SMT and NPS without a verdict, because chapter 5 varies those by workload or the OS layer can only infer them. Reads /sys, /proc and — as root — the HWCR MSR; no credentials, nothing written. Exit 0 on target, 1 a knob is wrong, 2 unresolved, which CI should treat as missing coverage rather than as a failure. The BIOS-only knobs are not reachable this way; see below.
    • BIOS audit over the BMC: sudo python3 scripts/platform_audit_bmc.py --bmc-user <ro> — covers the three knobs the OS cannot see (High Performance profile, APBDIS, DF C-states), targeted per 58011 §4.2.1, §4.4.3 and §4.4.4. Without --bmc-user it refuses to run unless --allow-account-creation is passed, because that path mints a temporary ADMINISTRATOR account on the BMC; exit 3 means such an account was left enabled or could not be confirmed revoked, and should page someone. The script's docstring has the account lifecycle and the rest of the exit codes.
    • Documentation source: docs/

    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, Claude Code, and Codex) 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.