Metadata-Version: 2.4
Name: pyvectorhound
Version: 1.3.2
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: Other/Proprietary License
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Rust
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Text Processing
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Requires-Dist: numpy==1.20.0
Requires-Dist: requests==2.28.0
Requires-Dist: python-frontmatter>=1.0.0
Requires-Dist: pyvectorhound[qdrant,chroma,milvus,weaviate,postgres,pgvector,dev] ; extra == 'all'
Requires-Dist: chromadb==0.4.0 ; extra == 'chroma'
Requires-Dist: pytest==7.0.0 ; extra == 'dev'
Requires-Dist: pytest-cov==4.0.0 ; extra == 'dev'
Requires-Dist: mypy==1.0.0 ; extra == 'dev'
Requires-Dist: black==23.0.0 ; extra == 'dev'
Requires-Dist: ruff==0.1.0 ; extra == 'dev'
Requires-Dist: maturin==1.0.0 ; extra == 'dev'
Requires-Dist: pymilvus==2.3.0 ; extra == 'milvus'
Requires-Dist: psycopg2-binary==2.9.0 ; extra == 'pgvector'
Requires-Dist: psycopg2-binary==2.9.0 ; extra == 'postgres'
Requires-Dist: qdrant-client==2.0.0 ; extra == 'qdrant'
Requires-Dist: weaviate-client==3.0.0 ; extra == 'weaviate'
Provides-Extra: all
Provides-Extra: chroma
Provides-Extra: dev
Provides-Extra: milvus
Provides-Extra: pgvector
Provides-Extra: postgres
Provides-Extra: qdrant
Provides-Extra: weaviate
License-File: LICENSE
Summary: Diagnostic tool for vector search failures in RAG and LLM systems. Evaluate embedding quality, analyze vector search rank correlation, benchmark BM25 vs semantic search, profile reranker performance. Identify root cause of retrieval failures.
Keywords: rag,retrieval-augmented-generation,vector-search,embedding,semantic-search,llm,large-language-models,information-retrieval,search-ranking,evaluation-metrics,bm25,reranking,debugging,diagnostics,nlp,natural-language-processing,similarity-search,faiss,elasticsearch,pinecone,milvus,ai-debugging
Author-email: Georgi Mammen Mullassery <mullassery@gmail.com>
Maintainer-email: Georgi Mammen Mullassery <mullassery@gmail.com>
License: Proprietary
Requires-Python: >=3.8
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Bug Tracker, https://github.com/Mullassery/Pyvectorhound/issues
Project-URL: Changelog, https://github.com/Mullassery/Pyvectorhound/releases
Project-URL: Discussions, https://github.com/Mullassery/Pyvectorhound/discussions
Project-URL: Documentation, https://github.com/Mullassery/Pyvectorhound#readme
Project-URL: Homepage, https://github.com/Mullassery/Pyvectorhound
Project-URL: Repository, https://github.com/Mullassery/Pyvectorhound
Project-URL: Source Code, https://github.com/Mullassery/Pyvectorhound/tree/main

# PyVectorHound

**Fix your RAG before it breaks production. Find retrieval bugs instantly.**

Your RAG system is losing documents. PyVectorHound diagnoses why. Pinpoint indexing errors, embedding failures, ranking problems, and chunking mistakes—then get actionable fixes.

[![PyPI](https://img.shields.io/pypi/v/pyvectorhound)](https://pypi.org/project/pyvectorhound)
[![Python 3.10+](https://img.shields.io/badge/Python-3.10%2B-blue)](https://www.python.org)
[![Tests Passing](https://img.shields.io/badge/tests-passing-success)](./tests)
[![License: Proprietary](https://img.shields.io/badge/License-Proprietary-blue.svg)](./LICENSE)

---

## 30-Second Start

```python
from pyvectorhound import Hound

# Diagnose RAG failures
hound = Hound(vector_db="pinecone", embeddings="openai")

# Find what's wrong
diagnosis = hound.diagnose(
    query="How do I reset my password?",
    expected_docs=["FAQ.md", "UserGuide.md"]
)

print(f"Retrieval success: {diagnosis.success_rate:.0%}")
print(f"Problems found: {len(diagnosis.issues)}")
for issue in diagnosis.issues:
    print(f"  - {issue.problem}: {issue.solution}")
```

---

## Why PyVectorHound?

**The Problem:**
- Your RAG system returns wrong documents
- You don't know why (embedding issue? indexing? ranking?)
- Debugging takes hours of manual work
- No way to validate before launching

**The Solution:**
- Automatic root cause diagnosis
- Pinpoint the exact step that's failing
- Get specific, actionable fixes
- Validate RAG quality before production

---

## Key Features

- **Root Cause Analysis:** Find where retrieval breaks (embedding, indexing, ranking, chunking)
- **Quality Metrics:** Measure precision, recall, NDCG across your documents
- **Fix Recommendations:** Get specific, code-ready solutions
- **Before/After Testing:** Compare RAG quality across changes
- **Multi-DB Support:** Pinecone, Weaviate, Qdrant, Milvus, Elasticsearch
- **Embedding Validation:** Test different embedding models
- **Batch Diagnostics:** Analyze 100s of queries at once

---

## Real-World Use Cases

**Before Launching:**
```python
# Validate RAG quality before production
hound = Hound()
quality = hound.validate_quality(
    test_queries=100,
    min_success_rate=0.85  # 85% minimum
)

if quality.success_rate < 0.85:
    print(f"Not ready: {quality.issues}")
    # Don't deploy
```

**Debugging Failures:**
```python
# Why did this query fail?
diagnosis = hound.diagnose(
    query="What's your return policy?",
    actual_results=["Pricing.pdf"],  # Wrong!
    expected_docs=["Returns.pdf", "Policy.md"]
)

# Get the fix
print(diagnosis.root_cause)  # "Embeddings too similar"
print(diagnosis.solution)    # "Use embedding model X instead"
```

**Comparing Approaches:**
```python
# Which embedding model is better?
before = hound.quality_score(embedding_model="openai")
after = hound.quality_score(embedding_model="cohere")

improvement = (after - before) / before * 100
print(f"Model improved quality by {improvement:.1f}%")
```

---

## Diagnostics It Runs

| Issue | Detection | Fix |
|-------|-----------|-----|
| **Embedding** | Vectors too similar, not capturing meaning | Suggest better embedding model |
| **Indexing** | Documents not in vector DB or corrupted | Rebuild index with validation |
| **Ranking** | Right documents present but ranked low | Tune similarity metric or weights |
| **Chunking** | Documents split wrong, breaking context | Adjust chunk size or overlap |
| **Query** | Query phrasing doesn't match documents | Suggest rephrasing or expansion |

---

## Installation

```bash
pip install pyvectorhound
# or with uv
uv pip install pyvectorhound
```

---

## Documentation

- [Quick Diagnosis](docs/QUICKSTART.md) — Debug your first RAG issue
- [Fixing RAG](docs/FIXES.md) — Solutions for common problems
- [Quality Metrics](docs/METRICS.md) — How retrieval is scored
- [Examples](examples/) — Real-world diagnostics

---

## License

Proprietary License - Free to use with explicit attribution. See [LICENSE](LICENSE).

---

**PyVectorHound v2.0.0** | RAG diagnostics & debugging | Python 3.10+

## License

MIT

---

**MCP 2.0 Mega-Platform | v2.0.0 | Wheels-Only Distribution**

