TheRock/rocm-systems/experimental/python/perfxpert/README.md

PerfXpert

AI-powered AMD ROCm GPU trace analysis.

Caution

Experimental software. PerfXpert is still evolving and is provided without warranties or guarantees. AI-generated analysis, explanations, and recommendations can be incomplete or incorrect, so verify important results before relying on them in production or performance-critical workflows.

Quickstart

Install

# SKIP-SAMPLE — package install + venv setup are host-specific
# Ubuntu 22/24 example. Use the package-manager equivalent on RHEL/SLES.
apt install -y curl git unzip python3-venv python3-pip
python3 -m venv .venv
. .venv/bin/activate
bun --version  # install bun from your approved package source if this fails

# Latest development build from ROCm/rocm-systems.
REF=develop; curl -fsSL "https://raw.githubusercontent.com/ROCm/rocm-systems/${REF}/experimental/python/perfxpert/scripts/pip-install-from-git.sh" | bash -s -- "${REF}"

Pin a tag or commit by changing REF:

# SKIP-SAMPLE — replace <SHA> with a real tag or commit
REF=<SHA>; curl -fsSL "https://raw.githubusercontent.com/ROCm/rocm-systems/${REF}/experimental/python/perfxpert/scripts/pip-install-from-git.sh" | bash -s -- "${REF}"

The wrapper installs from GitHub, scopes submodule init to the pinned PerfXpert opencode submodule, and builds the patched bundled perfxpert-code binary. If bun is missing, pip fails with an actionable prerequisite message instead of producing a partial TUI install. The wrapper verifies perfxpert-code before exiting. No separate opencode install is needed for the default perfxpert-code TUI. See docs/guides/getting-started.md for the Ubuntu/RHEL/SLES package matrix, direct-pip equivalent, editable installs, and troubleshooting.

LLM Providers

Provider	Source	Typical use
anthropic	Claude API	Production default; requires ANTHROPIC_API_KEY
openai	OpenAI API	Alternative hosted; requires OPENAI_API_KEY
ollama	Local Ollama	Fully local; requires a running ollama serve
private	Any OpenAI-compatible endpoint	Internal deployments; requires an endpoint (PERFXPERT_LLM_PRIVATE_URL) plus either PERFXPERT_LLM_PRIVATE_API_KEY or --llm-api-key; set PERFXPERT_LLM_PRIVATE_MODEL to select the deployment model
opencode	Bundled opencode CLI	Used by perfxpert-code; not callable from inside opencode itself (recursion-guarded)

Private endpoint example:

# SKIP-SAMPLE — requires a real trace.db and reachable private endpoint
export PERFXPERT_LLM_PRIVATE_URL="https://llm-api.iexample.com/OpenAI"
export PERFXPERT_LLM_PRIVATE_MODEL="gpt-5.3-codex"
export PERFXPERT_LLM_PRIVATE_API_KEY="..."
export PERFXPERT_LLM_PRIVATE_HEADERS='{"Ocp-Apim-Subscription-Key":".......","user":".....","api-version":"preview"}'
perfxpert analyze -i trace.db --llm private

Analyze

--format accepts text (default), json, markdown, and webview (AMD-themed HTML). text prints to stdout unless -o/-d is supplied. All other formats write a report file by default, even when -o and -d are omitted; use -o - to force stdout for pipelines.

LLM-backed analysis uses Chat Completions-style requests. Choose a provider model or private endpoint model that supports the Chat Completions API; Responses-only, embeddings-only, or non-chat models will fail.

# SKIP-SAMPLE — requires a real trace.db and provider credentials
export ANTHROPIC_API_KEY="sk-ant-..."
perfxpert analyze -i trace.db --llm anthropic --format webview -o report.html

export OPENAI_API_KEY="sk-..."
perfxpert analyze -i trace.db --llm openai --llm-model gpt-4o-mini --format markdown -o report.md

# Air-gap mode: no LLM calls, deterministic local analysis only.
PERFXPERT_AIRGAP=1 perfxpert analyze -i trace.db --format markdown -o report.md

Interactive TUI

# SKIP-SAMPLE — launches interactive CLIs and may write backend config
# Default first-class TUI: bundled patched opencode built during install.
perfxpert-code

# Use native shells with PerfXpert MCP and context installed for that backend.
perfxpert-code claude
perfxpert-code codex
perfxpert-code gemini

# Explicit upstream-opencode escape hatch. The default TUI does not need this.
PERFXPERT_OPENCODE_PATH="$(command -v opencode)" perfxpert-code opencode

Preview or uninstall a backend integration:

# SKIP-SAMPLE — preview/uninstall commands mutate or inspect backend setup
perfxpert-code claude --dry-run "analyze this trace"
perfxpert-code uninstall claude

Other Commands

# SKIP-SAMPLE — requires real trace DB paths
perfxpert diff baseline.db candidate.db --format markdown
perfxpert doctor

Architecture (v0.2.0+)

flowchart TD
  classDef entry fill:#e8f3ff,stroke:#1664ad,color:#0f2f4a,stroke-width:1px
  classDef runtime fill:#fff4d8,stroke:#a66a00,color:#4a3100,stroke-width:1px
  classDef agent fill:#eaf8ef,stroke:#227343,color:#143b26,stroke-width:1px
  classDef brain fill:#fff8c7,stroke:#9a6b00,color:#3d2b00,stroke-width:2px
  classDef guard fill:#ffe9e4,stroke:#b94a36,color:#5c2016,stroke-width:1px
  classDef data fill:#f4edff,stroke:#7250b5,color:#34205c,stroke-width:1px

  subgraph entry["Entry surfaces"]
    analyze["perfxpert analyze<br/>batch reports"]
    code["perfxpert-code<br/>bundled patched TUI"]
    mcp["perfxpert-mcp<br/>external MCP clients"]
    api["perfxpert.api<br/>Python embedding"]
  end

  subgraph brainSection["🧠 Shared PerfXpert brain"]
    runtime["Shared agent runtime/session<br/>same analysis brain for every shell"]
    hierarchy["8-agent hierarchy<br/>Root → Analysis / Recommendation / Correctness<br/>Compute / Memory / Latency / Diff specialists"]
  end

  knowledge["Deterministic tools + validated knowledge YAMLs<br/>classifiers, counters, hardware facts, trace diff"]
  gates["Correctness middleware<br/>gate_cascade + intent router"]
  readonly["56 READ_ONLY MCP tools<br/>8 agent tools + 47 classifier/knowledge tools + 1 diff tool"]

  analyze --> runtime
  code --> runtime
  api --> runtime
  mcp --> readonly
  readonly --> runtime
  runtime --> hierarchy
  hierarchy --> knowledge
  hierarchy --> gates
  knowledge --> gates

  class analyze,code,mcp,api entry
  class runtime,hierarchy brain
  class gates guard
  class knowledge,readonly data

The GitHub wrapper is the supported install path today. It installs PerfXpert and builds the default perfxpert-code TUI from the pinned experimental/python/perfxpert/opencode submodule plus the local patch series. If build prerequisites are missing, install fails with package-manager guidance instead of falling back to an arbitrary opencode binary.

Contributing

perfxpert welcomes contributions. Start with CONTRIBUTING.md for the extension-surface matrix + governance. Per-surface guides under docs/contributing/. Architectural changes go through an RFC.

Feature flags

Flag	Default	Purpose
PERFXPERT_OPENCODE_PATH	unset	Explicit upstream-opencode escape hatch used only by perfxpert-code opencode ...; the default TUI ignores it

Supported GPUs

Arch	GPU	CDNA/RDNA
gfx908	MI100	CDNA1
gfx90a	MI210/MI250/MI250X	CDNA2
gfx942	MI300A/MI300X/MI325X	CDNA3
gfx950	MI350X/MI355X	CDNA4
gfx1030	RX 6900 XT	RDNA2
gfx1100	RX 7900 XTX	RDNA3

Documentation

• Getting started
  • Getting started guide
  • Agentic mode: air-gap vs LLM, provider ladder
  • Multi-backend launcher (perfxpert-code claude|gemini|codex) — register perfxpert with your native Claude Code / Gemini CLI TUI while keeping the perfxpert tool-priority gate.
• Architecture (v0.2.0+)
  • Architecture overview
  • Architecture index
    • Agent hierarchy (Root / Analysis / Recommendation / specialists)
    • Gate cascade (5 correctness gates as middleware)
    • BackendAdapter protocol (multi-backend launcher)
• Integration
  • Integration index
    • MCP server (perfxpert-mcp) — 56 READ_ONLY tools (8 agent-hierarchy + 47 knowledge/classifier + 1 trace_diff)
    • Python API (perfxpert.api) — 1:1 mirror of the 8 agent MCP tools
• Contributing
  • CONTRIBUTING.md
  • Contributing index
    • External-tool dependencies (require_tool)
• Other
  • Historical migration notes

Licensing

MIT. opencode is also MIT — the packaged build bundles a patched binary from the pinned upstream submodule, and source/editable checkouts use that same fork via the local submodule build path.