pyvectorhound 1.1.1__tar.gz → 1.3.0__tar.gz

{pyvectorhound-1.1.1 → pyvectorhound-1.3.0}/.github/workflows/ci.yml

@@ -40,8 +40,14 @@ jobs:
         with:
           python-version: ${{ matrix.python-version }}
 
+      - name: Install maturin
+        run: pip install "maturin>=1.7,<2.0"
+
+      - name: Build and install extension module
+        run: maturin develop --release
+
       - name: Install dependencies
-        run: cd python && pip install -e ".[dev]"
+        run: pip install -e ".[dev]"
 
       - name: Run pytest
-        run: if [ -d "python/tests" ]; then cd python && pytest tests/ -v --tb=short; else echo "No Python tests found"; fi
+        run: pytest tests/ -v --tb=short

pyvectorhound-1.3.0/CHANGELOG.md

@@ -0,0 +1,110 @@
+# Changelog
+
+All notable changes to PyVectorHound are documented in this file.
+
+## [1.3.0] - 2026-08-16
+
+First PyPI release. This release fixes the diagnostic engine's core
+functionality, which was previously non-functional despite the codebase's
+size and test count:
+
+### Fixed
+- **Rust extension was unreachable.** The compiled native module's PyO3
+  entry point was named `pyhound_core`, but `pyproject.toml` /
+  `Cargo.toml` build it as `pyvectorhound._core`; the mismatched `PyInit_`
+  symbol meant the import always failed. `Diagnosis.analyze()` and
+  `QualityScorer.score()` additionally imported it from a nonexistent
+  `pyhound` package. Both are fixed and covered by a real test that spies
+  on the Rust call to confirm it executes.
+- **`Diagnosis.analyze()` fabricated its results.** Embedding quality,
+  BM25, and reranker analysis returned hardcoded constants regardless of
+  input. They now compute real metrics (via the Rust core, with an
+  equivalent pure-Python fallback) from the embeddings/scores actually
+  supplied, and report `"UNAVAILABLE"`/`"UNKNOWN"` with an explanation
+  instead of a number when the required input wasn't given.
+- **`Hound.diagnose()` fabricated the query embedding.** A query with no
+  `query_embedding` used to get a random vector (`np.random.randn`),
+  silently producing meaningless diagnoses. It now requires a
+  `query_embedding` or a configured `embed_fn` and raises a clear
+  `ValueError` otherwise. **This is a breaking change** for callers that
+  relied on the old silent fallback.
+- Database adapters (Qdrant/Chroma/Milvus/pgvector/Weaviate) returned the
+  *query* embedding as every result's `"embedding"`, corrupting any
+  downstream embedding-space analysis. They now fetch and return the
+  actual per-document embedding.
+- CI's Python test job referenced a nonexistent `python/` subdirectory and
+  never built the Rust extension, so it silently ran zero tests. It now
+  builds via `maturin develop --release` and runs the real suite at the
+  repo root.
+- `pydantic` was used in `database.py`/`validation.py` but missing from
+  `pyproject.toml` dependencies, so a clean install of `pyvectorhound`
+  failed on import. Added as a dependency.
+- Base dependencies pinned exact old versions (e.g. `numpy==1.20.0`) with
+  no wheels for the Python versions this package claims to support (up to
+  3.12); relaxed to compatible ranges. `dev` extras pinned a yanked/removed
+  `black` version, breaking `pip install .[dev]` entirely.
+- `Hound.__init__` eagerly connected to the database, requiring the
+  optional client library and a live server just to construct a `Hound`.
+  Connection is now lazy, matching every adapter method's existing
+  lazy-connect behavior.
+- `ModelComparison`/`compare_models()` fabricated quality scores
+  (`f1_score`, `ndcg`, etc.) from `hash(model_name)`. It now reports only
+  real published cost/latency metadata unless a `quality_fn` is supplied
+  for real, measured quality numbers.
+- `Hound.compare_metrics()`, `Hound.detect_drift()`, and
+  `QualityScorer.trend_analysis()` returned fixed placeholder output
+  (zeros / `"stable"` / `"No action needed"`) regardless of input, with no
+  backing data store. They now raise `NotImplementedError` pointing to the
+  real, tested alternative (`track_metric()` + `get_trend_report()` /
+  `TrendAnalyzer.detect_drift()`).
+- Removed `tests/test_vector_operations.py`, which tested `VectorStore`
+  and `EmbeddingManager` classes that do not exist anywhere in this
+  codebase and are not part of this package's scope (diagnosing failures
+  in databases you already run, not being one); its import error was
+  aborting the entire test suite before any test could run.
+
+### Added
+- `Hound(embed_fn=...)`: optional callable to embed queries (wrapping
+  OpenAI, Cohere, sentence-transformers, etc.), since PyVectorHound does
+  not bundle an embedding model itself.
+- `QualityScorer.score(embedding, reference_embeddings=...)` and
+  `QualityScorer.corpus_health(sample_embeddings=...)`: real
+  isotropy/coverage/distinctiveness against a supplied embedding sample.
+
+## [0.1.1] - 2025-01-20
+
+### Added
+- Component-level diagnostics for retrieval pipelines
+- Root cause analysis for embedding failures
+- Recommendations engine with ROI estimates
+- Support for Elasticsearch, Weaviate, and Pinecone
+- BM25 keyword search diagnostics
+- Reranker performance analysis
+
+### Fixed
+- Memory efficiency improvements in large batch processing
+- Vector similarity computation accuracy
+
+## [0.1.0] - 2024-12-15
+
+### Added
+- Initial release
+- Core retrieval diagnostics engine
+- Embedding quality assessment
+- Vector search performance profiling
+- MIT license
+
+### Known Issues
+- Streaming RAG pipelines not yet supported
+- LLamaIndex integration in progress
+
+## [Unreleased]
+
+### Planned
+- Streaming RAG support
+- LLamaIndex integration
+- Custom metric definitions
+- Dashboard UI
+- API server mode
+
+For details, see [ROADMAP.md](../ROADMAP.md).

{pyvectorhound-1.1.1 → pyvectorhound-1.3.0}/Cargo.lock

@@ -1,6 +1,6 @@
 # This file is automatically @generated by Cargo.
 # It is not intended for manual editing.
-version = 3
+version = 4
 
 [[package]]
 name = "autocfg"
@@ -37,9 +37,9 @@ checksum = "8f42a60cbdf9a97f5d2305f08a87dc4e09308d1276d28c869c684d7777685682"
 
 [[package]]
 name = "libc"
-version = "0.2.186"
+version = "0.2.189"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "68ab91017fe16c622486840e4c83c9a37afeff978bd239b5293d61ece587de66"
+checksum = "3eaf3ede3fee6db1a4c2ee091bf8a8b4dccdc6d17f656fb07896ee72867612f2"
 
 [[package]]
 name = "matrixmultiply"
@@ -146,9 +146,9 @@ dependencies = [
 
 [[package]]
 name = "proc-macro2"
-version = "1.0.106"
+version = "1.0.107"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "8fd00f0bb2e90d81d1044c2b32617f68fcb9fa3bb7640c23e9c748e53fb30934"
+checksum = "985e7ec9bb745e6ce6535b544d84d6cd6f7ad8bd711c398938ae983b91a766d9"
 dependencies = [
  "unicode-ident",
 ]
@@ -200,7 +200,7 @@ dependencies = [
  "proc-macro2",
  "pyo3-macros-backend",
  "quote",
- "syn",
+ "syn 2.0.119",
 ]
 
 [[package]]
@@ -213,12 +213,12 @@ dependencies = [
  "proc-macro2",
  "pyo3-build-config",
  "quote",
- "syn",
+ "syn 2.0.119",
 ]
 
 [[package]]
 name = "pyvectorhound"
-version = "1.0.0"
+version = "1.3.0"
 dependencies = [
  "numpy",
  "pyo3",
@@ -228,9 +228,9 @@ dependencies = [
 
 [[package]]
 name = "quote"
-version = "1.0.46"
+version = "1.0.47"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "dfbc457d0c7a0759a614551b11a6409e5951f6c7537be1f1b7682b9ae9230368"
+checksum = "1fbf4db142a473a8d80c26bbf18454ed458bf8d26c8219c331daecfdbd079001"
 dependencies = [
  "proc-macro2",
 ]
@@ -255,9 +255,9 @@ checksum = "cf54715a573b99ac80df0bc206da022bcd442c974952c7b9720069370852e21f"
 
 [[package]]
 name = "serde"
-version = "1.0.228"
+version = "1.0.229"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "9a8e94ea7f378bd32cbbd37198a4a91436180c5bb472411e48b5ec2e2124ae9e"
+checksum = "4148590afebada386688f18773da617792bf2ef03ffc1e4cbd2b1d45b023e0ba"
 dependencies = [
  "serde_core",
  "serde_derive",
@@ -265,29 +265,29 @@ dependencies = [
 
 [[package]]
 name = "serde_core"
-version = "1.0.228"
+version = "1.0.229"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "41d385c7d4ca58e59fc732af25c3983b67ac852c1a25000afe1175de458b67ad"
+checksum = "67dca2c9c51e58a4791a4b1ed58308b39c64224d349a935ab5039aa360942a48"
 dependencies = [
  "serde_derive",
 ]
 
 [[package]]
 name = "serde_derive"
-version = "1.0.228"
+version = "1.0.229"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "d540f220d3187173da220f885ab66608367b6574e925011a9353e4badda91d79"
+checksum = "e7a5d71263a5a7d47b41f6b3f06ba276f10cc18b0931f1799f710578e2309348"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn",
+ "syn 3.0.3",
 ]
 
 [[package]]
 name = "serde_json"
-version = "1.0.150"
+version = "1.0.151"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "e8014e44b4736ed0538adeecded0fce2a272f22dc9578a7eb6b2d9993c74cfb9"
+checksum = "c841b55ecdae098c80dcae9cf767f6f8a0c2cdb3416bbef72181df4d0fe73f14"
 dependencies = [
  "itoa",
  "memchr",
@@ -307,6 +307,17 @@ dependencies = [
  "unicode-ident",
 ]
 
+[[package]]
+name = "syn"
+version = "3.0.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "53e9bae58849f64dfa4f5d5ae372c8341f7305f82a3868709269343628b659a3"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "unicode-ident",
+]
+
 [[package]]
 name = "target-lexicon"
 version = "0.12.16"

{pyvectorhound-1.1.1 → pyvectorhound-1.3.0}/Cargo.toml

@@ -1,9 +1,9 @@
 [package]
 name = "pyvectorhound"
-version = "1.0.0"
+version = "1.3.0"
 edition = "2021"
 authors = ["Georgi Mammen Mullassery <mullassery@gmail.com>"]
-license = "MIT"
+license = "Proprietary"
 description = "Vector search diagnostics engine for RAG/LLM systems"
 readme = "README.md"
 

pyvectorhound-1.3.0/DASHBOARD_SHORTCUTS.md

@@ -0,0 +1,161 @@
+# 🎯 Dashboard Keyboard Shortcuts & Usage
+
+## Auto-Start on Installation
+
+The CLI dashboard **starts automatically** when you run the package for the first time or import it in Python:
+
+```bash
+$ pip install [package]
+# ✓ Dashboard appears in terminal automatically
+
+$ python3 -c "from [package] import *"
+# ✓ Dashboard initializes in background
+```
+
+The dashboard runs in **persistent daemon mode** — if you close it, it restarts automatically with your keyboard shortcuts.
+
+---
+
+## ⌨️ Keyboard Shortcuts
+
+After installing the package, run:
+
+```bash
+bash <(curl -s https://raw.githubusercontent.com/Mullassery/[PACKAGE]/main/scripts/setup_shortcuts.sh)
+```
+
+This adds aliases to your `~/.zshrc` or `~/.bashrc`:
+
+### Quick Access (all packages)
+
+```bash
+dashboards                      # Show all available dashboard shortcuts
+```
+
+### Per-Package Shortcuts
+
+Replace `[PACKAGE]` with any installed Mullassery package name:
+
+```bash
+dash-[PACKAGE]                  # Static snapshot (single view)
+dash-[PACKAGE]-live             # Live dashboard (Ctrl+C to close)
+dash-[PACKAGE]-export           # Export metrics to JSON
+```
+
+### Examples
+
+```bash
+# PyStreamAI
+$ dash-pystreamai               # View deployment metrics snapshot
+$ dash-pystreamai-live          # Watch real-time inference latency
+$ dash-pystreamai-export        # Save metrics for monitoring
+
+# PyRoboReplay
+$ dash-pyroboreplay             # View RGB+Thermal fusion status
+$ dash-pyroboreplay-live        # Monitor decision reconstruction in real-time
+$ dash-pyroboreplay-export      # Export to Prometheus/Datadog
+
+# PyTerrainMap
+$ dash-pyterrainmap             # View spatial layer metrics
+$ dash-pyterrainmap-live        # Watch fleet learning converge
+$ dash-pyterrainmap-export      # Save to /tmp/pyterrainmap_metrics.json
+```
+
+---
+
+## 🔄 Dashboard Modes
+
+### Static Snapshot (`--static`)
+```bash
+$ dash-pystreamai               # Single view, exits immediately
+# Useful for: CI/CD logs, monitoring integration, one-time checks
+```
+
+### Live View (`--live`)
+```bash
+$ dash-pystreamai-live          # Continuous updates until Ctrl+C
+# Useful for: real-time monitoring, troubleshooting, development
+```
+
+### JSON Export (`--export`)
+```bash
+$ dash-pystreamai-export        # Saves to /tmp/pystreamai_metrics.json
+# Useful for: integration with Prometheus, Datadog, custom dashboards
+```
+
+---
+
+## 🛑 Remove Keyboard Shortcuts
+
+To uninstall all dashboard aliases:
+
+```bash
+bash <(curl -s https://raw.githubusercontent.com/Mullassery/[PACKAGE]/main/scripts/setup_shortcuts.sh) --remove
+```
+
+This removes all `dash-*` aliases from your shell config.
+
+---
+
+## 📊 Monitoring Integration
+
+Export metrics for external monitoring systems:
+
+```bash
+# Prometheus
+$ dash-pystreamai-export > prometheus_metrics.txt
+
+# Datadog (with custom agent)
+$ dash-pystreamai-live | \
+  grep -o 'Status.*' | \
+  datadog-agent custom-metric
+
+# JSON for custom dashboards
+$ dash-pystreamai-export | jq '.metrics'
+```
+
+---
+
+## ❓ Troubleshooting
+
+**Shortcuts not working?**
+```bash
+# Reload shell config
+$ source ~/.zshrc          # macOS/Linux (zsh)
+$ source ~/.bashrc         # Linux (bash)
+
+# Or restart your terminal
+```
+
+**Dashboard won't start?**
+```bash
+# Ensure package is installed
+$ pip list | grep pystreamai
+
+# Start manually
+$ pystreamai dashboard --static
+```
+
+**Dashboard keeps closing?**
+```bash
+# Use live mode (restarts automatically)
+$ dash-pystreamai-live
+```
+
+---
+
+## 📖 Package-Specific Shortcuts
+
+The following Mullassery packages support dashboard shortcuts:
+
+- ✅ PyStreamAI (deployment metrics)
+- ✅ PyStreamMCP (tool orchestration)
+- ✅ PyStreamPDF (document processing)
+- ✅ PyStreamXL (formula extraction)
+- ✅ StatGuardian (data quality)
+- ✅ PyReverseETL (activation pipelines)
+- ✅ PyTerrainMap (spatial analysis)
+- ✅ PyRoboReplay (multi-modal fusion)
+- ✅ PyRoboSimulator (world engine)
+
+Run `dashboards` to see all available shortcuts.