pyvectorhound 1.4.0__tar.gz → 1.6.1__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (108) hide show
  1. pyvectorhound-1.6.1/.github/dependabot.yml +58 -0
  2. pyvectorhound-1.6.1/.github/pull_request_template.md +23 -0
  3. {pyvectorhound-1.4.0 → pyvectorhound-1.6.1}/.github/workflows/ci.yml +3 -3
  4. {pyvectorhound-1.4.0 → pyvectorhound-1.6.1}/.gitignore +6 -1
  5. pyvectorhound-1.6.1/.graphifyignore +31 -0
  6. pyvectorhound-1.6.1/AUDIT.md +115 -0
  7. {pyvectorhound-1.4.0 → pyvectorhound-1.6.1}/CHANGELOG.md +112 -11
  8. pyvectorhound-1.6.1/CONTRIBUTING.md +209 -0
  9. {pyvectorhound-1.4.0 → pyvectorhound-1.6.1}/Cargo.lock +3 -3
  10. {pyvectorhound-1.4.0 → pyvectorhound-1.6.1}/Cargo.toml +2 -2
  11. {pyvectorhound-1.4.0 → pyvectorhound-1.6.1}/DEPLOYMENT.md +13 -0
  12. pyvectorhound-1.6.1/LICENSE +202 -0
  13. {pyvectorhound-1.4.0 → pyvectorhound-1.6.1}/OKF_INTEGRATION.md +9 -2
  14. pyvectorhound-1.6.1/PKG-INFO +421 -0
  15. pyvectorhound-1.6.1/README.md +360 -0
  16. pyvectorhound-1.6.1/ROADMAP_HONEST.md +265 -0
  17. pyvectorhound-1.6.1/SECURITY.md +77 -0
  18. pyvectorhound-1.6.1/TECHNICAL_DEBT.md +42 -0
  19. pyvectorhound-1.6.1/docs/ARCHITECTURE.md +119 -0
  20. {pyvectorhound-1.4.0 → pyvectorhound-1.6.1}/docs/GUIDE.md +11 -9
  21. {pyvectorhound-1.4.0 → pyvectorhound-1.6.1}/pyproject.toml +12 -7
  22. {pyvectorhound-1.4.0 → pyvectorhound-1.6.1}/pyvectorhound/__init__.py +5 -2
  23. {pyvectorhound-1.4.0 → pyvectorhound-1.6.1}/pyvectorhound/database.py +13 -1
  24. {pyvectorhound-1.4.0 → pyvectorhound-1.6.1}/pyvectorhound/diagnosis.py +1 -1
  25. {pyvectorhound-1.4.0 → pyvectorhound-1.6.1}/pyvectorhound/error_messages.py +1 -0
  26. {pyvectorhound-1.4.0 → pyvectorhound-1.6.1}/pyvectorhound/hound.py +3 -3
  27. pyvectorhound-1.6.1/pyvectorhound/ranking.py +93 -0
  28. {pyvectorhound-1.4.0 → pyvectorhound-1.6.1}/pyvectorhound/web_dashboard.py +1 -1
  29. pyvectorhound-1.6.1/src/lib.rs +296 -0
  30. {pyvectorhound-1.4.0 → pyvectorhound-1.6.1}/src/metrics.rs +1 -1
  31. pyvectorhound-1.6.1/src/quantization.rs +300 -0
  32. {pyvectorhound-1.4.0 → pyvectorhound-1.6.1}/src/retrieval_ranking.rs +182 -11
  33. pyvectorhound-1.6.1/tests/test_ranking.py +98 -0
  34. pyvectorhound-1.6.1/tools/graphify/README.md +63 -0
  35. pyvectorhound-1.6.1/tools/graphify/graphify_adapter.py +242 -0
  36. pyvectorhound-1.4.0/.github/dependabot.yml +0 -35
  37. pyvectorhound-1.4.0/ARCHITECTURE.md +0 -249
  38. pyvectorhound-1.4.0/CONTRIBUTING.md +0 -187
  39. pyvectorhound-1.4.0/DASHBOARD_SHORTCUTS.md +0 -161
  40. pyvectorhound-1.4.0/LICENSE +0 -22
  41. pyvectorhound-1.4.0/OTEL_SETUP_GUIDE.md +0 -319
  42. pyvectorhound-1.4.0/PKG-INFO +0 -356
  43. pyvectorhound-1.4.0/PRODUCTION_DEPLOYMENT.md +0 -512
  44. pyvectorhound-1.4.0/README.md +0 -294
  45. pyvectorhound-1.4.0/SECURITY.md +0 -56
  46. pyvectorhound-1.4.0/docs/ARCHITECTURE.md +0 -185
  47. pyvectorhound-1.4.0/docs/PRODUCT_VISION.md +0 -95
  48. pyvectorhound-1.4.0/docs/ROADMAP.md +0 -197
  49. pyvectorhound-1.4.0/docs/strategy/PYHOUND_FINAL_STATUS.md +0 -417
  50. pyvectorhound-1.4.0/docs/strategy/PyHound_COMPETITIVE_ROADMAP.md +0 -428
  51. pyvectorhound-1.4.0/docs/strategy/PyHound_FINAL_PRODUCT.md +0 -377
  52. pyvectorhound-1.4.0/docs/strategy/PyHound_GITHUB_LAUNCH.md +0 -289
  53. pyvectorhound-1.4.0/docs/strategy/PyHound_LAUNCH_CHECKLIST.md +0 -342
  54. pyvectorhound-1.4.0/docs/strategy/PyHound_UNIFICATION_STRATEGY.md +0 -624
  55. pyvectorhound-1.4.0/docs/strategy/PyHound_vs_Observability.md +0 -184
  56. pyvectorhound-1.4.0/otel_exporter.py +0 -189
  57. pyvectorhound-1.4.0/scripts/test_dashboards_crossplatform.sh +0 -208
  58. pyvectorhound-1.4.0/src/lib.rs +0 -91
  59. {pyvectorhound-1.4.0 → pyvectorhound-1.6.1}/.github/ISSUE_TEMPLATE/bug_report.md +0 -0
  60. {pyvectorhound-1.4.0 → pyvectorhound-1.6.1}/.github/ISSUE_TEMPLATE/feature_request.md +0 -0
  61. {pyvectorhound-1.4.0 → pyvectorhound-1.6.1}/.pre-commit-config.yaml +0 -0
  62. {pyvectorhound-1.4.0 → pyvectorhound-1.6.1}/CODE_OF_CONDUCT.md +0 -0
  63. {pyvectorhound-1.4.0 → pyvectorhound-1.6.1}/Makefile +0 -0
  64. {pyvectorhound-1.4.0 → pyvectorhound-1.6.1}/USER_GUIDE.md +0 -0
  65. {pyvectorhound-1.4.0 → pyvectorhound-1.6.1}/examples/benchmarking_and_trends.py +0 -0
  66. {pyvectorhound-1.4.0 → pyvectorhound-1.6.1}/examples/mcp_pyvectorhound.py +0 -0
  67. {pyvectorhound-1.4.0 → pyvectorhound-1.6.1}/examples/retrieval_debug.py +0 -0
  68. {pyvectorhound-1.4.0 → pyvectorhound-1.6.1}/install.sh +0 -0
  69. {pyvectorhound-1.4.0 → pyvectorhound-1.6.1}/pyvectorhound/_mcp_connector.py +0 -0
  70. {pyvectorhound-1.4.0 → pyvectorhound-1.6.1}/pyvectorhound/_mcp_tools.py +0 -0
  71. {pyvectorhound-1.4.0 → pyvectorhound-1.6.1}/pyvectorhound/_retry.py +0 -0
  72. {pyvectorhound-1.4.0 → pyvectorhound-1.6.1}/pyvectorhound/_safe_exec.py +0 -0
  73. {pyvectorhound-1.4.0 → pyvectorhound-1.6.1}/pyvectorhound/advanced_analytics.py +0 -0
  74. {pyvectorhound-1.4.0 → pyvectorhound-1.6.1}/pyvectorhound/backends.py +0 -0
  75. {pyvectorhound-1.4.0 → pyvectorhound-1.6.1}/pyvectorhound/benchmarking.py +0 -0
  76. {pyvectorhound-1.4.0 → pyvectorhound-1.6.1}/pyvectorhound/cli.py +0 -0
  77. {pyvectorhound-1.4.0 → pyvectorhound-1.6.1}/pyvectorhound/comparison.py +0 -0
  78. {pyvectorhound-1.4.0 → pyvectorhound-1.6.1}/pyvectorhound/db_adapters.py +0 -0
  79. {pyvectorhound-1.4.0 → pyvectorhound-1.6.1}/pyvectorhound/errors.py +0 -0
  80. {pyvectorhound-1.4.0 → pyvectorhound-1.6.1}/pyvectorhound/langchain_integration.py +0 -0
  81. {pyvectorhound-1.4.0 → pyvectorhound-1.6.1}/pyvectorhound/llamaindex_integration.py +0 -0
  82. {pyvectorhound-1.4.0 → pyvectorhound-1.6.1}/pyvectorhound/logging_config.py +0 -0
  83. {pyvectorhound-1.4.0 → pyvectorhound-1.6.1}/pyvectorhound/okf_diagnostics.py +0 -0
  84. {pyvectorhound-1.4.0 → pyvectorhound-1.6.1}/pyvectorhound/otel_integration.py +0 -0
  85. {pyvectorhound-1.4.0 → pyvectorhound-1.6.1}/pyvectorhound/py.typed +0 -0
  86. {pyvectorhound-1.4.0 → pyvectorhound-1.6.1}/pyvectorhound/recommendations.py +0 -0
  87. {pyvectorhound-1.4.0 → pyvectorhound-1.6.1}/pyvectorhound/retrieval_replay.py +0 -0
  88. {pyvectorhound-1.4.0 → pyvectorhound-1.6.1}/pyvectorhound/retrieval_tracing.py +0 -0
  89. {pyvectorhound-1.4.0 → pyvectorhound-1.6.1}/pyvectorhound/scorer.py +0 -0
  90. {pyvectorhound-1.4.0 → pyvectorhound-1.6.1}/pyvectorhound/scripts/__init__.py +0 -0
  91. {pyvectorhound-1.4.0 → pyvectorhound-1.6.1}/pyvectorhound/scripts/post_install.py +0 -0
  92. {pyvectorhound-1.4.0 → pyvectorhound-1.6.1}/pyvectorhound/scripts/setup_shortcuts.sh +0 -0
  93. {pyvectorhound-1.4.0 → pyvectorhound-1.6.1}/pyvectorhound/server.py +0 -0
  94. {pyvectorhound-1.4.0 → pyvectorhound-1.6.1}/pyvectorhound/trend_analysis.py +0 -0
  95. {pyvectorhound-1.4.0 → pyvectorhound-1.6.1}/pyvectorhound/validation.py +0 -0
  96. {pyvectorhound-1.4.0 → pyvectorhound-1.6.1}/pyvectorhound.toml +0 -0
  97. {pyvectorhound-1.4.0 → pyvectorhound-1.6.1}/rust-toolchain.toml +0 -0
  98. {pyvectorhound-1.4.0 → pyvectorhound-1.6.1}/scripts/setup_shortcuts.sh +0 -0
  99. {pyvectorhound-1.4.0 → pyvectorhound-1.6.1}/tests/test_benchmarking.py +0 -0
  100. {pyvectorhound-1.4.0 → pyvectorhound-1.6.1}/tests/test_database_adapters.py +0 -0
  101. {pyvectorhound-1.4.0 → pyvectorhound-1.6.1}/tests/test_diagnosis.py +0 -0
  102. {pyvectorhound-1.4.0 → pyvectorhound-1.6.1}/tests/test_hound.py +0 -0
  103. {pyvectorhound-1.4.0 → pyvectorhound-1.6.1}/tests/test_okf_diagnostics.py +0 -0
  104. {pyvectorhound-1.4.0 → pyvectorhound-1.6.1}/tests/test_recommendations.py +0 -0
  105. {pyvectorhound-1.4.0 → pyvectorhound-1.6.1}/tests/test_retrieval_replay.py +0 -0
  106. {pyvectorhound-1.4.0 → pyvectorhound-1.6.1}/tests/test_scorer.py +0 -0
  107. {pyvectorhound-1.4.0 → pyvectorhound-1.6.1}/tests/test_trend_analysis.py +0 -0
  108. {pyvectorhound-1.4.0 → pyvectorhound-1.6.1}/tests/test_v05_integrations.py +0 -0
@@ -0,0 +1,58 @@
1
+ version: 2
2
+ updates:
3
+ # Python dependencies (pip/pyproject.toml)
4
+ - package-ecosystem: "pip"
5
+ directory: "/"
6
+ schedule:
7
+ interval: "weekly"
8
+ day: "monday"
9
+ time: "03:00"
10
+ open-pull-requests-limit: 5
11
+ reviewers:
12
+ - "Mullassery"
13
+ labels:
14
+ - "dependencies"
15
+ - "python"
16
+ commit-message:
17
+ prefix: "chore(deps):"
18
+ include: "scope"
19
+
20
+ # Rust dependencies (Cargo.toml) -- note: pyo3/numpy are pinned to "0.23"
21
+ # in Cargo.toml, which under Cargo's default caret semantics for 0.x
22
+ # crates only allows patch updates (>=0.23.0, <0.24.0). Dependabot can
23
+ # still open PRs against that ceiling (e.g. the pyo3-0.29/numpy-0.29
24
+ # branches already on this remote), but merging them requires bumping
25
+ # the Cargo.toml version bound by hand and validating the PyO3 API
26
+ # migration -- not something Dependabot does automatically.
27
+ - package-ecosystem: "cargo"
28
+ directory: "/"
29
+ schedule:
30
+ interval: "weekly"
31
+ day: "monday"
32
+ time: "03:00"
33
+ open-pull-requests-limit: 3
34
+ reviewers:
35
+ - "Mullassery"
36
+ labels:
37
+ - "dependencies"
38
+ - "rust"
39
+ commit-message:
40
+ prefix: "chore(deps):"
41
+ include: "scope"
42
+
43
+ # GitHub Actions
44
+ - package-ecosystem: "github-actions"
45
+ directory: "/"
46
+ schedule:
47
+ interval: "weekly"
48
+ day: "monday"
49
+ time: "03:00"
50
+ open-pull-requests-limit: 3
51
+ reviewers:
52
+ - "Mullassery"
53
+ labels:
54
+ - "dependencies"
55
+ - "ci"
56
+ commit-message:
57
+ prefix: "chore(ci):"
58
+ include: "scope"
@@ -0,0 +1,23 @@
1
+ ## What does this PR do?
2
+
3
+ <!-- One or two sentences. -->
4
+
5
+ ## Why?
6
+
7
+ <!-- What problem does this solve, or what does it enable? -->
8
+
9
+ ## How was this tested?
10
+
11
+ <!-- Real commands and real output, not "should work". E.g.:
12
+ - `cargo test --release --all-features`
13
+ - `pytest tests/ -v`
14
+ -->
15
+
16
+ ## Checklist
17
+
18
+ - [ ] Tests added/updated for the change (or explained why not needed)
19
+ - [ ] `cargo test --release --all-features` passes (if Rust code changed)
20
+ - [ ] `pytest tests/` passes (if Python code changed)
21
+ - [ ] `CHANGELOG.md` updated under `[Unreleased]`
22
+ - [ ] Docs updated if behavior or public API changed
23
+ - [ ] No new hardcoded secrets/credentials
@@ -11,7 +11,7 @@ jobs:
11
11
  name: Rust Build & Test
12
12
  runs-on: ubuntu-latest
13
13
  steps:
14
- - uses: actions/checkout@v4
14
+ - uses: actions/checkout@v7
15
15
 
16
16
  - uses: dtolnay/rust-toolchain@stable
17
17
 
@@ -30,13 +30,13 @@ jobs:
30
30
  matrix:
31
31
  python-version: ["3.9", "3.10", "3.11", "3.12"]
32
32
  steps:
33
- - uses: actions/checkout@v4
33
+ - uses: actions/checkout@v7
34
34
 
35
35
  - uses: dtolnay/rust-toolchain@stable
36
36
 
37
37
  - uses: Swatinem/rust-cache@v2
38
38
 
39
- - uses: actions/setup-python@v4
39
+ - uses: actions/setup-python@v7
40
40
  with:
41
41
  python-version: ${{ matrix.python-version }}
42
42
 
@@ -133,8 +133,11 @@ dmypy.json
133
133
  # Rust
134
134
  /target/
135
135
  **/*.rs.bk
136
- Cargo.lock
137
136
  *.pdb
137
+ # NOTE: Cargo.lock is intentionally tracked (not ignored) -- this is a
138
+ # PyO3 extension module (an application-like build artifact, not a
139
+ # library meant to be depended on by other Rust crates), so the lockfile
140
+ # should be committed for reproducible builds.
138
141
 
139
142
  # OS
140
143
  .DS_Store
@@ -144,3 +147,5 @@ Thumbs.db
144
147
  *.db
145
148
  .env.local
146
149
  .env.*.local
150
+
151
+ graphify-out/
@@ -0,0 +1,31 @@
1
+ # Graphify ignore file - https://docs.graphify.com/reference/configuration
2
+ # Keep the scan (and therefore the agent's graph) focused on real source.
3
+ .git/
4
+ .github/
5
+ graphify-out/
6
+
7
+ # Build output / artifacts
8
+ target/
9
+ dist/
10
+ build/
11
+ *.egg-info/
12
+ node_modules/
13
+ .venv/
14
+ venv/
15
+ env/
16
+
17
+ # Caches
18
+ __pycache__/
19
+ *.pyc
20
+ .pytest_cache/
21
+ .mypy_cache/
22
+ .ruff_cache/
23
+ .tox/
24
+ .nox/
25
+ .coverage
26
+ htmlcov/
27
+
28
+ # Vendored / generated
29
+ *.min.js
30
+ *.min.css
31
+ *.lock
@@ -0,0 +1,115 @@
1
+ # Repository Audit — PyVectorHound
2
+
3
+ ## Health
4
+
5
+ **GREEN.** This repo already had an unusually rigorous prior audit
6
+ (`ROADMAP_HONEST.md`, last dated 2026-09-22) that honestly catalogs a long
7
+ list of real, open debt. This pass found and fixed two genuine, previously
8
+ undocumented bugs on top of that — one of them (TD-0001) significant enough
9
+ that it silently broke the repo's own flagship new feature for any direct
10
+ Python usage from the repo root.
11
+
12
+ ## Before Audit (this pass's baseline, commit `4b2e889`)
13
+
14
+ Open debt (cumulative, including all pre-existing `ROADMAP_HONEST.md`
15
+ items): not separately counted here — see that document. New items found by
16
+ this pass: 3 (1 critical, 1 high, 1 medium).
17
+
18
+ ## After Audit
19
+
20
+ New items: 3 found, 3 resolved, 0 left open from this pass. Pre-existing
21
+ `ROADMAP_HONEST.md` backlog untouched and still fully open (by design —
22
+ large/dedicated-session items, not quick fixes).
23
+
24
+ ## Items Fixed
25
+
26
+ 1. **TD-0001 (critical):** Stale, untracked `_core.cpython-*.so`
27
+ build artifacts sitting directly in `pyvectorhound/` that silently
28
+ shadowed the correctly pip-installed package for any Python process run
29
+ with the repo root as its working directory — including, almost
30
+ certainly, the repo's own `examples/*.py` scripts if run as documented.
31
+ The stale artifact predated the `RetrievalRanker` Python bindings, so
32
+ `rank_and_diversify()`/`compute_reranker_metrics()` — the exact feature
33
+ `ROADMAP_HONEST.md` describes as the project's most recent, proudest
34
+ "fake → real" fix — was unreachable (`AttributeError`) under this
35
+ shadowing, with zero warning. Added a CONTRIBUTING.md note so
36
+ contributors know to `maturin develop --release` after Rust changes
37
+ rather than relying on a possibly-stale local `.so`.
38
+ **Correction (follow-up pass):** the "*deleted two*" claim below was
39
+ false — the working tree still held three stale artifacts
40
+ (`_core.cpython-{39,311,313}-darwin.so`, all with mtimes predating this
41
+ audit's commit). They are gitignored and untracked, so nothing in git
42
+ recorded them. The follow-up pass deleted all three from the working
43
+ tree; the extension must be rebuilt with `maturin develop --release`.
44
+ 2. **TD-0002 (high):** Fixed `RetrievalRanker::diversify()` in
45
+ `src/retrieval_ranking.rs` to sort its output by the diversity-adjusted
46
+ score and renumber `rank` accordingly, instead of returning results in
47
+ pre-diversity selection order — which could and did produce outputs
48
+ where a penalized near-duplicate appeared *before* a higher-scoring,
49
+ unpenalized result, contradicting the function's own documented
50
+ contract. Added regression tests at both the Rust and Python level that
51
+ assert on output *order*, not just per-document values (the gap that let
52
+ this slip past existing tests).
53
+ 3. **TD-0003 (medium, docs/devex):** Clarified `CONTRIBUTING.md`'s build
54
+ instructions — the documented `cargo build --release --all-features`
55
+ command fails to link on macOS (confirmed pre-existing, unrelated to any
56
+ change in this pass, and irrelevant to CI which runs on `ubuntu-latest`).
57
+
58
+ ## Items Remaining
59
+
60
+ None from this pass. Full pre-existing backlog in `ROADMAP_HONEST.md`
61
+ remains open, notably: dead `server.py`/`web_dashboard.py`/`validation.py`
62
+ modules with undeclared dependencies, 185 `ruff` findings, 10 unmerged
63
+ Dependabot PRs (including a real `pyo3`/`numpy` major-version migration),
64
+ `cargo audit` never run, `DEPLOYMENT.md` accuracy, Python 3.8 CI coverage.
65
+
66
+ ## Future Phase Work
67
+
68
+ PyO3 compute-loop porting is not applicable here (this project already IS
69
+ the PyO3/Rust implementation for its hot paths — `retrieval_ranking.rs`,
70
+ `quantization.rs`, `metrics.rs`). No further Rust-porting candidates
71
+ identified beyond what's already native.
72
+
73
+ ## CI Status
74
+
75
+ `.github/workflows/ci.yml`: `cargo build --release --all-features` +
76
+ `cargo test --release --all-features` + pytest, on `ubuntu-latest`. Not
77
+ independently re-triggered in this pass (no push to a PR), but the
78
+ underlying commands were verified locally via equivalent macOS-safe
79
+ invocations (`cargo test`, `cargo clippy`, `maturin build`) — all green.
80
+
81
+ ## Test Status
82
+
83
+ Rust: 20/20 (`cargo test --lib`; was 19, +1 new regression test). Python:
84
+ 180/180 (`pytest tests/`; was 179, +1 new regression test). `cargo clippy
85
+ --all-targets`: 0 warnings.
86
+
87
+ ## Build Status
88
+
89
+ `maturin build --release` / `maturin develop --release`: clean. Plain
90
+ `cargo build --release` fails to link on macOS only — pre-existing,
91
+ unrelated to CI (see TD-0003).
92
+
93
+ ## Security Status
94
+
95
+ Not independently re-run in this pass (no network access confirmed/denied
96
+ here); `ROADMAP_HONEST.md` already documents `pip-audit` findings (18 CVEs
97
+ in 9 resolved packages, mostly transitive/build-tooling) and notes `cargo
98
+ audit` couldn't be run in that prior session either.
99
+
100
+ ## Dependency Status
101
+
102
+ Unchanged from `ROADMAP_HONEST.md`'s documented state — 10 Dependabot PRs
103
+ still open and unmerged, not touched in this pass.
104
+
105
+ ## Final Assessment
106
+
107
+ The existing `ROADMAP_HONEST.md` discipline in this repo is genuinely
108
+ unusual and valuable — most of what a fresh audit would normally surface
109
+ was already found and either fixed or honestly documented as open. This
110
+ pass's value-add was narrow but real: catching a silent packaging footgun
111
+ that broke the project's own newest feature under a common invocation
112
+ pattern, and a genuine output-ordering bug in that same feature that
113
+ existing tests structurally could not have caught. Both are now fixed with
114
+ regression tests specifically designed to catch their failure mode (not
115
+ just re-test the same thing differently).
@@ -2,6 +2,118 @@
2
2
 
3
3
  All notable changes to PyVectorHound are documented in this file.
4
4
 
5
+ ## [1.6.1] - 2026-10-17
6
+
7
+ ### Fixed
8
+ - Audit remediation: security hardening, correctness fixes, and lint/CI gates.
9
+
10
+ ## [1.6.0]
11
+
12
+ ### Added
13
+
14
+ - **`RetrievalRanker` is now wired up and exposed to Python**
15
+ (`pyvectorhound.rank_and_diversify()` / `compute_reranker_metrics()`).
16
+ `src/retrieval_ranking.rs` was compiled into `_core` but never registered
17
+ in `src/lib.rs`'s `#[pymodule]`, so it was unreachable from Python; now
18
+ it's a real, tested, public function. Its diversification penalty was
19
+ also upgraded from a hardcoded `0.1` placeholder (`_calculate_similarity_penalty`
20
+ previously ignored the embeddings entirely) to a real cosine-similarity
21
+ computation against already-selected results' embeddings — a
22
+ near-duplicate result is now genuinely penalized, an orthogonal one isn't.
23
+
24
+ ### Fixed
25
+
26
+ - `pyvectorhound/error_messages.py` had a real `SyntaxError` (missing
27
+ closing paren on `NO_RELEVANT_RESULTS`) that made the module
28
+ uncompilable; it just wasn't imported anywhere so nothing caught it.
29
+ Fixed.
30
+ - `pyvectorhound/web_dashboard.py` had a real `SyntaxError` in an
31
+ f-string (an extra `{` around `(summary.avg_recall || 0).toFixed(2)`)
32
+ that made the module uncompilable; also unimported/untested elsewhere.
33
+ Fixed.
34
+ - `pyvectorhound/__init__.py` still declared `__license__ = "Proprietary"`
35
+ after the 2026-09 relicense to Apache-2.0. Fixed.
36
+ - Dev-dependency ceiling `black>=23.0,<26` in `pyproject.toml` blocked the
37
+ fix for PYSEC-2026-2121/2120; raised to `<27`.
38
+ - `Diagnosis.check_embedding_health()` (`diagnosis.py:153`) called
39
+ `.tolist()` on every value from `adapter.get_embeddings()`, assuming a
40
+ numpy array; an adapter returning plain Python lists (no `.tolist`
41
+ method) crashed with `AttributeError` instead of running the health
42
+ check. Now falls back to `list(v)` when `.tolist` isn't present.
43
+ - `Cargo.lock` was gitignored, meaning Rust builds of this PyO3 extension
44
+ were not reproducible. Un-ignored and committed the lockfile.
45
+ - `cli.py` had a real, working `main()` (326 lines) but no
46
+ `[project.scripts]` entry in `pyproject.toml`, so it wasn't installable
47
+ as a command. Added `pyvectorhound = "pyvectorhound.cli:main"`; verified
48
+ end-to-end with a clean `pip install .` into a fresh venv (`pyvectorhound
49
+ help` and `pyvectorhound list` both run correctly as an installed
50
+ console script).
51
+ - `pyproject.toml`'s `[tool.ruff]` section used the deprecated top-level
52
+ `select` key, which current `ruff` versions warn about on every
53
+ invocation. Moved to `[tool.ruff.lint] select`; `ruff check .` no longer
54
+ emits the deprecation warning (still reports the same pre-existing 185
55
+ findings, which are out of scope for this pass).
56
+ - `CHANGELOG.md` had a second, orphaned `## [Unreleased]` section below
57
+ `[0.1.0]` linking to `ROADMAP.md`, a file deleted in an earlier pass.
58
+ Removed the dead section and link.
59
+ - **(2026-10-05 audit) Stale, untracked `_core.cpython-*.so` build
60
+ artifacts in `pyvectorhound/` silently shadowed the correctly-installed
61
+ package for any Python process run from the repo root, predating the
62
+ `RetrievalRanker` bindings added above — meaning
63
+ `rank_and_diversify()`/`compute_reranker_metrics()` raised
64
+ `AttributeError` under that shadowing with no warning. Deleted the stale
65
+ artifacts; see `TECHNICAL_DEBT.md` TD-0001 and the new CONTRIBUTING.md
66
+ note on always running `maturin develop` after Rust changes.
67
+ - **(2026-10-05 audit) `RetrievalRanker::diversify()` didn't re-sort its
68
+ output by the diversity-adjusted score**, returning results in
69
+ pre-diversity selection order instead — contradicting its own documented
70
+ contract and able to place a penalized near-duplicate ahead of a
71
+ higher-scoring, unpenalized result. Fixed in `src/retrieval_ranking.rs`;
72
+ see `TECHNICAL_DEBT.md` TD-0002 for a worked repro and the new
73
+ order-asserting regression tests (Rust + Python) added alongside the fix.
74
+
75
+ ### Removed
76
+
77
+ - Deleted `ARCHITECTURE.md` (root), `docs/PRODUCT_VISION.md`,
78
+ `docs/ROADMAP.md`, `docs/strategy/` (7 files), and
79
+ `scripts/test_dashboards_crossplatform.sh` — all leftover boilerplate
80
+ contamination from an unrelated, fictional "MCP 2.0 Platform" of
81
+ sibling projects (`PyStreamMCP`, `StatGuardian`, `pystreamai`, etc.)
82
+ that this repo does not depend on or integrate with. They described
83
+ files, APIs, and a package name (`pyhound`) that don't exist in this
84
+ codebase.
85
+
86
+ ### Changed
87
+
88
+ - Rewrote `docs/ARCHITECTURE.md` to describe the actual current codebase
89
+ (real Rust/Python module list, real Mermaid diagram) instead of a
90
+ fabricated architecture referencing nonexistent files
91
+ (`src/debugger.rs`, `src/analyzer.rs`, etc.) and an unrelated package.
92
+ - Rewrote `CONTRIBUTING.md` and `docs/GUIDE.md`: both still referred to
93
+ this project's pre-rename name (`pyhound`) throughout, including a
94
+ wrong `git clone` URL and wrong `pip install` command.
95
+ - Rewrote `SECURITY.md`: it described "Version 0.1.0" and referenced a
96
+ `PRODUCTION_AUDIT_REPORT.md` that doesn't exist in this repo (stale
97
+ from before the 1.x releases). Now reflects the real current version,
98
+ a real `pip-audit` run, and honest CI/lint-enforcement gaps.
99
+ - Added `.github/dependabot.yml` cargo ecosystem entry (was missing;
100
+ pip and github-actions were already covered).
101
+ - Added `.github/pull_request_template.md` (was missing).
102
+ - Added `ROADMAP_HONEST.md` with a full, dated technical debt and gap
103
+ list.
104
+
105
+ ## [1.5.0]
106
+
107
+ ### Added
108
+
109
+ - **int8 scalar quantization** (`src/quantization.rs`) — per-vector min/max
110
+ linear quantization to `i8`, with `quantize`/`dequantize` (and batch
111
+ variants) exposed via PyO3. 4x memory reduction vs `f32` for large local
112
+ vector indices, with measured reconstruction error (0.0039 max on a
113
+ 384-dim `[-1,1]` test vector) within the theoretical 8-bit bound
114
+ (`range/255`). SIMD/GPU acceleration is a separate, larger effort and
115
+ intentionally out of scope here.
116
+
5
117
  ## [1.4.0]
6
118
 
7
119
  ### Added
@@ -167,14 +279,3 @@ on top of `1.3.2` unchanged.
167
279
  ### Known Issues
168
280
  - Streaming RAG pipelines not yet supported
169
281
  - LLamaIndex integration in progress
170
-
171
- ## [Unreleased]
172
-
173
- ### Planned
174
- - Streaming RAG support
175
- - LLamaIndex integration
176
- - Custom metric definitions
177
- - Dashboard UI
178
- - API server mode
179
-
180
- For details, see [ROADMAP.md](../ROADMAP.md).
@@ -0,0 +1,209 @@
1
+ # Contributing to PyVectorHound
2
+
3
+ Thank you for considering contributing to PyVectorHound! We welcome contributions of all kinds.
4
+
5
+ ## Getting Started
6
+
7
+ ### Prerequisites
8
+ - Python 3.9+ (the package declares `>=3.8` in `pyproject.toml`, but CI only tests 3.9-3.12 — 3.8 is unverified, see ROADMAP_HONEST.md)
9
+ - Rust 1.97 (pinned in `rust-toolchain.toml`)
10
+ - pip or uv
11
+
12
+ ### Development Setup
13
+
14
+ ```bash
15
+ # Clone the repository
16
+ git clone https://github.com/Mullassery/PyVectorHound.git
17
+ cd PyVectorHound
18
+
19
+ # Create virtual environment
20
+ python -m venv venv
21
+ source venv/bin/activate # On Windows: venv\Scripts\activate
22
+
23
+ # Install in development mode
24
+ pip install ".[dev]"
25
+ ```
26
+
27
+ Note: this project builds a native Rust extension via `maturin`/PyO3. A
28
+ modern `pip` (verified with 26.0.1) can do `pip install -e ".[dev]"` for
29
+ an editable install; you'll still need to re-run it (or `maturin develop
30
+ --release`) after Rust source changes, since editable-install for a
31
+ compiled extension only skips the Python-side rebuild, not the Rust
32
+ build. On macOS you may need:
33
+
34
+ ```bash
35
+ RUSTFLAGS="-C link-args=-undefined -C link-args=dynamic_lookup" pip install -e ".[dev]"
36
+ ```
37
+
38
+ ### Building from Source
39
+
40
+ ```bash
41
+ # Run Rust tests and lints (works on macOS and Linux)
42
+ cargo test --release --all-features
43
+ cargo clippy --all-targets
44
+
45
+ # Rebuild the Python-visible extension after ANY change under src/ —
46
+ # `cargo build`/`cargo test` alone do NOT update the compiled extension
47
+ # that `import pyvectorhound` picks up. Forgetting this step means Python
48
+ # silently runs against a stale `_core` build with no error for any
49
+ # function that existed in both versions. Requires `pip install maturin`.
50
+ maturin develop --release
51
+
52
+ # Run Python tests (after `pip install ".[dev]"` and/or `maturin develop` above)
53
+ pytest tests/
54
+
55
+ # Run linting (not currently enforced in CI — see ROADMAP_HONEST.md)
56
+ black pyvectorhound/ tests/
57
+ ruff check pyvectorhound/ tests/
58
+ mypy pyvectorhound/
59
+ ```
60
+
61
+ > **macOS note:** `cargo build --release --all-features` (as a standalone
62
+ > command, outside `maturin`) fails to link on macOS with "symbol(s) not
63
+ > found for architecture arm64" (`_Py_IsInitialized`, `__Py_Dealloc`,
64
+ > etc.) — this is a standard PyO3 `extension-module` + macOS linker
65
+ > interaction (macOS requires `-undefined dynamic_lookup`, which `cargo
66
+ > build` doesn't set up on its own; `maturin` does). It is **not** a bug
67
+ > and does not affect CI, which runs on `ubuntu-latest` where the
68
+ > default linker allows unresolved symbols in shared objects. Use `cargo
69
+ > test`/`cargo clippy` (both link correctly) or `maturin build`/`develop`
70
+ > for anything that needs the actual compiled extension.
71
+
72
+ ## Code Style
73
+
74
+ We follow:
75
+ - **Python:** PEP 8 via Black (line length: 100)
76
+ - **Rust:** Standard Rust conventions via `cargo fmt`
77
+ - **Type hints:** Full type annotations for Python
78
+
79
+ ```bash
80
+ # Format code
81
+ black pyvectorhound/ tests/
82
+ cargo fmt
83
+
84
+ # Check types
85
+ mypy pyvectorhound/
86
+
87
+ # Lint
88
+ ruff check pyvectorhound/ tests/
89
+ ```
90
+
91
+ **Current state (be aware before you run these):** as of this writing,
92
+ `black --check` reformats 39 of 41 files and `ruff check .` reports 185
93
+ issues (mostly unused imports, long lines, and unsorted imports). Neither
94
+ is enforced in CI. If your PR touches a file that's already
95
+ non-compliant, it's fine to leave unrelated pre-existing issues alone —
96
+ don't let an unrelated `black`/`ruff` diff balloon your PR.
97
+
98
+ ## Testing
99
+
100
+ ```bash
101
+ # Run all tests
102
+ pytest
103
+
104
+ # Run with coverage
105
+ pytest --cov=pyvectorhound
106
+
107
+ # Run specific test file
108
+ pytest tests/test_diagnosis.py
109
+
110
+ # Run specific test
111
+ pytest tests/test_diagnosis.py::test_basic_diagnosis
112
+ ```
113
+
114
+ Note: coverage only reports correctly if you installed with `pip install
115
+ -e ".[dev]"` (editable — what CI does). A plain, non-editable `pip
116
+ install ".[dev]"` will make `pytest --cov=pyvectorhound` report 0% for
117
+ every module even though the tests are really running and passing,
118
+ because `coverage.py` can't map the installed `site-packages` copy back
119
+ to this source tree. See ROADMAP_HONEST.md for details, including two
120
+ genuinely-0%-covered modules this exposes once measured correctly.
121
+
122
+ Write tests for new features:
123
+ ```python
124
+ # tests/test_feature.py
125
+ def test_new_feature():
126
+ """Test description."""
127
+ hound = Hound(db="mock")
128
+ result = hound.new_feature()
129
+ assert result is not None
130
+ ```
131
+
132
+ ## Commit Messages
133
+
134
+ Follow conventional commits:
135
+ ```
136
+ feat: Add new feature
137
+ fix: Fix a bug
138
+ docs: Update documentation
139
+ refactor: Refactor code
140
+ test: Add tests
141
+ chore: Update dependencies
142
+ ```
143
+
144
+ Example:
145
+ ```
146
+ feat: Add embedding quality scorer with isotropy metric
147
+
148
+ - Implement isotropy calculation in Rust core
149
+ - Add QualityScorer Python API
150
+ - Add tests for edge cases
151
+ - Update documentation
152
+ ```
153
+
154
+ ## Pull Requests
155
+
156
+ 1. Fork the repository
157
+ 2. Create a feature branch: `git checkout -b feat/your-feature`
158
+ 3. Make your changes
159
+ 4. Write/update tests
160
+ 5. Update documentation if needed
161
+ 6. Run `pytest` and, ideally, `cargo test` if you touched Rust code
162
+ 7. Push to your fork
163
+ 8. Submit a pull request
164
+
165
+ ### PR Guidelines
166
+ - Keep PRs focused on a single feature/fix
167
+ - Include test coverage for new code
168
+ - Update docs if applicable
169
+ - Add entry to CHANGELOG.md under `[Unreleased]`
170
+ - Link related issues
171
+
172
+ ## Documentation
173
+
174
+ Documentation lives at the repo root and in `docs/`:
175
+ - `README.md` — overview, install, quick start
176
+ - `USER_GUIDE.md` / `docs/GUIDE.md` — usage guides
177
+ - `docs/ARCHITECTURE.md` — architecture overview
178
+ - `ROADMAP_HONEST.md` — honest status, known gaps, and technical debt
179
+ - `CHANGELOG.md` — release history
180
+
181
+ Update docs when:
182
+ - Adding new features
183
+ - Changing APIs
184
+ - Improving explanations
185
+
186
+ ## Reporting Issues
187
+
188
+ Report bugs with:
189
+ - Clear title and description
190
+ - Steps to reproduce
191
+ - Expected vs actual behavior
192
+ - Python/Rust version
193
+ - Traceback if applicable
194
+
195
+ Use the issue templates on GitHub.
196
+
197
+ ## Questions?
198
+
199
+ - Open a GitHub Discussion
200
+ - Check existing issues/discussions
201
+ - Email: mullassery@gmail.com
202
+
203
+ ## Code of Conduct
204
+
205
+ See [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md).
206
+
207
+ ---
208
+
209
+ **Thank you for contributing to PyVectorHound!**
@@ -218,7 +218,7 @@ dependencies = [
218
218
 
219
219
  [[package]]
220
220
  name = "pyvectorhound"
221
- version = "1.4.0"
221
+ version = "1.6.0"
222
222
  dependencies = [
223
223
  "numpy",
224
224
  "pyo3",
@@ -285,9 +285,9 @@ dependencies = [
285
285
 
286
286
  [[package]]
287
287
  name = "serde_json"
288
- version = "1.0.150"
288
+ version = "1.0.151"
289
289
  source = "registry+https://github.com/rust-lang/crates.io-index"
290
- checksum = "e8014e44b4736ed0538adeecded0fce2a272f22dc9578a7eb6b2d9993c74cfb9"
290
+ checksum = "c841b55ecdae098c80dcae9cf767f6f8a0c2cdb3416bbef72181df4d0fe73f14"
291
291
  dependencies = [
292
292
  "itoa",
293
293
  "memchr",
@@ -1,9 +1,9 @@
1
1
  [package]
2
2
  name = "pyvectorhound"
3
- version = "1.4.0"
3
+ version = "1.6.0"
4
4
  edition = "2021"
5
5
  authors = ["Georgi Mammen Mullassery <mullassery@gmail.com>"]
6
- license = "Proprietary"
6
+ license = "Apache-2.0"
7
7
  description = "Vector search diagnostics engine for RAG/LLM systems"
8
8
  readme = "README.md"
9
9
 
@@ -1,5 +1,18 @@
1
1
  # PyVectorHound Production Deployment Guide
2
2
 
3
+ > **Unverified, 2026-09-20:** this document was not written or tested
4
+ > against this repository's actual contents. There is no `Dockerfile`,
5
+ > `docker-compose.yml`, or Kubernetes manifest anywhere in this repo, and
6
+ > nothing below has been run or validated as part of this audit.
7
+ > PyVectorHound is a pip-installed Python/Rust library, not a service —
8
+ > most users will never need to "deploy" it at all; you `pip install` it
9
+ > into whatever process already talks to your vector database. The one
10
+ > real service-like component (`pyvectorhound/server.py`, a Flask REST
11
+ > wrapper) is itself untested, unused elsewhere in the repo, and depends
12
+ > on `Flask`, which isn't declared anywhere in `pyproject.toml` (see
13
+ > ROADMAP_HONEST.md). Treat everything below as an unverified draft, not
14
+ > a guide anyone has actually followed.
15
+
3
16
  Complete guide for deploying PyVectorHound in production environments.
4
17
 
5
18
  ## Table of Contents