Skip to content

Format Markdown with Prettier and enforce in CI #10

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

Open
nbarbier-265 wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Format Markdown with Prettier and enforce in CI #10

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
fceae5f
Add Prettier config and CI check for Markdown formatting
nbarbier-265 Aug 20, 2026
c793732
Format Markdown files with Prettier
nbarbier-265 Aug 20, 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
19 changes: 19 additions & 0 deletions .github/workflows/prettier.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
name: Prettier

on:
push:
branches: [main]
pull_request:

permissions:
contents: read

jobs:
prettier:
name: Check Markdown formatting
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
- uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0
- name: Run Prettier
run: bunx prettier@3.8.3 --check "**/*.md"
3 changes: 3 additions & 0 deletions .prettierrc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
{
"proseWrap": "preserve"
}
1 change: 1 addition & 0 deletions CODE_OF_CONDUCT.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
## Code of Conduct

This project has adopted the [Amazon Open Source Code of Conduct](https://aws.github.io/code-of-conduct).
For more information see the [Code of Conduct FAQ](https://aws.github.io/code-of-conduct-faq) or contact
opensource-codeofconduct@amazon.com with any additional questions or comments.
57 changes: 28 additions & 29 deletions GETTING_STARTED_GUIDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,13 +10,13 @@ Common use cases include fused attention kernels, custom normalization operation

## Prerequisites

| # | Requirement | Details | Needed for |
|---|-------------|---------|------------|
| 1 | Trainium/Inferentia instance | trn1, trn2, inf2 EC2 instance (AL2023 DLAMI recommended) | Compiling, profiling, optimization |
| 2 | Neuron SDK | `aws-neuronx-tools` (pre-installed on DLAMI) | All on-device skills |
| 3 | Python venv with Neuron packages | `neuronx-cc`, `torch-neuronx`, `neuron-explorer` | Compilation, profiling, analysis |
| 4 | Kiro or Claude Code | Installed on the Trainium instance | Running agents and skills |
| 5 | Anthropic API key | For Claude model inference | Agent reasoning |
| # | Requirement | Details | Needed for |
| --- | -------------------------------- | -------------------------------------------------------- | ---------------------------------- |
| 1 | Trainium/Inferentia instance | trn1, trn2, inf2 EC2 instance (AL2023 DLAMI recommended) | Compiling, profiling, optimization |
| 2 | Neuron SDK | `aws-neuronx-tools` (pre-installed on DLAMI) | All on-device skills |
| 3 | Python venv with Neuron packages | `neuronx-cc`, `torch-neuronx`, `neuron-explorer` | Compilation, profiling, analysis |
| 4 | Kiro or Claude Code | Installed on the Trainium instance | Running agents and skills |
| 5 | Anthropic API key | For Claude model inference | Agent reasoning |

> **Important:** The agent runs on the same machine as the hardware. There is no laptop-to-remote-box file transfer — everything is co-located. Writing and documentation skills work anywhere (no hardware needed), but profiling and debugging require on-instance execution.

Expand Down Expand Up @@ -44,8 +44,7 @@ source ~/opt/aws_neuronx_venv_pytorch_2_9/bin/activate

## Step 3: Install Neuron Agentic Development


### Clone from GitHub (for customization or contribution):**
### Clone from GitHub (for customization or contribution):\*\*

```bash
git clone https://github.com/aws-neuron/neuron-agentic-development.git
Expand Down Expand Up @@ -79,24 +78,24 @@ The `neuron-nki-agent` is the unified entry point. It automatically selects the

### Example Prompts

| What you want to do | What to say | Hardware needed? |
|---------------------|-------------|------------------|
| Write a new kernel | "Write a fused softmax kernel for bf16 inputs" | No |
| Debug a compilation error | "Fix this kernel" (with error output) | Yes |
| Profile a kernel | "Profile my kernel and show me the metrics" | Yes |
| Analyze a profile | "What's the bottleneck in this kernel?" | Yes (neuron-explorer) |
| What you want to do | What to say | Hardware needed? |
| ------------------------- | ---------------------------------------------- | --------------------- |
| Write a new kernel | "Write a fused softmax kernel for bf16 inputs" | No |
| Debug a compilation error | "Fix this kernel" (with error output) | Yes |
| Profile a kernel | "Profile my kernel and show me the metrics" | Yes |
| Analyze a profile | "What's the bottleneck in this kernel?" | Yes (neuron-explorer) |

## Skills

The package provides five specialized skills that follow the natural kernel development pipeline: **write → debug → profile → analyze**.

| # | Skill | Category | Use when |
|---|-------|----------|----------|
| 1 | `neuron-nki-writing` | Authoring | Writing new kernels or modifying existing ones |
| 2 | `neuron-nki-debugging` | Debugging | Resolving compiler errors or numerical mismatches |
| 3 | `neuron-nki-docs` | Documentation | Looking up API signatures, tutorials, error codes |
| 4 | `neuron-nki-profiling` | Profiling | Capturing execution traces on hardware |
| 5 | `neuron-nki-profile-querying` | Analysis | SQL-based performance bounds and bottleneck analysis |
| # | Skill | Category | Use when |
| --- | ----------------------------- | ------------- | ---------------------------------------------------- |
| 1 | `neuron-nki-writing` | Authoring | Writing new kernels or modifying existing ones |
| 2 | `neuron-nki-debugging` | Debugging | Resolving compiler errors or numerical mismatches |
| 3 | `neuron-nki-docs` | Documentation | Looking up API signatures, tutorials, error codes |
| 4 | `neuron-nki-profiling` | Profiling | Capturing execution traces on hardware |
| 5 | `neuron-nki-profile-querying` | Analysis | SQL-based performance bounds and bottleneck analysis |

### Kernel Authoring (`neuron-nki-writing`)

Expand All @@ -120,12 +119,12 @@ Used across all stages of development. Provides API signatures and tutorials dur

## Agents

| # | Agent | Focus | What it does |
|---|-------|-------|--------------|
| 1 | `neuron-nki-agent` | Full lifecycle | Top-level entry point. Auto-selects the right workflow based on your request and orchestrates the appropriate skills. |
| 2 | `neuron-nki-writer-agent` | Authoring | Translates PyTorch, NumPy, or natural language descriptions into NKI code. Handles modifications to existing kernels. |
| 3 | `neuron-nki-debugger-agent` | Debugging | Autonomously analyzes compiler errors, searches documentation for fixes, and applies corrections. Tracks iterations (up to 10) and progressively simplifies when stuck. |
| 4 | `neuron-nki-profile-analysis-agent` | Profiling + Analysis | Captures execution profiles on hardware, then runs SQL queries against profile data to compute performance bounds, identify bottleneck engines, and localize inefficiencies. |
| # | Agent | Focus | What it does |
| --- | ----------------------------------- | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 1 | `neuron-nki-agent` | Full lifecycle | Top-level entry point. Auto-selects the right workflow based on your request and orchestrates the appropriate skills. |
| 2 | `neuron-nki-writer-agent` | Authoring | Translates PyTorch, NumPy, or natural language descriptions into NKI code. Handles modifications to existing kernels. |
| 3 | `neuron-nki-debugger-agent` | Debugging | Autonomously analyzes compiler errors, searches documentation for fixes, and applies corrections. Tracks iterations (up to 10) and progressively simplifies when stuck. |
| 4 | `neuron-nki-profile-analysis-agent` | Profiling + Analysis | Captures execution profiles on hardware, then runs SQL queries against profile data to compute performance bounds, identify bottleneck engines, and localize inefficiencies. |

## Architecture

Expand Down Expand Up @@ -161,7 +160,7 @@ Used across all stages of development. Provides API signatures and tutorials dur

Here's a typical end-to-end workflow:

1. **Write** — Ask the agent: *"Write an NKI kernel that computes scaled softmax: softmax(x * scale) along the last dimension, for input shape [batch, seq_len, hidden_dim] in bfloat16."* The agent produces a complete kernel with proper tiling, hardware-accelerated exp, float32 accumulation, and bfloat16 output cast.
1. **Write** — Ask the agent: _"Write an NKI kernel that computes scaled softmax: softmax(x _ scale) along the last dimension, for input shape [batch, seq_len, hidden_dim] in bfloat16."\* The agent produces a complete kernel with proper tiling, hardware-accelerated exp, float32 accumulation, and bfloat16 output cast.

2. **Debug** — Ask the agent to run the kernel and verify numerical parity against a PyTorch reference. If compilation errors occur, the agent diagnoses and fixes them autonomously.

Expand Down
36 changes: 18 additions & 18 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
# Neuron Agentic Development

This repository contains AI agents and skills for developing on [AWS Neuron](https://awsdocs-neuron.readthedocs-hosted.com/) (Trainium/Inferentia) hardware, including NKI kernel development, profiling and debugging. For an overview of Neuron Agentic Development and the tools it offers for agent-enabled workflows with Neuron, see [the overview of Neuron Agentic Development in the the public Neuron docs](https://awsdocs-neuron.readthedocs-hosted.com/en/latest/about-neuron/agentic-development-overview.html).

## Installation
Expand Down Expand Up @@ -27,30 +28,29 @@ deploy-neuron-agentic-development-to-claude

## Agents

| Agent | Description |
|-------|-------------|
| [neuron-nki-agent](agents/neuron-nki-agent.md) | Unified NKI kernel development agent. Full lifecycle: writing kernels from PyTorch/NumPy/natural language, debugging compilation errors, profiling performance, optimizing bottlenecks, migrating between API versions, analyzing Perfetto traces, and NKI documentation lookup. |
| [neuron-nki-writer-agent](agents/neuron-nki-writer-agent.md) | NKI kernel authoring and modification. Translates from PyTorch/NumPy/natural language, adds shape/dtype support, refactors tiling strategies, and implements new features following Beta 3 API patterns. |
| [neuron-nki-debugger-agent](agents/neuron-nki-debugger-agent.md) | Autonomous NKI kernel compilation error debugging. Analyzes compiler errors, searches documentation and code examples for fixes, applies corrections following simplicity over performance, and validates fixes. |
| [neuron-nki-profile-analysis-agent](agents/neuron-nki-profile-analysis-agent.md) | Profile and analyze NKI kernels on Neuron hardware. Captures execution traces, computes performance bounds, identifies bottleneck engines, and runs investigations to localize inefficiencies to NKI source lines. |
| [neuron-framework-autoport-agent](agents/neuron-framework-autoport-agent.md) | A model porting agent to port GPU-compatible models to functionally accurate implementation on Neuron. Executes the full porting workflow including architecture analysis, implementation, compilation, inference testing, and validation. |
| Agent | Description |
| -------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [neuron-nki-agent](agents/neuron-nki-agent.md) | Unified NKI kernel development agent. Full lifecycle: writing kernels from PyTorch/NumPy/natural language, debugging compilation errors, profiling performance, optimizing bottlenecks, migrating between API versions, analyzing Perfetto traces, and NKI documentation lookup. |
| [neuron-nki-writer-agent](agents/neuron-nki-writer-agent.md) | NKI kernel authoring and modification. Translates from PyTorch/NumPy/natural language, adds shape/dtype support, refactors tiling strategies, and implements new features following Beta 3 API patterns. |
| [neuron-nki-debugger-agent](agents/neuron-nki-debugger-agent.md) | Autonomous NKI kernel compilation error debugging. Analyzes compiler errors, searches documentation and code examples for fixes, applies corrections following simplicity over performance, and validates fixes. |
| [neuron-nki-profile-analysis-agent](agents/neuron-nki-profile-analysis-agent.md) | Profile and analyze NKI kernels on Neuron hardware. Captures execution traces, computes performance bounds, identifies bottleneck engines, and runs investigations to localize inefficiencies to NKI source lines. |
| [neuron-framework-autoport-agent](agents/neuron-framework-autoport-agent.md) | A model porting agent to port GPU-compatible models to functionally accurate implementation on Neuron. Executes the full porting workflow including architecture analysis, implementation, compilation, inference testing, and validation. |

## Skills

| Skill | Description |
|-------|-------------|
| [neuron-nki-writing](skills/neuron-nki-writing/SKILL.md) | Write and modify NKI kernels. Covers new kernel creation from PyTorch/NumPy/natural language, editing existing kernels, adding shape/dtype support, refactoring tiling strategies, and implementing new features. |
| [neuron-nki-debugging](skills/neuron-nki-debugging/SKILL.md) | Debug NKI compilation errors on Neuron hardware. |
| [neuron-nki-docs](skills/neuron-nki-docs/SKILL.md) | Research NKI documentation for API lookups, tutorials, error codes, and architecture details. |
| [neuron-nki-profiling](skills/neuron-nki-profiling/SKILL.md) | Profile NKI kernels to analyze performance on Neuron hardware. |
| [neuron-nki-profile-querying](skills/neuron-nki-profile-querying/SKILL.md) | Query and analyze NKI kernel profile data from neuron-explorer parquet files via SQL and Python. |
| [neuron-framework-autoport](skills/neuron-framework-autoport/SKILL.md) | Port a GPU compatible model to NeuronX Distributed Inference for AWS Trainium/Inferentia. Handles the full workflow including architecture analysis, NeuronX implementation, compilation, inference testing, and accuracy validation. |
| [neuron-framework-equivalence](skills/neuron-framework-equivalence/SKILL.md) | Verifies functional equivalence between two implementations of the same model using a hierarchical algorithm. |
| Skill | Description |
| ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [neuron-nki-writing](skills/neuron-nki-writing/SKILL.md) | Write and modify NKI kernels. Covers new kernel creation from PyTorch/NumPy/natural language, editing existing kernels, adding shape/dtype support, refactoring tiling strategies, and implementing new features. |
| [neuron-nki-debugging](skills/neuron-nki-debugging/SKILL.md) | Debug NKI compilation errors on Neuron hardware. |
| [neuron-nki-docs](skills/neuron-nki-docs/SKILL.md) | Research NKI documentation for API lookups, tutorials, error codes, and architecture details. |
| [neuron-nki-profiling](skills/neuron-nki-profiling/SKILL.md) | Profile NKI kernels to analyze performance on Neuron hardware. |
| [neuron-nki-profile-querying](skills/neuron-nki-profile-querying/SKILL.md) | Query and analyze NKI kernel profile data from neuron-explorer parquet files via SQL and Python. |
| [neuron-framework-autoport](skills/neuron-framework-autoport/SKILL.md) | Port a GPU compatible model to NeuronX Distributed Inference for AWS Trainium/Inferentia. Handles the full workflow including architecture analysis, NeuronX implementation, compilation, inference testing, and accuracy validation. |
| [neuron-framework-equivalence](skills/neuron-framework-equivalence/SKILL.md) | Verifies functional equivalence between two implementations of the same model using a hierarchical algorithm. |

## Contributing

We are evaluating the external contribution process. All capabilities undergo internal verification to ensure technical accuracy, security, and architectural alignment. In the interim, we welcome feedback and feature requests via [Issues](https://github.com/aws-neuron/neuron-agentic-development/issues)

We are evaluating the external contribution process. All capabilities undergo internal verification to ensure technical accuracy, security, and architectural alignment. In the interim, we welcome feedback and feature requests via [Issues](https://github.com/aws-neuron/neuron-agentic-development/issues)

## License

Expand Down
Loading