From fd88e5f5a3c9a09c4d82715f0222b755a17fa455 Mon Sep 17 00:00:00 2001 From: Nikolay Petrov Date: Thu, 19 Feb 2026 06:15:56 +0000 Subject: [PATCH 1/2] 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 --- .github/copilot-instructions.md | 50 +++++++++++++++++++++++++++++++++ AGENTS.md | 35 +++++++++++++++++++++++ 2 files changed, 85 insertions(+) create mode 100644 .github/copilot-instructions.md create mode 100644 AGENTS.md diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 0000000..f57c444 --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,50 @@ +# GitHub Copilot Instructions — mkl_fft + +## Identity +You are an expert Python/C developer working on `mkl_fft` at Intel. +Apply Intel engineering standards: correctness first, minimal diffs, no assumptions. + +## Source of truth +This file is canonical for Copilot/agent behavior. +`AGENTS.md` provides project context. + +## Precedence +copilot-instructions > nearest AGENTS > root AGENTS +Higher-precedence file overrides; lower must not restate overridden guidance. + +## Mandatory flow +1. Read root `AGENTS.md`. If absent, stop and report. +2. For edited files, use root AGENTS (no local AGENTS files exist here). +3. If future local `AGENTS.md` files appear, find nearest per file. + +## Contribution expectations +- Keep diffs minimal; prefer atomic single-purpose commits. +- Preserve NumPy/SciPy FFT API compatibility by default. +- For API changes: update tests + docstrings when user-visible. +- For bug fixes: add regression tests in `mkl_fft/tests/`. +- Do not generate code without a corresponding test update in the same step. +- Run `pre-commit run --all-files` before proposing code changes. + +## Authoring rules +- Use source-of-truth files for all mutable details. +- Never invent/hardcode versions, flags, or matrix values. +- Use stable entry points: `pip install -e .` (dev), `pytest mkl_fft/tests` (test). +- Never include sensitive data in any file. +- **C templates:** Edit only `src/*.c.src`; do not manually edit generated `.c` files. +- **Cython/MKL calls:** Release GIL with `with nogil:` blocks for performance-critical MKL functions. +- **Memory:** Ensure proper alignment for FFT buffers; respect MKL object lifecycle. +- **Compiler flags:** Do not hardcode ISA flags (AVX-512, etc.) outside `setup.py`. + +## Source-of-truth files +- Build/config: `pyproject.toml`, `setup.py` +- Dependencies: `pyproject.toml` (dependencies, optional-dependencies), `conda-recipe/meta.yaml`, `conda-recipe-cf/meta.yaml` +- CI: `.github/workflows/*.{yml,yaml}` +- Style/lint: `.pre-commit-config.yaml`, `.flake8`, `pyproject.toml` (tool.black, tool.isort, tool.cython-lint) +- API contracts: `mkl_fft/__init__.py`, `mkl_fft/interfaces/*.py`, NumPy FFT docs (https://numpy.org/doc/stable/reference/routines.fft.html), SciPy FFT docs (https://docs.scipy.org/doc/scipy/reference/fft.html) +- Test data: `mkl_fft/tests/` + +## Intel-specific constraints +- Package channels: Intel PyPI (https://software.repos.intel.com/python/pypi), Intel conda (https://software.repos.intel.com/python/conda), conda-forge +- MKL backend: requires `mkl-devel` at build time, `mkl-service` at runtime +- Performance: for claims, reference https://github.com/intelpython/fft_benchmark +- Do not hardcode MKL version assumptions; respect `pyproject.toml` `requires-python` range diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..15b7307 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,35 @@ +# AGENTS.md — mkl_fft + +## What this project is +NumPy-based Python interface to Intel® oneMKL FFT functions. Provides MKL-accelerated FFT for real/complex transforms. Part of Intel® Distribution for Python. Archetype: **python** (Cython + C extensions). + +Layers: Python interfaces, Cython bindings (`_pydfti.pyx`), C backend (`src/*.c.src`). + +## How it's structured +- `mkl_fft/interfaces/` — drop-in replacements for `numpy.fft`, `scipy.fft` +- `mkl_fft/src/` — C templates (`.c.src`) +- `mkl_fft/tests/` — pytest suite +- `conda-recipe/`, `conda-recipe-cf/` — Intel/conda-forge builds + +Build: `pyproject.toml` + `setup.py`. Runtime: `mkl-service`, `numpy>=1.26.4`. + +## How to work in it +- Keep changes atomic and single-purpose. +- Preserve NumPy/SciPy FFT API; document divergence in commit message. +- Pair changes with tests and docstrings. +- Never assume MKL or NumPy versions; use source-of-truth files. +- **C templates:** Edit only `*.c.src` files; generated `.c` is ephemeral (via `_vendored/conv_template.py`). +- **Local dev:** `conda create -n dev python numpy cython mkl-devel pytest && pip install -e .` + +For agent policy: `.github/copilot-instructions.md` + +## Where truth lives +- Build/config: `pyproject.toml`, `setup.py` +- Dependencies: `pyproject.toml` (`dependencies`, `optional-dependencies`), `conda-recipe/meta.yaml`, `conda-recipe-cf/meta.yaml` +- CI: `.github/workflows/` +- Style/lint: `.pre-commit-config.yaml`, `.flake8`, `pyproject.toml` (black/isort/cython-lint) +- API/contracts: `mkl_fft/__init__.py`, `mkl_fft/interfaces/`, NumPy/SciPy FFT docs +- Stable entry points: `python -m pip install .`, `pytest mkl_fft/tests` + +## Directory map +No local AGENTS files — project is small enough for root-level guidance only. From d9a817aeb83cf32e87449e50ed5d60a6ab1f7c77 Mon Sep 17 00:00:00 2001 From: Nikolay Petrov Date: Tue, 3 Mar 2026 08:47:42 -0800 Subject: [PATCH 2/2] Expand AGENTS docs to multi-level structure --- .github/AGENTS.md | 15 ++++++++ .github/copilot-instructions.md | 51 ++++++++++++------------- AGENTS.md | 66 +++++++++++++++++++-------------- _vendored/AGENTS.md | 8 ++++ conda-recipe-cf/AGENTS.md | 10 +++++ conda-recipe/AGENTS.md | 11 ++++++ mkl_fft/AGENTS.md | 16 ++++++++ mkl_fft/interfaces/AGENTS.md | 11 ++++++ mkl_fft/src/AGENTS.md | 11 ++++++ mkl_fft/tests/AGENTS.md | 11 ++++++ 10 files changed, 155 insertions(+), 55 deletions(-) create mode 100644 .github/AGENTS.md create mode 100644 _vendored/AGENTS.md create mode 100644 conda-recipe-cf/AGENTS.md create mode 100644 conda-recipe/AGENTS.md create mode 100644 mkl_fft/AGENTS.md create mode 100644 mkl_fft/interfaces/AGENTS.md create mode 100644 mkl_fft/src/AGENTS.md create mode 100644 mkl_fft/tests/AGENTS.md diff --git a/.github/AGENTS.md b/.github/AGENTS.md new file mode 100644 index 0000000..9272488 --- /dev/null +++ b/.github/AGENTS.md @@ -0,0 +1,15 @@ +# AGENTS.md — .github/ + +CI/CD workflows and repo automation. + +## Workflows (source of truth) +- `conda-package.yml` — Intel channel conda build/test pipeline +- `conda-package-cf.yml` — conda-forge-oriented build/test pipeline +- `build-with-clang.yml` — clang compatibility checks +- `build_pip.yaml` — wheel build pipeline +- `pre-commit.yml` — lint/format checks +- `openssf-scorecard.yml` — security scanning + +## Policy +- Treat workflow YAML as canonical for platform/Python matrices. +- Avoid doc claims about CI coverage unless present in workflow config. diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index f57c444..b86f50f 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -1,50 +1,45 @@ # GitHub Copilot Instructions — mkl_fft ## Identity -You are an expert Python/C developer working on `mkl_fft` at Intel. -Apply Intel engineering standards: correctness first, minimal diffs, no assumptions. +You are an expert Python/C/Cython developer working on `mkl_fft` at Intel. +Prioritize correctness, API compatibility, and minimal diffs. ## Source of truth This file is canonical for Copilot/agent behavior. -`AGENTS.md` provides project context. +`AGENTS.md` files provide project context. ## Precedence copilot-instructions > nearest AGENTS > root AGENTS -Higher-precedence file overrides; lower must not restate overridden guidance. +Higher-precedence file overrides lower-precedence context. ## Mandatory flow 1. Read root `AGENTS.md`. If absent, stop and report. -2. For edited files, use root AGENTS (no local AGENTS files exist here). -3. If future local `AGENTS.md` files appear, find nearest per file. +2. For each edited file, locate and follow the nearest `AGENTS.md`. +3. If no local file exists, inherit from root `AGENTS.md`. ## Contribution expectations -- Keep diffs minimal; prefer atomic single-purpose commits. -- Preserve NumPy/SciPy FFT API compatibility by default. -- For API changes: update tests + docstrings when user-visible. -- For bug fixes: add regression tests in `mkl_fft/tests/`. -- Do not generate code without a corresponding test update in the same step. -- Run `pre-commit run --all-files` before proposing code changes. +- Keep changes atomic and single-purpose. +- Preserve NumPy/SciPy FFT compatibility by default. +- For behavior changes: update/add tests in `mkl_fft/tests/` in the same change. +- For bug fixes: include a regression test. +- Run `pre-commit run --all-files` when `.pre-commit-config.yaml` is present. ## Authoring rules -- Use source-of-truth files for all mutable details. -- Never invent/hardcode versions, flags, or matrix values. -- Use stable entry points: `pip install -e .` (dev), `pytest mkl_fft/tests` (test). -- Never include sensitive data in any file. -- **C templates:** Edit only `src/*.c.src`; do not manually edit generated `.c` files. -- **Cython/MKL calls:** Release GIL with `with nogil:` blocks for performance-critical MKL functions. -- **Memory:** Ensure proper alignment for FFT buffers; respect MKL object lifecycle. -- **Compiler flags:** Do not hardcode ISA flags (AVX-512, etc.) outside `setup.py`. +- Never invent versions, build flags, CI matrices, or channel policies. +- Use source-of-truth files for mutable details. +- **C templates:** edit only `mkl_fft/src/*.c.src`; do not manually edit generated `.c` files. +- Prefer stable local entry points: + - `python -m pip install -e .` + - `pytest mkl_fft/tests` ## Source-of-truth files - Build/config: `pyproject.toml`, `setup.py` -- Dependencies: `pyproject.toml` (dependencies, optional-dependencies), `conda-recipe/meta.yaml`, `conda-recipe-cf/meta.yaml` +- Dependencies: `pyproject.toml`, `conda-recipe/meta.yaml`, `conda-recipe-cf/meta.yaml` - CI: `.github/workflows/*.{yml,yaml}` -- Style/lint: `.pre-commit-config.yaml`, `.flake8`, `pyproject.toml` (tool.black, tool.isort, tool.cython-lint) -- API contracts: `mkl_fft/__init__.py`, `mkl_fft/interfaces/*.py`, NumPy FFT docs (https://numpy.org/doc/stable/reference/routines.fft.html), SciPy FFT docs (https://docs.scipy.org/doc/scipy/reference/fft.html) -- Test data: `mkl_fft/tests/` +- API: `mkl_fft/__init__.py`, `mkl_fft/interfaces/*.py`, `mkl_fft/_pydfti.pyx` +- Tests: `mkl_fft/tests/` ## Intel-specific constraints -- Package channels: Intel PyPI (https://software.repos.intel.com/python/pypi), Intel conda (https://software.repos.intel.com/python/conda), conda-forge -- MKL backend: requires `mkl-devel` at build time, `mkl-service` at runtime -- Performance: for claims, reference https://github.com/intelpython/fft_benchmark -- Do not hardcode MKL version assumptions; respect `pyproject.toml` `requires-python` range +- Build-time MKL: `mkl-devel`; runtime MKL integration via `mkl-service` +- Performance claims require reproducible benchmark context +- Do not introduce ISA-specific assumptions outside explicit build configuration diff --git a/AGENTS.md b/AGENTS.md index 15b7307..3b57ebd 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,35 +1,47 @@ # AGENTS.md — mkl_fft -## What this project is -NumPy-based Python interface to Intel® oneMKL FFT functions. Provides MKL-accelerated FFT for real/complex transforms. Part of Intel® Distribution for Python. Archetype: **python** (Cython + C extensions). - -Layers: Python interfaces, Cython bindings (`_pydfti.pyx`), C backend (`src/*.c.src`). - -## How it's structured -- `mkl_fft/interfaces/` — drop-in replacements for `numpy.fft`, `scipy.fft` -- `mkl_fft/src/` — C templates (`.c.src`) -- `mkl_fft/tests/` — pytest suite -- `conda-recipe/`, `conda-recipe-cf/` — Intel/conda-forge builds - -Build: `pyproject.toml` + `setup.py`. Runtime: `mkl-service`, `numpy>=1.26.4`. +Entry point for agent context in this repo. -## How to work in it -- Keep changes atomic and single-purpose. -- Preserve NumPy/SciPy FFT API; document divergence in commit message. -- Pair changes with tests and docstrings. -- Never assume MKL or NumPy versions; use source-of-truth files. -- **C templates:** Edit only `*.c.src` files; generated `.c` is ephemeral (via `_vendored/conv_template.py`). -- **Local dev:** `conda create -n dev python numpy cython mkl-devel pytest && pip install -e .` - -For agent policy: `.github/copilot-instructions.md` +## What this project is +`mkl_fft` is a NumPy/SciPy-compatible FFT interface backed by Intel® oneMKL. +It provides accelerated FFT transforms while aiming to preserve upstream API behavior. + +## Key components +- **Package:** `mkl_fft/` +- **Cython bindings:** `mkl_fft/_pydfti.pyx` +- **Template-based C backend:** `mkl_fft/src/*.c.src` +- **Interface adapters:** `mkl_fft/interfaces/` +- **Tests:** `mkl_fft/tests/` +- **Vendored helpers:** `_vendored/` +- **Packaging:** `conda-recipe/`, `conda-recipe-cf/` + +## Build/runtime basics +- Build system: `pyproject.toml` + `setup.py` +- Build deps: `cython`, `numpy`, `mkl-devel` +- Runtime deps: `numpy`, `mkl-service` + +## Development guardrails +- Preserve NumPy/SciPy FFT API compatibility unless change is explicitly requested. +- Edit template sources (`*.c.src`), not generated C artifacts. +- Pair behavior changes with tests and keep diffs minimal. +- Avoid hardcoding mutable versions/matrices/channels in docs. ## Where truth lives - Build/config: `pyproject.toml`, `setup.py` -- Dependencies: `pyproject.toml` (`dependencies`, `optional-dependencies`), `conda-recipe/meta.yaml`, `conda-recipe-cf/meta.yaml` -- CI: `.github/workflows/` -- Style/lint: `.pre-commit-config.yaml`, `.flake8`, `pyproject.toml` (black/isort/cython-lint) -- API/contracts: `mkl_fft/__init__.py`, `mkl_fft/interfaces/`, NumPy/SciPy FFT docs -- Stable entry points: `python -m pip install .`, `pytest mkl_fft/tests` +- Dependencies: `pyproject.toml`, `conda-recipe*/meta.yaml` +- CI/workflows: `.github/workflows/*.{yml,yaml}` +- Public API: `mkl_fft/__init__.py`, `mkl_fft/interfaces/` +- Tests: `mkl_fft/tests/` + +For behavior policy, see `.github/copilot-instructions.md`. ## Directory map -No local AGENTS files — project is small enough for root-level guidance only. +Use nearest local `AGENTS.md` when present: +- `.github/AGENTS.md` — CI workflows and automation policy +- `mkl_fft/AGENTS.md` — package-level implementation context +- `mkl_fft/interfaces/AGENTS.md` — NumPy/SciPy interface adapters +- `mkl_fft/src/AGENTS.md` — C template backend rules +- `mkl_fft/tests/AGENTS.md` — test scope/conventions +- `conda-recipe/AGENTS.md` — Intel-channel conda packaging +- `conda-recipe-cf/AGENTS.md` — conda-forge recipe context +- `_vendored/AGENTS.md` — vendored tooling boundaries diff --git a/_vendored/AGENTS.md b/_vendored/AGENTS.md new file mode 100644 index 0000000..c3c0dfc --- /dev/null +++ b/_vendored/AGENTS.md @@ -0,0 +1,8 @@ +# AGENTS.md — _vendored/ + +Vendored utilities used by build/code-generation flows. + +## Guardrails +- Prefer updating upstream source when feasible; keep local vendored diffs minimal. +- Do not refactor vendored code opportunistically in unrelated PRs. +- If vendored logic affects generated sources, validate downstream build/test paths. diff --git a/conda-recipe-cf/AGENTS.md b/conda-recipe-cf/AGENTS.md new file mode 100644 index 0000000..9d8655e --- /dev/null +++ b/conda-recipe-cf/AGENTS.md @@ -0,0 +1,10 @@ +# AGENTS.md — conda-recipe-cf/ + +Conda-forge recipe context for `mkl_fft`. + +## Scope +- conda-forge specific recipe files under this directory. + +## Guardrails +- Keep conda-forge recipe semantics separate from Intel-channel recipe. +- Align changes with `conda-package-cf.yml` workflow behavior. diff --git a/conda-recipe/AGENTS.md b/conda-recipe/AGENTS.md new file mode 100644 index 0000000..7c7cef4 --- /dev/null +++ b/conda-recipe/AGENTS.md @@ -0,0 +1,11 @@ +# AGENTS.md — conda-recipe/ + +Intel-channel conda packaging context. + +## Scope +- `meta.yaml` — package metadata and dependency pins +- `build.sh` / `bld.bat` — platform build scripts + +## Guardrails +- Treat recipe files as canonical for packaging intent. +- Keep recipe updates synchronized with CI workflow behavior. diff --git a/mkl_fft/AGENTS.md b/mkl_fft/AGENTS.md new file mode 100644 index 0000000..9f21e28 --- /dev/null +++ b/mkl_fft/AGENTS.md @@ -0,0 +1,16 @@ +# AGENTS.md — mkl_fft/ + +Core package implementation for MKL-backed FFT operations. + +## Key files +- `__init__.py` — public package API surface +- `_pydfti.pyx` — Cython bindings for DFTI interactions +- `_mkl_fft.py` / `_fft_utils.py` — runtime FFT helper logic +- `interfaces/` — NumPy/SciPy adapter modules +- `src/` — C template backend (`*.c.src`) +- `tests/` — package tests (see local AGENTS in tests) + +## Guardrails +- Preserve NumPy/SciPy-compatible behavior by default. +- Keep adapter, binding, and backend changes coordinated with tests. +- Prefer minimal isolated edits around changed API paths. diff --git a/mkl_fft/interfaces/AGENTS.md b/mkl_fft/interfaces/AGENTS.md new file mode 100644 index 0000000..bba8727 --- /dev/null +++ b/mkl_fft/interfaces/AGENTS.md @@ -0,0 +1,11 @@ +# AGENTS.md — mkl_fft/interfaces/ + +Adapter layer for `numpy.fft` / `scipy.fft` style interfaces. + +## Scope +- Interface modules mapping user-facing calls to MKL-backed implementation. + +## Guardrails +- Preserve function signatures and behavioral expectations unless explicitly requested. +- Keep compatibility with upstream NumPy/SciPy semantics in mind. +- Any user-visible behavior change here should include tests in `mkl_fft/tests/`. diff --git a/mkl_fft/src/AGENTS.md b/mkl_fft/src/AGENTS.md new file mode 100644 index 0000000..9461c94 --- /dev/null +++ b/mkl_fft/src/AGENTS.md @@ -0,0 +1,11 @@ +# AGENTS.md — mkl_fft/src/ + +C template backend for FFT internals. + +## Scope +- Template sources (`*.c.src`) used to generate C implementation artifacts. + +## Guardrails +- Edit template files (`*.c.src`) rather than generated `.c` files. +- Keep template changes tightly scoped and validated by tests. +- Coordinate with Cython/binding/API layers when changing function behavior. diff --git a/mkl_fft/tests/AGENTS.md b/mkl_fft/tests/AGENTS.md new file mode 100644 index 0000000..1b48ec3 --- /dev/null +++ b/mkl_fft/tests/AGENTS.md @@ -0,0 +1,11 @@ +# AGENTS.md — mkl_fft/tests/ + +Test suite for FFT API compatibility and regressions. + +## Expectations +- Behavior changes should include test updates in the same PR. +- Bug fixes require regression tests. +- Keep tests deterministic and avoid brittle performance-dependent assertions. + +## Entry point +- `pytest mkl_fft/tests`