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

Changelog

All notable changes to perfxpert will be documented in this file. The format is based on Keep a Changelog.

[Unreleased]

Added

• Advanced specialist tools — 8 new READ_ONLY MCP tools. The specialist fences now consume eight additional deterministic tools surfaced on the MCP wire: kernel_fusion.find_fusion_candidates (adjacent-short-kernel fusion), gpu_runtime_monitor.parse_amd_smi_json / parse_rocm_smi_json / analyze_thermal (thermal / throttle envelope), unified_memory.analyze_paging (MI300X paging + cross-die), dependency_graph.reconstruct_dag (critical-path + GPU bubbles), pragma.lookup_pragmas / explain_pragma / suggest_pragmas_for_kernel (LLVM loop-hint advanced recommendations, gated behind --advanced).
• Change-Impact Prediction — 3 new MCP tools. predict_impact.predict_change_impact, predict_impact.list_supported_changes, predict_impact.explain_prediction. Returns a conservative speedup bracket (hi × 0.85), confidence, rationale, and a source_citation back into knowledge/proven_optimizations.yaml. Amdahl + tier-2 gates enforced internally. Bumps schema_version to 0.3.3 when any rec fires a prediction.
• Live Roofline — roofline.plot_points MCP tool. Emits a per-kernel (ai, achieved_flops_per_s, bottleneck_class, fp_type, confidence) list + arch ridge point; webview renders an inline-SVG log-log plot. Populating the top-level roofline key bumps schema_version to 0.3.4.
• Communication / RCCL analysis — rccl_analysis.analyze_collectives + interconnect.lookup_peaks MCP tools. Per-collective effective_bw_gbps / efficiency_pct / efficiency_label + rollup summary. Validated at the module boundary via the CommunicationBlock + CollectiveEntry Pydantic models (perfxpert/agents/schemas.py). Bumps schema_version to 0.3.2.
• ATT Flamegraph (webview-only pure-rendering derivative). perfxpert/formatters/_att_flamegraph.py renders an inline-SVG flamegraph under the Thread Trace .scard when thread_trace.has_att_data is true. No new payload key — pure function of the existing thread_trace.kernels + top_stalling_instructions subfields.
• Knowledge YAML conventions. applies_to_gfx arch gate on matrix_meter.yaml + attention_patterns.yaml (plus selective entries in proven_optimizations.yaml / compiler_pragmas.yaml); units field on every expected_impact entry in fusion_patterns.yaml.
• Fence template consolidation. diff_specialist.md is now the canonical per-agent fence template; root.md and recommendation.md were re-aligned to that layout.
• Agents-as-MCP-tools (8 READ_ONLY agent tools). The MCP server now exposes every agent in the hierarchy as its own tool: perfxpert_agent_root, perfxpert_agent_analysis, perfxpert_agent_recommendation, perfxpert_agent_correctness, perfxpert_agent_compute_specialist, perfxpert_agent_memory_specialist, perfxpert_agent_latency_specialist, perfxpert_agent_diff_specialist. Backend TUIs (Claude Code, Gemini CLI, Codex CLI, opencode) read the agent hierarchy as reference in AGENTS.md and freely pick whichever of the 56 MCP tools matches the user's intent. Current MCP tool inventory: 56 (8 agent-hierarchy + 48 classifier / knowledge / advanced-specialist / trace_diff). Schemas remain frozen per perfxpert/agents/schemas.py.
• Public Python API (perfxpert.api). 1:1 mirror of the 8 agent MCP tools (api.agent_root, api.agent_analysis, etc.) for in-process embedding without standing up an MCP server. The perfxpert analyze CLI now calls perfxpert.api.agent_root(...) internally — same function the MCP tool wraps.
• Scoped submodule-init fast-install path. scripts/pip-install-from-git.sh (new wrapper) + the equivalent GIT_CONFIG_COUNT=1 GIT_CONFIG_KEY_0=submodule.active GIT_CONFIG_VALUE_0=experimental/python/perfxpert/opencode pip install … incantation drops the rocm-systems submodule-init time from ~141 sec (recursive init of ~34 unrelated submodules) down to ~30 ms. Detailed measurements + rationale in docs/guides/getting-started.md §1.2. The plain recursive one-liner still works for users who want it.

Changed

• Codex gate discovery. Codex-rendered gate prompts now allow only tool_search / tool_search_tool as a discovery-only prelude when the required PerfXpert MCP gate tools are deferred out of the initial tool inventory; shell, SSH, build, edit, and profiling fallbacks remain blocked until perfxpert_intent_classify returns.
• Breaking: non-text perfxpert analyze formats now write report files by default. --format json, --format markdown, and --format webview synthesize a report filename when -o/-d are omitted. Use -o - to preserve stdout for shell pipelines.
• Git install hardening. The GitHub wrapper no longer runs apt/dnf/zypper/sudo unless PERFXPERT_AUTO_INSTALL_PREREQS=1 or --auto-install-prereqs is explicitly supplied. The bundled opencode build no longer bootstraps bun unless PERFXPERT_AUTO_INSTALL_BUN=1 is explicitly supplied.
• --llm providers. All five providers — anthropic, openai, ollama, private, opencode — are selectable from the CLI and from perfxpert.api.agent_root(..., provider=<name>). claude-code stays removed (single-provider wrapper, superseded by the opencode + backend-adapter stack).
• No forced aggregator tool. The backend LLM no longer must call a single perfxpert_run_root_analysis after perfxpert_intent_classify. The "MUST call perfxpert_run_root_analysis" contract is gone; backends choose any of the 56 MCP tools based on intent. The tool-priority gate still requires perfxpert_intent_classify as the first call.
• FallbackProvider exception taxonomy. Documented the full typed-error set — AuthError, RateLimitError, QuotaExceededError, TransientError, FatalError, TimeoutError, ProviderChainExhausted. Only transient + rate-limit cascade; auth / quota / fatal surface immediately because retry is futile. See docs/guides/agentic-mode.md §"Fallback chain".

Docs

• README.md — MCP count 34→43, 5-provider list restored, pip upgrade hint, fast-install wrapper surfaced.
• docs/guides/getting-started.md — MCP count refreshed in 3 places, §10 LLM Providers rebuilt for all 5 providers with CLI/API parity, duplicate §3/4/5/6 heading numbering fixed (continued into §7-§14), §1.2 scoped-submodule content retained. Footer marker reintroduced.
• docs/guides/backends.md — MCP count refreshed, forced-tool-call language removed.
• docs/guides/agentic-mode.md — typed-error taxonomy table added.
• docs/integration/README.md — MCP count refreshed, agent-tools line added.
• docs/integration/mcp-server.md — MCP count refreshed in 5 places, "Snapshot: agent-hierarchy tools" section added, _safety machinery reference rewritten as "private _-prefixed skip list".
• docs/architecture.md — providers documented as CLI- AND library-accessible.
• docs/architecture/README.md — backend-adapter.md index row added.
• docs/architecture/agent-hierarchy.md — agent MCP + API surface cross-reference added; "only reachable via Root" implication removed.
• NEW docs/guides/python-api.md — embedding guide with one example per agent, links back to docs/integration/mcp-server.md.

[0.2.0] — 2026-04-19 (release cut)

This is the first tagged perfxpert release. It consolidates the multi-backend launcher (previously drafted as v0.3.0 below), the Codex backend adapter (drafted as v0.3.1 below), and Phase 8's final cleanup into a single v0.2.0 cut. The v0.3.0 and v0.3.1 headings below are retained as implementation-cycle drafts for audit trail; the canonical user-visible release is this v0.2.0 block.

Changed

• Version bump 0.1.0 → 0.2.0. pyproject.toml, perfxpert/__init__.py, CMakeLists.txt, the perfxpert doctor banner fallback, and the docs/guides/getting-started.md footer marker all move together. JSON analysis output keeps schema_version = "0.1.0" by design — that field tracks the on-disk analysis schema, not the module version, and consumers key off it independently.
• Claude Code pointer path migrated from .claude/CLAUDE.md to CLAUDE.local.md at the project root. Claude Code auto-loads CLAUDE.local.md at session start, so the perfxpert prompt now reaches the model without requiring a manual /read. User-facing docs (docs/guides/backends.md, docs/integration/mcp-server.md, docs/architecture/backend-adapter.md) are refreshed to match.
• claude mcp list parser now handles Anthropic Claude CLI's plain-text output format. Recent Claude CLI releases dropped the --json flag; the adapter parses the plain-text table form instead. The JSON-specific helpers in perfxpert/cli/_backend/claude.py (_extract_server_names, _extract_tool_names) are removed.

Added

• Codex backend (perfxpert-code codex). Full Codex CLI adapter landed in PR 2. Trust-gate workflow ([projects."<cwd>"].trust_level = "trusted" in ~/.codex/config.toml) with interactive prompt + CI-mode PERFXPERT_AUTO_TRUST=1 bypass (emits an always-on stderr warning even under --quiet). Gate enforcement is prompt-layer-only because Codex's native PreToolUse hook intercepts Bash only (not MCP tool calls) as of April 2026 — see the Codex hook-surface decision record. tomlkit is promoted to a required runtime dependency so the comment-preserving TOML fallback path works out of the box without an [extras] install step. Full install / uninstall recipe in docs/guides/backends.md.
• Multi-backend perfxpert-code launcher — claude, gemini, codex, uninstall subcommands in one dispatcher. Per-(backend, cwd-hash, file-set-hash) consent; --dry-run and --quiet dispatcher flags; MCP warmup + retry with env-configurable timeouts (PERFXPERT_MCP_WARMUP_TIMEOUT_S, PERFXPERT_MCP_RETRY_BUDGET_S, PERFXPERT_SKIP_LIVE_CHECK).

Fixed

• Wordmark. The perfxpert-code banner previously rendered mis-shaped glyphs for r, f, p, t — so users saw a string that did not read as "PerfXpert". Patch 0051-amd-wordmark-ui.patch is rewritten with correctly-shaped 9-letter block-letter art (44 chars wide) and the bundled opencode binary is rebuilt so the fix reaches pip-install users automatically.

Docs

• docs/guides/getting-started.md fully audited and refreshed for cycle-2/3 stack state (agentic-only, no PERFXPERT_LEGACY, multi-backend launcher recipes, Codex trust-gate section).
• Phase-9 docs-audit cleanup: docs/canonical_facts/ + inventory snapshot artifacts dropped; docs-tooling test suite pared down and relocated under experimental/python/perfxpert/tests/.
• Red-team / ship-readiness gate consolidated into tests/test_ship_readiness.py (strict mode) — ships-as-tested evidence rather than CI-gate-only.

v0.3.1 — Codex backend

Added

• perfxpert-code codex subcommand — full Codex CLI adapter. Registers perfxpert under [mcp_servers.perfxpert] in <cwd>/.codex/config.toml for trusted projects (falling back to ~/.codex/config.toml when project scope is unavailable), stages the perfxpert-managed compatibility file AGENTS.override.md (shadow-copies root AGENTS.md when present), and handles Codex's [projects."<cwd>"].trust_level = "trusted" requirement (interactive prompt, or PERFXPERT_AUTO_TRUST=1 for CI with an always-on stderr warning bypassing --quiet). Gate enforcement is prompt-layer-only because Codex's native PreToolUse hook intercepts Bash only as of April 2026 (rationale in the local Codex hook-surface decision record). perfxpert-code uninstall codex reverses the install (MCP table + trust entry + staged AGENTS.override.md), with ConfigClobber / skipped_due_to_drift protection against git-tracked or malformed TOML.

v0.3.0 — multi-backend launcher

Added

• perfxpert-code claude|gemini|codex|uninstall subcommands. Multi-backend launcher. claude / gemini adapters fully ship in PR 1; codex is a stub that prints a deferred notice and exits 42. uninstall <backend> reverses an install.
• --dry-run, --quiet dispatcher flags. --dry-run runs adapter.plan(), prints the actions, skips every write + spawn(). --quiet suppresses the AMD banner + per-step progress log.
• BackendAdapter Protocol for contributors. Locked day-1 interface under perfxpert/cli/_backend/protocol.py so fifth-backend work doesn't need Protocol churn. See docs/architecture/backend-adapter.md.
• Per-backend gate hook with event-based lift. Native PreToolUse for Claude Code, native BeforeTool / AfterTool hooks for Gemini CLI. Lift fires once perfxpert_intent_classify returns in the current session; non-perfxpert tool calls before that are rejected with a retry-hint message.
• MCP warmup + retry (env-configurable). PERFXPERT_MCP_WARMUP_TIMEOUT_S (default 10s), PERFXPERT_MCP_RETRY_BUDGET_S (default 30s), PERFXPERT_SKIP_LIVE_CHECK to skip post-install verification in CI.
• Consent model: per-(backend, cwd-hash, file-set-hash) tuple. Persisted under ~/.perfxpert/consent.json. Re-runs in the same directory are silent; changing the file set re-prompts. PERFXPERT_ASSUME_CONSENT=1 bypasses the prompt (required for non-interactive stdin).

Deferred

• Codex adapter. Lands in PR 2 (plan Task 10). The codex subcommand is wired as a stub in PR 1 for surface stability.

Decisions

• Claude Code gate hook uses the native PreToolUse surface (not permissions.deny). Doc-fetch evidence + rationale are captured in the local Claude hook-surface decision record.

Docs

• docs/guides/getting-started.md §"Choosing a backend" — short-recipe overview.
• docs/guides/backends.md — dedicated user guide (comparison table, install / uninstall recipes, env-var reference, four troubleshooting scenarios).
• docs/architecture/backend-adapter.md — contributor-facing Protocol + lifecycle + "how to add a new backend" steps.
• docs/integration/mcp-server.md — cross-link to guides/backends.md at the top (manual snippets remain for direct-CLI users).

vNEXT

Removed

• BREAKING: pre-rename API-key env vars from the old project name are no longer honored. Any environment variable prefixed with the old project name (including the reference-guide override previously referenced in migration docs) must be re-exported under the PERFXPERT_* namespace. The canonical names are PERFXPERT_LLM_ANTHROPIC_KEY, PERFXPERT_LLM_OPENAI_KEY, and the standard vendor ANTHROPIC_API_KEY / OPENAI_API_KEY continue to be honored. A single pre-rename alias (the ROCPD_LLM_* prefix — the rest were removed in Phase 7.1) still works with a DeprecationWarning as a migration ramp.
• Legacy ai_analysis module (perfxpert/ai_analysis/) fully removed, along with all parity and feature-flag dispatch tests. The PERFXPERT_LEGACY environment variable is now unrecognized — setting it has no effect.
• docs/deprecation/PERFXPERT_LEGACY.md superseded; migration notes moved to docs/archive/migration-to-agentic.md.

Changed

• perfxpert.analyze.execute() unconditionally delegates to the agentic runtime; the _execute_legacy fallback is gone.
• perfxpert.agents.root wires the real tasks.* tools (create / next / update / close) instead of no-op lambda stubs.

v0.2.0 draft — 2026-04-18 (agentic-runtime landing, rolled into v0.2.0 above)

Added

• Agentic runtime: perfxpert/agents/ with 7 agent definitions (Root, Analysis, Recommendation, Correctness, 3 specialists) over OpenAI Agents SDK. See design spec for full architecture.
• perfxpert-code: new interactive TUI. Ships as part of the pip install (bundles opencode per-platform). Replaces the old conversational mode flag on perfxpert analyze.
• MCP server: perfxpert/mcp_server/ exposes READ_ONLY tools to external clients (Claude Desktop, Cursor, etc.).
• Split fence: per-agent agents/fence/*.md (≤ 400 lines each; CI-enforced) replaces the monolithic llm-reference-guide.md.
• 22 knowledge YAMLs in perfxpert/knowledge/ replace structured data that used to be prose in the fence.
• 45 deterministic tools in perfxpert/tools/ — all unit-testable, no LLM calls.
• 5 provider adapters in perfxpert/providers/ (Anthropic, OpenAI, Ollama, private, opencode) — pluggable via Agents SDK Model protocol.
• Deterministic 5-gate cascade (runtime/gate_cascade.py) — anti-Sakana protection via SOL bound + bitwise/numeric correctness + regression gate + test anchors.
• perfxpert doctor now reports active mode (agentic | legacy).

Changed

• PERFXPERT_USE_AGENTS was removed in Phase 7.1, along with the toggle code it kept alive.
• The single-call LLM entrypoint was subsequently removed; use perfxpert.agents.runtime.build_session() + session.run_root(...).
• CI matrix inverted: agentic is the primary test matrix; the pre-v0.2.0 matrix was subsequently removed.
• README, CONTRIBUTING, and the Python API docs rewritten for the new architecture.

Deprecated

• PERFXPERT_LEGACY was introduced as a one-minor-version fallback in v0.2.0 and was then subsequently removed.
• LLMAnalyzer was kept as a deprecation stub in v0.2.0 and was removed in Phase 7.1.

Removed

• Pre-agentic interactive workflow module (~4000 LOC: InteractiveSession + WorkflowSession + 7-phase loop) subsequently removed. Replaced by perfxpert-code wrapping the bundled opencode TUI. (The 7-phase loop here refers to the user-facing workflow phases — profile → analyze → optimize → re-profile — not release phases.)
• Pre-agentic LLM conversation module (~600 LOC: streaming + auto-compaction) subsequently removed. Replaced by Agents SDK native sessions.
• Monolithic fence reference guide subsequently removed. Split into per-agent slices + structured knowledge YAMLs under perfxpert/knowledge/.
• LLMAnalyzer.analyze_with_llm and the _call_<provider>() private methods were removed in Phase 7.1.
• tests/test_llm_conversation.py (51 tests of a deleted module) subsequently removed.
• Conversational-session CLI flags subsequently removed. Users typing the old flags get a migration hint pointing to perfxpert-code.
• load_reference_guide export from the pre-agentic tree was subsequently removed (previously relocated to perfxpert.providers._reference_guide).

Migration

See docs/archive/migration-to-agentic.md.

Backwards-compatible stubs (v0.2.0 only, all subsequently removed)

• LLMAnalyzer stub class — still importable in v0.2.0, removed in Phase 7.1.
• PERFXPERT_USE_AGENTS env var — no-op in v0.2.0, removed in Phase 7.1.
• PERFXPERT_LEGACY — fallback toggle in v0.2.0, subsequently removed. A user-supplied reference-guide override env var (pre-rename name) was also required while PERFXPERT_LEGACY=1 was active; both were removed along with it.

---

[0.1.x] — 2026-0X-XX and earlier

See git history. v0.1.x ran the pre-agentic path by default. The experimental opt-in PERFXPERT_USE_AGENTS (available in later v0.1.x releases during the agentic refactor) was removed in Phase 7.1.