Refine AGENTS docs and resolve PR review comments

Author: napetrov

.github/AGENTS.md

@@ -3,14 +3,14 @@
 CI/CD workflows, automation, security scanning, and package distribution.
 
 ## Workflows
-- **conda-package.yml** — main build/test pipeline (Linux/Windows/macOS, Python 3.10-3.14)
-- **build-with-clang.yml** — Clang compiler compatibility validation
+- **conda-package.yml** — main build/test pipeline (Linux/Windows, Python 3.10-3.14)
+- **build-with-clang.yml** — Linux Clang compiler compatibility validation
 - **pre-commit.yml** — code quality checks (flake8, etc.)
 - **openssf-scorecard.yml** — security posture scanning
 
 ## CI/CD policy
 - Keep build matrix (Python versions, platforms) in workflow files only
-- Required checks: conda build + test on all supported Python versions
+- Required checks: conda build + test on supported Python versions/platforms in CI
 - Artifact naming: `$PACKAGE_NAME $OS Python $VERSION`
 - Channels: `conda-forge`, `conda-forge/label/python_rc`, Intel channel
 
@@ -21,8 +21,7 @@ CI/CD workflows, automation, security scanning, and package distribution.
 
 ## Platform specifics
 - **Linux:** RTLD_GLOBAL handling for MKL library loading
-- **Windows:** DLL search path configuration
-- **macOS:** dylib loading and rpath setup
+- **Windows:** DLL search path configuration for venv/runtime loading
 
 ## Notes
 - Workflow/job renames are breaking for downstream tooling

.github/copilot-instructions.md

@@ -0,0 +1,47 @@
+# GitHub Copilot Instructions — mkl-service
+
+## Identity
+You are an expert Python/Cython/C developer working on `mkl-service` 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` files provide 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 each edited file, locate and follow the nearest `AGENTS.md`.
+3. If no local file exists, inherit rules from root `AGENTS.md`.
+
+## Contribution expectations
+- Keep diffs minimal; prefer atomic single-purpose commits.
+- Preserve public API signatures in `mkl/__init__.py` unless change is explicitly requested.
+- For user-visible behavior changes: update tests in `mkl/tests/test_mkl_service.py`.
+- For bug fixes: add or extend regression tests in the same change.
+- Do not generate code without corresponding test updates when behavior changes.
+- 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, CI matrices, channels, or compiler flags.
+- Prefer stable local entry points:
+  - `python -m pip install -e .`
+  - `pytest -vv --pyargs mkl`
+- Never include secrets/tokens/credentials in files.
+
+## Source-of-truth files
+- Build/config: `pyproject.toml`, `setup.py`
+- Recipe/deps: `conda-recipe/meta.yaml`, `conda-recipe/conda_build_config.yaml`
+- CI: `.github/workflows/*.{yml,yaml}`
+- API contracts: `mkl/__init__.py`, `mkl/_mkl_service.pyx`
+- Tests: `mkl/tests/test_mkl_service.py`
+
+## MKL-specific constraints
+- Linux runtime init path may require `RTLD_GLOBAL` preloading (`mkl/_mklinitmodule.c`).
+- Windows venv DLL handling is in `mkl/_init_helper.py`.
+- Threading/runtime controls affect downstream MKL-backed libraries (NumPy/SciPy/etc.); maintain compatibility.
+- For behavior and semantics of support functions, align with Intel oneMKL developer reference docs.

AGENTS.md

@@ -3,26 +3,26 @@
 Entry point for agent context in this repo.
 
 ## What this repository is
-`mkl-service` provides Python API for runtime control of Intel® OneMKL (Math Kernel Library). It exposes support functions for:
+`mkl-service` provides a Python API for runtime control of Intel® oneMKL (Math Kernel Library). It exposes support functions for:
 - Threading control (set/get number of threads, domain-specific threading)
 - Version information (MKL version, build info)
 - Memory management (peak memory usage, memory statistics)
 - Conditional Numerical Reproducibility (CNR)
 - Timing functions (get CPU/wall clock time)
 - Miscellaneous utilities (MKL_VERBOSE control, etc.)
 
-Originally part of Intel® Distribution for Python*, now standalone package available via conda-forge and Intel channels.
+Originally part of Intel® Distribution for Python*, now a standalone package available via conda-forge and Intel channels.
 
 ## Key components
 - **Python interface:** `mkl/__init__.py` — public API surface
 - **Cython wrapper:** `mkl/_mkl_service.pyx` — wraps MKL support functions
-- **C init module:** `mkl/_mklinitmodule.c` — MKL library initialization
-- **Helper:** `mkl/_init_helper.py` — loading and RTLD_GLOBAL handling
+- **C init module:** `mkl/_mklinitmodule.c` — Linux-side MKL runtime preloading / initialization
+- **Helper:** `mkl/_init_helper.py` — Windows venv DLL loading helper
 - **Build system:** setuptools + Cython
 
 ## Build dependencies
 **Required:**
-- Intel® OneMKL
+- Intel® oneMKL
 - Cython
 - Python 3.10+
 
@@ -33,11 +33,11 @@ python setup.py install
 ```
 
 ## CI/CD
-- **Platforms:** Linux, Windows, macOS
+- **Platforms in CI workflows:** Linux, Windows
 - **Python versions:** 3.10, 3.11, 3.12, 3.13, 3.14
 - **Workflows:** `.github/workflows/`
-  - `conda-package.yml` — main build/test pipeline
-  - `build-with-clang.yml` — Clang compatibility
+  - `conda-package.yml` — main conda build/test pipeline
+  - `build-with-clang.yml` — Linux Clang compatibility
   - `pre-commit.yml` — code quality checks
   - `openssf-scorecard.yml` — security scanning
 
@@ -48,9 +48,9 @@ python setup.py install
 ## Usage
 ```python
 import mkl
-mkl.set_num_threads(4)              # Set global thread count
-mkl.domain_set_num_threads(1, "fft") # FFT functions run sequentially
-mkl.get_version_string()            # MKL version info
+mkl.set_num_threads(4)               # Set global thread count
+mkl.domain_set_num_threads(1, "fft")  # FFT functions run sequentially
+mkl.get_version_string()             # MKL version info
 ```
 
 ## How to work in this repo
@@ -62,12 +62,13 @@ mkl.get_version_string()            # MKL version info
 
 ## Code structure
 - **Cython layer:** `_mkl_service.pyx` + `_mkl_service.pxd` (C declarations)
-- **C init:** `_mklinitmodule.c` handles MKL library loading (RTLD_GLOBAL)
+- **C init:** `_mklinitmodule.c` handles Linux preloading (`dlopen(..., RTLD_GLOBAL)`) for MKL runtime
+- **Windows loading helper:** `_init_helper.py` handles DLL path setup in Windows venv
 - **Python wrapper:** `__init__.py` imports `_py_mkl_service` (generated from `.pyx`)
 - **Version:** `_version.py` (dynamic via setuptools)
 
 ## Notes
-- RTLD_GLOBAL required for MKL on Linux (handled by `RTLD_for_MKL` context manager)
+- RTLD_GLOBAL preloading is required on Linux (handled by `RTLD_for_MKL` context manager)
 - MKL must be available at runtime (conda: mkl, pip: relies on system MKL)
 - Threading functions affect NumPy, SciPy, and other MKL-backed libraries
 

conda-recipe/AGENTS.md

@@ -6,29 +6,29 @@ Conda package build recipe for conda-forge and Intel channel distribution.
 - **meta.yaml** — package metadata, dependencies, build requirements
 - **build.sh** — Linux/macOS build script
 - **bld.bat** — Windows build script
-- **conda_build_config.yaml** — build matrix (Python versions, platforms)
+- **conda_build_config.yaml** — compiler / stdlib pinning used by conda-build variants
 
 ## Build configuration
 - **Channels:** `conda-forge`, `conda-forge/label/python_rc`, Intel channel
-- **Python versions:** 3.10, 3.11, 3.12, 3.13, 3.14
-- **Compilers:** system default (GCC/Clang/MSVC)
-- **Dependencies:** mkl (runtime), mkl-devel (build), cython
+- **Python versions in CI build matrix:** 3.10, 3.11, 3.12, 3.13, 3.14
+- **Compilers:** pinned via `conda_build_config.yaml` (GCC/GXX on Linux, VS2022 on Windows)
+- **Dependencies:** `mkl` (runtime), `mkl-devel` (build), `cython`
 
 ## Build outputs
 - Conda package: `mkl-service-<version>-<build>.conda`
-- Platform-specific: `linux-64/`, `win-64/`, `osx-64/`, `osx-arm64/`
+- Platform-specific artifacts from CI currently: `linux-64/`, `win-64/`
 
 ## CI usage
 - Built in `.github/workflows/conda-package.yml`
 - Artifacts uploaded per Python version and platform
-- Test stage uses built artifacts from channel
+- Test stage uses built artifacts from a temporary local channel
 
 ## Platform specifics
-- **Linux:** RTLD_GLOBAL handling in build script
+- **Linux:** RTLD_GLOBAL handling in runtime init path
 - **Windows:** MKL library path configuration
-- **macOS:** Universal2 builds for Intel + ARM (if supported)
+- **macOS:** recipe scripts exist, but current GitHub Actions matrix does not build/test macOS
 
 ## Maintenance
-- Keep `conda_build_config.yaml` in sync with CI matrix
-- MKL version pin: track Intel MKL releases
-- Python 3.14: requires `conda-forge/label/python_rc` until stable
+- Keep recipe metadata in sync with workflow matrix and package metadata
+- MKL version pinning: track Intel MKL releases through recipe deps
+- Python 3.14 in CI uses `conda-forge/label/python_rc` while pre-release

examples/AGENTS.md

@@ -3,14 +3,12 @@
 Usage examples for mkl-service runtime control API.
 
 ## Files
-- **example.py** — basic usage: threading control, version info, timing
+- **example.py** — basic usage: MKL version query, instruction dispatch control, and timing
 
 ## Examples cover
-- Setting global thread count with `mkl.set_num_threads()`
-- Domain-specific threading (FFT, BLAS, etc.)
-- Querying MKL version and build info
-- Memory usage statistics
-- Timing functions for benchmarking
+- Querying MKL version/build info (`get_version()`, `get_version_string()`)
+- Controlling instruction dispatch with `enable_instructions()`
+- Using `dsecnd()` for simple timing
 
 ## Running examples
 ```bash
@@ -19,5 +17,5 @@ python examples/example.py
 
 ## Notes
 - Examples assume MKL is installed (conda: `mkl` package)
-- Threading changes affect all MKL-backed libraries in the process
-- Useful for verifying mkl-service installation and MKL availability
+- Example is intended as a lightweight installation/runtime sanity check
+- Threading/domain APIs are available in `mkl-service` but not exercised in this example

mkl/AGENTS.md

@@ -6,8 +6,8 @@ Core Python/Cython implementation: MKL support function wrappers and runtime con
 - `__init__.py` — public API, RTLD_GLOBAL context manager, module initialization
 - `_mkl_service.pyx` — Cython wrappers for MKL support functions
 - `_mkl_service.pxd` — Cython declarations (C function signatures)
-- `_mklinitmodule.c` — C extension for MKL library initialization
-- `_init_helper.py` — loading helpers and diagnostics
+- `_mklinitmodule.c` — C extension for Linux-side MKL runtime preloading/init
+- `_init_helper.py` — Windows loading helper (DLL path setup in venv)
 - `_version.py` — version string (dynamic via setuptools)
 - `tests/` — unit tests for API functionality
 
@@ -38,17 +38,19 @@ Core Python/Cython implementation: MKL support function wrappers and runtime con
 - **Thread safety:** All threading functions must be thread-safe
 - **API stability:** Preserve function signatures (widely used in ecosystem)
 - **MKL dependency:** Assumes MKL is available at runtime (conda: mkl package)
-- **RTLD_GLOBAL:** Required on Linux; handled by `RTLD_for_MKL` context manager in `__init__.py`
+- **RTLD_GLOBAL preload path:** Linux preload is handled in `_mklinitmodule.c`; Windows DLL setup is in `_init_helper.py`
 
 ## Cython details
 - `_mkl_service.pyx` → generates `_py_mkl_service` extension module
 - `.pxd` file declares external C functions from MKL headers
-- Cython build requires MKL headers (mkl-devel)
+- Cython build requires MKL headers (`mkl-devel`)
 
 ## C init module
 - `_mklinitmodule.c` → `_mklinit` extension
-- Ensures MKL library is loaded with correct flags before Cython extension
-- Platform-specific: Windows uses `LoadLibrary`, Linux uses `dlopen`
+- Ensures MKL runtime is initialized with correct flags before Cython extension
+- Platform-specific behavior in current code:
+  - Linux: `dlopen(..., RTLD_GLOBAL)` preload path (when applicable)
+  - Windows: runtime DLL loading support is handled by `_init_helper.py`
 
 ## Notes
 - Domain strings: "fft", "vml", "pardiso", "blas", etc. (see MKL docs)

mkl/tests/AGENTS.md

@@ -10,17 +10,17 @@ Unit tests for MKL runtime control API.
 - Version: `get_version`, `get_version_string` format validation
 - Memory: `peak_mem_usage`, `mem_stat` (if supported by MKL build)
 - CNR: Conditional Numerical Reproducibility flags
-- Edge cases: invalid domains, negative thread counts, thread-local settings
+- Edge cases currently covered: thread-local settings and API round-trips
 
 ## Running tests
 ```bash
 pytest mkl/tests/
 ```
 
 ## CI integration
-- Tests run in conda-package.yml workflow
-- Separate test jobs per Python version and platform
-- Linux + Windows + macOS coverage
+- Tests run in `conda-package.yml` workflow
+- Separate test jobs per Python version and CI platform
+- CI coverage: Linux + Windows
 
 ## Adding tests
 - New API functions → add to `test_mkl_service.py` with validation