Metadata-Version: 2.2
Name: uhsr
Version: 0.2.8
Summary: Unified Hyperbolic Spectral Retrieval (UHSR) - a novel text retrieval algorithm combining lexical and semantic search.
Home-page: https://github.com/vedaant00/uhsr
Author: Vedaant Singh
Keywords: uhsr,text retrieval,BM25,FAISS,Pinecone,vector search,semantic search,lexical search,spectral re-ranking,machine learning,NLP
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.6
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: sentence-transformers
Requires-Dist: pinecone-client
Requires-Dist: openai
Provides-Extra: gpu
Requires-Dist: faiss-gpu; extra == "gpu"
Provides-Extra: cpu
Requires-Dist: faiss-cpu; extra == "cpu"
Dynamic: author
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# Unified Hyperbolic Spectral Retrieval (UHSR)

Unified Hyperbolic Spectral Retrieval (UHSR) is an advanced **hybrid text retrieval model** that seamlessly integrates **lexical search (BM25)** with **semantic search (FAISS/Pinecone)** while employing **spectral re-ranking** for **interpretable and normalized** relevance scores in the **[0,1] range**.

## 🚀 Key Features

- **🔍 Hybrid Retrieval:** Combines **BM25** for lexical scoring and **dense vector** semantic similarity for contextual understanding.
- **🎯 Multi-Metric Similarity:** Supports **cosine, euclidean, mahalanobis, manhattan, chebyshev, jaccard, and hamming** similarity.
- **🔬 Spectral Re-Ranking:** Uses **graph Laplacian & Fiedler vector** to boost highly relevant candidates.
- **⚡ AI-powered Reranking:** Supports **Hugging Face Cross-Encoders & OpenAI API-based Reranking**.
- **📈 Interpretable Scores:** Final relevance scores are **logistic-normalized** in **[0,1]** for **easy ranking**.
- **🚀 Scalable & Efficient:** Works with **FAISS (local)** for fast retrieval and **Pinecone (cloud-based)** for large-scale vector search.

---

## 🛠️ **How It Works**

UHSR **enhances traditional retrieval** by blending **BM25-based keyword matching** with **semantic vector representations** using the following pipeline:

| Step | Description |
|------|-------------|
| 1️⃣ **Lexical Filtering** | Uses **BM25** to rank documents by keyword relevance |
| 2️⃣ **Semantic Scoring** | Computes similarity using **FAISS or Pinecone** |
| 3️⃣ **Fusion Process** | Blends scores via **logistic normalization & harmonic fusion** |
| 4️⃣ **Spectral Re-Ranking** | Uses **graph Laplacian analysis** to boost central candidates |
| 5️⃣ **(Optional) AI Reranking** | Uses **OpenAI API or Hugging Face Cross-Encoders** |

---

## 🌍 **Supported Retrieval Methods**
- ✅ **BM25 (Lexical Matching)**
- ✅ **FAISS (Local Vector Search)**
- ✅ **Pinecone (Cloud Vector Search)**
- ✅ **Hugging Face Rerankers**
- ✅ **OpenAI API-based Reranking**

---

## 📌 **Why UHSR?**
- **Better Search Results:** Combines **exact keyword matching (BM25)** with **contextual embeddings (Semantic Search)**.
- **Faster & Scalable:** Uses **FAISS for local retrieval** or **Pinecone for cloud-based vector search**.
- **Interpretable Ranking:** Outputs **normalized scores in [0,1]**, making it easy to **interpret**.
- **Multi-Metric Similarity:** Supports **cosine, euclidean, mahalanobis, manhattan, chebyshev, jaccard, and hamming**.

---

## 🎯 **Intended Use**

UHSR is designed for:
- **Information Retrieval Research**
- **Search Engines & Recommendation Systems**
- **NLP Applications in AI & Machine Learning**
- **Academic & Industry-scale Document Ranking**

---

## 📂 **Code & Documentation**
For complete documentation, usage examples, and implementation details, visit the **[GitHub repository](https://github.com/vedaant00/uhsr).**

_Learn More about this package on [Medium](https://vedaantsingh706.medium.com/revolutionizing-text-retrieval-with-uhsr-a-hybrid-approach-combining-lexical-semantic-spectral-6c7e28c3e7d9)._

---

### 🔥 **Try UHSR today and revolutionize your search engine!** 🚀
