feat(python): ship .pyi type stubs + document subset-rerank result cap#209
feat(python): ship .pyi type stubs + document subset-rerank result cap#209Fieldnote-Echo wants to merge 2 commits into
Conversation
The abi3 native module (_ordvec) carries no embedded type information, so downstream users got no IDE hints / mypy coverage. Add a hand-written _ordvec.pyi mirroring the exact PyO3 surface (Rank/RankQuant/Bitmap/SignBitmap classes, the module-level rank-math primitives, the byte-LUT / eval scorers, and the MAX_* loader constants) plus a py.typed marker. maturin packages both files automatically from python-source — no pyproject changes needed. Verified with mypy.stubtest (no invented or missing members) and mypy --strict on the re-exporting package. Hand-written route chosen to avoid a new build dependency (the pyo3-stub-gen alternative needs sign-off). Closes #32 Signed-off-by: Nelson Spence <nelson@projectnavi.ai>
…)) cap search_asymmetric_subset returns (scores, ids) of length min(k, len(candidates)), not k: passing k > len(candidates) yields arrays shorter than k (the subset path never pads with sentinel rows). Make this explicit in the method docstring, the package docstring, and a new README 'Two-stage retrieval' section so callers building fixed-width (n_q, k) buffers don't assume k rows back. The contract itself is unchanged (covered by test_search_asymmetric_subset_k_caps_at_candidate_count) — docs only. The README also gains a Type stubs note for the .pyi shipped alongside. Closes #14 Signed-off-by: Nelson Spence <nelson@projectnavi.ai>
Codecov Report✅ All modified and coverable lines are covered by tests. 📢 Thoughts on this report? Let us know! |
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request introduces hand-written type stubs (_ordvec.pyi) and a py.typed marker for the ordvec Python package to enable static analysis and autocompletion. Additionally, it updates the documentation in the README, __init__.py, and Rust source code (lib.rs) to clarify the behavior of RankQuant.search_asymmetric_subset, specifically noting that the returned arrays are sized to min(k, len(candidates)) and do not pad with sentinel rows when k > len(candidates). There are no review comments, so no feedback is provided.
Important
The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.
1 participant
ordvec-python: type stubs + subset-rerank result-cap doc
_ordvec.pyicovering the current public surface (4 classes + 11 free functions + 3 constants,@final) plus apy.typedmarker; maturin auto-includes both in the wheel (verified).mypy.stubtestreports a 1:1 match (no invented methods);mypy --strictclean.RankQuant.search_asymmetric_subsetreturnsmin(k, len(candidates))results (method docstring + package doc + README).Scope:
ordvec-python/only; no core-crate changes, no bindings for unmerged APIs (stubs the current surface).Gate:
cargo fmt -p ordvec-python --check,cargo clippy -p ordvec-python --all-targets -- -D warnings,maturin develop, 510 pytest pass.Closes #32. Closes #14.
🤖 Generated with Claude Code