From 872d37dfa17713ddbd416c4a5d7f13c42da7b7ed Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Mon, 2 Mar 2026 22:22:24 +0000 Subject: [PATCH 1/3] Initial plan From 8d550e905210075df1e116da0c2cc3884638417a Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Mon, 2 Mar 2026 22:25:24 +0000 Subject: [PATCH 2/3] Reorganize README to focus on user experience and primary usage modes Co-authored-by: mawad-amd <112003944+mawad-amd@users.noreply.github.com> --- README.md | 196 +++++++++++++++--------------------------------------- 1 file changed, 55 insertions(+), 141 deletions(-) diff --git a/README.md b/README.md index fbddd6a..223edd4 100644 --- a/README.md +++ b/README.md @@ -8,14 +8,59 @@ **LLM-Ready Profiling and Analysis Toolkit for AMD CPU and GPUs** -IntelliKit is a collection of intelligent tools designed to make CPU and GPU code development, profiling, and validation accessible to LLMs and human developers alike. Built for AMD ROCm, these tools provide clean abstractions over complex GPU internals. +IntelliKit is a collection of profiling and analysis tools for AMD ROCm that expose clean, human-readable APIs for both developers and LLM-driven workflows. -## Philosophy +## Installation + +Install all tools from Git (one command): -Traditional CPU and GPU profiling and analysis tools expose raw hardware counters and assembly. IntelliKit tools are designed to: +```bash +curl -sSL https://raw.githubusercontent.com/AMDResearch/intellikit/main/install/tools/install.sh | bash +``` + +**Options:** + +- **Custom pip command** (for multiple Python versions): + ```bash + curl -sSL https://raw.githubusercontent.com/AMDResearch/intellikit/main/install/tools/install.sh | bash -s -- --pip-cmd pip3.12 + ``` -- **Decode complexity**: Turn hardware metrics into human-readable insights -- **Enable LLM integration**: Provide clean APIs suitable for LLM-driven workflows (MCP-ready) +- **Install from a specific branch/tag:** + ```bash + curl -sSL https://raw.githubusercontent.com/AMDResearch/intellikit/main/install/tools/install.sh | bash -s -- --ref my-branch + ``` + +- **Dry-run (preview commands):** + ```bash + curl -sSL https://raw.githubusercontent.com/AMDResearch/intellikit/main/install/tools/install.sh | bash -s -- --dry-run + ``` + +**Install individual tools from Git:** + +```bash +pip install "git+https://github.com/AMDResearch/intellikit.git#subdirectory=accordo" +pip install "git+https://github.com/AMDResearch/intellikit.git#subdirectory=linex" +pip install "git+https://github.com/AMDResearch/intellikit.git#subdirectory=metrix" +pip install "git+https://github.com/AMDResearch/intellikit.git#subdirectory=nexus" +pip install "git+https://github.com/AMDResearch/intellikit.git#subdirectory=rocm_mcp" +pip install "git+https://github.com/AMDResearch/intellikit.git#subdirectory=uprof_mcp" +``` + +**From a clone (editable installs):** + +```bash +git clone https://github.com/AMDResearch/intellikit.git +cd intellikit +pip install -e ./accordo +pip install -e ./linex +# ... or any subset of the tools +``` + +## Requirements + +- **Python**: >= 3.10 +- **ROCm**: >= 6.0 (7.0+ for linex) +- **Hardware**: MI300+ GPUs ## Tools @@ -167,118 +212,21 @@ Add to your JSON MCP config: } ``` -## Installation - -Install each tool from its subdirectory. No top-level metapackage. +## Agent Skills (AI agents) -**Install all tools from Git (one command):** +Install IntelliKit skills so AI agents can discover and use Metrix, Accordo, and Nexus: ```bash -curl -sSL https://raw.githubusercontent.com/AMDResearch/intellikit/main/install/tools/install.sh | bash -``` - -**Options:** - -- **Custom pip command** (for multiple Python versions): - ```bash - curl -sSL https://raw.githubusercontent.com/AMDResearch/intellikit/main/install/tools/install.sh | bash -s -- --pip-cmd pip3.12 - # or - curl -sSL https://raw.githubusercontent.com/AMDResearch/intellikit/main/install/tools/install.sh | bash -s -- --pip-cmd "python3.12 -m pip" - ``` - -- **Install from a specific branch/tag:** - ```bash - curl -sSL https://raw.githubusercontent.com/AMDResearch/intellikit/main/install/tools/install.sh | bash -s -- --ref my-branch - ``` - -- **Dry-run (preview commands):** - ```bash - curl -sSL https://raw.githubusercontent.com/AMDResearch/intellikit/main/install/tools/install.sh | bash -s -- --dry-run - ``` - -- **From a clone:** - ```bash - ./install/tools/install.sh --pip-cmd pip3.12 --ref main --dry-run - ``` - -**Environment variables** (CLI options take precedence): `PIP_CMD`, `INTELLIKIT_REPO_URL`, `INTELLIKIT_REF` - -**Install individual tools from Git:** - -```bash -pip install "git+https://github.com/AMDResearch/intellikit.git#subdirectory=accordo" -pip install "git+https://github.com/AMDResearch/intellikit.git#subdirectory=linex" -pip install "git+https://github.com/AMDResearch/intellikit.git#subdirectory=metrix" -pip install "git+https://github.com/AMDResearch/intellikit.git#subdirectory=nexus" -pip install "git+https://github.com/AMDResearch/intellikit.git#subdirectory=rocm_mcp" -pip install "git+https://github.com/AMDResearch/intellikit.git#subdirectory=uprof_mcp" -``` - -**From a clone (editable installs from local paths):** - -```bash -git clone https://github.com/AMDResearch/intellikit.git -cd intellikit -pip install -e ./accordo -pip install -e ./linex -# ... or any subset of the tools -``` - -### Agent Skills (AI agents) - -Install IntelliKit skills so AI agents can discover and use Metrix, Accordo, and Nexus. Skills are installed as `SKILL.md` files under a single directory; agents that read that location get the instructions automatically. - -**Default: local (current workspace) - agents target** - -```bash -# One-liner: installs into ./.agents/skills/ (current directory) +# Install into ./.agents/skills/ (current directory) curl -sSL https://raw.githubusercontent.com/AMDResearch/intellikit/main/install/skills/install.sh | bash -``` - -**Different agent targets** (cursor, claude, codex, agents): -```bash -# Cursor +# Install for a specific agent (cursor, claude, codex) curl -sSL https://raw.githubusercontent.com/AMDResearch/intellikit/main/install/skills/install.sh | bash -s -- --target cursor -# Claude -curl -sSL https://raw.githubusercontent.com/AMDResearch/intellikit/main/install/skills/install.sh | bash -s -- --target claude - -# Codex -curl -sSL https://raw.githubusercontent.com/AMDResearch/intellikit/main/install/skills/install.sh | bash -s -- --target codex -``` - -**Global (all projects)** - -```bash -# Install into ~/.cursor/skills/ (or ~/.claude/skills/, etc.) +# Install globally (~/.cursor/skills/, etc.) curl -sSL https://raw.githubusercontent.com/AMDResearch/intellikit/main/install/skills/install.sh | bash -s -- --target cursor --global ``` -**From a clone** - -```bash -git clone https://github.com/AMDResearch/intellikit.git -cd intellikit -./install/skills/install.sh # local: ./.agents/skills/ -./install/skills/install.sh --target cursor # local: ./.cursor/skills/ -./install/skills/install.sh --target claude --global # global: ~/.claude/skills/ -./install/skills/install.sh --dry-run # show what would be installed -``` - -**Resulting layout:** - -- **Local (agents):** `./.agents/skills/metrix/SKILL.md`, `./.agents/skills/accordo/SKILL.md`, `./.agents/skills/nexus/SKILL.md` -- **Local (cursor):** `./.cursor/skills/metrix/SKILL.md`, `./.cursor/skills/accordo/SKILL.md`, `./.cursor/skills/nexus/SKILL.md` -- **Global (claude):** `~/.claude/skills/metrix/SKILL.md`, `~/.claude/skills/accordo/SKILL.md`, `~/.claude/skills/nexus/SKILL.md` - -## Requirements - -- **Python**: >= 3.10 -- **ROCm**: >= 6.0 (7.0+ for linex) -- **Hardware**: MI300+ GPUs - - ## Documentation Each tool has its own detailed documentation: @@ -290,40 +238,6 @@ Each tool has its own detailed documentation: - [ROCm-MCP Documentation](rocm_mcp/README.md) + [Examples](rocm_mcp/examples/) - [uprof-MCP Documentation](uprof_mcp/README.md) + [Examples](uprof_mcp/examples/) -## Example Workflow - -```python -# 1. Profile baseline kernel with Metrix -from metrix import Metrix -profiler = Metrix() -baseline_results = profiler.profile("./app_baseline") -baseline_bw = baseline_results.kernels[0].metrics['memory.hbm_bandwidth_utilization'].avg - -# 2. Extract kernel source with Nexus -from nexus import Nexus -nexus = Nexus() -trace = nexus.run(["./app_baseline"]) -for kernel in trace: - print(kernel.hip) # Source code - -# 3. Apply optimization (external step) -# ... modify kernel ... - -# 4. Validate with Accordo -from accordo import Accordo -validator = Accordo(binary="./app_baseline", kernel_name="my_kernel") - -ref_snap = validator.capture_snapshot(binary="./app_baseline") -opt_snap = validator.capture_snapshot(binary="./app_opt") -result = validator.compare_snapshots(ref_snap, opt_snap, tolerance=1e-6) - -if result.is_valid: - opt_results = profiler.profile("./app_opt") - opt_bw = opt_results.kernels[0].metrics['memory.hbm_bandwidth_utilization'].avg - print(f"✓ PASS: {result.num_arrays_validated} arrays matched") - print(f"BW Improvement: {opt_bw - baseline_bw:.1f}%") -``` - ## Contributing We welcome contributions and feedback! Open an issue or create a PR. From a0714f15052b812a5b3022b58a69c2c233742277 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Mon, 2 Mar 2026 22:29:01 +0000 Subject: [PATCH 3/3] Add install/README.md for all options; include skills in Installation section of main README Co-authored-by: mawad-amd <112003944+mawad-amd@users.noreply.github.com> --- README.md | 38 ++++------------------ install/README.md | 82 +++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 88 insertions(+), 32 deletions(-) create mode 100644 install/README.md diff --git a/README.md b/README.md index 223edd4..954232a 100644 --- a/README.md +++ b/README.md @@ -12,28 +12,17 @@ IntelliKit is a collection of profiling and analysis tools for AMD ROCm that exp ## Installation -Install all tools from Git (one command): +**Install all tools and agent skills** (one command each): ```bash +# Tools curl -sSL https://raw.githubusercontent.com/AMDResearch/intellikit/main/install/tools/install.sh | bash -``` - -**Options:** -- **Custom pip command** (for multiple Python versions): - ```bash - curl -sSL https://raw.githubusercontent.com/AMDResearch/intellikit/main/install/tools/install.sh | bash -s -- --pip-cmd pip3.12 - ``` - -- **Install from a specific branch/tag:** - ```bash - curl -sSL https://raw.githubusercontent.com/AMDResearch/intellikit/main/install/tools/install.sh | bash -s -- --ref my-branch - ``` +# Agent skills (so AI agents can discover and use IntelliKit tools) +curl -sSL https://raw.githubusercontent.com/AMDResearch/intellikit/main/install/skills/install.sh | bash +``` -- **Dry-run (preview commands):** - ```bash - curl -sSL https://raw.githubusercontent.com/AMDResearch/intellikit/main/install/tools/install.sh | bash -s -- --dry-run - ``` +See [install/README.md](install/README.md) for all options (custom pip command, branch/tag, agent targets, dry-run, etc.). **Install individual tools from Git:** @@ -212,21 +201,6 @@ Add to your JSON MCP config: } ``` -## Agent Skills (AI agents) - -Install IntelliKit skills so AI agents can discover and use Metrix, Accordo, and Nexus: - -```bash -# Install into ./.agents/skills/ (current directory) -curl -sSL https://raw.githubusercontent.com/AMDResearch/intellikit/main/install/skills/install.sh | bash - -# Install for a specific agent (cursor, claude, codex) -curl -sSL https://raw.githubusercontent.com/AMDResearch/intellikit/main/install/skills/install.sh | bash -s -- --target cursor - -# Install globally (~/.cursor/skills/, etc.) -curl -sSL https://raw.githubusercontent.com/AMDResearch/intellikit/main/install/skills/install.sh | bash -s -- --target cursor --global -``` - ## Documentation Each tool has its own detailed documentation: diff --git a/install/README.md b/install/README.md new file mode 100644 index 0000000..87cef0a --- /dev/null +++ b/install/README.md @@ -0,0 +1,82 @@ +# IntelliKit Install Scripts + +## Tools (`install/tools/install.sh`) + +Installs all IntelliKit Python tools via pip. + +```bash +curl -sSL https://raw.githubusercontent.com/AMDResearch/intellikit/main/install/tools/install.sh | bash +``` + +**Options:** + +| Option | Description | +|--------|-------------| +| `--pip-cmd ` | Pip command to use (default: `pip`). Example: `--pip-cmd 'python3.12 -m pip'` | +| `--ref ` | Git branch, tag, or commit to install from (default: `main`) | +| `--repo-url ` | Git repo URL (default: `https://github.com/AMDResearch/intellikit.git`) | +| `--dry-run` | Print pip commands without running them | +| `--help` | Show help and exit | + +**Environment variables** (CLI options take precedence): `PIP_CMD`, `INTELLIKIT_REPO_URL`, `INTELLIKIT_REF` + +**Examples:** + +```bash +# Custom pip command (for a specific Python version) +curl -sSL https://raw.githubusercontent.com/AMDResearch/intellikit/main/install/tools/install.sh | bash -s -- --pip-cmd 'python3.12 -m pip' + +# Install from a specific branch or tag +curl -sSL https://raw.githubusercontent.com/AMDResearch/intellikit/main/install/tools/install.sh | bash -s -- --ref v1.2.0 + +# Dry-run (preview commands without executing) +curl -sSL https://raw.githubusercontent.com/AMDResearch/intellikit/main/install/tools/install.sh | bash -s -- --dry-run + +# From a clone +./install/tools/install.sh --pip-cmd pip3.12 --ref main --dry-run +``` + +## Agent Skills (`install/skills/install.sh`) + +Downloads each tool's `SKILL.md` into a skills directory so AI agents can discover and use IntelliKit tools. + +```bash +curl -sSL https://raw.githubusercontent.com/AMDResearch/intellikit/main/install/skills/install.sh | bash +``` + +**Options:** + +| Option | Description | +|--------|-------------| +| `--target ` | Where to install: `agents` (default), `codex`, `cursor`, `claude` | +| `--global` | Use user-level dir (e.g. `~/.cursor/skills`) instead of project-level | +| `--base-url ` | Base URL for raw files (default: main branch) | +| `--dry-run` | Show what would be downloaded without making changes | +| `--help` | Show help and exit | + +**Environment variables**: `INTELLIKIT_RAW_URL` + +**Resulting layout:** + +| Target | Project-level | Global | +|--------|--------------|--------| +| `agents` | `.agents/skills/` | `~/.agents/skills/` | +| `codex` | `.codex/skills/` | `~/.codex/skills/` | +| `cursor` | `.cursor/skills/` | `~/.cursor/skills/` | +| `claude` | `.claude/skills/` | `~/.claude/skills/` | + +**Examples:** + +```bash +# Install for Cursor (project-level) +curl -sSL https://raw.githubusercontent.com/AMDResearch/intellikit/main/install/skills/install.sh | bash -s -- --target cursor + +# Install for Claude globally +curl -sSL https://raw.githubusercontent.com/AMDResearch/intellikit/main/install/skills/install.sh | bash -s -- --target claude --global + +# Dry-run +curl -sSL https://raw.githubusercontent.com/AMDResearch/intellikit/main/install/skills/install.sh | bash -s -- --dry-run + +# From a clone +./install/skills/install.sh --target cursor --global +```