task: agent ready prep by jharlow-intel · Pull Request #280 · IntelPython/mkl_umath

jharlow-intel · 2026-10-07T18:47:02Z

Very similar to IntelPython/mkl_fft#379: adds contributor and coding-agent guidance (CONTRIBUTING.md, AGENTS.md), PR and issue templates, and a README pointer, checked against this repo's build and CI. It also corrects the existing AGENTS.md files.

- CONTRIBUTING.md: use --override-channels, install pre-commit with the pylint and shellcheck its system hooks need, note Windows support and the meson.build GCC/MSVC branches, and match the CHANGELOG link format - AGENTS.md: restore supported platforms, add the meson.build guardrail, and note that checkout tests need the editable install - conda-recipe-cf/AGENTS.md: gnu_thread is Linux-only, llvm-openmp has no run pin, and each recipe has its own conda_build_config.yaml - mkl_umath/src/AGENTS.md: scope the patch lock claim and note per-thread patch/restore balance - .github/AGENTS.md: list the templates and repo config files

napetrov

I checked the docs at 3f8573f against the tree and by running them.

I ran the CONTRIBUTING.md setup verbatim in a clean condaforge/miniforge3 container. Creating the env, the editable install, pytest mkl_umath/tests (392 passed, 1 skipped) and pre-commit run --all-files all pass. A control build without -Dmkl_threading=gnu_thread fails at import with libmkl_intel_thread.so.3: undefined symbol: __atomic_compare_exchange, so the gnu_thread note is right.
I also ran a static check of the paths, commands and identifiers the guidance names. At head it finds no broken references. At base it found the stale mkl_random mentions and the src/__umath_generated.c path, which this PR fixes.
I checked loading with Claude Code 2.1.296. The root AGENTS.md loads from every directory, and each nested one loads once the agent works in its subtree. .github/copilot-instructions.md is never loaded; more on that inline.

A few remaining points are inline. None of them block the PR.

# Conflicts: # AGENTS.md # conda-recipe/AGENTS.md # mkl_umath/tests/AGENTS.md

# Conflicts: # conda-recipe-cf/AGENTS.md # conda-recipe/AGENTS.md

antonwolfy · 2026-10-29T13:29:03Z

+- `generate_umath_doc.py`, `ufunc_docstrings_numpy2.py` — docstring sources
+  adapted from NumPy; the build does not run them


Since #282 the build does run them: meson.build:144-150 generates _umath_doc_generated.h from generate_umath_doc.py, with ufunc_docstrings_numpy2.py in depend_files, and _ufuncs compiles that header (meson.build:201). Suggest something like: "ufunc_docstrings_numpy2.py — the ufunc docstrings, adapted from NumPy; edit them here. generate_umath_doc.py turns them into _umath_doc_generated.h at build time."

Fixed in 3f6872c: ufunc_docstrings_numpy2.py is now the place to edit docstrings, and generate_umath_doc.py turns it into _umath_doc_generated.h at build time.

antonwolfy · 2026-10-29T13:29:03Z

+
+## Development guardrails
+- Preserve NumPy ufunc behavior; patched loops stand in for NumPy's own.
+- Edit the `*.src` templates and `generate_umath.py`, not generated C.


With #282 docstrings are a third edit point: ufunc_docstrings_numpy2.py, which the build turns into _umath_doc_generated.h. The old root file pointed to it and this one doesn't, and "Ufunc extension" at lines 12-13 lists only __umath_generated.c. Suggest "Edit the *.src templates, generate_umath.py and ufunc_docstrings_numpy2.py, not generated C or headers." The same rule is at CONTRIBUTING.md:51.

Done in 3f6872c, in both AGENTS.md and CONTRIBUTING.md; "Ufunc extension" now lists the docstring header too.

antonwolfy · 2026-10-29T13:29:03Z

- **Vectorization:** `-fveclib=SVML -fvectorize` for SIMD (Intel compiler only)
- **Optimization reports:** `-Dopt_report=true` meson option for `-qopt-report=3`
+## Guardrails
+- Edit the `.src` templates, not the generated `.c`/`.h`.


Two of the generated files don't come from .src templates: __umath_generated.c is from generate_umath.py and _umath_doc_generated.h from generate_umath_doc.py. This also differs from the root rule (AGENTS.md:36), which names generate_umath.py. Maybe point to the root rule instead of restating it, so the copies can't drift.

Done in 3f6872c: it now says "edit sources, not generated files" and points to the root AGENTS.md for the edit points.

antonwolfy · 2026-10-29T13:29:03Z

+- Build system: `pyproject.toml` + `meson.build`, with options in `meson.options`
+- Build deps: `mkl-devel`, `numpy`, `meson-python`, `cmake`, `ninja`, `cython`,
+  and a C compiler (CI uses `icx` and `clang`)
+- Runtime deps: `numpy`; the conda recipes add the MKL and compiler runtimes


Since #289 it's NumPy 2 only: numpy >=2 in pyproject.toml, and the NumPy 1 code paths are gone. Worth saying, so an agent doesn't add a NumPy 1 fallback: "Runtime deps: numpy, NumPy 2 only (see pyproject.toml); ..."

Added in 3f6872c: "Runtime deps: numpy, NumPy 2 only (see pyproject.toml)".

antonwolfy · 2026-10-29T13:29:03Z

+- Setup, checks, and style: `CONTRIBUTING.md`
+- Single test: `pytest mkl_umath/tests/<file>.py::<test>`, from a checkout with the
+  editable install in `CONTRIBUTING.md`
+- Single-file lint: `pre-commit run --files <path>`


This fails on main too: no-commit-to-branch has always_run: true and pass_filenames: false, so it runs no matter which files you pass. Suggest adding "(from a branch, see CONTRIBUTING.md)".

Added in 3f6872c: "…, from a branch (see CONTRIBUTING.md)".

antonwolfy · 2026-10-29T13:29:04Z

+  functions from `_patch_numpy`
+- `_init_helper.py` — imported first by `__init__.py`; in a Windows venv, adds
+  `Library/bin` to the DLL search path so the extensions can load
+- `generate_umath.py` — generates `__umath_generated.c` in the build directory


An "adding a ufunc" note would help, since these hand-kept lists must change together: the defdict entry in generate_umath.py, the loop and its declaration in src/mkl_umath_loops.{c,h}.src, the docstring in ufunc_docstrings_numpy2.py, and the import and __all__ in __init__.py.

Added in 3f6872c: an "adding a ufunc" guardrail listing the defdict entry, the loop and its declaration in the .src templates, the docstring, and the __init__.py import and __all__.

antonwolfy · 2026-10-29T13:29:04Z

+so the suite itself is under `benchmarks/benchmarks/`.
+
+## Scope
+- `asv.conf.json` — ASV configuration, channels, and regression thresholds


Worth saying where to run asv: asv.conf.json is here, so from the repo root asv doesn't find a config, and README.md doesn't say to cd benchmarks. Also, environment_type is conda, so without --python=same (as in the README commands) asv builds conda envs. requirements.txt is missing from this list too.

Added in 3f6872c: run asv from benchmarks/ with --python=same, and requirements.txt is now in the Scope list.

antonwolfy · 2026-10-29T13:29:04Z

+CC=icx pip install -e . --no-build-isolation --no-deps \
+    -Csetup-args=-Dmkl_threading=gnu_thread
+```


Worth noting that the editable install rebuilds on import after a change to .c, .src or .pyx sources, so pytest and python need mkl_umath-dev active, with icx and ninja on PATH.

Added in 3f6872c.

antonwolfy · 2026-10-29T13:29:04Z

- `openssf-scorecard.yml` — security scanning
+- `coverity.yml` — Coverity static analysis (see `coverity/README.md`)
+- `openssf-scorecard.yml` — OpenSSF Scorecard
+- `zizmor.yml` — GitHub Actions security lint


The Policy section could list the conventions for editing workflows, which every workflow here already follows and zizmor checks: pin each action to a full commit SHA with a # vX.Y.Z comment, set least-privilege permissions, and use persist-credentials: false on checkouts.

Added in 3f6872c.

antonwolfy · 2026-10-29T13:29:04Z

+- Public API: `mkl_umath/__init__.py`, `mkl_umath/src/_patch_numpy.pyx`
+- Tests: `mkl_umath/tests/`
+
+For behavior policy, see `.github/copilot-instructions.md`.


Following up on the earlier thread on copilot-instructions.md:22: four rules are still only in copilot-instructions.md, which Claude Code doesn't load. They are: never invent versions, compilers or CI values (:30), no hardcoded ISA assumptions (:33), no secrets in code or docs (:34), and performance must not compromise correctness (:47). That file also calls itself canonical (:8), while most guardrails now live here. Suggest moving those four into the guardrails above, so this file is the one list.

Done in 3f6872c: all four are now in the root AGENTS.md guardrails.

jharlow-intel requested review from antonwolfy, ndgrigorian, vlad-perevezentsev and xaleryb as code owners October 7, 2026 18:47

task: agent ready prep

823e526

jharlow-intel force-pushed the task/agent-ready branch from c80b57b to 823e526 Compare October 7, 2026 18:52

task: clean up CONTRIBUTING.md

9cefba6

antonwolfy reviewed Oct 13, 2026

View reviewed changes

jharlow-intel requested a review from antonwolfy October 13, 2026 19:00

napetrov reviewed Oct 13, 2026

View reviewed changes

Comment thread CONTRIBUTING.md

Comment thread conda-recipe/AGENTS.md Outdated

Comment thread AGENTS.md Outdated

Comment thread .github/copilot-instructions.md

antonwolfy reviewed Oct 14, 2026

View reviewed changes

antonwolfy added this to the 0.7.0 release milestone Oct 15, 2026

jharlow-intel and others added 4 commits October 16, 2026 11:27

Merge remote-tracking branch 'origin/main' into task/agent-ready

67f65c0

# Conflicts: # AGENTS.md # conda-recipe/AGENTS.md # mkl_umath/tests/AGENTS.md

task: address second review round on agent docs

0d3f956

Merge branch 'main' into task/agent-ready

ec65659

Merge branch 'main' into task/agent-ready

27d9109

antonwolfy reviewed Oct 20, 2026

View reviewed changes

Comment thread benchmarks/AGENTS.md

Comment thread mkl_umath/AGENTS.md Outdated

Comment thread AGENTS.md Outdated

Comment thread CONTRIBUTING.md

jharlow-intel added 2 commits October 28, 2026 10:46

Merge remote-tracking branch 'origin/main' into task/agent-ready

781390f

# Conflicts: # conda-recipe-cf/AGENTS.md # conda-recipe/AGENTS.md

task: address third review round on agent docs

4aed2ad

jharlow-intel self-assigned this Oct 28, 2026

jharlow-intel requested review from antonwolfy and napetrov October 28, 2026 18:31

Merge branch 'main' into task/agent-ready

1c36162

antonwolfy reviewed Oct 29, 2026

View reviewed changes

task: address fourth review round on agent docs

3f6872c

jharlow-intel requested a review from antonwolfy October 29, 2026 16:30

		- `generate_umath_doc.py`, `ufunc_docstrings_numpy2.py` — docstring sources
		adapted from NumPy; the build does not run them

Conversation

jharlow-intel commented Oct 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

napetrov left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

jharlow-intel commented Oct 7, 2026 •

edited

Loading