Skip to content

Refocus main README on user experience and getting started #64

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
Copilot wants to merge 3 commits into
base: main
Choose a base branch
from
Draft

Refocus main README on user experience and getting started #64

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
872d37d
Initial plan
Copilot Mar 2, 2026
8d550e9
Reorganize README to focus on user experience and primary usage modes
Copilot Mar 2, 2026
a0714f1
Add install/README.md for all options; include skills in Installation…
Copilot Mar 2, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
190 changes: 39 additions & 151 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,14 +8,48 @@

**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 and agent skills** (one command each):

```bash
# Tools
curl -sSL https://raw.githubusercontent.com/AMDResearch/intellikit/main/install/tools/install.sh | bash

# 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
```

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:**

```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
```

Traditional CPU and GPU profiling and analysis tools expose raw hardware counters and assembly. IntelliKit tools are designed to:
## Requirements

- **Decode complexity**: Turn hardware metrics into human-readable insights
- **Enable LLM integration**: Provide clean APIs suitable for LLM-driven workflows (MCP-ready)
- **Python**: >= 3.10
- **ROCm**: >= 6.0 (7.0+ for linex)
- **Hardware**: MI300+ GPUs

## Tools

Expand Down Expand Up @@ -167,118 +201,6 @@ Add to your JSON MCP config:
}
```

## Installation

Install each tool from its subdirectory. No top-level metapackage.

**Install all tools from Git (one command):**

```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)
curl -sSL https://raw.githubusercontent.com/AMDResearch/intellikit/main/install/skills/install.sh | bash
```

**Different agent targets** (cursor, claude, codex, agents):

```bash
# Cursor
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.)
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:
Expand All @@ -290,40 +212,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.
Expand Down
82 changes: 82 additions & 0 deletions install/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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 <cmd>` | Pip command to use (default: `pip`). Example: `--pip-cmd 'python3.12 -m pip'` |
| `--ref <ref>` | Git branch, tag, or commit to install from (default: `main`) |
| `--repo-url <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 <name>` | Where to install: `agents` (default), `codex`, `cursor`, `claude` |
| `--global` | Use user-level dir (e.g. `~/.cursor/skills`) instead of project-level |
| `--base-url <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
```