{"id":37085178,"url":"https://github.com/vedaant00/uhsr","last_synced_at":"2026-01-14T10:28:14.329Z","repository":{"id":278286677,"uuid":"935119354","full_name":"vedaant00/uhsr","owner":"vedaant00","description":"UHSR (Unified Hyperbolic Spectral Retrieval) is a next-generation hybrid text retrieval framework that combines BM25 (Lexical Search) with FAISS/Pinecone (Semantic Search), enhanced by Spectral Re-Ranking \u0026 AI-Powered Reranking. It supports multiple similarity metrics, provides interpretable normalized scores, \u0026 is designed for scalability \u0026 speed.","archived":false,"fork":false,"pushed_at":"2025-10-31T12:01:43.000Z","size":510,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-10-31T13:20:40.459Z","etag":null,"topics":["artificial-intelligence","data-science","hacktoberfest","machine-learning","semantic-search","text-mining","text-retrieval"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vedaant00.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-02-18T23:52:13.000Z","updated_at":"2025-10-31T12:01:47.000Z","dependencies_parsed_at":"2025-02-19T01:22:26.467Z","dependency_job_id":"aae2c776-5cef-47c2-88b5-a1811e5d3f6d","html_url":"https://github.com/vedaant00/uhsr","commit_stats":null,"previous_names":["vedaant00/uhsr"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/vedaant00/uhsr","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vedaant00%2Fuhsr","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vedaant00%2Fuhsr/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vedaant00%2Fuhsr/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vedaant00%2Fuhsr/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vedaant00","download_url":"https://codeload.github.com/vedaant00/uhsr/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vedaant00%2Fuhsr/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28417226,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-14T10:25:19.714Z","status":"ssl_error","status_checked_at":"2026-01-14T10:22:49.371Z","response_time":107,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["artificial-intelligence","data-science","hacktoberfest","machine-learning","semantic-search","text-mining","text-retrieval"],"created_at":"2026-01-14T10:28:13.685Z","updated_at":"2026-01-14T10:28:14.324Z","avatar_url":"https://github.com/vedaant00.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"logo.png\" alt=\"UHSR Logo\" width=\"300\"\u003e\n  \u003chr\u003e\n  \u003cbr/\u003e\n\u003c/div\u003e\n\n# Unified Hyperbolic Spectral Retrieval (UHSR)\n\nUHSR is a **next-generation hybrid text retrieval model** that seamlessly integrates **lexical search (BM25)** and **semantic search (FAISS/Pinecone)** with **spectral re-ranking** to produce **interpretable** and **normalized** relevance scores in the `[0,1]` range.\n\n---\n\n## ⚡ Key Highlights\n- ✅ **Hybrid Search:** Combines BM25 with dense embeddings.  \n- 🔍 **Custom Similarity Metrics:** Supports **cosine, euclidean, mahalanobis, manhattan, chebyshev, jaccard, and hamming**.  \n- 🎯 **Spectral Re-Ranking:** Uses **Graph Laplacian \u0026 Fiedler vector** for robust ranking.  \n- 📈 **Interpretable Scores:** Final scores are **logistic-normalized** in **[0,1]**.  \n- 🚀 **Scalable \u0026 Efficient:** Built on **FAISS** (local) and **Pinecone** (cloud).  \n- 🤖 **AI-powered Reranking:** Integrates **Hugging Face Cross-Encoders** and **OpenAI Rerankers**.\n\n---\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://www.python.org/\"\u003e\u003cimg src=\"http://ForTheBadge.com/images/badges/made-with-python.svg\" alt=\"made-with-python\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/python-3.6+-blue.svg\" alt=\"Python Version\"\u003e\n  \u003ca href=\"https://pypi.org/project/uhsr\"\u003e\u003cimg src=\"https://img.shields.io/pypi/v/uhsr-retrieval.svg\" alt=\"PyPI Version\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://pypi.org/project/uhsr\"\u003e\u003cimg src=\"https://img.shields.io/pypi/status/uhsr.svg\" alt=\"PyPI Status\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/vedaant00/uhsr/blob/main/LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/pypi/l/uhsr.svg\" alt=\"License\"\u003e\u003c/a\u003e\n  \u003cimg src=\"https://img.shields.io/pypi/dm/uhsr\" alt=\"Downloads\"\u003e\n  \u003cbr/\u003e\n  \u003cimg src=\"https://img.shields.io/github/stars/vedaant00/uhsr?style=social\" alt=\"GitHub stars\"\u003e\n  \u003cimg src=\"https://img.shields.io/github/forks/vedaant00/uhsr?style=social\" alt=\"GitHub forks\"\u003e\n  \u003cimg src=\"https://komarev.com/ghpvc/?username=vedaant00\u0026style=flat-square\" alt=\"Profile views\"\u003e\n\u003c/p\u003e\n\n---\n\n## 🚀 What is UHSR?\n\nUHSR unifies **lexical and semantic retrieval** into a single hybrid retrieval pipeline:\n\n| Component | Functionality |\n|------------|---------------|\n| 🔹 **Lexical Search** | BM25 for keyword-based ranking |\n| 🔹 **Semantic Search** | FAISS (local) or Pinecone (cloud-based) vector search |\n| 🔹 **Fusion** | Logistic Normalization + Harmonic Fusion for score blending |\n| 🔹 **Spectral Re-Ranking** | Graph Laplacian + Fiedler vector for centrality-based refinement |\n| 🔹 **AI-based Reranking** | Hugging Face Cross-Encoder or OpenAI-based rerankers |\n\n---\n\n## 📌 Features\n- **🔍 Multi-Metric Retrieval:** cosine, euclidean, mahalanobis, manhattan, chebyshev, jaccard, hamming  \n- **🌐 Pinecone Support:** seamless cloud-based semantic search  \n- **🤖 AI-Powered Reranking:** Hugging Face or OpenAI models  \n- **📊 Hybrid Fusion:** BM25 + semantic scoring  \n- **♾️ Normalized Scores:** interpretable `[0,1]` relevance  \n- **📈 Spectral Graph Ranking:** enhances candidate ranking stability  \n- **🚀 Scalable:** FAISS for fast local retrieval  \n\n---\n\n## 📦 Installation\n\n### 1️⃣ Install core package\n```bash\npip install uhsr[cpu]\n```\n\n### 2️⃣ (Optional) GPU acceleration\n```bash\npip install uhsr[gpu]\n```\n\n### 3️⃣ (Optional) Pinecone for cloud-based retrieval\n```bash\npip install pinecone-client\n```\n\n### 4️⃣ (Optional) OpenAI-based reranking\n```bash\npip install openai\n```\n\n---\n\n## ⚡ Usage Example\n\n```python\nfrom sentence_transformers import SentenceTransformer\nfrom uhsr import UHSR\nimport numpy as np\n\n# Sample documents\ndocuments = [\n    \"Apple releases new iPhone\",\n    \"Tesla's stock price surges\",\n    \"Google announces AI updates\",\n    \"Amazon introduces drone delivery\",\n    \"Microsoft acquires a gaming company\"\n]\n\n# Load embedding model\nmodel = SentenceTransformer('all-MiniLM-L6-v2')\nembeddings = model.encode(documents, normalize_embeddings=True)\nquery_embedding = model.encode(\"Did Tesla's stock price go up?\", normalize_embeddings=True)\n\n# Initialize UHSR with OpenAI Reranker\nretrieval_system = UHSR(\n    documents,\n    embeddings,\n    reranker_type=\"openai\",\n    openai_api_key=\"your-openai-api-key\"\n)\n\n# Retrieve results\nretrieved_docs, scores = retrieval_system.retrieve(\n    \"Did Tesla's stock price go up?\",\n    query_embedding,\n    top_k=3,\n    metric='cosine',\n    rerank=True\n)\n\nfor doc, score in zip(retrieved_docs, scores):\n    print(f\"{doc} (Score: {score:.4f})\")\n```\n\n---\n\n## 🌐 Using Pinecone for Scalable Search\n\n```python\nretrieval_system = UHSR(\n    documents,\n    embeddings,\n    use_pinecone=True,\n    pinecone_api_key=\"your_pinecone_api_key\"\n)\n\nretrieved_docs, scores = retrieval_system.retrieve(\n    \"Did Tesla's stock price go up?\",\n    query_embedding,\n    top_k=3,\n    metric='cosine'\n)\n```\n\n---\n\n## 🎛️ Supported Similarity Metrics\n```python\nretrieved_docs, scores = retrieval_system.retrieve(\"query\", query_embedding, metric='cosine')      # ✅ Cosine\nretrieved_docs, scores = retrieval_system.retrieve(\"query\", query_embedding, metric='euclidean')   # ✅ Euclidean\nretrieved_docs, scores = retrieval_system.retrieve(\"query\", query_embedding, metric='mahalanobis') # ✅ Mahalanobis\nretrieved_docs, scores = retrieval_system.retrieve(\"query\", query_embedding, metric='manhattan')   # ✅ Manhattan\nretrieved_docs, scores = retrieval_system.retrieve(\"query\", query_embedding, metric='chebyshev')   # ✅ Chebyshev\nretrieved_docs, scores = retrieval_system.retrieve(\"query\", query_embedding, metric='jaccard')     # ✅ Jaccard\nretrieved_docs, scores = retrieval_system.retrieve(\"query\", query_embedding, metric='hamming')     # ✅ Hamming\n```\n\n---\n\n## 📂 Repository Structure\n```\nuhsr-retrieval/\n├── uhsr/\n│   ├── core.py             # Main retrieval logic\n│   ├── bm25.py             # BM25 implementation\n│   ├── faiss_retrieval.py  # FAISS backend\n│   ├── vector_db.py        # Pinecone integration\n│   ├── similarity.py       # Similarity metrics\n│   ├── reranker.py         # AI-based reranking\n│   ├── utils.py            # Utility functions\n├── examples/\n│   ├── example.py\n├── README.md\n├── setup.py\n├── requirements.txt\n```\n\n---\n\n## 🎯 Requirements\n- `numpy`\n- `sentence-transformers`\n- `faiss-cpu` / `faiss-gpu`\n- `pinecone-client`\n- `openai`\n\n---\n\n## 🧪 Running Tests\n```bash\npytest\n```\n\n---\n\n_Learn more about UHSR on [Medium](https://vedaantsingh706.medium.com/revolutionizing-text-retrieval-with-uhsr-a-hybrid-approach-combining-lexical-semantic-spectral-6c7e28c3e7d9)._\n\n🚀 **Try UHSR today \u0026 supercharge your search!**","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvedaant00%2Fuhsr","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvedaant00%2Fuhsr","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvedaant00%2Fuhsr/lists"}