Skip to content

Add AGENTS.md documentation structure #151

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
napetrov wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Add AGENTS.md documentation structure #151

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 30 additions & 0 deletions .github/AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,30 @@
# AGENTS.md — .github/

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)
Copy link

Copilot AI Feb 20, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The workflow list claims conda-package.yml is a Linux/Windows/macOS pipeline, but the actual workflow only defines Linux and Windows jobs. Please either add a macOS job to the workflow or update this doc to reflect current CI coverage (and optionally note macOS support is only via recipe/build scripts).

Suggested change
- **conda-package.yml** — main build/test pipeline (Linux/Windows/macOS, Python 3.10-3.14)
- **conda-package.yml** — main build/test pipeline (Linux/Windows, Python 3.10-3.14)

Copilot uses AI. Check for mistakes.
- **build-with-clang.yml** — 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
- Artifact naming: `$PACKAGE_NAME $OS Python $VERSION`
- Channels: `conda-forge`, `conda-forge/label/python_rc`, Intel channel

## Security
- OpenSSF Scorecard runs automatically
- CODEOWNERS enforces review policy
- Dependabot monitors dependencies (`.github/dependabot.yml`)

## Platform specifics
- **Linux:** RTLD_GLOBAL handling for MKL library loading
- **Windows:** DLL search path configuration
- **macOS:** dylib loading and rpath setup

## Notes
- Workflow/job renames are breaking for downstream tooling
- Cache key includes `meta.yaml` hash for conda packages
- Python 3.14 uses `conda-forge/label/python_rc` for pre-release support
87 changes: 87 additions & 0 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,87 @@
# AGENTS.md

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

## 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
- **Build system:** setuptools + Cython

## Build dependencies
**Required:**
- Intel® OneMKL
- Cython
- Python 3.10+

**Conda environment:**
```bash
conda install -c conda-forge mkl-devel cython
python setup.py install
```

## CI/CD
- **Platforms:** Linux, Windows, macOS
Copy link

Copilot AI Feb 20, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This repository-level CI/CD section states the GitHub Actions CI covers Linux/Windows/macOS, but there are no macOS jobs in .github/workflows/ (only Linux/Windows in conda-package.yml, and Ubuntu in build-with-clang.yml). Please update the platform list (or add macOS jobs) so the entry point stays accurate.

Suggested change
- **Platforms:** Linux, Windows, macOS
- **Platforms:** Linux, Windows

Copilot uses AI. Check for mistakes.
- **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
- `pre-commit.yml` — code quality checks
- `openssf-scorecard.yml` — security scanning

## Distribution
- **Conda:** `conda-forge` and `https://software.repos.intel.com/python/conda`
- **PyPI:** `python -m pip install mkl-service`

## 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
```

## How to work in this repo
- **API stability:** Preserve existing function signatures (widely used in ecosystem)
- **Threading:** Changes to threading control must be thread-safe
- **CNR:** Conditional Numerical Reproducibility flags require careful documentation
- **Testing:** Add tests to `mkl/tests/test_mkl_service.py`
- **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)

## Code structure
- **Cython layer:** `_mkl_service.pyx` + `_mkl_service.pxd` (C declarations)
- **C init:** `_mklinitmodule.c` handles MKL library loading (RTLD_GLOBAL)
- **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)
- MKL must be available at runtime (conda: mkl, pip: relies on system MKL)
- Threading functions affect NumPy, SciPy, and other MKL-backed libraries

## Directory map
Below directories have local `AGENTS.md` for deeper context:
- `.github/AGENTS.md` — CI/CD workflows and automation
- `mkl/AGENTS.md` — Python/Cython implementation
- `mkl/tests/AGENTS.md` — unit tests
- `conda-recipe/AGENTS.md` — conda packaging
- `examples/AGENTS.md` — usage examples

---

For broader IntelPython ecosystem context, see:
- `mkl_umath` (MKL-backed NumPy ufuncs)
- `mkl_random` (MKL-based random number generation)
- `dpnp` (Data Parallel NumPy)
34 changes: 34 additions & 0 deletions conda-recipe/AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,34 @@
# AGENTS.md — conda-recipe/

Conda package build recipe for conda-forge and Intel channel distribution.

## Files
- **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)

Comment on lines +8 to +10
Copy link

Copilot AI Feb 20, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

conda_build_config.yaml is described as containing the Python/platform build matrix, but in this repo it only pins compiler/stdlib settings (no Python version matrix). Consider updating the description to reflect what’s actually in the file, and reference the workflow for Python-version coverage instead.

Copilot uses AI. Check for mistakes.
## 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)
Copy link

Copilot AI Feb 20, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This states compilers are “system default”, but the conda recipe pins toolchain details (e.g., gcc/gxx and vs2022) via conda_build_config.yaml. Please update the wording to avoid implying the host system compiler is used.

Suggested change
- **Compilers:** system default (GCC/Clang/MSVC)
- **Compilers:** pinned via `conda_build_config.yaml` (GCC, Clang, MSVC toolchains)

Copilot uses AI. Check for mistakes.
- **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/`

## CI usage
- Built in `.github/workflows/conda-package.yml`
- Artifacts uploaded per Python version and platform
- Test stage uses built artifacts from channel

## Platform specifics
- **Linux:** RTLD_GLOBAL handling in build script
- **Windows:** MKL library path configuration
- **macOS:** Universal2 builds for Intel + ARM (if supported)

## 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
23 changes: 23 additions & 0 deletions examples/AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
# AGENTS.md — examples/

Usage examples for mkl-service runtime control API.

## Files
- **example.py** — basic usage: threading control, version info, 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

Comment on lines +6 to +14
Copy link

Copilot AI Feb 20, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

examples/example.py doesn’t show threading control; it prints version info, adjusts instruction dispatch with enable_instructions, and measures time with dsecnd(). Please update this file description (or update the example) so it matches the current contents.

Suggested change
- **example.py** — basic usage: threading control, version info, 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
- **example.py** — basic usage: version info, instruction control, and timing
## Examples cover
- Querying MKL version and build info
- Controlling instruction dispatch with `enable_instructions()`
- Using `dsecnd()` for simple timing and benchmarking

Copilot uses AI. Check for mistakes.
Comment on lines +6 to +14
Copy link

Copilot AI Feb 20, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

These bullets list threading control (global + domain) and memory-usage statistics, but examples/example.py currently doesn’t call set_num_threads, domain_set_num_threads, peak_mem_usage, or mem_stat. Please align the list with the example, or extend the example to cover the APIs mentioned here.

Suggested change
- **example.py** — basic usage: threading control, version info, 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
- **example.py** — basic usage: version info and timing
## Examples cover
- Querying MKL version and build info
- Basic mkl-service runtime usage
- Timing functions for benchmarking

Copilot uses AI. Check for mistakes.
## Running examples
```bash
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
56 changes: 56 additions & 0 deletions mkl/AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,56 @@
# AGENTS.md — mkl/

Core Python/Cython implementation: MKL support function wrappers and runtime control.

## Structure
- `__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
- `_version.py` — version string (dynamic via setuptools)
- `tests/` — unit tests for API functionality

## API categories
### Threading control
- `set_num_threads(n)` — global thread count
- `get_max_threads()` — max threads available
- `domain_set_num_threads(n, domain)` — per-domain threading (FFT, VML, etc.)
- `domain_get_max_threads(domain)` — domain-specific max threads

### Version information
- `get_version()` — MKL version dict
- `get_version_string()` — formatted version string

### Memory management
- `peak_mem_usage(memtype)` — peak memory usage stats
- `mem_stat()` — memory allocation statistics

### CNR (Conditional Numerical Reproducibility)
- `set_num_threads_local(n)` — thread-local thread count
- CNR mode control functions

### Timing
- `second()` — wall clock time
- `dsecnd()` — high-precision timing

## Development guardrails
- **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`

## 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)

## 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`
Copy link

Copilot AI Feb 20, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This section claims _mklinitmodule.c uses LoadLibrary on Windows, but the implementation only contains a Linux dlopen(..., RTLD_GLOBAL) preload path; Windows DLL handling is instead in _init_helper.py. Please update the platform-specific note to match the code.

Suggested change
- Platform-specific: Windows uses `LoadLibrary`, Linux uses `dlopen`
- Platform-specific: Linux uses `dlopen(..., RTLD_GLOBAL)` preload; Windows DLL handling is in `_init_helper.py`

Copilot uses AI. Check for mistakes.

## Notes
- Domain strings: "fft", "vml", "pardiso", "blas", etc. (see MKL docs)
- Threading changes affect all MKL-using libraries (NumPy, SciPy, etc.)
- `MKL_VERBOSE` environment variable controls MKL diagnostic output
28 changes: 28 additions & 0 deletions mkl/tests/AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
# AGENTS.md — mkl/tests/

Unit tests for MKL runtime control API.

## Test files
- **test_mkl_service.py** — API functionality, threading control, version info

## Test coverage
- Threading: `set_num_threads`, `get_max_threads`, domain-specific threading
- 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
Copy link

Copilot AI Feb 20, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The “Edge cases” bullet lists coverage for invalid domains, negative thread counts, and thread-local settings, but mkl/tests/test_mkl_service.py doesn’t currently include invalid/negative argument tests (and thread-local is already covered separately). Please either add those tests or narrow this bullet to what’s actually exercised.

Suggested change
- Edge cases: invalid domains, negative thread counts, thread-local settings
- Edge cases: thread-local settings

Copilot uses AI. Check for mistakes.

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

## Adding tests
- New API functions → add to `test_mkl_service.py` with validation
- Threading behavior → test thread count changes take effect
- Use `mkl.get_version()` to check MKL availability before tests
Loading