Skip to content

Commit 8f8cd3d

Browse files
napetrovndgrigorian
napetrov
and
ndgrigorian
authored
Add AGENTS.md and GitHub Copilot instructions (#276)
* Add AGENTS.md and Copilot instructions Introduce structured AI agent instructions following Intel's AGENTS spec v4: - AGENTS.md: project context (archetype, structure, source-of-truth) - .github/copilot-instructions.md: agent behavior policy Key guidance: - Preserve NumPy/SciPy FFT API compatibility - C templates: edit only .c.src files - Cython: release GIL for MKL calls - Local dev: conda env + pip install -e . - Pre-commit hooks required Token budget: 205 words (AGENTS.md) + copilot-instructions Reviewed by: architect + pragmatist agents * Expand AGENTS docs to multi-level structure * Add patching guidance to FFT AGENTS and Copilot instructions --------- Co-authored-by: ndgrigorian <46709016+ndgrigorian@users.noreply.github.com>
1 parent d10d5b9 commit 8f8cd3d

File tree

10 files changed

+188
-0
lines changed

10 files changed

+188
-0
lines changed

‎.github/AGENTS.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
# AGENTS.md — .github/
2+
3+
CI/CD workflows and repo automation.
4+
5+
## Workflows (source of truth)
6+
- `conda-package.yml` — Intel channel conda build/test pipeline
7+
- `conda-package-cf.yml` — conda-forge-oriented build/test pipeline
8+
- `build-with-clang.yml` — clang compatibility checks
9+
- `build_pip.yaml` — wheel build pipeline
10+
- `pre-commit.yml` — lint/format checks
11+
- `openssf-scorecard.yml` — security scanning
12+
13+
## Policy
14+
- Treat workflow YAML as canonical for platform/Python matrices.
15+
- Avoid doc claims about CI coverage unless present in workflow config.

‎.github/copilot-instructions.md‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
# GitHub Copilot Instructions — mkl_fft
2+
3+
## Identity
4+
You are an expert Python/C/Cython developer working on `mkl_fft` at Intel.
5+
Prioritize correctness, API compatibility, and minimal diffs.
6+
7+
## Source of truth
8+
This file is canonical for Copilot/agent behavior.
9+
`AGENTS.md` files provide project context.
10+
11+
## Precedence
12+
copilot-instructions > nearest AGENTS > root AGENTS
13+
Higher-precedence file overrides lower-precedence context.
14+
15+
## Mandatory flow
16+
1. Read root `AGENTS.md`. If absent, stop and report.
17+
2. For each edited file, locate and follow the nearest `AGENTS.md`.
18+
3. If no local file exists, inherit from root `AGENTS.md`.
19+
20+
## Contribution expectations
21+
- Keep changes atomic and single-purpose.
22+
- Preserve NumPy/SciPy FFT compatibility by default.
23+
- If touching interface wrappers/patch adapters, preserve reversible behavior and update interface tests.
24+
- For behavior changes: update/add tests in `mkl_fft/tests/` in the same change.
25+
- For bug fixes: include a regression test.
26+
- Run `pre-commit run --all-files` when `.pre-commit-config.yaml` is present.
27+
28+
## Authoring rules
29+
- Never invent versions, build flags, CI matrices, or channel policies.
30+
- Use source-of-truth files for mutable details.
31+
- **C templates:** edit only `mkl_fft/src/*.c.src`; do not manually edit generated `.c` files.
32+
- Prefer stable local entry points:
33+
- `python -m pip install -e .`
34+
- `pytest mkl_fft/tests`
35+
36+
## Source-of-truth files
37+
- Build/config: `pyproject.toml`, `setup.py`
38+
- Dependencies: `pyproject.toml`, `conda-recipe/meta.yaml`, `conda-recipe-cf/meta.yaml`
39+
- CI: `.github/workflows/*.{yml,yaml}`
40+
- API: `mkl_fft/__init__.py`, `mkl_fft/interfaces/*.py`, `mkl_fft/_pydfti.pyx` (interface wrappers are integration/patch entry points)
41+
- Tests: `mkl_fft/tests/`
42+
43+
## Intel-specific constraints
44+
- Build-time MKL: `mkl-devel`; runtime MKL integration via `mkl-service`
45+
- Performance claims require reproducible benchmark context
46+
- Do not introduce ISA-specific assumptions outside explicit build configuration

‎AGENTS.md‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
# AGENTS.md — mkl_fft
2+
3+
Entry point for agent context in this repo.
4+
5+
## What this project is
6+
`mkl_fft` is a NumPy/SciPy-compatible FFT interface backed by Intel® oneMKL.
7+
It provides accelerated FFT transforms while aiming to preserve upstream API behavior.
8+
9+
## Key components
10+
- **Package:** `mkl_fft/`
11+
- **Cython bindings:** `mkl_fft/_pydfti.pyx`
12+
- **Template-based C backend:** `mkl_fft/src/*.c.src`
13+
- **Interface adapters:** `mkl_fft/interfaces/`
14+
- **Tests:** `mkl_fft/tests/`
15+
- **Vendored helpers:** `_vendored/`
16+
- **Packaging:** `conda-recipe/`, `conda-recipe-cf/`
17+
18+
## Build/runtime basics
19+
- Build system: `pyproject.toml` + `setup.py`
20+
- Build deps: `cython`, `numpy`, `mkl-devel`
21+
- Runtime deps: `numpy`, `mkl-service`
22+
23+
## Development guardrails
24+
- Preserve NumPy/SciPy FFT API compatibility unless change is explicitly requested.
25+
- Edit template sources (`*.c.src`), not generated C artifacts.
26+
- Pair behavior changes with tests and keep diffs minimal.
27+
- If interface-level patching/wrapping behavior is changed, keep it explicit, reversible, and documented.
28+
- Avoid hardcoding mutable versions/matrices/channels in docs.
29+
30+
## Where truth lives
31+
- Build/config: `pyproject.toml`, `setup.py`
32+
- Dependencies: `pyproject.toml`, `conda-recipe*/meta.yaml`
33+
- CI/workflows: `.github/workflows/*.{yml,yaml}`
34+
- Public API: `mkl_fft/__init__.py`, `mkl_fft/interfaces/` (including wrapper/patch adapter modules)
35+
- Tests: `mkl_fft/tests/`
36+
37+
For behavior policy, see `.github/copilot-instructions.md`.
38+
39+
## Directory map
40+
Use nearest local `AGENTS.md` when present:
41+
- `.github/AGENTS.md` — CI workflows and automation policy
42+
- `mkl_fft/AGENTS.md` — package-level implementation context
43+
- `mkl_fft/interfaces/AGENTS.md` — NumPy/SciPy interface adapters
44+
- `mkl_fft/src/AGENTS.md` — C template backend rules
45+
- `mkl_fft/tests/AGENTS.md` — test scope/conventions
46+
- `conda-recipe/AGENTS.md` — Intel-channel conda packaging
47+
- `conda-recipe-cf/AGENTS.md` — conda-forge recipe context
48+
- `_vendored/AGENTS.md` — vendored tooling boundaries

‎_vendored/AGENTS.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
# AGENTS.md — _vendored/
2+
3+
Vendored utilities used by build/code-generation flows.
4+
5+
## Guardrails
6+
- Prefer updating upstream source when feasible; keep local vendored diffs minimal.
7+
- Do not refactor vendored code opportunistically in unrelated PRs.
8+
- If vendored logic affects generated sources, validate downstream build/test paths.

‎conda-recipe-cf/AGENTS.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
# AGENTS.md — conda-recipe-cf/
2+
3+
Conda-forge recipe context for `mkl_fft`.
4+
5+
## Scope
6+
- conda-forge specific recipe files under this directory.
7+
8+
## Guardrails
9+
- Keep conda-forge recipe semantics separate from Intel-channel recipe.
10+
- Align changes with `conda-package-cf.yml` workflow behavior.

‎conda-recipe/AGENTS.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
# AGENTS.md — conda-recipe/
2+
3+
Intel-channel conda packaging context.
4+
5+
## Scope
6+
- `meta.yaml` — package metadata and dependency pins
7+
- `build.sh` / `bld.bat` — platform build scripts
8+
9+
## Guardrails
10+
- Treat recipe files as canonical for packaging intent.
11+
- Keep recipe updates synchronized with CI workflow behavior.

‎mkl_fft/AGENTS.md‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
# AGENTS.md — mkl_fft/
2+
3+
Core package implementation for MKL-backed FFT operations.
4+
5+
## Key files
6+
- `__init__.py` — public package API surface
7+
- `_pydfti.pyx` — Cython bindings for DFTI interactions
8+
- `_mkl_fft.py` / `_fft_utils.py` — runtime FFT helper logic
9+
- `interfaces/` — NumPy/SciPy adapter modules
10+
- `src/` — C template backend (`*.c.src`)
11+
- `tests/` — package tests (see local AGENTS in tests)
12+
13+
## Guardrails
14+
- Preserve NumPy/SciPy-compatible behavior by default.
15+
- Keep adapter, binding, and backend changes coordinated with tests.
16+
- Treat interface wrappers as patch/integration points: behavior changes must stay explicit and reversible.
17+
- Prefer minimal isolated edits around changed API paths.

‎mkl_fft/interfaces/AGENTS.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
# AGENTS.md — mkl_fft/interfaces/
2+
3+
Adapter layer for `numpy.fft` / `scipy.fft` style interfaces.
4+
5+
## Scope
6+
- Interface modules mapping user-facing calls to MKL-backed implementation.
7+
8+
## Guardrails
9+
- Preserve function signatures and behavioral expectations unless explicitly requested.
10+
- Keep compatibility with upstream NumPy/SciPy semantics in mind.
11+
- Any user-visible behavior change here should include tests in `mkl_fft/tests/`.

‎mkl_fft/src/AGENTS.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
# AGENTS.md — mkl_fft/src/
2+
3+
C template backend for FFT internals.
4+
5+
## Scope
6+
- Template sources (`*.c.src`) used to generate C implementation artifacts.
7+
8+
## Guardrails
9+
- Edit template files (`*.c.src`) rather than generated `.c` files.
10+
- Keep template changes tightly scoped and validated by tests.
11+
- Coordinate with Cython/binding/API layers when changing function behavior.

‎mkl_fft/tests/AGENTS.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
# AGENTS.md — mkl_fft/tests/
2+
3+
Test suite for FFT API compatibility and regressions.
4+
5+
## Expectations
6+
- Behavior changes should include test updates in the same PR.
7+
- Bug fixes require regression tests.
8+
- Keep tests deterministic and avoid brittle performance-dependent assertions.
9+
10+
## Entry point
11+
- `pytest mkl_fft/tests`

0 commit comments

Comments
 (0)