pyvectorhound 0.1.0__tar.gz → 1.1.0__tar.gz

pyvectorhound-1.1.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,39 @@
+---
+name: Bug Report
+about: Report a bug to help us improve
+title: "[BUG] "
+labels: bug
+assignees: ''
+---
+
+## Description
+Briefly describe the bug.
+
+## Steps to Reproduce
+1. ...
+2. ...
+3. ...
+
+## Expected Behavior
+What should happen?
+
+## Actual Behavior
+What actually happened?
+
+## Environment
+- OS: [e.g. macOS, Linux, Windows]
+- Python version: [e.g. 3.10]
+- Library version: [e.g. 2.0.0]
+
+## Minimal Example
+```python
+# Minimal code to reproduce the bug
+```
+
+## Error Message
+```
+# Paste full error traceback here
+```
+
+## Additional Context
+Any other context about the issue?

pyvectorhound-1.1.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,27 @@
+---
+name: Feature Request
+about: Suggest an idea to improve the project
+title: "[FEATURE] "
+labels: enhancement
+assignees: ''
+---
+
+## Problem Statement
+Describe the problem this feature would solve.
+
+## Proposed Solution
+How should this feature work?
+
+## Use Case
+What use case does this solve?
+
+## Example
+```python
+# Example of how this would be used
+```
+
+## Alternatives
+Any alternative approaches you've considered?
+
+## Additional Context
+Any other context or screenshots?

pyvectorhound-1.1.0/.github/dependabot.yml

@@ -0,0 +1,35 @@
+version: 2
+updates:
+  # Python dependencies (pip/pyproject.toml)
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+      time: "03:00"
+    open-pull-requests-limit: 5
+    reviewers:
+      - "Mullassery"
+    labels:
+      - "dependencies"
+      - "python"
+    commit-message:
+      prefix: "chore(deps):"
+      include: "scope"
+
+  # GitHub Actions
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+      time: "03:00"
+    open-pull-requests-limit: 3
+    reviewers:
+      - "Mullassery"
+    labels:
+      - "dependencies"
+      - "ci"
+    commit-message:
+      prefix: "chore(ci):"
+      include: "scope"

pyvectorhound-1.1.0/.github/workflows/ci.yml

@@ -0,0 +1,47 @@
+name: Tests & Build
+
+on:
+  push:
+    branches: [main, develop]
+  pull_request:
+    branches: [main]
+
+jobs:
+  rust-build:
+    name: Rust Build & Test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: dtolnay/rust-toolchain
+
+      - uses: Swatinem/rust-cache@v2
+
+      - name: Build Rust
+        run: cargo build --release --all-features
+
+      - name: Test Rust
+        run: cargo test --release --all-features
+
+  python-tests:
+    name: Python Tests (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: dtolnay/rust-toolchain
+
+      - uses: Swatinem/rust-cache@v2
+
+      - uses: actions/setup-python@v4
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+
+      - name: Run pytest
+        run: pytest tests/ -v --tb=short

pyvectorhound-1.1.0/.pre-commit-config.yaml

@@ -0,0 +1,33 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.5.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-added-large-files
+        args: ['--maxkb=500']
+
+  - repo: https://github.com/rust-lang/rust-clippy
+    rev: v1.77.0
+    hooks:
+      - id: clippy
+        args: ['--all-targets', '--', '-W', 'clippy::all']
+
+  - repo: https://github.com/rust-lang/rustfmt
+    rev: v1.7.0
+    hooks:
+      - id: rustfmt
+
+  - repo: https://github.com/psf/black
+    rev: 24.1.1
+    hooks:
+      - id: black
+        language_version: python3
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.2.0
+    hooks:
+      - id: ruff
+        args: ['--fix']
+      - id: ruff-format

pyvectorhound-1.1.0/ARCHITECTURE.md

@@ -0,0 +1,249 @@
+# PyVectorHound Architecture & PyStreamMCP Integration
+
+## Mission
+
+**Debug & Optimize Retrieval**
+
+Core Question: Why did this retrieval work (or fail)? How do we improve it?
+
+## Core Responsibility
+
+PyVectorHound is **exclusively responsible** for:
+
+- **Retrieval Debugging** — Understanding why queries returned specific results
+- **Relevance Analysis** — Scoring retrieved documents for relevance
+- **Failure Analysis** — Root-cause analysis of retrieval failures
+- **Replay & Forensics** — Replaying queries to debug issues
+- **Quality Scoring** — Measuring retrieval quality
+- **Attribution Analysis** — Tracing why a result was retrieved
+
+## What We Do NOT Own
+
+### ❌ Query Optimization (PyStreamMCP)
+- Query planning
+- Source discovery
+- Token optimization
+- Streaming retrieval
+- Cost estimation
+
+**Our role:** Debug & analyze queries that PyStreamMCP produces.
+
+### ❌ Data Validation (StatGuardian)
+- Schema validation
+- Data freshness
+- Drift detection
+
+**Our role:** Assume data is valid, focus on why it was/wasn't retrieved.
+
+## Critical: Use PyStreamMCP, Don't Rebuild It
+
+**IMPORTANT:** PyVectorHound must integrate with PyStreamMCP rather than rebuilding query functionality.
+
+### Architecture Pattern
+
+```
+Query
+    ↓
+PyStreamMCP (Optimization & Execution)
+    ↓
+Retrieval Results
+    ↓
+PyVectorHound (Debug & Analyze)
+    ↓
+Root Cause Analysis & Insights
+    ↓
+Feedback Loop to PyStreamMCP
+```
+
+### Integration Example
+
+```python
+# ✅ CORRECT: Use PyStreamMCP's query execution
+from pystreammcp import Agent, QueryExecutor
+from pyvectorhound import RetrievalDebugger
+
+# Create query with PyStreamMCP
+agent = Agent(agent_id="debug_query")
+query_result = agent.query("customer data")
+
+# Debug why this query returned these results
+debugger = RetrievalDebugger(query_result)
+analysis = debugger.analyze()
+# - Why were these documents retrieved?
+# - What sources were queried?
+# - What was the token cost?
+# - Could we have done better?
+
+# Get root causes
+root_causes = analysis.root_causes()
+# - Low relevance due to source X
+# - Token budget exceeded, missing source Y
+# - Query optimization missed source Z
+
+# Recommend improvements
+improvements = analysis.recommend_improvements()
+# - Use token_efficient strategy
+# - Include source Z in next run
+# - Adjust relevance threshold
+```
+
+### What NOT to Do
+
+❌ **WRONG: Don't rebuild PyStreamMCP's functionality**
+
+```python
+# ❌ DO NOT DO THIS
+class QueryOptimizer:
+    def discover_sources(self):  # ← PyStreamMCP owns this
+        pass
+    
+    def optimize_for_tokens(self):  # ← PyStreamMCP owns this
+        pass
+    
+    def estimate_cost(self):  # ← PyStreamMCP owns this
+        pass
+```
+
+Instead, use PyStreamMCP's QueryExecutor:
+```python
+# ✅ DO THIS
+from pystreammcp import QueryExecutor
+
+executor = QueryExecutor()
+result = executor.execute_query(optimized_query)
+
+# Then debug the result
+debugger = RetrievalDebugger(result)
+```
+
+### Why?
+
+PyStreamMCP already provides:
+- ✓ Query planning & optimization
+- ✓ Context discovery (6+ framework integrations)
+- ✓ 7 optimization techniques
+- ✓ Cost tracking & estimation
+- ✓ Token efficiency (60-75% reduction)
+- ✓ Streaming execution
+- ✓ Multi-agent optimization
+
+Rebuilding this in PyVectorHound would:
+- Duplicate 1000+ lines of code
+- Miss learned optimizations
+- Create maintenance burden
+- Break integration with PyStreamMCP
+
+## Focused Responsibility
+
+PyVectorHound excels at what it's built for:
+
+✓ **Why did retrieval fail?**
+- Which sources had no matches?
+- Why were expected documents missing?
+- Did token budget cause truncation?
+- Was relevance threshold too high?
+
+✓ **Can we do better?**
+- Which optimization would help most?
+- Should we use different sources?
+- Can we adjust token allocation?
+- What does the replay show?
+
+✓ **Root Cause Analysis**
+- 8-failure taxonomy
+- Automatic classification
+- Replay debugging
+- Forensic analysis
+
+## Integration Points
+
+### With PyStreamMCP (Primary Integration)
+
+```python
+from pystreammcp import QueryExecutor, Agent
+from pyvectorhound import RetrievalDebugger, RootCauseAnalyzer
+
+# Execute query using PyStreamMCP
+executor = QueryExecutor()
+result = executor.execute_query(
+    query="customer data",
+    strategy="token_efficient"
+)
+
+# Debug the result
+debugger = RetrievalDebugger(result)
+analysis = debugger.analyze()
+
+# Get root causes using PyVectorHound's forensics
+analyzer = RootCauseAnalyzer()
+causes = analyzer.analyze(analysis)
+
+# Example causes:
+# - TokenBudgetExceeded: "Missing source X due to token limit"
+# - LowRelevanceScore: "Document below 0.5 threshold"
+# - SourceNotQueried: "Source Y not discovered by PyStreamMCP"
+```
+
+### With StatGuardian
+
+```python
+from statguardian import ValidationGate
+from pyvectorhound import RetrievalDebugger
+
+# Check if data is valid before analyzing
+validation = ValidationGate.check(source="customer_data")
+
+if validation.is_valid():
+    # Safe to debug
+    debugger = RetrievalDebugger(result)
+else:
+    # Data quality issue, not a retrieval issue
+    print(f"Data quality issue: {validation.error}")
+```
+
+## Module Structure
+
+```
+src/
+├── debugger.rs           # Core retrieval debugging
+├── analyzer.rs           # Root cause analysis
+├── failure_taxonomy.rs   # 8 failure types
+├── replay.rs             # Query replay for debugging
+├── forensics/            # Forensic analysis
+│   ├── source_analysis.rs
+│   ├── relevance_analysis.rs
+│   └── token_analysis.rs
+└── storage/              # Debug data persistence
+```
+
+## Philosophy
+
+PyVectorHound is to retrieval debugging what a debugger is to code execution.
+
+- A code debugger doesn't write programs, it debugs them
+- A database profiler doesn't optimize queries, it analyzes them
+- PyVectorHound doesn't optimize retrieval, it debugs it
+
+PyStreamMCP handles optimization. PyVectorHound explains why it worked or didn't.
+
+## Outcome
+
+When properly integrated:
+
+```
+Query Submitted
+        ↓
+PyStreamMCP executes with optimizations
+        ↓
+Results Retrieved
+        ↓
+PyVectorHound analyzes the result
+        ↓
+Root cause identified
+        ↓
+Feedback to PyStreamMCP for next run
+        ↓
+Continuous Improvement
+```
+
+PyStreamMCP optimizes. PyVectorHound debugs. Together they form a complete retrieval intelligence system.

pyvectorhound-1.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,9 @@
+# Code of Conduct
+
+This project adopts the [Contributor Covenant](https://www.contributor-covenant.org/version/2/1/code_of_conduct/),
+version 2.1.
+
+In short: be respectful and constructive. Harassment and discrimination are not tolerated.
+
+To report unacceptable behavior, contact the maintainer at mullassery@gmail.com. Reports will
+be handled confidentially.

{pyvectorhound-0.1.0 → pyvectorhound-1.1.0}/Cargo.lock

@@ -1,6 +1,6 @@
 # This file is automatically @generated by Cargo.
 # It is not intended for manual editing.
-version = 4
+version = 3
 
 [[package]]
 name = "autocfg"
@@ -43,9 +43,9 @@ checksum = "68ab91017fe16c622486840e4c83c9a37afeff978bd239b5293d61ece587de66"
 
 [[package]]
 name = "matrixmultiply"
-version = "0.3.10"
+version = "0.3.11"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "a06de3016e9fae57a36fd14dba131fccf49f74b40b7fbdb472f96e361ec71a08"
+checksum = "3f607c237553f086e7043417a51df26b2eb899d3caff94e6a67592ff992fedc7"
 dependencies = [
  "autocfg",
  "rawpointer",
@@ -53,9 +53,9 @@ dependencies = [
 
 [[package]]
 name = "memchr"
-version = "2.8.2"
+version = "2.8.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "88904434abc2901f197fe8cc55f0445e7ded921dba5911dad2e2b39b48e663c4"
+checksum = "cf8baf1c55e62ffcace7a9f06f4bd9cd3f0c4beb022d3b367256b91b87513d98"
 
 [[package]]
 name = "memoffset"
@@ -131,9 +131,9 @@ checksum = "9f7c3e4beb33f85d45ae3e3a1792185706c8e16d043238c593331cc7cd313b50"
 
 [[package]]
 name = "portable-atomic"
-version = "1.13.1"
+version = "1.14.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "c33a9471896f1c69cecef8d20cbe2f7accd12527ce60845ff44c153bb2a21b49"
+checksum = "3d20d5497ef88037a52ff98267d066e7f11fcc5e99bbfbd58a42336193aacec3"
 
 [[package]]
 name = "portable-atomic-util"
@@ -218,7 +218,7 @@ dependencies = [
 
 [[package]]
 name = "pyvectorhound"
-version = "0.1.0"
+version = "1.0.0"
 dependencies = [
  "numpy",
  "pyo3",
@@ -243,15 +243,15 @@ checksum = "60a357793950651c4ed0f3f52338f53b2f809f32d83a07f72909fa13e4c6c1e3"
 
 [[package]]
 name = "rustc-hash"
-version = "2.1.2"
+version = "2.1.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "94300abf3f1ae2e2b8ffb7b58043de3d399c73fa6f4b73826402a5c457614dbe"
+checksum = "6b1e7f9a428571be2dc5bc0505c13fb6bf936822b894ec87abf8a08a4e51742d"
 
 [[package]]
 name = "rustversion"
-version = "1.0.22"
+version = "1.0.23"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "b39cdef0fa800fc44525c84ccb54a029961a8215f9619753635a9c0d2538d46d"
+checksum = "cf54715a573b99ac80df0bc206da022bcd442c974952c7b9720069370852e21f"
 
 [[package]]
 name = "serde"
@@ -298,9 +298,9 @@ dependencies = [
 
 [[package]]
 name = "syn"
-version = "2.0.118"
+version = "2.0.119"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "1b9ae57f904213ebb649ce6895b8a66c66f0203b9319718f69a5612a065b1422"
+checksum = "872831b642d1a07999a962a351ed35b955ea2cfc8f3862091e2a240a84f17297"
 dependencies = [
  "proc-macro2",
  "quote",
@@ -327,6 +327,6 @@ checksum = "7264e107f553ccae879d21fbea1d6724ac785e8c3bfc762137959b5802826ef3"
 
 [[package]]
 name = "zmij"
-version = "1.0.21"
+version = "1.0.23"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "b8848ee67ecc8aedbaf3e4122217aff892639231befc6a1b58d29fff4c2cabaa"
+checksum = "29666d0abbfad1e3dc4dcf6144730dd3a3ab225bbbdac83319345b1b44ccfc1b"

{pyvectorhound-0.1.0 → pyvectorhound-1.1.0}/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "pyvectorhound"
-version = "0.1.0"
+version = "1.0.0"
 edition = "2021"
 authors = ["Georgi Mammen Mullassery <mullassery@gmail.com>"]
 license = "MIT"
@@ -14,5 +14,5 @@ serde = { version = "1.0", features = ["derive"] }
 serde_json = "1.0"
 
 [lib]
-name = "pyhound_core"
+name = "_core"
 crate-type = ["cdylib"]

pyvectorhound-1.1.0/Makefile

@@ -0,0 +1,49 @@
+.PHONY: install install-dev build test lint fmt clean help setup-hooks
+
+help:
+	@echo "pyvectorhound development tasks:"
+	@echo "  make install         Install pre-commit hooks"
+	@echo "  make build           Build release wheel"
+	@echo "  make test            Run all tests"
+	@echo "  make test-cov        Run tests with coverage"
+	@echo "  make lint            Run linters (clippy, black, ruff, mypy)"
+	@echo "  make fmt             Format code"
+	@echo "  make fmt-check       Check format without changing"
+	@echo "  make clean           Remove build artifacts"
+
+install: setup-hooks
+	@echo "✓ Development environment ready"
+
+setup-hooks:
+	@command -v pre-commit >/dev/null 2>&1 || pip install pre-commit
+	pre-commit install
+
+build:
+	maturin build --release
+
+test:
+	pytest -v
+
+test-cov:
+	pytest -v --cov=pyvectorhound --cov-report=term-missing
+
+lint:
+	cargo clippy --all-targets
+	black --check .
+	ruff check .
+	mypy pyvectorhound
+
+fmt:
+	cargo fmt --all
+	black .
+	ruff check . --fix
+
+fmt-check:
+	cargo fmt --all -- --check
+	black --check .
+
+clean:
+	cargo clean
+	find . -type d -name __pycache__ -exec rm -rf {} +
+	find . -type f -name "*.pyc" -delete
+	rm -rf build dist *.egg-info .pytest_cache .mypy_cache