Expand AGENTS docs to multi-level structure

Author: napetrov

.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.

.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

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

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.

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.

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.

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.

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`