arrowspace_tuner 0.2.0__tar.gz

arrowspace_tuner-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,57 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint:
+    name: ruff + mypy
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          version: "latest"
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies (no arrowspace — lint only)
+        run: uv sync --extra dev --no-install-project
+
+      - name: Lint (ruff)
+        run: uv run ruff check src
+
+      - name: Type check (mypy)
+        run: uv run mypy src
+
+  test:
+    name: pytest
+    runs-on: ubuntu-latest
+    needs: lint
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          version: "latest"
+
+      - name: Set up Python 3.12
+        run: uv python install 3.12
+
+      - name: Install project + dev dependencies
+        run: uv sync --extra dev
+
+      - name: Run tests
+        run: uv run pytest -v --cov=arrowspace_tuner --cov-report=term-missing

arrowspace_tuner-0.2.0/.gitignore

@@ -0,0 +1,26 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# Test artefacts
+.coverage
+htmlcov/
+.pytest_cache/
+
+# Local experiment outputs — keep folder, ignore contents
+results/*
+!results/.gitkeep
+
+# Local data
+data/
+
+.ruff_cache/
+.mypy_cache/
+ruff_errors.txt

arrowspace_tuner-0.2.0/.python-version

@@ -0,0 +1 @@
+3.13

arrowspace_tuner-0.2.0/CHANGELOG.md

@@ -0,0 +1,26 @@
+# Changelog
+
+All notable changes to `arrowspace_tuner` are documented here.
+Format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
+Versioning follows [Semantic Versioning](https://semver.org/).
+
+---
+
+## [0.1.0] — 2026-04-29
+
+Initial release.
+
+### Added
+
+- `EpsTuner` — main public class for hyperparameter discovery over `eps`, `k`, `tau`
+- `arrowspace_tuner.optuna()` — one-liner convenience API: `aspace, gl = arrowspace.optuna(embeddings)`
+- `StudyConfig` / `BuildParams` — typed dataclasses for power-user configuration
+- Query-free spectral objective: weighted composite of MRR-Top0 proxy, Fiedler value, and lambda variance
+- Optuna TPE sampler with pruning on degenerate graphs (NNZ ≤ N, disconnected, flat spectrum)
+- `sample_n` subsampling: 33x speedup on 50k corpus with identical best params (validated)
+- `storage` parameter for SQLite-backed persistence and parallel/resumed runs
+- `tuner.save_report()` — saves `trials.csv`, `best_params.json`, and Plotly HTML plots
+- `[report]` optional extra (pandas + plotly) — kept out of hard dependencies
+- `py.typed` marker — PEP 561 compliant, full mypy strict mode
+- Comprehensive test suite: `test_objective.py`, `test_tuner.py`, `conftest.py`
+- CI workflow: pytest + ruff + mypy on every push and pull request

arrowspace_tuner-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,56 @@
+# Contributing
+
+Thank you for contributing to **arrowspace-tuner**!
+
+## Commit Convention
+
+We use [Conventional Commits](https://www.conventionalcommits.org/). Every commit message must follow this format:
+
+```
+<type>: <short summary>
+
+[optional body]
+```
+
+### Types
+
+| Type | When to use |
+|---|---|
+| `feat` | New feature or behaviour |
+| `fix` | Bug fix |
+| `test` | Adding or fixing tests |
+| `refactor` | Code change with no behaviour change |
+| `chore` | Tooling, CI, dependencies, repo hygiene |
+| `docs` | Documentation only |
+| `perf` | Performance improvement |
+
+### Examples
+
+```
+feat: add early-stopping to EpsTuner.fit()
+fix: catch BaseException around ArrowSpace .build() for Rust panics
+test: add degenerate-corpus fixture for pruning paths
+chore: update .gitignore, remove .coverage artefact
+docs: add quickstart section to README
+```
+
+### Rules
+
+- Summary line ≤ 72 characters
+- Use the imperative mood: "add", not "added" or "adds"
+- Body explains **why**, not what (the diff shows the what)
+- Reference issues/PRs in the body: `Fixes #12`
+
+## Branch Names
+
+```
+feat/<short-description>
+fix/<short-description>
+chore/<short-description>
+```
+
+## Pull Requests
+
+- All PRs must pass CI (pytest + ruff + mypy) before merging
+- Squash-merge into `main`
+- PR title must follow the same conventional commit format

arrowspace_tuner-0.2.0/LICENSE

@@ -0,0 +1,13 @@
+   Copyright [2026] Tommaso Moriondo
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

arrowspace_tuner-0.2.0/PKG-INFO

@@ -0,0 +1,154 @@
+Metadata-Version: 2.4
+Name: arrowspace_tuner
+Version: 0.2.0
+Summary: Hyperparameter discovery (eps auto-tuning) for ArrowSpace via Optuna.
+Project-URL: Homepage, https://github.com/Genefold/arrowspace_tuner
+Project-URL: Repository, https://github.com/Genefold/arrowspace_tuner.git
+Author-email: Tommaso Moriondo <moriondotommaso@gmail.com>
+License: Apache-2.0
+License-File: LICENSE
+Keywords: arrowspace,graph-laplacian,hyperparameter-tuning,optuna,spectral-analysis,vector-search
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: arrowspace>=0.26.0
+Requires-Dist: numpy>=2.4.4
+Requires-Dist: optuna>=4.8.0
+Requires-Dist: scipy>=1.17.1
+Provides-Extra: dev
+Requires-Dist: mypy>=1.15; extra == 'dev'
+Requires-Dist: pandas>=3.0.0; extra == 'dev'
+Requires-Dist: plotly>=6.7.0; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.9; extra == 'dev'
+Provides-Extra: report
+Requires-Dist: pandas>=3.0.0; extra == 'report'
+Requires-Dist: plotly>=6.7.0; extra == 'report'
+Description-Content-Type: text/markdown
+
+# arrowspace_tuner
+
+[![CI](https://github.com/Genefold/arrowspace_tuner/actions/workflows/ci.yml/badge.svg)](https://github.com/Genefold/arrowspace_tuner/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/arrowspace-tuner)](https://pypi.org/project/arrowspace-tuner/)
+[![Python](https://img.shields.io/pypi/pyversions/arrowspace-tuner)](https://pypi.org/project/arrowspace-tuner/)
+[![License](https://img.shields.io/badge/license-Apache--2.0-blue)](LICENSE)
+
+Hyperparameter discovery for [ArrowSpace](https://github.com/tuned-org-uk/arrowspace-rs) — automatically finds the best `eps`, `k`, and `tau` for your corpus using a query-free spectral objective.
+
+## Why
+
+ArrowSpace's retrieval quality depends on three graph-construction parameters:
+
+| Parameter | What it controls |
+|---|---|
+| `eps` | Neighbourhood radius for graph edges |
+| `k` | Number of nearest neighbours per node |
+| `tau` | Search temperature (exploration vs. exploitation) |
+
+Setting these by hand is tedious and corpus-dependent. `arrowspace_tuner` uses [Optuna](https://optuna.org/) and a label-free spectral MRR proxy to find them automatically in minutes.
+
+## Install
+
+```bash
+# Core (no pandas/plotly)
+pip install arrowspace-tuner
+
+# With HTML/CSV reporting
+pip install arrowspace-tuner[report]
+```
+
+## Quickstart
+
+```python
+import numpy as np
+import arrowspace_tuner as arrowspace
+
+embeddings = np.load("corpus.npy")   # shape (N, D) float64
+
+# One-liner: auto-discover eps, k, tau — runs in ~15 min on 50k corpus
+aspace, gl = arrowspace.optuna(embeddings)
+
+# Search as normal
+results = aspace.search(query_embedding, gl, tau=0.8)
+```
+
+## Power-user API
+
+```python
+from arrowspace_tuner import EpsTuner
+
+tuner = EpsTuner(
+    n_trials  = 15,
+    sample_n  = 5_000,    # 33x faster: explore on 5k, final build on full corpus
+    eps_low   = 0.8,      # narrow bounds if you know your corpus geometry
+    eps_high  = 2.5,
+    k_low     = 15,
+    k_high    = 40,
+    tau_low   = 0.05,
+    tau_high  = 0.5,
+    n_probe   = 50,
+    storage   = "sqlite:///tune.db",   # resume interrupted runs
+)
+
+aspace, gl = tuner.fit(embeddings)
+
+print(tuner.best_params)    # {"eps": 1.615, "k": 38, "tau": 0.114}
+print(tuner.best_score)     # 2.138
+print(tuner.best_fiedler)   # 0.718  — graph connectivity health
+print(tuner.best_mrr_proxy) # 2.896  — retrieval coherence proxy
+
+# Save CSV + HTML plots (requires [report] extra)
+tuner.save_report(out_dir="results")
+```
+
+## Speed
+
+The dominant cost is building the ArrowSpace graph on N vectors. With `sample_n`:
+
+| Setting | Per trial | 15 trials | Notes |
+|---|---|---|---|
+| sample_n = 50k | ~23 min | ~5.8h | baseline |
+| `sample_n=5_000` | ~1.5 min | **~27 min** | **33x faster, same best params** |
+
+The final build after the study always uses the full corpus.
+
+## Objective
+
+The objective is a weighted composite of three spectral signals — no ground-truth labels required:
+
+```
+score = 0.70 * mrr_top0_spectral   # retrieval coherence
+      + 0.20 * log1p(fiedler)      # graph connectivity health
+      + 0.10 * log1p(var_lambda)   # spectral richness
+```
+
+## Parallel runs
+
+Optuna + SQLite lets you run multiple workers simultaneously:
+
+```bash
+# Terminal 1
+python -m arrowspace_tuner --storage sqlite:///tune.db --trials 15
+
+# Terminal 2 (simultaneously)
+python -m arrowspace_tuner --storage sqlite:///tune.db --trials 15
+```
+
+## Requirements
+
+- Python ≥ 3.12
+- `arrowspace >= 0.26.0`
+- `optuna >= 4.8.0`
+- `scipy >= 1.17.1`
+- `numpy >= 2.4.4`
+
+## License
+
+Apache-2.0 — see [LICENSE](LICENSE).

arrowspace_tuner-0.2.0/README.md

@@ -0,0 +1,119 @@
+# arrowspace_tuner
+
+[![CI](https://github.com/Genefold/arrowspace_tuner/actions/workflows/ci.yml/badge.svg)](https://github.com/Genefold/arrowspace_tuner/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/arrowspace-tuner)](https://pypi.org/project/arrowspace-tuner/)
+[![Python](https://img.shields.io/pypi/pyversions/arrowspace-tuner)](https://pypi.org/project/arrowspace-tuner/)
+[![License](https://img.shields.io/badge/license-Apache--2.0-blue)](LICENSE)
+
+Hyperparameter discovery for [ArrowSpace](https://github.com/tuned-org-uk/arrowspace-rs) — automatically finds the best `eps`, `k`, and `tau` for your corpus using a query-free spectral objective.
+
+## Why
+
+ArrowSpace's retrieval quality depends on three graph-construction parameters:
+
+| Parameter | What it controls |
+|---|---|
+| `eps` | Neighbourhood radius for graph edges |
+| `k` | Number of nearest neighbours per node |
+| `tau` | Search temperature (exploration vs. exploitation) |
+
+Setting these by hand is tedious and corpus-dependent. `arrowspace_tuner` uses [Optuna](https://optuna.org/) and a label-free spectral MRR proxy to find them automatically in minutes.
+
+## Install
+
+```bash
+# Core (no pandas/plotly)
+pip install arrowspace-tuner
+
+# With HTML/CSV reporting
+pip install arrowspace-tuner[report]
+```
+
+## Quickstart
+
+```python
+import numpy as np
+import arrowspace_tuner as arrowspace
+
+embeddings = np.load("corpus.npy")   # shape (N, D) float64
+
+# One-liner: auto-discover eps, k, tau — runs in ~15 min on 50k corpus
+aspace, gl = arrowspace.optuna(embeddings)
+
+# Search as normal
+results = aspace.search(query_embedding, gl, tau=0.8)
+```
+
+## Power-user API
+
+```python
+from arrowspace_tuner import EpsTuner
+
+tuner = EpsTuner(
+    n_trials  = 15,
+    sample_n  = 5_000,    # 33x faster: explore on 5k, final build on full corpus
+    eps_low   = 0.8,      # narrow bounds if you know your corpus geometry
+    eps_high  = 2.5,
+    k_low     = 15,
+    k_high    = 40,
+    tau_low   = 0.05,
+    tau_high  = 0.5,
+    n_probe   = 50,
+    storage   = "sqlite:///tune.db",   # resume interrupted runs
+)
+
+aspace, gl = tuner.fit(embeddings)
+
+print(tuner.best_params)    # {"eps": 1.615, "k": 38, "tau": 0.114}
+print(tuner.best_score)     # 2.138
+print(tuner.best_fiedler)   # 0.718  — graph connectivity health
+print(tuner.best_mrr_proxy) # 2.896  — retrieval coherence proxy
+
+# Save CSV + HTML plots (requires [report] extra)
+tuner.save_report(out_dir="results")
+```
+
+## Speed
+
+The dominant cost is building the ArrowSpace graph on N vectors. With `sample_n`:
+
+| Setting | Per trial | 15 trials | Notes |
+|---|---|---|---|
+| sample_n = 50k | ~23 min | ~5.8h | baseline |
+| `sample_n=5_000` | ~1.5 min | **~27 min** | **33x faster, same best params** |
+
+The final build after the study always uses the full corpus.
+
+## Objective
+
+The objective is a weighted composite of three spectral signals — no ground-truth labels required:
+
+```
+score = 0.70 * mrr_top0_spectral   # retrieval coherence
+      + 0.20 * log1p(fiedler)      # graph connectivity health
+      + 0.10 * log1p(var_lambda)   # spectral richness
+```
+
+## Parallel runs
+
+Optuna + SQLite lets you run multiple workers simultaneously:
+
+```bash
+# Terminal 1
+python -m arrowspace_tuner --storage sqlite:///tune.db --trials 15
+
+# Terminal 2 (simultaneously)
+python -m arrowspace_tuner --storage sqlite:///tune.db --trials 15
+```
+
+## Requirements
+
+- Python ≥ 3.12
+- `arrowspace >= 0.26.0`
+- `optuna >= 4.8.0`
+- `scipy >= 1.17.1`
+- `numpy >= 2.4.4`
+
+## License
+
+Apache-2.0 — see [LICENSE](LICENSE).

arrowspace_tuner-0.2.0/pyproject.toml

@@ -0,0 +1,110 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "arrowspace_tuner"
+version = "0.2.0"
+description = "Hyperparameter discovery (eps auto-tuning) for ArrowSpace via Optuna."
+readme = "README.md"
+license = { text = "Apache-2.0" }
+authors = [
+    { name = "Tommaso Moriondo", email = "moriondotommaso@gmail.com" },
+]
+requires-python = ">=3.12"
+keywords = [
+    "vector-search",
+    "spectral-analysis",
+    "hyperparameter-tuning",
+    "optuna",
+    "arrowspace",
+    "graph-laplacian",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+
+# ── Hard dependencies ──────────────────────────────────────────────────────
+# These are always required: the Rust wheel, Optuna, SciPy for Fiedler, NumPy.
+# plotly and pandas are NOT here — they are opt-in via [report].
+dependencies = [
+    "arrowspace>=0.26.0",
+    "numpy>=2.4.4",
+    "optuna>=4.8.0",
+    "scipy>=1.17.1",
+]
+
+# ── Optional extras ─────────────────────────────────────────────────────────
+[project.optional-dependencies]
+
+# pip install arrowspace_tuner[report]
+# Needed for tuner.save_report() and all HTML/CSV output from reporter.py
+report = [
+    "plotly>=6.7.0",
+    "pandas>=3.0.0",
+]
+
+# pip install arrowspace_tuner[dev]
+# Full dev environment: testing + linting + type checking
+dev = [
+    "pytest>=8.0",
+    "pytest-cov>=5.0",
+    "ruff>=0.9",
+    "mypy>=1.15",
+    "plotly>=6.7.0",   # needed to test reporter.py
+    "pandas>=3.0.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/Genefold/arrowspace_tuner"
+Repository = "https://github.com/Genefold/arrowspace_tuner.git"
+
+# ── Hatchling config ───────────────────────────────────────────────────────────
+[tool.hatch.build.targets.wheel]
+packages = ["src/arrowspace_tuner"]
+exclude = [
+    "tests/",
+    "notebooks/",
+    "docs/",
+    ".github/",
+    "*.db",
+    "*.sqlite",
+    "*.ipynb",
+    ".ruff_cache/",
+    ".mypy_cache/",
+    ".pytest_cache/",
+    "dist/",
+    "*.egg-info/",
+]
+
+# ── Ruff ──────────────────────────────────────────────────────────────────
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "ANN"]
+ignore = ["ANN101"]
+
+# ── Mypy ────────────────────────────────────────────────────────────────────
+[tool.mypy]
+python_version = "3.12"
+strict = true
+ignore_missing_imports = true   # arrowspace has no stubs
+
+# ── Pytest ─────────────────────────────────────────────────────────────────
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "--cov=arrowspace_tuner --cov-report=term-missing"
+
+[dependency-groups]
+dev = [
+    "twine>=6.2.0",
+]

arrowspace_tuner-0.2.0/scripts/test_eval.py

@@ -0,0 +1,83 @@
+#!/usr/bin/env python3
+"""
+scripts/test_eval.py
+====================
+Run the arrowspace_tuner optimisation pipeline on the CVE .npy corpus.
+
+    uv run python scripts/test_eval.py \
+        --data  data/cve_embs/cve1999-2025.npy \
+        --n     50000 \
+        --trials 20 \
+        --seed  42
+"""
+from __future__ import annotations
+
+import argparse
+import logging
+
+import numpy as np
+
+from arrowspace_tuner.tuner import EpsTuner
+
+logging.basicConfig(
+    level=logging.INFO,
+    format="[%(asctime)s] %(levelname)s %(name)s | %(message)s",
+)
+log = logging.getLogger(__name__)
+
+
+def load_npy(path: str, n: int, seed: int) -> np.ndarray:
+    log.info("Loading %s …", path)
+    X = np.load(path)
+    log.info("  full shape : %s  dtype=%s", X.shape, X.dtype)
+    n = min(n, len(X))
+    rng = np.random.default_rng(seed)
+    idx = rng.choice(len(X), size=n, replace=False)
+    idx.sort()
+    X = X[idx].astype(np.float64)
+    norms = np.linalg.norm(X, axis=1, keepdims=True)
+    X = X / np.clip(norms, 1e-12, None)
+    log.info("  subsample  : %s  (L2-normalised)", X.shape)
+    return X
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--data",   default="data/cve_embs/cve1999-2025.npy")
+    parser.add_argument("--n",      type=int, default=5000)
+    parser.add_argument("--trials", type=int, default=20)
+    parser.add_argument("--seed",   type=int, default=54)
+
+    args = parser.parse_args()
+
+    embeddings = load_npy(args.data, args.n, args.seed)
+
+    tuner = EpsTuner(
+        n_trials   = args.trials,
+        sample_n   = None,          # already subsampled above
+        seed       = args.seed,
+        study_name = "cve_arrowspace_fstar",
+        storage    = None,
+    )
+
+    log.info("Starting | n=%d  trials=%d  seed=%d", len(embeddings), args.trials, args.seed)
+
+    aspace, gl = tuner.fit(embeddings)
+
+    print("\n=== Best result ===")
+    print(f"  F**        : {tuner.best_score:.8f}")
+    print(f"  eps        : {tuner.best_params['eps']:.5f}")
+    print(f"  k          : {tuner.best_params['k']}")
+    print(f"  tau        : {tuner.best_params['tau']:.4f}")
+    print(f"  fiedler    : {tuner.best_fiedler}")
+    print(f"  var_lambda : {tuner.best_var_lambda}")
+    print(f"  mrr_proxy  : {tuner.best_mrr_proxy}")
+    print(f"\n  ArrowSpace : {aspace}")
+    print(f"  Graph      : {gl}")
+
+    tuner.save_report(out_dir="results")
+    log.info("Report saved to results/")
+
+
+if __name__ == "__main__":
+    main()

arrowspace_tuner-0.2.0/src/arrowspace_tuner/__init__.py

@@ -0,0 +1,40 @@
+"""
+arrowspace_tuner — hyperparameter discovery for ArrowSpace.
+
+Quickstart
+----------
+    import numpy as np
+    import arrowspace_tuner as arrowspace
+
+    embeddings = np.load("corpus.npy")
+
+    # one-liner: auto-discover eps, k, tau
+    aspace, gl = arrowspace.optuna(embeddings)
+
+    # power-user: full control + post-run inspection
+    from arrowspace_tuner import EpsTuner
+
+    tuner = EpsTuner(n_trials=100, sample_n=10_000, eps_low=0.5, eps_high=3.0)
+    aspace, gl = tuner.fit(embeddings)
+    print(tuner.best_params)    # {"eps": 1.2, "k": 14, "tau": 0.8}
+    print(tuner.best_score)
+    tuner.save_report()         # requires pip install arrowspace-tuner[report]
+"""
+from .api import optuna
+
+# Power-user exports: config dataclasses for advanced customisation
+from .core import BuildParams, StudyConfig
+from .tuner import EpsTuner
+
+__version__ = "0.1.0"
+
+__all__ = [
+    # primary public API
+    "optuna",
+    "EpsTuner",
+    # config — for power users
+    "BuildParams",
+    "StudyConfig",
+    # version
+    "__version__",
+]