From fd88e5f5a3c9a09c4d82715f0222b755a17fa455 Mon Sep 17 00:00:00 2001 From: Nikolay Petrov Date: Thu, 19 Feb 2026 06:15:56 +0000 Subject: [PATCH] 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.