From 8254a04ba669706139968300743904ba74109bdd Mon Sep 17 00:00:00 2001 From: Nikolay Petrov Date: Thu, 19 Feb 2026 20:55:02 +0000 Subject: [PATCH 1/3] docs: enhance AGENTS with project context and performance guardrails Based on multi-agent review (architect, pragmatist, prompt-specialist, perf-expert): Root AGENTS.md: - Add project description, tech stack (C++20, MKL, OpenMP, pybind11) - Add core principle: performance over simplicity - Add quick start commands (build/test/Python) - Add directory map .github/copilot-instructions.md: - Add concrete authoring rules (no full-file refactors for 2-line changes) - Add contribution expectations (backward compat, pre-commit, regression tests) - Expand source-of-truth: explicitly list mkl.cmake, multi-arch.cmake, numa.cmake, pyproject.toml - Add negative constraint: no std::iostream in perf-critical headers include/svs/AGENTS.md: - Add performance-critical constraints: memory alignment, SIMD dispatch, hot path rules - Add failure modes: template instantiation impact, ABI compat bindings/python/AGENTS.md: - Add pybind11 integration rules: GIL release, type validation, memory ownership - Add common failure modes: wrapper sync, edge case testing, lifetime management - Explicitly list source-of-truth files cmake/AGENTS.md: - Add Intel-specific module docs: mkl.cmake (threading), multi-arch.cmake (ISA dispatch), numa.cmake, openmp.cmake - Add guardrails: no flag removal without benchmark validation benchmark/AGENTS.md: - Add constraints: warmup/iteration stability, dataset provenance, baseline comparisons - Add reporting requirements: median/min/max/stddev include/svs/quantization/AGENTS.md (new): - Add quantization guardrails: type safety, precision bounds, SIMD alignment, codec compat - Add common failure modes: float in hot paths, misaligned access, codebook sync --- .github/copilot-instructions.md | 24 ++++++++++++++-------- AGENTS.md | 32 ++++++++++++++++++++++-------- benchmark/AGENTS.md | 6 ++++++ bindings/python/AGENTS.md | 12 ++++++++++- cmake/AGENTS.md | 12 ++++++++++- include/svs/AGENTS.md | 12 ++++++++++- include/svs/quantization/AGENTS.md | 13 ++++++++++++ 7 files changed, 92 insertions(+), 19 deletions(-) create mode 100644 include/svs/quantization/AGENTS.md diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 8a7cc3acc..707496026 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -3,21 +3,29 @@ This file is the canonical instruction set for Copilot behavior in this repository (required flow, precedence, and fallback rules). -`AGENTS.md` is reserved for AGENTS-aware tooling context and should not duplicate -Copilot policy text. +`AGENTS.md` provides project context and tech stack overview. ## Mandatory -1. Read root `AGENTS.md` first. +1. Read root `AGENTS.md` for project context. 2. Read the nearest directory `AGENTS.md` for edited files. 3. If multiple apply, use the most specific. ## Authoring rules -- Keep suggestions minimal and scoped. +- Keep suggestions minimal and scoped (do not refactor entire files for 2-line changes). - Use source-of-truth files for mutable details. - Do not invent or hardcode versions/flags/matrices. +- Avoid `std::iostream` in performance-critical headers. + +## Contribution expectations +- Preserve backward compatibility for public API (`include/svs/`) +- Prefer additive API evolution (avoid duplication of existing functionality) +- Pair public API changes with tests and documentation +- For bug fixes: add regression tests +- Run `pre-commit run --all-files` before proposing changes ## Source-of-truth files -- `CMakeLists.txt`, `cmake/*.cmake` -- `.github/workflows/` -- `.clang-format`, `.pre-commit-config.yaml` -- `include/svs/`, `bindings/python/` +- Build: `CMakeLists.txt`, `cmake/*.cmake` (incl. `cmake/mkl.cmake`, `cmake/multi-arch.cmake`, `cmake/numa.cmake`) +- Dependencies: `bindings/python/pyproject.toml`, `bindings/python/setup.py` +- CI: `.github/workflows/` +- Style: `.clang-format`, `.pre-commit-config.yaml` +- API: `include/svs/`, `bindings/python/` diff --git a/AGENTS.md b/AGENTS.md index 7d556c957..9b440a23b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,12 +1,28 @@ -# AGENTS.md +# AGENTS.md — ScalableVectorSearch -This file is for AGENTS-aware tools. +## What this project is +High-performance C++ library for vector similarity search at billion scale. Uses Intel MKL, AVX-512/multi-arch SIMD dispatch, LVQ quantization, NUMA-aware memory, OpenMP threading. Python bindings via pybind11. Archetype: **C++** (with Python bindings). -Scope: -- Tool-specific guidance for AGENTS-aware agents. -- Repository context that is not Copilot-specific. +Tech stack: C++20, Intel MKL, OpenMP, pybind11, CMake. +Core principle: **Performance over simplicity** in hot paths. -For Copilot policy (required flow, source-of-truth, fallback rules), see: -- `.github/copilot-instructions.md` (canonical for Copilot behavior) +## How to work +- Backward compatibility is default for public API (`include/svs/`) +- Performance-critical: avoid allocations in hot loops, respect memory alignment +- For SIMD dispatch changes: consult `cmake/multi-arch.cmake` and `include/svs/multi-arch/` +- Python bindings: update `bindings/python/` and ensure GIL release for blocking MKL calls -Do not duplicate Copilot policy here. +## Quick start +Build: `cmake -B build && cmake --build build` +Test: `ctest --test-dir build` +Python: `pip install -e bindings/python/` + +## Directory AGENTS files +- `.github/AGENTS.md` — CI/CD +- `benchmark/AGENTS.md` — performance benchmarks +- `bindings/AGENTS.md` — C++/Python bindings (router) +- `cmake/AGENTS.md` — build system +- `include/svs/AGENTS.md` — public C++ API +- `tests/AGENTS.md` — test suite + +For Copilot/agent behavior policy: `.github/copilot-instructions.md` diff --git a/benchmark/AGENTS.md b/benchmark/AGENTS.md index cc04677f0..f7f64e8ff 100644 --- a/benchmark/AGENTS.md +++ b/benchmark/AGENTS.md @@ -5,3 +5,9 @@ Benchmark harness and performance-eval code. - Keep runs reproducible (inputs/config in repo). - Separate harness changes from algorithm changes when possible. - If shared with tests, validate impacted test targets. + +## Performance benchmarking constraints +- **Warmup and iterations:** Do not change warmup rounds or iteration counts without justification. These values are tuned for CI stability. +- **Input datasets:** Use fixed seeds and document dataset provenance. Do not commit large binary datasets without approval. +- **Baseline comparisons:** When adding new benchmarks, provide baseline comparisons against existing algorithms. +- **Reporting:** Report median, min, max, stddev — not just mean. Flag outliers and variance sources (e.g., NUMA effects, Turbo Boost). diff --git a/bindings/python/AGENTS.md b/bindings/python/AGENTS.md index c44f36205..8a0d0d560 100644 --- a/bindings/python/AGENTS.md +++ b/bindings/python/AGENTS.md @@ -2,7 +2,17 @@ Python package, extension bindings, and Python-facing behavior. -- Source of truth: files under `bindings/python/` (+ cross-check with `CMakeLists.txt`). +- Source of truth: `bindings/python/pyproject.toml`, `setup.py`, `CMakeLists.txt`. - Keep API compatibility by default. - Preserve clear dtype/shape validation and error messages. - Add tests for every user-visible behavior change. + +## pybind11 integration +- **GIL release:** For blocking MKL calls or long-running C++ operations, release GIL with `py::call_guard()`. +- **Type validation:** Explicitly validate NumPy dtypes (float32, float64, uint8 for quantized) and shapes before passing to C++. +- **Memory ownership:** Document lifetime expectations for array views vs copies in docstrings. + +## Common failure modes +- Forgetting to update pybind11 wrappers when C++ signatures change in `include/svs/`. +- Not testing edge cases: empty arrays, mismatched dtypes, out-of-bounds indices. +- Returning raw pointers without proper lifetime management — use `py::return_value_policy`. diff --git a/cmake/AGENTS.md b/cmake/AGENTS.md index 71a5fb3a2..f6f81aecb 100644 --- a/cmake/AGENTS.md +++ b/cmake/AGENTS.md @@ -5,4 +5,14 @@ Build modules, dependency wiring, and feature toggles. - `CMakeLists.txt` + `cmake/*.cmake` are authoritative. - Keep option names/defaults stable unless task requires change. - Prefer additive options over rewrites. -- Validate option/target changes against CI workflows. +- Validate option/target changes against CI workflows (`.github/workflows/`). + +## Intel-specific modules +- **`cmake/mkl.cmake`:** MKL linkage (static vs dynamic threading). Do not hardcode MKL versions. When changing linkage mode, validate threading behavior in tests. +- **`cmake/multi-arch.cmake`:** AVX-512 / SIMD ISA dispatch. Do not hardcode `-march` or ISA flags outside this file. Changes must align with `include/svs/multi-arch/` runtime dispatch code. +- **`cmake/numa.cmake`:** NUMA-aware memory allocation. Respect NUMA topology assumptions in performance-critical code. +- **`cmake/openmp.cmake`:** Threading model. Do not assume specific OpenMP version or runtime without checking source-of-truth. + +## Guardrails +- Do not remove optimization flags without justification and benchmark validation. +- Keep CMake minimum version conservative unless a new feature is required across all CI targets. diff --git a/include/svs/AGENTS.md b/include/svs/AGENTS.md index 36664a20c..42f77ef3b 100644 --- a/include/svs/AGENTS.md +++ b/include/svs/AGENTS.md @@ -3,6 +3,16 @@ Public C++ headers and API contracts. - Backward compatibility is default. -- Prefer additive API evolution. +- Prefer additive API evolution (avoid duplicating existing functionality). - Keep headers self-contained and aligned with CMake C++ standard. - Pair public API changes with tests and docs. + +## Performance-critical constraints +- **Memory alignment:** Respect alignment requirements for SIMD operations (use SVS-specific allocators). +- **SIMD dispatch:** Changes to `include/svs/multi-arch/` must align with `cmake/multi-arch.cmake` ISA dispatch logic. +- **Hot paths:** Avoid heap allocations, virtual calls, and `std::iostream` in performance-critical code. +- **MKL integration:** Do not hardcode MKL versions or assume threading model; check `cmake/mkl.cmake`. + +## Failure modes to avoid +- Adding template instantiations without checking compile-time impact. +- Changing header-only code without validating ABI compatibility. diff --git a/include/svs/quantization/AGENTS.md b/include/svs/quantization/AGENTS.md new file mode 100644 index 000000000..e08f20ec2 --- /dev/null +++ b/include/svs/quantization/AGENTS.md @@ -0,0 +1,13 @@ +# AGENTS.md — include/svs/quantization/ + +Quantization algorithms and data types (LVQ, scalar quantization). + +- **Type safety:** Explicitly validate quantized dtype (uint8, int8, uint16) before operations. +- **Precision:** Changes to quantization schemes must preserve reconstruction error bounds. Document expected accuracy impact. +- **SIMD alignment:** Quantized data structures must respect SIMD lane widths (16/32/64 bytes for AVX-512). +- **Codec compatibility:** Do not break serialization format without versioning and migration path. + +## Common failure modes +- Using `float` arithmetic in quantization hot paths (use integer SIMD intrinsics). +- Misaligned memory access in quantized vector loads/stores. +- Forgetting to update codebook when changing quantization levels. From a930693a60dea4aea425fbdc0aafbd4c36dd0272 Mon Sep 17 00:00:00 2001 From: Nikolay Petrov Date: Fri, 20 Feb 2026 21:55:15 -0800 Subject: [PATCH 2/3] Update AGENTS.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Mihai Capotă --- AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 9b440a23b..d596fc030 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,7 +1,7 @@ # AGENTS.md — ScalableVectorSearch ## What this project is -High-performance C++ library for vector similarity search at billion scale. Uses Intel MKL, AVX-512/multi-arch SIMD dispatch, LVQ quantization, NUMA-aware memory, OpenMP threading. Python bindings via pybind11. Archetype: **C++** (with Python bindings). +High-performance C++ library for vector similarity search at billion scale. Uses Intel MKL, AVX-512/multi-arch SIMD dispatch, quantization, NUMA-aware memory, OpenMP threading. Python bindings via pybind11. Archetype: **C++** (with Python bindings). Tech stack: C++20, Intel MKL, OpenMP, pybind11, CMake. Core principle: **Performance over simplicity** in hot paths. From 2d1e3945bde301193a10d7f195b5f6536120c461 Mon Sep 17 00:00:00 2001 From: Nikolay Petrov Date: Fri, 20 Feb 2026 21:55:22 -0800 Subject: [PATCH 3/3] Update include/svs/quantization/AGENTS.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Mihai Capotă --- include/svs/quantization/AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/include/svs/quantization/AGENTS.md b/include/svs/quantization/AGENTS.md index e08f20ec2..9db948fec 100644 --- a/include/svs/quantization/AGENTS.md +++ b/include/svs/quantization/AGENTS.md @@ -1,6 +1,6 @@ # AGENTS.md — include/svs/quantization/ -Quantization algorithms and data types (LVQ, scalar quantization). +Quantization algorithms and data types (scalar quantization). - **Type safety:** Explicitly validate quantized dtype (uint8, int8, uint16) before operations. - **Precision:** Changes to quantization schemes must preserve reconstruction error bounds. Document expected accuracy impact.