🚀 FindaLedge: Simple Ensemble Search for RAG 🔍
FindaLedge is a Python library for building robust, hybrid search backends for Retrieval-Augmented Generation (RAG) and LLM applications. It unifies vector and keyword search, manages document ingestion, and provides a simple, powerful API.
✨ Build powerful RAG search backends with ease! ✨
🇯🇵 日本語版 README はこちら (Click here for Japanese README)
🤔 Why FindaLedge?
- Vector search (semantic) and keyword search (BM25) each have strengths and weaknesses.
- FindaLedge combines both (ensemble search) for best accuracy, with zero setup hassle.
- Handles all the plumbing: document loading, chunking, embedding, index sync, result fusion (RRF), and more!
✨ Features
| Feature | Description |
|---|---|
| 🎯 Hybrid Search | Combines vector & keyword search (BM25) with RRF fusion |
| 🔌 Flexible | Supports Chroma, FAISS, BM25s, OpenAI, Ollama, HuggingFace, etc. |
| 📚 Easy Ingestion | Add files, directories, or LangChain Documents instantly |
| 🔄 Auto Indexing | Indices are auto-created, updated, and persisted |
| 🧹 Simple API | Add, search, remove documents with one-liners |
| 🧩 LangChain Ready | Use as a Retriever in LangChain chains |
| 🧪 Full Test Suite | 100+ tests, pytest/uv compatible |
⚙️ Supported Environment
| Item | Supported |
|---|---|
| Python | 3.11+ (Windows/Powershell推奨) |
| OS | Windows, macOS, Linux |
| Vector DB | Chroma, FAISS (optional) |
| Embeddings | OpenAI, Ollama, HuggingFace, etc. |
| Agents SDK | OpenAI Agents SDK |
| Test | pytest, pytest-cov, uv |
🛠️ Quick Start
1. Install (with uv & venv recommended)
# Create and activate venv
python -m venv .venv
.venv\Scripts\Activate.ps1 # (Windows Powershell)
# Install uv (if not yet)
pip install uv
# Install dependencies
uv pip install -r requirements.txt
# or: uv pip install .
2. Set Environment Variables (optional)
$env:OPENAI_API_KEY="sk-..." # For OpenAI
$env:FINDALEDGE_EMBEDDING_MODEL_NAME="text-embedding-3-small"
$env:FINDALEDGE_PERSIST_DIR="./my_data"
3. Basic Usage
from findaledge import FindaLedge
ledge = FindaLedge()
ledge.add_document("docs/manual.txt")
results = ledge.search("What is the main topic?")
for r in results:
print(r.document.page_content, r.score)
4. Run Tests
.venv\Scripts\Activate.ps1
uv pip install -r requirements.txt
pytest
🏗️ Architecture (Layered)
| Layer | Class | Responsibility |
|---|---|---|
| Controller | FindaLedge | Unified API, orchestrates all below |
| UseCase | Finder | Hybrid search, RRF fusion |
| Gateway | ChromaDocumentStore, BM25sStore | Vector/BM25 storage |
| Function | DocumentLoader, DocumentSplitter, EmbeddingModelFactory | Loading, splitting, embedding |
| Data | LangchainDocument, SearchResult | Data objects |
| Utility | Tokenizer, config/env | Tokenize, config |
@startuml
FindaLedge --> Finder
FindaLedge --> DocumentLoader
FindaLedge --> DocumentSplitter
FindaLedge --> EmbeddingModelFactory
FindaLedge --> ChromaDocumentStore
FindaLedge --> BM25sStore
Finder --> SearchResult
@enduml
🧑💻 Main API (Class Table)
| Class | Role | Key Methods |
|---|---|---|
| FindaLedge | Facade/Controller | add_document, search, remove_document, get_context |
| Finder | UseCase (Hybrid) | search (RRF), find |
| ChromaDocumentStore | Gateway | add_documents, as_retriever |
| BM25sStore | Gateway | add_documents, as_retriever |
| EmbeddingModelFactory | Factory | create_embeddings |
| DocumentLoader | Loader | load_file, load_from_directory |
| DocumentSplitter | Splitter | split_documents |
📖 Documentation
🧪 Testing
- All tests pass (pytest/uv, Windows Powershell)
- Run:
pytest - Coverage: pytest-cov enabled
🤝 Contributing
Contributions welcome! Fork, branch, PR, and let's build better RAG search together 🚀
📜 License
MIT License. See LICENSE.
Metadata
Release files for findaledge 0.1.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| findaledge-0.1.1.tar.gz | 5.0 kB | Without provenance | Details for findaledge-0.1.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| findaledge-0.1.1-py3-none-any.whl | Python 3 | none | any | Details for findaledge-0.1.1-py3-none-any.whl |
Total release size: 9.3 kB
Release files / findaledge-0.1.1.tar.gz
| Download URL | findaledge-0.1.1.tar.gz |
|---|---|
| Size | 5.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
79ed8101f1450269e983a30481d33b1761e88f590bf4cff442ab89f5e1279ae3
|
|
BLAKE2b-256 checksum How to use checksums |
e092d54e8a0fa9856ae0eabaa51a5fccfe60c30f753c0a7df5c4a18a7bd13590
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.12.5
|
Release files / findaledge-0.1.1-py3-none-any.whl
| Download URL | findaledge-0.1.1-py3-none-any.whl |
|---|---|
| Size | 4.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
0e81b25c9fc8fd9009dd6242d7f5fd3088e86d8e4fb77cea4098e0a91e30d947
|
|
BLAKE2b-256 checksum How to use checksums |
c1f99e0132651f5428aa30f2cd184fee4b9f589319c64f67a5f38d3127873194
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.12.5
|
Security for findaledge 0.1.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.