From 3611e85505b6863cc74bd9f993cb3be051a376a3 Mon Sep 17 00:00:00 2001 From: Nikolay Petrov Date: Thu, 19 Feb 2026 21:56:52 +0000 Subject: [PATCH 1/3] Add AGENTS.md and Copilot instructions Introduce structured AI agent instructions following Intel's AGENTS spec v4: - AGENTS.md: project context (RNG interface, archetype, structure, source-of-truth) - .github/copilot-instructions.md: agent behavior policy Key guidance: - Preserve numpy.random API compatibility - RNG specifics: BRNG selection, statistical properties - Cython: release GIL for MKL RNG calls (thread-safe) - Local dev: conda env + pip install -e . - Statistical validation required for RNG changes Token budget: 217 words (AGENTS.md) + copilot-instructions Based on mkl_fft pattern --- .github/copilot-instructions.md | 48 +++++++++++++++++++++++++++++++++ AGENTS.md | 36 +++++++++++++++++++++++++ 2 files changed, 84 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..be23539 --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,48 @@ +# GitHub Copilot Instructions — mkl_random + +## Identity +You are an expert Python/C developer working on `mkl_random` 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.random` API compatibility by default. +- For API changes: update tests + docstrings when user-visible. +- For bug fixes: add regression tests in `mkl_random/tests/`. +- Do not generate code without a corresponding test update in the same step. +- Run `pre-commit run --all-files` if `.pre-commit-config.yaml` exists. + +## 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_random/tests` (test). +- Never include sensitive data in any file. +- **Cython/MKL calls:** Release GIL with `with nogil:` blocks for RNG operations (they are thread-safe in MKL). +- **Memory:** Ensure proper alignment for RNG state structures; respect MKL object lifecycle. +- **BRNG selection:** Do not hardcode BRNG (basic RNG) names outside `__init__.py` or 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` +- CI: `.github/workflows/*.{yml,yaml}` +- API contracts: `mkl_random/__init__.py`, NumPy `random` docs (https://numpy.org/doc/stable/reference/random/index.html) +- Test data: `mkl_random/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` at runtime +- Statistical properties: preserve distribution correctness; no RNG changes without validation +- 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..5cf969b --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,36 @@ +# AGENTS.md — mkl_random + +## What this project is +NumPy-based Python interface to Intel® oneMKL Random Number Generation (RNG) functionality. Provides MKL-accelerated random sampling from distributions compatible with `numpy.random`. Part of Intel® Distribution for Python. Archetype: **python** (Cython + C extensions). + +Layers: Python interface, Cython bindings (`mklrand.pyx`), C backend (`src/`). + +## How it's structured +- `mkl_random/` — main package + - `mklrand.pyx` — Cython RNG interface + - `src/` — C code generation scripts + - `tests/` — pytest suite +- `conda-recipe/`, `conda-recipe-cf/` — Intel/conda-forge builds +- `examples/` — parallel MC, random states demos + +Build: `pyproject.toml` + `setup.py`. Runtime: `mkl`, `numpy>=1.26.4`. + +## How to work in it +- Keep changes atomic and single-purpose. +- Preserve `numpy.random` API compatibility; document divergence in commit message. +- Pair changes with tests and docstrings. +- Never assume MKL or NumPy versions; use source-of-truth files. +- **RNG specifics:** Changes to BRNG (basic RNG) selection or distribution methods must preserve statistical properties. +- **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/` +- API/contracts: `mkl_random/__init__.py`, NumPy `random` docs +- Stable entry points: `python -m pip install .`, `pytest mkl_random/tests` + +## Directory map +No local AGENTS files — project is small enough for root-level guidance only. From b0e4a387d47ee49eec82fbd99613e853d375c53d Mon Sep 17 00:00:00 2001 From: Nikolay Petrov Date: Tue, 3 Mar 2026 08:47:41 -0800 Subject: [PATCH 2/3] Expand AGENTS docs to multi-level structure --- .github/AGENTS.md | 14 ++++++++ .github/copilot-instructions.md | 49 ++++++++++++------------- AGENTS.md | 64 ++++++++++++++++++--------------- conda-recipe-cf/AGENTS.md | 10 ++++++ conda-recipe/AGENTS.md | 12 +++++++ examples/AGENTS.md | 11 ++++++ mkl_random/AGENTS.md | 16 +++++++++ mkl_random/tests/AGENTS.md | 12 +++++++ 8 files changed, 134 insertions(+), 54 deletions(-) create mode 100644 .github/AGENTS.md create mode 100644 conda-recipe-cf/AGENTS.md create mode 100644 conda-recipe/AGENTS.md create mode 100644 examples/AGENTS.md create mode 100644 mkl_random/AGENTS.md create mode 100644 mkl_random/tests/AGENTS.md diff --git a/.github/AGENTS.md b/.github/AGENTS.md new file mode 100644 index 0000000..56cde05 --- /dev/null +++ b/.github/AGENTS.md @@ -0,0 +1,14 @@ +# 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-docs.yml` — docs build pipeline + +## Policy +- Treat workflow YAML as canonical for platform/Python matrices. +- Keep artifact naming and channel usage aligned with workflow files. +- Avoid doc claims about CI coverage unless present in workflow config. diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index be23539..3acbdd2 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -1,48 +1,45 @@ # GitHub Copilot Instructions — mkl_random ## Identity -You are an expert Python/C developer working on `mkl_random` at Intel. -Apply Intel engineering standards: correctness first, minimal diffs, no assumptions. +You are an expert Python/C/Cython developer working on `mkl_random` at Intel. +Prioritize correctness, numerical/statistical integrity, 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.random` API compatibility by default. -- For API changes: update tests + docstrings when user-visible. -- For bug fixes: add regression tests in `mkl_random/tests/`. -- Do not generate code without a corresponding test update in the same step. -- Run `pre-commit run --all-files` if `.pre-commit-config.yaml` exists. +- Keep changes atomic and single-purpose. +- Preserve `numpy.random` compatibility by default. +- For behavior changes: update/add tests in `mkl_random/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_random/tests` (test). -- Never include sensitive data in any file. -- **Cython/MKL calls:** Release GIL with `with nogil:` blocks for RNG operations (they are thread-safe in MKL). -- **Memory:** Ensure proper alignment for RNG state structures; respect MKL object lifecycle. -- **BRNG selection:** Do not hardcode BRNG (basic RNG) names outside `__init__.py` or tests. +- Never invent versions, build flags, CI matrices, or channel policies. +- Use source-of-truth files for mutable details. +- Do not hardcode BRNG behavior outside intended API/configuration points. +- Prefer stable local entry points: + - `python -m pip install -e .` + - `pytest mkl_random/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}` -- API contracts: `mkl_random/__init__.py`, NumPy `random` docs (https://numpy.org/doc/stable/reference/random/index.html) -- Test data: `mkl_random/tests/` +- API: `mkl_random/__init__.py`, `mkl_random/mklrand.pyx` +- Tests: `mkl_random/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` at runtime -- Statistical properties: preserve distribution correctness; no RNG changes without validation -- Do not hardcode MKL version assumptions; respect `pyproject.toml` `requires-python` range +- Build-time MKL: `mkl-devel`; runtime MKL: `mkl` +- Preserve statistical properties for distribution/BRNG-related changes +- Do not claim performance/statistical improvements without reproducible validation diff --git a/AGENTS.md b/AGENTS.md index 5cf969b..ea0947d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,36 +1,44 @@ # AGENTS.md — mkl_random -## What this project is -NumPy-based Python interface to Intel® oneMKL Random Number Generation (RNG) functionality. Provides MKL-accelerated random sampling from distributions compatible with `numpy.random`. Part of Intel® Distribution for Python. Archetype: **python** (Cython + C extensions). - -Layers: Python interface, Cython bindings (`mklrand.pyx`), C backend (`src/`). - -## How it's structured -- `mkl_random/` — main package - - `mklrand.pyx` — Cython RNG interface - - `src/` — C code generation scripts - - `tests/` — pytest suite -- `conda-recipe/`, `conda-recipe-cf/` — Intel/conda-forge builds -- `examples/` — parallel MC, random states demos - -Build: `pyproject.toml` + `setup.py`. Runtime: `mkl`, `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.random` API compatibility; document divergence in commit message. -- Pair changes with tests and docstrings. -- Never assume MKL or NumPy versions; use source-of-truth files. -- **RNG specifics:** Changes to BRNG (basic RNG) selection or distribution methods must preserve statistical properties. -- **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_random` is a NumPy-compatible random module backed by Intel® oneMKL RNG. +It provides accelerated random sampling with API compatibility goals relative to `numpy.random`. + +## Key components +- **Python package:** `mkl_random/` +- **Cython layer:** `mkl_random/mklrand.pyx` +- **C backend/templates:** `mkl_random/src/` +- **Tests:** `mkl_random/tests/` +- **Packaging:** `conda-recipe/`, `conda-recipe-cf/` +- **Examples:** `examples/` + +## Build/runtime basics +- Build system: `pyproject.toml` + `setup.py` +- Build deps: `cython`, `numpy`, `mkl-devel` +- Runtime deps: `numpy`, `mkl` + +## Development guardrails +- Preserve `numpy.random` API compatibility unless change is explicitly requested. +- RNG changes must preserve statistical correctness and reproducibility expectations. +- Keep diffs minimal and pair behavior changes with tests. +- 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/` -- API/contracts: `mkl_random/__init__.py`, NumPy `random` docs -- Stable entry points: `python -m pip install .`, `pytest mkl_random/tests` +- Dependencies: `pyproject.toml`, `conda-recipe*/meta.yaml` +- CI matrices/workflows: `.github/workflows/*.{yml,yaml}` +- Public API: `mkl_random/__init__.py` +- Tests: `mkl_random/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_random/AGENTS.md` — package-level implementation context +- `mkl_random/tests/AGENTS.md` — testing scope and conventions +- `conda-recipe/AGENTS.md` — Intel-channel conda packaging +- `conda-recipe-cf/AGENTS.md` — conda-forge recipe context +- `examples/AGENTS.md` — runnable examples and expected behavior diff --git a/conda-recipe-cf/AGENTS.md b/conda-recipe-cf/AGENTS.md new file mode 100644 index 0000000..21394bc --- /dev/null +++ b/conda-recipe-cf/AGENTS.md @@ -0,0 +1,10 @@ +# AGENTS.md — conda-recipe-cf/ + +Conda-forge recipe context for `mkl_random`. + +## Scope +- conda-forge specific `meta.yaml` and build scripts in this directory. + +## Guardrails +- Keep conda-forge recipe semantics separate from Intel-channel recipe. +- Align recipe 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..d92bf60 --- /dev/null +++ b/conda-recipe/AGENTS.md @@ -0,0 +1,12 @@ +# 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 build/runtime dependency intent. +- Keep recipe updates synchronized with CI workflow expectations. +- Do not infer platform/Python matrix from docs; read workflow YAML. diff --git a/examples/AGENTS.md b/examples/AGENTS.md new file mode 100644 index 0000000..3a9e9de --- /dev/null +++ b/examples/AGENTS.md @@ -0,0 +1,11 @@ +# AGENTS.md — examples/ + +Runnable usage examples for `mkl_random`. + +## Intent +- Demonstrate practical usage patterns (parallel MC, random states, etc.). +- Serve as quick sanity checks, not exhaustive correctness/performance tests. + +## Guardrails +- Keep examples concise and runnable. +- If API behavior in examples changes, keep comments/output expectations consistent. diff --git a/mkl_random/AGENTS.md b/mkl_random/AGENTS.md new file mode 100644 index 0000000..f53da1e --- /dev/null +++ b/mkl_random/AGENTS.md @@ -0,0 +1,16 @@ +# AGENTS.md — mkl_random/ + +Core package implementation for MKL-backed random functionality. + +## Key files +- `__init__.py` — public package exports/API wiring +- `mklrand.pyx` — Cython bindings to MKL RNG support +- `_init_helper.py` — platform/runtime loading helpers +- `src/` — C-level support and generation assets +- `tests/` — package tests (see local AGENTS in tests) + +## Guardrails +- Preserve `numpy.random`-compatible behavior by default. +- RNG algorithm/distribution changes must preserve statistical correctness. +- Keep BRNG/distribution behavior explicit and test-covered. +- Prefer minimal, isolated edits around touched API paths. diff --git a/mkl_random/tests/AGENTS.md b/mkl_random/tests/AGENTS.md new file mode 100644 index 0000000..257688a --- /dev/null +++ b/mkl_random/tests/AGENTS.md @@ -0,0 +1,12 @@ +# AGENTS.md — mkl_random/tests/ + +Test suite for RNG behavior, API compatibility, and regressions. + +## Expectations +- Behavior changes in package code should include test updates in the same PR. +- Add regression tests for bug fixes. +- Keep tests deterministic when possible (fixed seeds / stable assertions). +- For statistical assertions, use robust criteria and document rationale. + +## Entry point +- `pytest mkl_random/tests` From fe624751676d311cea24e26917997a6e3a61b8ef Mon Sep 17 00:00:00 2001 From: Nikolay Petrov Date: Sat, 7 Mar 2026 06:13:50 -0800 Subject: [PATCH 3/3] Update AGENTS for interfaces namespace and patching guidance --- .github/copilot-instructions.md | 4 ++-- AGENTS.md | 6 ++++-- mkl_random/AGENTS.md | 4 +++- 3 files changed, 9 insertions(+), 5 deletions(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 3acbdd2..37c202a 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -19,7 +19,7 @@ Higher-precedence file overrides lower-precedence context. ## Contribution expectations - Keep changes atomic and single-purpose. -- Preserve `numpy.random` compatibility by default. +- Preserve `numpy.random` compatibility by default, including compatibility aliases during namespace transitions. - For behavior changes: update/add tests in `mkl_random/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. @@ -36,7 +36,7 @@ Higher-precedence file overrides lower-precedence context. - Build/config: `pyproject.toml`, `setup.py` - Dependencies: `pyproject.toml`, `conda-recipe/meta.yaml`, `conda-recipe-cf/meta.yaml` - CI: `.github/workflows/*.{yml,yaml}` -- API: `mkl_random/__init__.py`, `mkl_random/mklrand.pyx` +- API: `mkl_random/__init__.py`, `mkl_random/mklrand.pyx`, `mkl_random/interfaces/*.py` (when present) - Tests: `mkl_random/tests/` ## Intel-specific constraints diff --git a/AGENTS.md b/AGENTS.md index ea0947d..cef53a8 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -9,7 +9,7 @@ It provides accelerated random sampling with API compatibility goals relative to ## Key components - **Python package:** `mkl_random/` - **Cython layer:** `mkl_random/mklrand.pyx` -- **C backend/templates:** `mkl_random/src/` +- **C/C++ backend sources:** `mkl_random/src/` (`*.cpp`, `*.h`, support scripts) - **Tests:** `mkl_random/tests/` - **Packaging:** `conda-recipe/`, `conda-recipe-cf/` - **Examples:** `examples/` @@ -21,7 +21,9 @@ It provides accelerated random sampling with API compatibility goals relative to ## Development guardrails - Preserve `numpy.random` API compatibility unless change is explicitly requested. +- Keep namespace/API transitions explicit (e.g., `mkl_random.MKLRandomState` with compatibility aliases where applicable). - RNG changes must preserve statistical correctness and reproducibility expectations. +- If patching/integration entry points are touched, keep patch semantics and rollback behavior explicit. - Keep diffs minimal and pair behavior changes with tests. - Avoid hardcoding mutable versions/matrices/channels in docs. @@ -29,7 +31,7 @@ It provides accelerated random sampling with API compatibility goals relative to - Build/config: `pyproject.toml`, `setup.py` - Dependencies: `pyproject.toml`, `conda-recipe*/meta.yaml` - CI matrices/workflows: `.github/workflows/*.{yml,yaml}` -- Public API: `mkl_random/__init__.py` +- Public API: `mkl_random/__init__.py`, `mkl_random/interfaces/*.py` (when present) - Tests: `mkl_random/tests/` For behavior policy, see `.github/copilot-instructions.md`. diff --git a/mkl_random/AGENTS.md b/mkl_random/AGENTS.md index f53da1e..84d5142 100644 --- a/mkl_random/AGENTS.md +++ b/mkl_random/AGENTS.md @@ -6,11 +6,13 @@ Core package implementation for MKL-backed random functionality. - `__init__.py` — public package exports/API wiring - `mklrand.pyx` — Cython bindings to MKL RNG support - `_init_helper.py` — platform/runtime loading helpers -- `src/` — C-level support and generation assets +- `src/` — C/C++ support sources and headers - `tests/` — package tests (see local AGENTS in tests) ## Guardrails - Preserve `numpy.random`-compatible behavior by default. +- Keep namespace compatibility explicit (`MKLRandomState` + compatibility aliases where needed). - RNG algorithm/distribution changes must preserve statistical correctness. - Keep BRNG/distribution behavior explicit and test-covered. +- If patching/integration shims are modified, ensure behavior remains reversible and test-covered. - Prefer minimal, isolated edits around touched API paths.