# š ZeroEntropy Reranker for Elasticsearch
**Boost your Elasticsearch results with LLM reranking in 5 minutes.**
This open-source tool adds a smart reranking layer to your existing Elastic queries using [ZeroEntropy's](https://zeroentropy.ai) API.
š§ Built for developers who want great search results without rebuilding their stack.
[](https://badge.fury.io/py/elastic-zeroentropy)
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/MIT)
[](https://fastapi.tiangolo.com/)
[](https://zeroentropy.ai)
[](https://www.elastic.co/)
[](http://makeapullrequest.com)
---
## š„ļø Demo UI Preview
*Interactive A/B testing interface comparing original Elasticsearch results with ZeroEntropy LLM-reranked results*
---
## šÆ The Problem
Most Elasticsearch users struggle with:
- **Vague queries** that return irrelevant results
- **Complex search intent** that BM25 can't understand
- **Ambiguous terms** that need contextual understanding
- **No AI skills** to implement vector search
**Solution**: Add LLM-powered reranking without changing your existing setup.
---
## āØ Features
- š **Plug-and-play**: Drop-in proxy or client wrapper
- š§ **LLM-powered relevance** via ZeroEntropy API
- ā” **Works with any Elasticsearch** or OpenSearch backend
- š **Hybrid-ready**: Rerank BM25 + vector results
- š **Side-by-side comparison**: Original vs reranked output
- š **5-minute setup**: No AI expertise required
- š° **Cost-effective**: Only rerank top N results
---
## š Quick Demo
### š„ļø Interactive Demo UI
Try our **live A/B testing interface** to compare original vs reranked results:
```bash
# Quick start (recommended)
./run_demo.sh
# Or manual setup
cd examples
pip install -r requirements_demo.txt
streamlit run demo_ui.py
```
**Features:**
- š Side-by-side comparison
- āļø Interactive parameter controls
- š Real-time performance metrics
- šÆ Demo mode (no API keys needed)
### š» Code Example
```python
import asyncio
from elastic_zeroentropy import ElasticZeroEntropyReranker
async def main():
async with ElasticZeroEntropyReranker() as reranker:
response = await reranker.search(
query="machine learning applications in healthcare",
index="research_papers"
)
for result in response.results:
print(f"š {result.document.title}")
print(f" š Score: {result.score:.4f}")
print(f" š {result.document.text[:100]}...")
asyncio.run(main())
```
**Before vs After:**
| Query | Original Elastic | Reranked (ZeroEntropy) |
|-------|------------------|-------------------------|
| "books about hope and war" | š» Generic results | ā
Contextually relevant |
| "machine learning healthcare" | š» Broad matches | ā
Domain-specific papers |
| "python async programming" | š» Mixed relevance | ā
Focused tutorials |
---
## š„ļø Demo UI Guide
The **Elastic-ZeroEntropy Demo UI** is a powerful A/B testing interface that lets you compare original Elasticsearch results with ZeroEntropy reranked results in real-time.
### š Getting Started
1. **Launch the Demo:**
```bash
./run_demo.sh
```
This opens the UI at http://localhost:8501
2. **Choose Your Mode:**
- **Demo Mode** (default): Works without API keys using sample data
- **Live Mode**: Connect to your Elasticsearch + ZeroEntropy API
### šļø UI Features
#### **Main Interface**
- **š Search Bar**: Enter your query to test
- **š Run A/B Test**: Execute the comparison
- **š Results Comparison**: Side-by-side view of original vs reranked
#### **Sidebar Configuration**
**š API Configuration:**
- **ZeroEntropy API Key**: Your API key from https://zeroentropy.dev
- **Elasticsearch URL**: Your ES instance (default: http://localhost:9200)
- **Index Name**: Target Elasticsearch index
**š Search Settings:**
- **Initial Results from ES**: How many docs to retrieve (10-200)
- **Documents to Rerank**: How many to send for reranking (5-50)
- **Final Results**: How many to display (5-20)
**š§ Reranking Settings:**
- **ZeroEntropy Model**: Choose `zerank-1` or `zerank-1-small`
- **Combine Scores**: Mix ES + rerank scores
- **Score Weights**: Adjust ES vs rerank importance (0.0-1.0)
**š Demo Data:**
- **Use Demo Data**: Enable for testing without real connections
### š Understanding Results
#### **Performance Metrics**
- **Query Time**: Total search + reranking duration
- **ES Time**: Elasticsearch query time
- **Reranking Time**: ZeroEntropy API processing time
- **Model Used**: Which ZeroEntropy model was applied
#### **Results Comparison**
- **Original Ranking**: Elasticsearch BM25 results
- **Reranked Results**: ZeroEntropy LLM-enhanced results
- **Score Breakdown**: ES score vs rerank score vs combined score
- **Relevance Improvement**: Visual indicators of better matches
#### **Visual Features**
- **š Performance Charts**: Real-time metrics visualization
- **šÆ Relevance Indicators**: Color-coded relevance scores
- **š Detailed Metadata**: Document info, timestamps, sources
- **š A/B Comparison**: Side-by-side result analysis
### šÆ Use Cases
#### **Testing Search Quality**
1. Enter a complex query like "machine learning healthcare applications"
2. Compare original vs reranked results
3. Notice how LLM reranking improves contextual relevance
#### **Parameter Tuning**
1. Adjust `top_k_initial` to control ES result pool
2. Modify `top_k_rerank` to balance cost vs quality
3. Tune score weights for your use case
4. Test different ZeroEntropy models
#### **Performance Optimization**
1. Monitor query times for different configurations
2. Balance speed vs accuracy with model selection
3. Optimize for your specific workload
### š§ Advanced Features
#### **Real-time Configuration**
- **Dynamic Parameter Updates**: Change settings without restart
- **Live API Testing**: Test your ZeroEntropy API key
- **Elasticsearch Connection**: Verify ES connectivity
#### **Demo Mode Benefits**
- **No API Keys Required**: Test the interface immediately
- **Sample Data**: Realistic documents for testing
- **Simulated Reranking**: Understand the process flow
#### **Production Mode**
- **Live Elasticsearch**: Connect to your actual ES instance
- **Real ZeroEntropy API**: Use actual LLM reranking
- **Performance Monitoring**: Track real-world metrics
### š” Pro Tips
1. **Start with Demo Mode**: Understand the interface before connecting APIs
2. **Test Complex Queries**: Try ambiguous or multi-concept searches
3. **Compare Different Models**: Test `zerank-1` vs `zerank-1-small`
4. **Monitor Performance**: Watch query times and adjust parameters
5. **Save Configurations**: Note your best settings for production
### šØ Troubleshooting
**Demo won't start:**
```bash
# Check if port 8501 is free
lsof -i :8501
# Kill existing process if needed
pkill -f streamlit
```
**API connection issues:**
- Verify your ZeroEntropy API key
- Check Elasticsearch URL and connectivity
- Ensure index exists and is accessible
**Performance problems:**
- Reduce `top_k_initial` for faster queries
- Use `zerank-1-small` for lower latency
- Adjust score weights for your use case
---
## š¦ Installation
```bash
pip install elastic-zeroentropy
```
Or with CLI tools:
```bash
pip install "elastic-zeroentropy[cli]"
```
---
## ā” 5-Minute Setup
### 1. Get ZeroEntropy API Key
```bash
# Sign up at https://zeroentropy.ai
export ZEROENTROPY_API_KEY="your_api_key_here"
```
### 2. Configure Elasticsearch
```bash
export ELASTICSEARCH_URL="http://localhost:9200"
```
### 3. Run Your First Search
```python
from elastic_zeroentropy import ElasticZeroEntropyReranker
async with ElasticZeroEntropyReranker() as reranker:
results = await reranker.search("your query", "your_index")
```
---
## šļø Advanced Usage
### Custom Reranking Configuration
```python
from elastic_zeroentropy import RerankerConfig
config = RerankerConfig(
top_k_initial=100, # Get 100 docs from Elasticsearch
top_k_rerank=20, # Send top 20 to reranker
top_k_final=10, # Return top 10 final results
model="zerank-1-small", # Use faster model
combine_scores=True, # Mix ES + rerank scores
score_weights={
"elasticsearch": 0.3,
"rerank": 0.7
}
)
response = await reranker.search(
query="deep learning neural networks",
index="ai_papers",
reranker_config=config
)
```
### Batch Processing
```python
from elastic_zeroentropy import SearchRequest
requests = [
SearchRequest(query="machine learning", index="papers"),
SearchRequest(query="natural language processing", index="papers"),
SearchRequest(query="computer vision", index="papers"),
]
responses = await reranker.search_batch(requests, max_concurrent=3)
```
### Health Monitoring
```python
health = await reranker.health_check()
print(f"Status: {health.status}")
print(f"Elasticsearch: {health.elasticsearch['status']}")
print(f"ZeroEntropy: {health.zeroentropy['status']}")
```
---
## š„ļø Command Line Interface
### Basic Search
```bash
elastic-zeroentropy search "machine learning" my_index --top-k 5
```
### Advanced Search with Filters
```bash
elastic-zeroentropy search \
"deep learning" \
research_papers \
--top-k-initial 100 \
--top-k-rerank 20 \
--top-k 10 \
--model zerank-1-small \
--filters '{"category": "AI", "year": {"gte": 2020}}' \
--debug-info
```
### Health Check
```bash
elastic-zeroentropy health
```
---
## šļø Architecture
```
User Query ā Elasticsearch ā Top N Results ā ZeroEntropy API ā Reranked Results
```
1. **Elasticsearch Search**: Get initial results using your existing queries
2. **Document Selection**: Choose top N documents for reranking
3. **ZeroEntropy Reranking**: Send to LLM for contextual relevance scoring
4. **Score Combination**: Mix Elasticsearch and rerank scores (optional)
5. **Final Results**: Return intelligently reranked results
---
## šÆ Performance
Based on ZeroEntropy's benchmarks:
- **Accuracy**: Up to 28% improvement in NDCG@10
- **Speed**: ~150ms latency for small payloads
- **Cost**: $0.025 per million tokens (50% less than competitors)
- **Throughput**: High concurrent request support
---
## š§ Configuration
### Environment Variables
```bash
# Required
ZEROENTROPY_API_KEY=your_api_key_here
# Optional
ZEROENTROPY_BASE_URL=https://api.zeroentropy.dev/v1
ZEROENTROPY_MODEL=zerank-1
ELASTICSEARCH_URL=http://localhost:9200
DEFAULT_TOP_K_INITIAL=100
DEFAULT_TOP_K_RERANK=20
DEFAULT_TOP_K_FINAL=10
```
### Programmatic Configuration
```python
from elastic_zeroentropy import ElasticZeroEntropyConfig
config = ElasticZeroEntropyConfig(
zeroentropy_api_key="your_key",
elasticsearch_url="http://localhost:9200",
default_top_k_final=15
)
```
---
## š§© Coming Soon
- [ ] **Smart Reranking**: Only rerank when needed (query classifier)
- [x] **UI Toggle**: Compare original vs reranked results ā
- [ ] **LangChain Integration**: Plugin for LangChain workflows
- [x] **Streamlit App**: Interactive demo and testing ā
- [ ] **More Models**: Support for additional ZeroEntropy models
- [ ] **Caching**: Intelligent result caching for repeated queries
---
## š¤ Contributing
We're building a better search UX together! PRs, feedback, and ideas welcome.
### Development Setup
```bash
git clone https://github.com/vagabond11/elastic-zeroentropy.git
cd elastic-zeroentropy
pip install -e ".[dev]"
pytest
```
### Areas to Contribute
- šØ **UI/UX**: Better demos and visualizations
- š§ **Integrations**: LangChain, Streamlit, FastAPI plugins
- š **Analytics**: Search quality metrics and monitoring
- š **Documentation**: Examples, tutorials, case studies
---
## š Community Stats
[](https://github.com/vagabond11/elastic-zeroentropy/stargazers)
[](https://github.com/vagabond11/elastic-zeroentropy/network/members)
[](https://github.com/vagabond11/elastic-zeroentropy/issues)
[](https://pypi.org/project/elastic-zeroentropy/)
---
## š Why This Works
**Most Elastic users struggle with vague, complex, or ambiguous queries.**
This tool reranks the top N results using LLM-based contextual understanding via ZeroEntropy.
**No vectors? No problem.**
**No AI skills needed.**
Just drop in the reranker and get smarter search results instantly.
---
## š License
MIT License - see [LICENSE](LICENSE) for details.
---
## š Links
- **š¦ PyPI**: https://pypi.org/project/elastic-zeroentropy/
- **š GitHub**: https://github.com/vagabond11/elastic-zeroentropy
- **š¤ ZeroEntropy**: https://zeroentropy.ai
- **š Issues**: https://github.com/vagabond11/elastic-zeroentropy/issues
- **š¬ Discussions**: https://github.com/vagabond11/elastic-zeroentropy/discussions
---
**Made with ā¤ļø by houssam Ait O.**
*Keywords: elasticsearch, search, ai-search, reranking, llm, zeroentropy, semantic-search, bm25, relevance, hybrid-search, open-source-search*
Raw data
{
"_id": null,
"home_page": null,
"name": "elastic-zeroentropy",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "ai, elasticsearch, llm, reranking, search, zeroentropy",
"author": null,
"author_email": "Houssam A\u00eft <houssam@example.com>",
"download_url": "https://files.pythonhosted.org/packages/64/cf/89944c6a76eb86e56eb8752302136367b99cbe98f4b0df3c93866f3cda31/elastic_zeroentropy-0.1.1.tar.gz",
"platform": null,
"description": "# \ud83d\udd01 ZeroEntropy Reranker for Elasticsearch\n\n**Boost your Elasticsearch results with LLM reranking in 5 minutes.** \nThis open-source tool adds a smart reranking layer to your existing Elastic queries using [ZeroEntropy's](https://zeroentropy.ai) API.\n\n\ud83e\udde0 Built for developers who want great search results without rebuilding their stack.\n\n[](https://badge.fury.io/py/elastic-zeroentropy)\n[](https://www.python.org/downloads/)\n[](https://opensource.org/licenses/MIT)\n[](https://fastapi.tiangolo.com/)\n[](https://zeroentropy.ai)\n[](https://www.elastic.co/)\n[](http://makeapullrequest.com)\n\n---\n\n## \ud83d\udda5\ufe0f Demo UI Preview\n\n\n\n*Interactive A/B testing interface comparing original Elasticsearch results with ZeroEntropy LLM-reranked results*\n\n---\n\n## \ud83c\udfaf The Problem\n\nMost Elasticsearch users struggle with:\n- **Vague queries** that return irrelevant results\n- **Complex search intent** that BM25 can't understand \n- **Ambiguous terms** that need contextual understanding\n- **No AI skills** to implement vector search\n\n**Solution**: Add LLM-powered reranking without changing your existing setup.\n\n---\n\n## \u2728 Features\n\n- \ud83d\udd0c **Plug-and-play**: Drop-in proxy or client wrapper\n- \ud83e\udde0 **LLM-powered relevance** via ZeroEntropy API\n- \u26a1 **Works with any Elasticsearch** or OpenSearch backend\n- \ud83d\udd0d **Hybrid-ready**: Rerank BM25 + vector results\n- \ud83d\udcca **Side-by-side comparison**: Original vs reranked output\n- \ud83d\ude80 **5-minute setup**: No AI expertise required\n- \ud83d\udcb0 **Cost-effective**: Only rerank top N results\n\n---\n\n## \ud83d\ude80 Quick Demo\n\n### \ud83d\udda5\ufe0f Interactive Demo UI\nTry our **live A/B testing interface** to compare original vs reranked results:\n\n```bash\n# Quick start (recommended)\n./run_demo.sh\n\n# Or manual setup\ncd examples\npip install -r requirements_demo.txt\nstreamlit run demo_ui.py\n```\n\n**Features:**\n- \ud83d\udd04 Side-by-side comparison\n- \u2699\ufe0f Interactive parameter controls \n- \ud83d\udcca Real-time performance metrics\n- \ud83c\udfaf Demo mode (no API keys needed)\n\n### \ud83d\udcbb Code Example\n```python\nimport asyncio\nfrom elastic_zeroentropy import ElasticZeroEntropyReranker\n\nasync def main():\n async with ElasticZeroEntropyReranker() as reranker:\n response = await reranker.search(\n query=\"machine learning applications in healthcare\",\n index=\"research_papers\"\n )\n \n for result in response.results:\n print(f\"\ud83d\udd0d {result.document.title}\")\n print(f\" \ud83d\udcca Score: {result.score:.4f}\")\n print(f\" \ud83d\udcc4 {result.document.text[:100]}...\")\n\nasyncio.run(main())\n```\n\n**Before vs After:**\n| Query | Original Elastic | Reranked (ZeroEntropy) |\n|-------|------------------|-------------------------|\n| \"books about hope and war\" | \ud83d\udd3b Generic results | \u2705 Contextually relevant |\n| \"machine learning healthcare\" | \ud83d\udd3b Broad matches | \u2705 Domain-specific papers |\n| \"python async programming\" | \ud83d\udd3b Mixed relevance | \u2705 Focused tutorials |\n\n---\n\n## \ud83d\udda5\ufe0f Demo UI Guide\n\nThe **Elastic-ZeroEntropy Demo UI** is a powerful A/B testing interface that lets you compare original Elasticsearch results with ZeroEntropy reranked results in real-time.\n\n\n\n### \ud83d\ude80 Getting Started\n\n1. **Launch the Demo:**\n ```bash\n ./run_demo.sh\n ```\n This opens the UI at http://localhost:8501\n\n2. **Choose Your Mode:**\n - **Demo Mode** (default): Works without API keys using sample data\n - **Live Mode**: Connect to your Elasticsearch + ZeroEntropy API\n\n### \ud83c\udf9b\ufe0f UI Features\n\n#### **Main Interface**\n- **\ud83d\udd0d Search Bar**: Enter your query to test\n- **\ud83d\ude80 Run A/B Test**: Execute the comparison\n- **\ud83d\udcca Results Comparison**: Side-by-side view of original vs reranked\n\n#### **Sidebar Configuration**\n\n**\ud83d\udd11 API Configuration:**\n- **ZeroEntropy API Key**: Your API key from https://zeroentropy.dev\n- **Elasticsearch URL**: Your ES instance (default: http://localhost:9200)\n- **Index Name**: Target Elasticsearch index\n\n**\ud83d\udd0d Search Settings:**\n- **Initial Results from ES**: How many docs to retrieve (10-200)\n- **Documents to Rerank**: How many to send for reranking (5-50)\n- **Final Results**: How many to display (5-20)\n\n**\ud83e\udde0 Reranking Settings:**\n- **ZeroEntropy Model**: Choose `zerank-1` or `zerank-1-small`\n- **Combine Scores**: Mix ES + rerank scores\n- **Score Weights**: Adjust ES vs rerank importance (0.0-1.0)\n\n**\ud83d\udcca Demo Data:**\n- **Use Demo Data**: Enable for testing without real connections\n\n### \ud83d\udcc8 Understanding Results\n\n#### **Performance Metrics**\n- **Query Time**: Total search + reranking duration\n- **ES Time**: Elasticsearch query time\n- **Reranking Time**: ZeroEntropy API processing time\n- **Model Used**: Which ZeroEntropy model was applied\n\n#### **Results Comparison**\n- **Original Ranking**: Elasticsearch BM25 results\n- **Reranked Results**: ZeroEntropy LLM-enhanced results\n- **Score Breakdown**: ES score vs rerank score vs combined score\n- **Relevance Improvement**: Visual indicators of better matches\n\n#### **Visual Features**\n- **\ud83d\udcca Performance Charts**: Real-time metrics visualization\n- **\ud83c\udfaf Relevance Indicators**: Color-coded relevance scores\n- **\ud83d\udccb Detailed Metadata**: Document info, timestamps, sources\n- **\ud83d\udd04 A/B Comparison**: Side-by-side result analysis\n\n### \ud83c\udfaf Use Cases\n\n#### **Testing Search Quality**\n1. Enter a complex query like \"machine learning healthcare applications\"\n2. Compare original vs reranked results\n3. Notice how LLM reranking improves contextual relevance\n\n#### **Parameter Tuning**\n1. Adjust `top_k_initial` to control ES result pool\n2. Modify `top_k_rerank` to balance cost vs quality\n3. Tune score weights for your use case\n4. Test different ZeroEntropy models\n\n#### **Performance Optimization**\n1. Monitor query times for different configurations\n2. Balance speed vs accuracy with model selection\n3. Optimize for your specific workload\n\n### \ud83d\udd27 Advanced Features\n\n#### **Real-time Configuration**\n- **Dynamic Parameter Updates**: Change settings without restart\n- **Live API Testing**: Test your ZeroEntropy API key\n- **Elasticsearch Connection**: Verify ES connectivity\n\n#### **Demo Mode Benefits**\n- **No API Keys Required**: Test the interface immediately\n- **Sample Data**: Realistic documents for testing\n- **Simulated Reranking**: Understand the process flow\n\n#### **Production Mode**\n- **Live Elasticsearch**: Connect to your actual ES instance\n- **Real ZeroEntropy API**: Use actual LLM reranking\n- **Performance Monitoring**: Track real-world metrics\n\n### \ud83d\udca1 Pro Tips\n\n1. **Start with Demo Mode**: Understand the interface before connecting APIs\n2. **Test Complex Queries**: Try ambiguous or multi-concept searches\n3. **Compare Different Models**: Test `zerank-1` vs `zerank-1-small`\n4. **Monitor Performance**: Watch query times and adjust parameters\n5. **Save Configurations**: Note your best settings for production\n\n### \ud83d\udea8 Troubleshooting\n\n**Demo won't start:**\n```bash\n# Check if port 8501 is free\nlsof -i :8501\n# Kill existing process if needed\npkill -f streamlit\n```\n\n**API connection issues:**\n- Verify your ZeroEntropy API key\n- Check Elasticsearch URL and connectivity\n- Ensure index exists and is accessible\n\n**Performance problems:**\n- Reduce `top_k_initial` for faster queries\n- Use `zerank-1-small` for lower latency\n- Adjust score weights for your use case\n\n---\n\n## \ud83d\udce6 Installation\n\n```bash\npip install elastic-zeroentropy\n```\n\nOr with CLI tools:\n```bash\npip install \"elastic-zeroentropy[cli]\"\n```\n\n---\n\n## \u26a1 5-Minute Setup\n\n### 1. Get ZeroEntropy API Key\n```bash\n# Sign up at https://zeroentropy.ai\nexport ZEROENTROPY_API_KEY=\"your_api_key_here\"\n```\n\n### 2. Configure Elasticsearch\n```bash\nexport ELASTICSEARCH_URL=\"http://localhost:9200\"\n```\n\n### 3. Run Your First Search\n```python\nfrom elastic_zeroentropy import ElasticZeroEntropyReranker\n\nasync with ElasticZeroEntropyReranker() as reranker:\n results = await reranker.search(\"your query\", \"your_index\")\n```\n\n---\n\n## \ud83c\udf9b\ufe0f Advanced Usage\n\n### Custom Reranking Configuration\n```python\nfrom elastic_zeroentropy import RerankerConfig\n\nconfig = RerankerConfig(\n top_k_initial=100, # Get 100 docs from Elasticsearch\n top_k_rerank=20, # Send top 20 to reranker\n top_k_final=10, # Return top 10 final results\n model=\"zerank-1-small\", # Use faster model\n combine_scores=True, # Mix ES + rerank scores\n score_weights={\n \"elasticsearch\": 0.3,\n \"rerank\": 0.7\n }\n)\n\nresponse = await reranker.search(\n query=\"deep learning neural networks\",\n index=\"ai_papers\",\n reranker_config=config\n)\n```\n\n### Batch Processing\n```python\nfrom elastic_zeroentropy import SearchRequest\n\nrequests = [\n SearchRequest(query=\"machine learning\", index=\"papers\"),\n SearchRequest(query=\"natural language processing\", index=\"papers\"),\n SearchRequest(query=\"computer vision\", index=\"papers\"),\n]\n\nresponses = await reranker.search_batch(requests, max_concurrent=3)\n```\n\n### Health Monitoring\n```python\nhealth = await reranker.health_check()\nprint(f\"Status: {health.status}\")\nprint(f\"Elasticsearch: {health.elasticsearch['status']}\")\nprint(f\"ZeroEntropy: {health.zeroentropy['status']}\")\n```\n\n---\n\n## \ud83d\udda5\ufe0f Command Line Interface\n\n### Basic Search\n```bash\nelastic-zeroentropy search \"machine learning\" my_index --top-k 5\n```\n\n### Advanced Search with Filters\n```bash\nelastic-zeroentropy search \\\n \"deep learning\" \\\n research_papers \\\n --top-k-initial 100 \\\n --top-k-rerank 20 \\\n --top-k 10 \\\n --model zerank-1-small \\\n --filters '{\"category\": \"AI\", \"year\": {\"gte\": 2020}}' \\\n --debug-info\n```\n\n### Health Check\n```bash\nelastic-zeroentropy health\n```\n\n---\n\n## \ud83c\udfd7\ufe0f Architecture\n\n```\nUser Query \u2192 Elasticsearch \u2192 Top N Results \u2192 ZeroEntropy API \u2192 Reranked Results\n```\n\n1. **Elasticsearch Search**: Get initial results using your existing queries\n2. **Document Selection**: Choose top N documents for reranking\n3. **ZeroEntropy Reranking**: Send to LLM for contextual relevance scoring\n4. **Score Combination**: Mix Elasticsearch and rerank scores (optional)\n5. **Final Results**: Return intelligently reranked results\n\n---\n\n## \ud83c\udfaf Performance\n\nBased on ZeroEntropy's benchmarks:\n- **Accuracy**: Up to 28% improvement in NDCG@10\n- **Speed**: ~150ms latency for small payloads\n- **Cost**: $0.025 per million tokens (50% less than competitors)\n- **Throughput**: High concurrent request support\n\n---\n\n## \ud83d\udd27 Configuration\n\n### Environment Variables\n```bash\n# Required\nZEROENTROPY_API_KEY=your_api_key_here\n\n# Optional\nZEROENTROPY_BASE_URL=https://api.zeroentropy.dev/v1\nZEROENTROPY_MODEL=zerank-1\nELASTICSEARCH_URL=http://localhost:9200\nDEFAULT_TOP_K_INITIAL=100\nDEFAULT_TOP_K_RERANK=20\nDEFAULT_TOP_K_FINAL=10\n```\n\n### Programmatic Configuration\n```python\nfrom elastic_zeroentropy import ElasticZeroEntropyConfig\n\nconfig = ElasticZeroEntropyConfig(\n zeroentropy_api_key=\"your_key\",\n elasticsearch_url=\"http://localhost:9200\",\n default_top_k_final=15\n)\n```\n\n---\n\n## \ud83e\udde9 Coming Soon\n\n- [ ] **Smart Reranking**: Only rerank when needed (query classifier)\n- [x] **UI Toggle**: Compare original vs reranked results \u2705\n- [ ] **LangChain Integration**: Plugin for LangChain workflows\n- [x] **Streamlit App**: Interactive demo and testing \u2705\n- [ ] **More Models**: Support for additional ZeroEntropy models\n- [ ] **Caching**: Intelligent result caching for repeated queries\n\n---\n\n## \ud83e\udd1d Contributing\n\nWe're building a better search UX together! PRs, feedback, and ideas welcome.\n\n### Development Setup\n```bash\ngit clone https://github.com/vagabond11/elastic-zeroentropy.git\ncd elastic-zeroentropy\npip install -e \".[dev]\"\npytest\n```\n\n### Areas to Contribute\n- \ud83c\udfa8 **UI/UX**: Better demos and visualizations\n- \ud83d\udd27 **Integrations**: LangChain, Streamlit, FastAPI plugins\n- \ud83d\udcca **Analytics**: Search quality metrics and monitoring\n- \ud83c\udf10 **Documentation**: Examples, tutorials, case studies\n\n---\n\n## \ud83d\udcca Community Stats\n\n[](https://github.com/vagabond11/elastic-zeroentropy/stargazers)\n[](https://github.com/vagabond11/elastic-zeroentropy/network/members)\n[](https://github.com/vagabond11/elastic-zeroentropy/issues)\n[](https://pypi.org/project/elastic-zeroentropy/)\n\n---\n\n## \ud83c\udfc6 Why This Works\n\n**Most Elastic users struggle with vague, complex, or ambiguous queries.**\n\nThis tool reranks the top N results using LLM-based contextual understanding via ZeroEntropy.\n\n**No vectors? No problem.** \n**No AI skills needed.**\n\nJust drop in the reranker and get smarter search results instantly.\n\n---\n\n## \ud83d\udcc4 License\n\nMIT License - see [LICENSE](LICENSE) for details.\n\n---\n\n## \ud83d\udd17 Links\n\n- **\ud83d\udce6 PyPI**: https://pypi.org/project/elastic-zeroentropy/\n- **\ud83d\udc19 GitHub**: https://github.com/vagabond11/elastic-zeroentropy\n- **\ud83e\udd16 ZeroEntropy**: https://zeroentropy.ai\n- **\ud83d\udccb Issues**: https://github.com/vagabond11/elastic-zeroentropy/issues\n- **\ud83d\udcac Discussions**: https://github.com/vagabond11/elastic-zeroentropy/discussions\n\n---\n\n**Made with \u2764\ufe0f by houssam Ait O.**\n\n*Keywords: elasticsearch, search, ai-search, reranking, llm, zeroentropy, semantic-search, bm25, relevance, hybrid-search, open-source-search*\n",
"bugtrack_url": null,
"license": null,
"summary": "Turn Elasticsearch into a smart search engine in 5 minutes with ZeroEntropy's LLM-powered reranking.",
"version": "0.1.1",
"project_urls": {
"Documentation": "https://github.com/vagabond11/elastic-zeroentropy#readme",
"Homepage": "https://github.com/vagabond11/elastic-zeroentropy",
"Issues": "https://github.com/vagabond11/elastic-zeroentropy/issues",
"Repository": "https://github.com/vagabond11/elastic-zeroentropy"
},
"split_keywords": [
"ai",
" elasticsearch",
" llm",
" reranking",
" search",
" zeroentropy"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "e3eaeb03b8c0b392546e1cd1016b8e5242aea8c03275caffd9edf9f6b7564ddd",
"md5": "d3450b81cfe293917c96ceccc8861fa0",
"sha256": "03e534c1c45345b0b491dc2ee45c1faeeb569c071a95098e2513fc82fb5b5865"
},
"downloads": -1,
"filename": "elastic_zeroentropy-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d3450b81cfe293917c96ceccc8861fa0",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 31745,
"upload_time": "2025-07-30T05:16:19",
"upload_time_iso_8601": "2025-07-30T05:16:19.130188Z",
"url": "https://files.pythonhosted.org/packages/e3/ea/eb03b8c0b392546e1cd1016b8e5242aea8c03275caffd9edf9f6b7564ddd/elastic_zeroentropy-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "64cf89944c6a76eb86e56eb8752302136367b99cbe98f4b0df3c93866f3cda31",
"md5": "dd934f056ae87bb78ad0bcadc8241cb0",
"sha256": "530c8014e7722326cb9f51bfa50f08417285e31099c872f064ea583478d49baa"
},
"downloads": -1,
"filename": "elastic_zeroentropy-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "dd934f056ae87bb78ad0bcadc8241cb0",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 36316,
"upload_time": "2025-07-30T05:16:20",
"upload_time_iso_8601": "2025-07-30T05:16:20.522108Z",
"url": "https://files.pythonhosted.org/packages/64/cf/89944c6a76eb86e56eb8752302136367b99cbe98f4b0df3c93866f3cda31/elastic_zeroentropy-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-30 05:16:20",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "vagabond11",
"github_project": "elastic-zeroentropy#readme",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "elastic-zeroentropy"
}
JSON
