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.
frompyvectorhoundimportHound# Diagnose RAG failureshound=Hound(vector_db="pinecone", embeddings="openai")
# Find what's wrongdiagnosis=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)}")
forissueindiagnosis.issues:
print(f" - {issue.problem}: {issue.solution}")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
- 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
Before Launching:
# Validate RAG quality before productionhound=Hound()
quality=hound.validate_quality(
test_queries=100,
min_success_rate=0.85# 85% minimum
)
ifquality.success_rate<0.85:
print(f"Not ready: {quality.issues}")
# Don't deployDebugging Failures:
# 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 fixprint(diagnosis.root_cause) # "Embeddings too similar"print(diagnosis.solution) # "Use embedding model X instead"Comparing Approaches:
# Which embedding model is better?before=hound.quality_score(embedding_model="openai")
after=hound.quality_score(embedding_model="cohere")
improvement= (after-before) /before*100print(f"Model improved quality by {improvement:.1f}%")| 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 |
pip install pyvectorhound
# or with uv
uv pip install pyvectorhound- Quick Diagnosis — Debug your first RAG issue
- Fixing RAG — Solutions for common problems
- Quality Metrics — How retrieval is scored
- Examples — Real-world diagnostics
Proprietary License - Free to use with explicit attribution. See LICENSE.
PyVectorHound v2.0.0 | RAG diagnostics & debugging | Python 3.10+
MIT
MCP 2.0 Mega-Platform | v2.0.0 | Wheels-Only Distribution