vector-engine 1.0.2__tar.gz → 1.1.1__tar.gz

{vector_engine-1.0.2/vector_engine.egg-info → vector_engine-1.1.1}/PKG-INFO

@@ -1,9 +1,23 @@
 Metadata-Version: 2.4
 Name: vector-engine
-Version: 1.0.2
+Version: 1.1.1
 Summary: ML-first vector computation and retrieval engine.
 Author: Neel Panchal
 License-Expression: MIT
+Project-URL: Homepage, https://github.com/neelpanchal11/Vector-Engine
+Project-URL: Repository, https://github.com/neelpanchal11/Vector-Engine
+Project-URL: Issues, https://github.com/neelpanchal11/Vector-Engine/issues
+Project-URL: Documentation, https://github.com/neelpanchal11/Vector-Engine/tree/main/docs
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
@@ -16,7 +30,7 @@ Provides-Extra: dev
 Requires-Dist: pytest<9,>=8.2; extra == "dev"
 Dynamic: license-file
 
-# Vector Engine v1.0.0
+# Vector Engine v1.1.1
 
 Reproducibility-first vector retrieval toolkit for local ML and IR workflows.
 
@@ -95,7 +109,17 @@ results = index.search(xq, k=5)
 print(results.ids[0], results.scores[0])
 ```
 
-## v1.0.0 Surface
+## Colab Demos
+
+Each notebook opens directly from this repo, so it always matches the current release.
+
+- Semantic search: [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/neelpanchal11/Vector-Engine/blob/main/notebooks/01_semantic_search.ipynb)
+- kNN baseline classifier: [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/neelpanchal11/Vector-Engine/blob/main/notebooks/02_knn_baseline.ipynb)
+- Item-item recommender similarity: [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/neelpanchal11/Vector-Engine/blob/main/notebooks/03_recommender_similarity.ipynb)
+
+`notebooks/04_stability_runs.ipynb` analyzes locally generated benchmark artifacts (see [Reproducibility and Evidence](#reproducibility-and-evidence)) and is not a standalone Colab demo.
+
+## v1.1.0 Surface
 
 - Core: `VectorArray`, `VectorIndex`, `Metric`, `SearchResult`
 - ML: `knn_classify`, `knn_regress`, `kmeans`, `KMeansResult`
@@ -192,8 +216,8 @@ python scripts/credibility_audit.py --matrix-summary artifacts/benchmark_matrix/
 
 ## Project Links
 
-- `docs/releases/v1.0.0.md`
-- `docs/releases/v1.0.0-checklist.md`
+- `docs/releases/v1.1.0.md`
+- `docs/releases/v1.1.0-checklist.md`
 - `docs/reproducibility.md`
 - `docs/use_cases.md`
 - `docs/api_stability.md`

vector_engine-1.0.2/PKG-INFO → vector_engine-1.1.1/README.md

@@ -1,22 +1,4 @@
-Metadata-Version: 2.4
-Name: vector-engine
-Version: 1.0.2
-Summary: ML-first vector computation and retrieval engine.
-Author: Neel Panchal
-License-Expression: MIT
-Requires-Python: >=3.10
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: numpy<2.0,>=1.26.4
-Provides-Extra: faiss
-Requires-Dist: faiss-cpu>=1.7.4; (platform_system != "Darwin" or platform_machine != "arm64") and extra == "faiss"
-Provides-Extra: ml
-Requires-Dist: scikit-learn<1.7,>=1.4; extra == "ml"
-Provides-Extra: dev
-Requires-Dist: pytest<9,>=8.2; extra == "dev"
-Dynamic: license-file
-
-# Vector Engine v1.0.0
+# Vector Engine v1.1.1
 
 Reproducibility-first vector retrieval toolkit for local ML and IR workflows.
 
@@ -95,7 +77,17 @@ results = index.search(xq, k=5)
 print(results.ids[0], results.scores[0])
 ```
 
-## v1.0.0 Surface
+## Colab Demos
+
+Each notebook opens directly from this repo, so it always matches the current release.
+
+- Semantic search: [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/neelpanchal11/Vector-Engine/blob/main/notebooks/01_semantic_search.ipynb)
+- kNN baseline classifier: [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/neelpanchal11/Vector-Engine/blob/main/notebooks/02_knn_baseline.ipynb)
+- Item-item recommender similarity: [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/neelpanchal11/Vector-Engine/blob/main/notebooks/03_recommender_similarity.ipynb)
+
+`notebooks/04_stability_runs.ipynb` analyzes locally generated benchmark artifacts (see [Reproducibility and Evidence](#reproducibility-and-evidence)) and is not a standalone Colab demo.
+
+## v1.1.0 Surface
 
 - Core: `VectorArray`, `VectorIndex`, `Metric`, `SearchResult`
 - ML: `knn_classify`, `knn_regress`, `kmeans`, `KMeansResult`
@@ -192,8 +184,8 @@ python scripts/credibility_audit.py --matrix-summary artifacts/benchmark_matrix/
 
 ## Project Links
 
-- `docs/releases/v1.0.0.md`
-- `docs/releases/v1.0.0-checklist.md`
+- `docs/releases/v1.1.0.md`
+- `docs/releases/v1.1.0-checklist.md`
 - `docs/reproducibility.md`
 - `docs/use_cases.md`
 - `docs/api_stability.md`

vector_engine-1.1.1/pyproject.toml

@@ -0,0 +1,50 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "vector-engine"
+version = "1.1.1"
+description = "ML-first vector computation and retrieval engine."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [
+  { name = "Neel Panchal" }
+]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Science/Research",
+  "Intended Audience :: Developers",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Scientific/Engineering :: Artificial Intelligence",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+  "numpy>=1.26.4,<2.0",
+]
+
+[project.optional-dependencies]
+faiss = [
+  "faiss-cpu>=1.7.4; platform_system != 'Darwin' or platform_machine != 'arm64'",
+]
+ml = [
+  "scikit-learn>=1.4,<1.7",
+]
+dev = [
+  "pytest>=8.2,<9",
+]
+
+[project.urls]
+Homepage = "https://github.com/neelpanchal11/Vector-Engine"
+Repository = "https://github.com/neelpanchal11/Vector-Engine"
+Issues = "https://github.com/neelpanchal11/Vector-Engine/issues"
+Documentation = "https://github.com/neelpanchal11/Vector-Engine/tree/main/docs"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["vector_engine*"]

{vector_engine-1.0.2 → vector_engine-1.1.1}/tests/test_core.py

@@ -37,3 +37,17 @@ def test_index_save_and_load_roundtrip(tmp_path):
     loaded = VectorIndex.load(str(path))
     second = loaded.search(xq, k=4)
     assert np.array_equal(first.ids, second.ids)
+
+
+def test_index_backend_capabilities_and_runtime_stats():
+    xb = VectorArray.from_numpy(np.random.randn(16, 4).astype(np.float32), ids=np.arange(16))
+    xq = VectorArray.from_numpy(np.random.randn(2, 4).astype(np.float32))
+    index = VectorIndex.create(xb, metric="cosine", backend="bruteforce")
+    caps = index.backend_capabilities()
+    assert caps["supports_add"] is True
+    assert caps["supports_ann_tuning"] is False
+    index.search(xq, k=3)
+    stats = index.runtime_stats()
+    assert stats["search_calls"] == 1
+    assert stats["last_search_k"] == 3
+    assert stats["backend_stats"]["backend"] == "bruteforce"

{vector_engine-1.0.2 → vector_engine-1.1.1}/tests/test_dataset_benchmark_tooling.py

@@ -4,8 +4,8 @@ import subprocess
 import numpy as np
 import pytest
 
-from scripts.benchmark_matrix import _apply_memory_limit, _parse_matrix, run_matrix
-from scripts.datasets import load_jsonl_bundle, load_numpy_bundle, with_deterministic_splits
+from scripts.benchmark_matrix import _apply_memory_limit, _build_run_variants, _parse_matrix, run_matrix
+from scripts.datasets import estimate_numpy_bundle_memory_mb, load_jsonl_bundle, load_numpy_bundle, with_deterministic_splits
 
 
 def test_parse_matrix_profile_defaults_to_dev():
@@ -14,6 +14,29 @@ def test_parse_matrix_profile_defaults_to_dev():
     assert {"name", "n", "d", "nq", "k"}.issubset(set(matrix[0].keys()))
 
 
+def test_parse_matrix_profile_scale():
+    matrix = _parse_matrix(None, profile="scale")
+    assert len(matrix) >= 1
+    assert "ann_index_factory_options" in matrix[0]
+
+
+def test_build_run_variants_ann_expands():
+    variants = _build_run_variants(
+        {
+            "name": "cfg",
+            "n": 1000,
+            "d": 64,
+            "nq": 32,
+            "k": 5,
+            "ann_index_factory_options": ["IVF64,Flat", "IVF128,Flat"],
+            "ann_nprobe_options": [4, 8],
+        },
+        mode="ann",
+    )
+    assert len(variants) == 5
+    assert any(v["faiss_ivf_nprobe"] == 8 for v in variants)
+
+
 def test_apply_memory_limit_filters_large_configs():
     matrix = [
         {"name": "a", "n": 1000, "d": 32, "nq": 64, "k": 5},
@@ -40,6 +63,24 @@ def test_load_numpy_bundle(tmp_path):
     assert bundle.metadata is not None
 
 
+def test_load_numpy_bundle_memmap_mode(tmp_path):
+    xb = np.random.randn(6, 12).astype(np.float32)
+    emb = tmp_path / "emb.npy"
+    ids = tmp_path / "ids.json"
+    np.save(emb, xb)
+    ids.write_text(json.dumps([f"doc-{i}" for i in range(6)]), encoding="utf-8")
+    bundle = load_numpy_bundle(str(emb), str(ids), mmap_mode="r")
+    assert bundle.embeddings.shape == (6, 12)
+    assert bundle.ids[0] == "doc-0"
+
+
+def test_estimate_numpy_bundle_memory_mb():
+    estimate = estimate_numpy_bundle_memory_mb(1000, 64)
+    assert estimate > 0.0
+    with pytest.raises(ValueError, match="dataset_error"):
+        estimate_numpy_bundle_memory_mb(0, 64)
+
+
 def test_load_numpy_bundle_with_extended_fields(tmp_path):
     xb = np.random.randn(4, 8).astype(np.float32)
     emb = tmp_path / "emb.npy"
@@ -189,3 +230,55 @@ def test_run_matrix_fails_when_overlap_gate_enabled_without_faiss(tmp_path, monk
             profile="dev",
             max_memory_mb=1024.0,
         )
+
+
+def test_run_matrix_ann_sweep_invokes_multiple_configs(tmp_path, monkeypatch):
+    calls: list[list[str]] = []
+
+    def fake_check_call(cmd):
+        calls.append(cmd)
+        out_path = cmd[cmd.index("--output") + 1]
+        payload = {
+            "timestamp_utc": "2026-01-01T00:00:00+00:00",
+            "config": {"mode": "ann", "k": 5, "min_flat_overlap": None},
+            "environment": {"platform": "darwin", "python_version": "3.12", "machine": "arm64", "processor": "arm"},
+            "results": [
+                {
+                    "backend": "bruteforce",
+                    "qps": 900.0,
+                    "latency_p50_ms": 1.1,
+                    "latency_p95_ms": 2.2,
+                    "overlap_vs_bruteforce": 1.0,
+                    "memory_mb_estimate": 10.0,
+                }
+            ],
+            "artifact_contract_version": "1.0",
+        }
+        with open(out_path, "w", encoding="utf-8") as f:
+            json.dump(payload, f)
+
+    monkeypatch.setattr(subprocess, "check_call", fake_check_call)
+    summary = run_matrix(
+        matrix=[
+            {
+                "name": "tiny",
+                "n": 2000,
+                "d": 32,
+                "nq": 64,
+                "k": 5,
+                "ann_index_factory_options": ["IVF64,Flat"],
+                "ann_nprobe_options": [4, 8],
+            }
+        ],
+        mode="ann",
+        warmup=1,
+        loops=1,
+        seed=7,
+        min_flat_overlap=None,
+        out_dir=str(tmp_path / "out"),
+        profile="dev",
+        max_memory_mb=1024.0,
+    )
+    assert len(calls) == 3
+    assert summary["protocol"]["expanded_run_count"] == 3
+    assert "pareto_frontier" in summary

{vector_engine-1.0.2 → vector_engine-1.1.1}/tests/test_ingest_pipeline.py

@@ -81,3 +81,19 @@ def test_run_ingest_rejects_duplicate_ids(tmp_path):
             embedding_dim=8,
             seed=7,
         )
+
+
+def test_run_ingest_honors_memory_cap(tmp_path):
+    source = tmp_path / "source.jsonl"
+    rows = [{"id": f"d{i}", "text": f"text-{i}"} for i in range(10)]
+    _write_jsonl(source, rows)
+    with pytest.raises(ValueError, match="max_memory_mb"):
+        run_ingest(
+            input_jsonl=str(source),
+            output_dir=str(tmp_path / "out"),
+            id_field="id",
+            text_field="text",
+            embedding_dim=64,
+            seed=7,
+            max_memory_mb=0.0001,
+        )

vector_engine-1.1.1/tests/test_matrix_profile_advisor.py

@@ -0,0 +1,24 @@
+import json
+
+from scripts.matrix_profile_advisor import recommend_configs
+
+
+def test_recommend_configs_returns_sorted_recommendations(tmp_path):
+    run_dir = tmp_path / "runs"
+    run_dir.mkdir(parents=True, exist_ok=True)
+    matrix_summary = {
+        "expanded_runs": ["cfg_a", "cfg_b"],
+        "runs_dir": str(run_dir),
+    }
+    (tmp_path / "matrix_summary.json").write_text(json.dumps(matrix_summary), encoding="utf-8")
+    for name, qps, p95, overlap in [("cfg_a", 1200.0, 10.0, 0.90), ("cfg_b", 1000.0, 8.0, 0.98)]:
+        payload = {
+            "results": [
+                {"backend": "bruteforce", "qps": 500.0, "latency_p95_ms": 12.0, "overlap_vs_bruteforce": 1.0},
+                {"backend": "faiss_ivf", "qps": qps, "latency_p95_ms": p95, "overlap_vs_bruteforce": overlap},
+            ]
+        }
+        (run_dir / f"{name}.json").write_text(json.dumps(payload), encoding="utf-8")
+    out = recommend_configs(str(tmp_path / "matrix_summary.json"), top_n=1)
+    assert len(out["recommendations"]) == 1
+    assert out["recommendations"][0]["run"] in {"cfg_a", "cfg_b"}

vector_engine-1.1.1/tests/test_release_performance_workflow.py

@@ -0,0 +1,125 @@
+import json
+
+from scripts.performance_gates import run_performance_gates
+from scripts.publishable_results import build_publishable_summary
+
+
+def _write(path, payload):
+    path.write_text(json.dumps(payload), encoding="utf-8")
+
+
+def test_performance_gates_passes_with_reasonable_metrics(tmp_path):
+    matrix = {
+        "timestamp_utc": "2026-01-01T00:00:00+00:00",
+        "protocol": {"mode": "exact", "warmup": 2, "loops": 5, "seed": 7, "matrix_size": 1, "min_flat_overlap": 0.99},
+        "environment": {},
+        "matrix": [{"name": "cfg", "n": 1000, "d": 32, "nq": 64, "k": 5}],
+        "backend_summary": {
+            "bruteforce": {
+                "latency_p50_ms": {"mean": 1.0, "median": 1.0, "min": 1.0, "max": 1.0},
+                "latency_p95_ms": {"mean": 2.0, "median": 2.0, "min": 2.0, "max": 2.0},
+                "qps": {"mean": 100.0, "median": 100.0, "min": 90.0, "max": 110.0},
+                "overlap_vs_bruteforce": {"mean": 1.0, "median": 1.0, "min": 1.0, "max": 1.0},
+            }
+        },
+        "runs_dir": "artifacts/benchmark_matrix",
+        "artifact_contract_version": "1.0",
+    }
+    stability = {
+        "timestamp_utc": "2026-01-01T00:00:00+00:00",
+        "run_count": 3,
+        "backend": "bruteforce",
+        "config": {},
+        "environment": {},
+        "performance_summary": {
+            "latency_p50_ms": {"mean": 1.0},
+            "latency_p95_ms": {"mean": 2.0},
+            "qps": {"mean": 150.0},
+        },
+        "metric_summary": {"recall@10": {"mean": 0.95}, "ndcg@10": {"mean": 0.92}},
+        "check_pass_rate": {},
+        "input_files": {},
+        "runs_path": "runs.jsonl",
+        "artifact_contract_version": "1.0",
+    }
+    matrix_path = tmp_path / "matrix.json"
+    stability_path = tmp_path / "stability.json"
+    out_path = tmp_path / "gates.json"
+    _write(matrix_path, matrix)
+    _write(stability_path, stability)
+    report = run_performance_gates(
+        matrix_summary_path=str(matrix_path),
+        stability_summary_path=str(stability_path),
+        output_path=str(out_path),
+        min_recall=0.8,
+        min_ndcg=0.8,
+        max_latency_p95_ms=50.0,
+        min_qps=50.0,
+    )
+    assert report["status"] == "pass"
+    assert out_path.exists()
+
+
+def test_build_publishable_summary_includes_release_delta(tmp_path):
+    matrix = {
+        "timestamp_utc": "2026-01-01T00:00:00+00:00",
+        "protocol": {"mode": "exact", "warmup": 2, "loops": 8, "seed": 7, "matrix_size": 1},
+        "environment": {},
+        "matrix": [{"name": "cfg", "n": 1000, "d": 32, "nq": 64, "k": 5}],
+        "backend_summary": {
+            "bruteforce": {
+                "latency_p50_ms": {"mean": 1.0, "median": 1.0, "min": 1.0, "max": 1.0},
+                "latency_p95_ms": {"mean": 2.0, "median": 2.0, "min": 2.0, "max": 2.0},
+                "qps": {"mean": 100.0, "median": 100.0, "min": 95.0, "max": 105.0},
+                "overlap_vs_bruteforce": {"mean": 1.0, "median": 1.0, "min": 1.0, "max": 1.0},
+            }
+        },
+        "runs_dir": "artifacts/benchmark_matrix",
+        "artifact_contract_version": "1.0",
+    }
+    stability = {
+        "timestamp_utc": "2026-01-01T00:00:00+00:00",
+        "run_count": 2,
+        "backend": "bruteforce",
+        "config": {"run_count": 2},
+        "environment": {},
+        "performance_summary": {
+            "latency_p50_ms": {"mean": 1.0, "median": 1.0, "std": 0.0, "cv": 0.0, "p02_5": 1.0, "p97_5": 1.0, "min": 1.0, "max": 1.0},
+            "latency_p95_ms": {"mean": 2.0, "median": 2.0, "std": 0.0, "cv": 0.0, "p02_5": 2.0, "p97_5": 2.0, "min": 2.0, "max": 2.0},
+            "qps": {"mean": 120.0, "median": 120.0, "std": 0.0, "cv": 0.0, "p02_5": 120.0, "p97_5": 120.0, "min": 120.0, "max": 120.0},
+        },
+        "metric_summary": {"recall@1": {"mean": 0.9}},
+        "check_pass_rate": {},
+        "input_files": {},
+        "runs_path": "runs.jsonl",
+        "artifact_contract_version": "1.0",
+    }
+    previous = {
+        "matrix_backend_summary": {
+            "bruteforce": {
+                "latency_p95_ms": {"mean": 3.0},
+                "qps": {"mean": 100.0},
+                "overlap_vs_bruteforce": {"mean": 1.0},
+            }
+        },
+        "stability_performance_summary": {
+            "latency_p95_ms": {"mean": 2.5},
+            "qps": {"mean": 100.0},
+        },
+    }
+    matrix_path = tmp_path / "matrix.json"
+    stability_path = tmp_path / "stability.json"
+    previous_path = tmp_path / "previous.json"
+    out_path = tmp_path / "publishable.json"
+    _write(matrix_path, matrix)
+    _write(stability_path, stability)
+    _write(previous_path, previous)
+    payload = build_publishable_summary(
+        matrix_summary_path=str(matrix_path),
+        stability_summary_path=str(stability_path),
+        out_path=str(out_path),
+        previous_summary_path=str(previous_path),
+    )
+    assert "release_over_release_delta" in payload
+    delta = payload["release_over_release_delta"]["stability_performance_delta"]
+    assert delta["latency_p95_ms_mean_delta"] < 0.0

{vector_engine-1.0.2 → vector_engine-1.1.1}/vector_engine/__init__.py

@@ -1,6 +1,6 @@
 """Vector Engine public API."""
 
-__version__ = "1.0.0"
+__version__ = "1.1.1"
 
 from .array import VectorArray
 from .index import VectorIndex

{vector_engine-1.0.2 → vector_engine-1.1.1}/vector_engine/backends/base.py

@@ -23,6 +23,9 @@ class BaseBackend(Protocol):
     def save(self, path: str) -> None:
         ...
 
+    def get_runtime_stats(self) -> dict[str, float | int | str]:
+        ...
+
     @classmethod
     def load(cls, path: str) -> "BaseBackend":
         ...

{vector_engine-1.0.2 → vector_engine-1.1.1}/vector_engine/backends/bruteforce.py

@@ -23,6 +23,8 @@ class BruteForceBackend:
             "supports_delete": False,
             "supports_custom_metric": True,
             "supports_persistence": True,
+            "supports_add": True,
+            "supports_ann_tuning": False,
         }
     )
     xb: np.ndarray | None = None
@@ -94,6 +96,18 @@ class BruteForceBackend:
                 f,
             )
 
+    def get_runtime_stats(self) -> dict[str, float | int | str]:
+        count = int(self.xb.shape[0]) if self.xb is not None else 0
+        dim = int(self.xb.shape[1]) if self.xb is not None else 0
+        metric_name = self.metric.name if self.metric is not None else "unknown"
+        return {
+            "backend": self.name,
+            "count": count,
+            "dim": dim,
+            "metric": metric_name,
+            "vector_bytes": int(self.xb.nbytes) if self.xb is not None else 0,
+        }
+
     @classmethod
     def load(cls, path: str) -> "BruteForceBackend":
         with open(os.path.join(path, "backend_meta.json"), "r", encoding="utf-8") as f:

{vector_engine-1.0.2 → vector_engine-1.1.1}/vector_engine/backends/faiss_backend.py

@@ -23,6 +23,8 @@ class FaissBackend:
             "supports_delete": False,
             "supports_custom_metric": False,
             "supports_persistence": True,
+            "supports_add": True,
+            "supports_ann_tuning": True,
         }
     )
     _index: object | None = None
@@ -110,6 +112,17 @@ class FaissBackend:
                 f,
             )
 
+    def get_runtime_stats(self) -> dict[str, float | int | str]:
+        metric_name = self._metric.name if self._metric is not None else "unknown"
+        config = self._config or {}
+        return {
+            "backend": self.name,
+            "count": int(self._count),
+            "metric": metric_name,
+            "index_factory": str(config.get("index_factory", "Flat")),
+            "nprobe": int(config.get("nprobe", 0)) if config.get("nprobe") is not None else 0,
+        }
+
     @classmethod
     def load(cls, path: str) -> "FaissBackend":
         backend = cls()

{vector_engine-1.0.2 → vector_engine-1.1.1}/vector_engine/index.py

@@ -55,6 +55,9 @@ class VectorIndex:
     _row_to_external: list[int | str] = field(default_factory=list)
     _metadata: list[dict[str, Any]] | None = None
     _dim: int = 0
+    _search_calls: int = 0
+    _last_search_k: int = 0
+    _last_search_nq: int = 0
 
     @classmethod
     def create(
@@ -121,6 +124,9 @@ class VectorIndex:
         if k <= 0:
             raise ValueError("index_error: k must be > 0")
         scores, internal_ids = self._backend.search(queries.values, k)
+        self._search_calls += 1
+        self._last_search_k = int(k)
+        self._last_search_nq = int(queries.shape[0])
         external_ids = _to_external_ids(internal_ids, self._row_to_external)
         md_out = None
         if return_metadata and self._metadata is not None:
@@ -136,6 +142,31 @@ class VectorIndex:
                 md_out.append(items)
         return SearchResult(ids=external_ids, scores=scores, metadata=md_out)
 
+    def backend_capabilities(self) -> dict[str, bool]:
+        if self._backend is None:
+            raise RuntimeError("index_error: index is not initialized")
+        caps = getattr(self._backend, "capabilities", None)
+        if not isinstance(caps, dict):
+            return {}
+        return {str(k): bool(v) for k, v in caps.items()}
+
+    def runtime_stats(self) -> dict[str, Any]:
+        if self._backend is None:
+            raise RuntimeError("index_error: index is not initialized")
+        backend_stats: dict[str, Any] = {}
+        if hasattr(self._backend, "get_runtime_stats"):
+            backend_stats = dict(getattr(self._backend, "get_runtime_stats")())
+        return {
+            "backend": self.backend_name,
+            "dim": int(self._dim),
+            "count": int(len(self._row_to_external)),
+            "search_calls": int(self._search_calls),
+            "last_search_k": int(self._last_search_k),
+            "last_search_nq": int(self._last_search_nq),
+            "capabilities": self.backend_capabilities(),
+            "backend_stats": backend_stats,
+        }
+
     def save(self, path: str) -> None:
         if self._backend is None:
             raise RuntimeError("index_error: index is not initialized")

vector_engine-1.0.2/README.md → vector_engine-1.1.1/vector_engine.egg-info/PKG-INFO

@@ -1,4 +1,36 @@
-# Vector Engine v1.0.0
+Metadata-Version: 2.4
+Name: vector-engine
+Version: 1.1.1
+Summary: ML-first vector computation and retrieval engine.
+Author: Neel Panchal
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/neelpanchal11/Vector-Engine
+Project-URL: Repository, https://github.com/neelpanchal11/Vector-Engine
+Project-URL: Issues, https://github.com/neelpanchal11/Vector-Engine/issues
+Project-URL: Documentation, https://github.com/neelpanchal11/Vector-Engine/tree/main/docs
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy<2.0,>=1.26.4
+Provides-Extra: faiss
+Requires-Dist: faiss-cpu>=1.7.4; (platform_system != "Darwin" or platform_machine != "arm64") and extra == "faiss"
+Provides-Extra: ml
+Requires-Dist: scikit-learn<1.7,>=1.4; extra == "ml"
+Provides-Extra: dev
+Requires-Dist: pytest<9,>=8.2; extra == "dev"
+Dynamic: license-file
+
+# Vector Engine v1.1.1
 
 Reproducibility-first vector retrieval toolkit for local ML and IR workflows.
 
@@ -77,7 +109,17 @@ results = index.search(xq, k=5)
 print(results.ids[0], results.scores[0])
 ```
 
-## v1.0.0 Surface
+## Colab Demos
+
+Each notebook opens directly from this repo, so it always matches the current release.
+
+- Semantic search: [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/neelpanchal11/Vector-Engine/blob/main/notebooks/01_semantic_search.ipynb)
+- kNN baseline classifier: [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/neelpanchal11/Vector-Engine/blob/main/notebooks/02_knn_baseline.ipynb)
+- Item-item recommender similarity: [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/neelpanchal11/Vector-Engine/blob/main/notebooks/03_recommender_similarity.ipynb)
+
+`notebooks/04_stability_runs.ipynb` analyzes locally generated benchmark artifacts (see [Reproducibility and Evidence](#reproducibility-and-evidence)) and is not a standalone Colab demo.
+
+## v1.1.0 Surface
 
 - Core: `VectorArray`, `VectorIndex`, `Metric`, `SearchResult`
 - ML: `knn_classify`, `knn_regress`, `kmeans`, `KMeansResult`
@@ -174,8 +216,8 @@ python scripts/credibility_audit.py --matrix-summary artifacts/benchmark_matrix/
 
 ## Project Links
 
-- `docs/releases/v1.0.0.md`
-- `docs/releases/v1.0.0-checklist.md`
+- `docs/releases/v1.1.0.md`
+- `docs/releases/v1.1.0-checklist.md`
 - `docs/reproducibility.md`
 - `docs/use_cases.md`
 - `docs/api_stability.md`

{vector_engine-1.0.2 → vector_engine-1.1.1}/vector_engine.egg-info/SOURCES.txt

@@ -12,6 +12,7 @@ tests/test_faiss_optional.py
 tests/test_hardening.py
 tests/test_ingest_pipeline.py
 tests/test_install_smoke.py
+tests/test_matrix_profile_advisor.py
 tests/test_ml_eval.py
 tests/test_perf_smoke.py
 tests/test_persistence_compat.py
@@ -19,6 +20,7 @@ tests/test_profile_local.py
 tests/test_rag_reliability.py
 tests/test_real_corpus_eval.py
 tests/test_release_bundle.py
+tests/test_release_performance_workflow.py
 tests/test_v02_features.py
 vector_engine/__init__.py
 vector_engine/array.py

vector_engine-1.0.2/pyproject.toml

@@ -1,32 +0,0 @@
-[build-system]
-requires = ["setuptools>=68", "wheel"]
-build-backend = "setuptools.build_meta"
-
-[project]
-name = "vector-engine"
-version = "1.0.2"
-description = "ML-first vector computation and retrieval engine."
-readme = "README.md"
-requires-python = ">=3.10"
-license = "MIT"
-authors = [
-  { name = "Neel Panchal" }
-]
-dependencies = [
-  "numpy>=1.26.4,<2.0",
-]
-
-[project.optional-dependencies]
-faiss = [
-  "faiss-cpu>=1.7.4; platform_system != 'Darwin' or platform_machine != 'arm64'",
-]
-ml = [
-  "scikit-learn>=1.4,<1.7",
-]
-dev = [
-  "pytest>=8.2,<9",
-]
-
-[tool.setuptools.packages.find]
-where = ["."]
-include = ["vector_engine*"]