Skip to content

Commit f4fb7ab

Browse files
napetrovnapetrov
committed
Add AGENTS.md documentation structure
- Root AGENTS.md with ecosystem context and directory map - .github/AGENTS.md: CI/CD workflows, multi-platform support - mkl/AGENTS.md: Python/Cython implementation, MKL support functions - mkl/tests/AGENTS.md: unit tests and validation - conda-recipe/AGENTS.md: conda packaging for multiple platforms - examples/AGENTS.md: usage examples Follows dpnp/mkl_umath AGENTS.md pattern for IntelPython ecosystem consistency.
1 parent a0bb95d commit f4fb7ab

6 files changed

Lines changed: 258 additions & 0 deletions

File tree

‎.github/AGENTS.md‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
# AGENTS.md — .github/
2+
3+
CI/CD workflows, automation, security scanning, and package distribution.
4+
5+
## Workflows
6+
- **conda-package.yml** — main build/test pipeline (Linux/Windows/macOS, Python 3.10-3.14)
7+
- **build-with-clang.yml** — Clang compiler compatibility validation
8+
- **pre-commit.yml** — code quality checks (flake8, etc.)
9+
- **openssf-scorecard.yml** — security posture scanning
10+
11+
## CI/CD policy
12+
- Keep build matrix (Python versions, platforms) in workflow files only
13+
- Required checks: conda build + test on all supported Python versions
14+
- Artifact naming: `$PACKAGE_NAME $OS Python $VERSION`
15+
- Channels: `conda-forge`, `conda-forge/label/python_rc`, Intel channel
16+
17+
## Security
18+
- OpenSSF Scorecard runs automatically
19+
- CODEOWNERS enforces review policy
20+
- Dependabot monitors dependencies (`.github/dependabot.yml`)
21+
22+
## Platform specifics
23+
- **Linux:** RTLD_GLOBAL handling for MKL library loading
24+
- **Windows:** DLL search path configuration
25+
- **macOS:** dylib loading and rpath setup
26+
27+
## Notes
28+
- Workflow/job renames are breaking for downstream tooling
29+
- Cache key includes `meta.yaml` hash for conda packages
30+
- Python 3.14 uses `conda-forge/label/python_rc` for pre-release support

‎AGENTS.md‎

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
# AGENTS.md
2+
3+
Entry point for agent context in this repo.
4+
5+
## What this repository is
6+
`mkl-service` provides Python API for runtime control of Intel® OneMKL (Math Kernel Library). It exposes support functions for:
7+
- Threading control (set/get number of threads, domain-specific threading)
8+
- Version information (MKL version, build info)
9+
- Memory management (peak memory usage, memory statistics)
10+
- Conditional Numerical Reproducibility (CNR)
11+
- Timing functions (get CPU/wall clock time)
12+
- Miscellaneous utilities (MKL_VERBOSE control, etc.)
13+
14+
Originally part of Intel® Distribution for Python*, now standalone package available via conda-forge and Intel channels.
15+
16+
## Key components
17+
- **Python interface:** `mkl/__init__.py` — public API surface
18+
- **Cython wrapper:** `mkl/_mkl_service.pyx` — wraps MKL support functions
19+
- **C init module:** `mkl/_mklinitmodule.c` — MKL library initialization
20+
- **Helper:** `mkl/_init_helper.py` — loading and RTLD_GLOBAL handling
21+
- **Build system:** setuptools + Cython
22+
23+
## Build dependencies
24+
**Required:**
25+
- Intel® OneMKL
26+
- Cython
27+
- Python 3.10+
28+
29+
**Conda environment:**
30+
```bash
31+
conda install -c conda-forge mkl-devel cython
32+
python setup.py install
33+
```
34+
35+
## CI/CD
36+
- **Platforms:** Linux, Windows, macOS
37+
- **Python versions:** 3.10, 3.11, 3.12, 3.13, 3.14
38+
- **Workflows:** `.github/workflows/`
39+
- `conda-package.yml` — main build/test pipeline
40+
- `build-with-clang.yml` — Clang compatibility
41+
- `pre-commit.yml` — code quality checks
42+
- `openssf-scorecard.yml` — security scanning
43+
44+
## Distribution
45+
- **Conda:** `conda-forge` and `https://software.repos.intel.com/python/conda`
46+
- **PyPI:** `python -m pip install mkl-service`
47+
48+
## Usage
49+
```python
50+
import mkl
51+
mkl.set_num_threads(4) # Set global thread count
52+
mkl.domain_set_num_threads(1, "fft") # FFT functions run sequentially
53+
mkl.get_version_string() # MKL version info
54+
```
55+
56+
## How to work in this repo
57+
- **API stability:** Preserve existing function signatures (widely used in ecosystem)
58+
- **Threading:** Changes to threading control must be thread-safe
59+
- **CNR:** Conditional Numerical Reproducibility flags require careful documentation
60+
- **Testing:** Add tests to `mkl/tests/test_mkl_service.py`
61+
- **Docs:** MKL support functions documented in [Intel oneMKL Developer Reference](https://www.intel.com/content/www/us/en/docs/onemkl/developer-reference-c/2025-2/support-functions.html)
62+
63+
## Code structure
64+
- **Cython layer:** `_mkl_service.pyx` + `_mkl_service.pxd` (C declarations)
65+
- **C init:** `_mklinitmodule.c` handles MKL library loading (RTLD_GLOBAL)
66+
- **Python wrapper:** `__init__.py` imports `_py_mkl_service` (generated from `.pyx`)
67+
- **Version:** `_version.py` (dynamic via setuptools)
68+
69+
## Notes
70+
- RTLD_GLOBAL required for MKL on Linux (handled by `RTLD_for_MKL` context manager)
71+
- MKL must be available at runtime (conda: mkl, pip: relies on system MKL)
72+
- Threading functions affect NumPy, SciPy, and other MKL-backed libraries
73+
74+
## Directory map
75+
Below directories have local `AGENTS.md` for deeper context:
76+
- `.github/AGENTS.md` — CI/CD workflows and automation
77+
- `mkl/AGENTS.md` — Python/Cython implementation
78+
- `mkl/tests/AGENTS.md` — unit tests
79+
- `conda-recipe/AGENTS.md` — conda packaging
80+
- `examples/AGENTS.md` — usage examples
81+
82+
---
83+
84+
For broader IntelPython ecosystem context, see:
85+
- `mkl_umath` (MKL-backed NumPy ufuncs)
86+
- `mkl_random` (MKL-based random number generation)
87+
- `dpnp` (Data Parallel NumPy)

‎conda-recipe/AGENTS.md‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
# AGENTS.md — conda-recipe/
2+
3+
Conda package build recipe for conda-forge and Intel channel distribution.
4+
5+
## Files
6+
- **meta.yaml** — package metadata, dependencies, build requirements
7+
- **build.sh** — Linux/macOS build script
8+
- **bld.bat** — Windows build script
9+
- **conda_build_config.yaml** — build matrix (Python versions, platforms)
10+
11+
## Build configuration
12+
- **Channels:** `conda-forge`, `conda-forge/label/python_rc`, Intel channel
13+
- **Python versions:** 3.10, 3.11, 3.12, 3.13, 3.14
14+
- **Compilers:** system default (GCC/Clang/MSVC)
15+
- **Dependencies:** mkl (runtime), mkl-devel (build), cython
16+
17+
## Build outputs
18+
- Conda package: `mkl-service-<version>-<build>.conda`
19+
- Platform-specific: `linux-64/`, `win-64/`, `osx-64/`, `osx-arm64/`
20+
21+
## CI usage
22+
- Built in `.github/workflows/conda-package.yml`
23+
- Artifacts uploaded per Python version and platform
24+
- Test stage uses built artifacts from channel
25+
26+
## Platform specifics
27+
- **Linux:** RTLD_GLOBAL handling in build script
28+
- **Windows:** MKL library path configuration
29+
- **macOS:** Universal2 builds for Intel + ARM (if supported)
30+
31+
## Maintenance
32+
- Keep `conda_build_config.yaml` in sync with CI matrix
33+
- MKL version pin: track Intel MKL releases
34+
- Python 3.14: requires `conda-forge/label/python_rc` until stable

‎examples/AGENTS.md‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
# AGENTS.md — examples/
2+
3+
Usage examples for mkl-service runtime control API.
4+
5+
## Files
6+
- **example.py** — basic usage: threading control, version info, timing
7+
8+
## Examples cover
9+
- Setting global thread count with `mkl.set_num_threads()`
10+
- Domain-specific threading (FFT, BLAS, etc.)
11+
- Querying MKL version and build info
12+
- Memory usage statistics
13+
- Timing functions for benchmarking
14+
15+
## Running examples
16+
```bash
17+
python examples/example.py
18+
```
19+
20+
## Notes
21+
- Examples assume MKL is installed (conda: `mkl` package)
22+
- Threading changes affect all MKL-backed libraries in the process
23+
- Useful for verifying mkl-service installation and MKL availability

‎mkl/AGENTS.md‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
# AGENTS.md — mkl/
2+
3+
Core Python/Cython implementation: MKL support function wrappers and runtime control.
4+
5+
## Structure
6+
- `__init__.py` — public API, RTLD_GLOBAL context manager, module initialization
7+
- `_mkl_service.pyx` — Cython wrappers for MKL support functions
8+
- `_mkl_service.pxd` — Cython declarations (C function signatures)
9+
- `_mklinitmodule.c` — C extension for MKL library initialization
10+
- `_init_helper.py` — loading helpers and diagnostics
11+
- `_version.py` — version string (dynamic via setuptools)
12+
- `tests/` — unit tests for API functionality
13+
14+
## API categories
15+
### Threading control
16+
- `set_num_threads(n)` — global thread count
17+
- `get_max_threads()` — max threads available
18+
- `domain_set_num_threads(n, domain)` — per-domain threading (FFT, VML, etc.)
19+
- `domain_get_max_threads(domain)` — domain-specific max threads
20+
21+
### Version information
22+
- `get_version()` — MKL version dict
23+
- `get_version_string()` — formatted version string
24+
25+
### Memory management
26+
- `peak_mem_usage(memtype)` — peak memory usage stats
27+
- `mem_stat()` — memory allocation statistics
28+
29+
### CNR (Conditional Numerical Reproducibility)
30+
- `set_num_threads_local(n)` — thread-local thread count
31+
- CNR mode control functions
32+
33+
### Timing
34+
- `second()` — wall clock time
35+
- `dsecnd()` — high-precision timing
36+
37+
## Development guardrails
38+
- **Thread safety:** All threading functions must be thread-safe
39+
- **API stability:** Preserve function signatures (widely used in ecosystem)
40+
- **MKL dependency:** Assumes MKL is available at runtime (conda: mkl package)
41+
- **RTLD_GLOBAL:** Required on Linux; handled by `RTLD_for_MKL` context manager in `__init__.py`
42+
43+
## Cython details
44+
- `_mkl_service.pyx` → generates `_py_mkl_service` extension module
45+
- `.pxd` file declares external C functions from MKL headers
46+
- Cython build requires MKL headers (mkl-devel)
47+
48+
## C init module
49+
- `_mklinitmodule.c` → `_mklinit` extension
50+
- Ensures MKL library is loaded with correct flags before Cython extension
51+
- Platform-specific: Windows uses `LoadLibrary`, Linux uses `dlopen`
52+
53+
## Notes
54+
- Domain strings: "fft", "vml", "pardiso", "blas", etc. (see MKL docs)
55+
- Threading changes affect all MKL-using libraries (NumPy, SciPy, etc.)
56+
- `MKL_VERBOSE` environment variable controls MKL diagnostic output

‎mkl/tests/AGENTS.md‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
# AGENTS.md — mkl/tests/
2+
3+
Unit tests for MKL runtime control API.
4+
5+
## Test files
6+
- **test_mkl_service.py** — API functionality, threading control, version info
7+
8+
## Test coverage
9+
- Threading: `set_num_threads`, `get_max_threads`, domain-specific threading
10+
- Version: `get_version`, `get_version_string` format validation
11+
- Memory: `peak_mem_usage`, `mem_stat` (if supported by MKL build)
12+
- CNR: Conditional Numerical Reproducibility flags
13+
- Edge cases: invalid domains, negative thread counts, thread-local settings
14+
15+
## Running tests
16+
```bash
17+
pytest mkl/tests/
18+
```
19+
20+
## CI integration
21+
- Tests run in conda-package.yml workflow
22+
- Separate test jobs per Python version and platform
23+
- Linux + Windows + macOS coverage
24+
25+
## Adding tests
26+
- New API functions → add to `test_mkl_service.py` with validation
27+
- Threading behavior → test thread count changes take effect
28+
- Use `mkl.get_version()` to check MKL availability before tests

0 commit comments

Comments
 (0)