Resonance-Based Semantic Protocol — Zero-Dependency Pure-Python Search Engine
BM25 · TF-IDF · HNSW Vector Search · Hybrid Semantic Ranking · 3,233 Tests · 85 Modules · 0 Dependencies
Full-Text Search | Semantic Vector Search | Hybrid Resonance Fusion | HTTP API Server | CLI Tool
RBSP (Resonance-Based Semantic Protocol) is a state-of-the-art, production-ready search engine written entirely in Python with zero external dependencies. It combines classical information retrieval techniques (BM25, TF-IDF, inverted indices, Porter stemming) with modern vector search (HNSW graphs, binary/product quantization) and a novel resonance-based hybrid fusion algorithm.
Ships as a Python library, CLI tool, and HTTP API server — everything works out of the box with just Python 3.9+ and the standard library. No heavy dependencies like NumPy, PyTorch, or Elasticsearch required.
Whether you need a lightweight embedded search for your application, a standalone search server, or a research platform for IR experimentation, RBSP delivers enterprise-grade search without the infrastructure overhead.
- BM25 Ranking — Industry-standard probabilistic ranking with tuned k1/b parameters
- TF-IDF Scoring — Classic term frequency-inverse document frequency weighting
- Semantic Vector Search — HNSW (Hierarchical Navigable Small World) approximate nearest neighbor graphs
- Resonance-Based Hybrid Fusion — Novel algorithm combining lexical and semantic signals for superior relevance
- Binary & Product Quantization — Memory-efficient vector compression for large corpora
- Inverted Index — High-performance positional inverted index with skip lists
- Porter Stemmer — Built-in English stemming (hand-ported, zero-dependency)
- Tokenization & Normalization — Unicode-aware token pipeline with stop-word filtering
- N-gram Support — Character and word n-grams for fuzzy matching
- Incremental Indexing — Add, update, and delete documents without full rebuilds
- Python API — Clean, idiomatic
init(),index(),search()interface - CLI Tool —
rbspcommand for indexing and searching from the terminal - HTTP API Server — RESTful search endpoint with JSON responses
- Docker Support — Production-ready
Dockerfileincluded - Pre-commit Hooks — Configured for code quality enforcement
- 3,233 Tests — Comprehensive test suite across 85+ test files
- 80%+ Code Coverage — Thoroughly tested across Python 3.9–3.13
- Zero Dependencies — Pure stdlib, no C extensions, no pip conflicts
- MIT Licensed — Use freely in personal and commercial projects
| Category | Technology | Version |
|---|---|---|
| Language | Python | 3.9 – 3.13 |
| Build | setuptools | ≥ 68.0 |
| Dependencies | None (stdlib only) | — |
| CI | GitHub Actions | — |
| License | MIT | — |
| Testing | unittest (stdlib) | — |
| Formatting | Black | — |
| Containerization | Docker | — |
| Package Distribution | PyPI | rbsp |
pip install rbspgit clone https://github.com/yethikrishna/rbsp-framework.git
cd rbsp-framework
pip install -e .from rbsp import init, index, search
# Initialize the search engine for a project directory
init("/path/to/your/project")
# Index all documents in the directory
stats = index("/path/to/your/project")
print(f"Indexed {stats.files_indexed} files in {stats.duration:.2f}s")
print(f"Vocabulary size: {stats.vocab_size}")
# Perform a search
results = search("resonance-based hybrid ranking")
for r in results[:10]:
print(f"[{r.score:.4f}] {r.path}: {r.snippet}")# Index a directory
rbsp index ./my-docs
# Search the index
rbsp search "machine learning optimization"
# Start the HTTP server
rbsp serve --host 0.0.0.0 --port 8080# Start the server
rbsp serve --port 8080
# Search via curl
curl "http://localhost:8080/search?q=semantic+vector+search&limit=10"
# Index via API
curl -X POST http://localhost:8080/index \
-H "Content-Type: application/json" \
-d '{"path": "/data/documents"}'rbsp-framework/
├── src/
│ └── rbsp/ # Main package
│ ├── core/ # Core indexing & search logic
│ ├── ranking/ # BM25, TF-IDF, resonance fusion
│ ├── vector/ # HNSW, quantization, embeddings
│ ├── analysis/ # Tokenization, stemming, n-grams
│ ├── api/ # HTTP server implementation
│ ├── runtime/ # CLI entry point & runtime
│ └── utils/ # Utility modules
├── tests/ # 3,233 tests across 85+ files
├── benchmarks/ # Performance benchmarks
├── docs/ # Documentation
├── .github/
│ └── workflows/ci.yml # CI pipeline
├── Dockerfile # Docker containerization
├── pyproject.toml # Build configuration
├── CHANGELOG.md # Version history
├── CONTRIBUTING.md # Contribution guidelines
├── SECURITY.md # Security policy
├── LICENSE # MIT License
└── README.md # This file
docker build -t rbsp .
docker run -p 8080:8080 rbsp serve --host 0.0.0.0 --port 8080The package is published to PyPI as rbsp:
pip install rbsp- Run behind a reverse proxy (nginx, Caddy) for TLS termination
- Use persistent volumes for index storage in containerized deployments
- Monitor memory usage with large corpora; quantization settings help
- The HTTP API is stateless — horizontally scalable behind a load balancer
| Feature | RBSP | Elasticsearch | Whoosh | Tantivy |
|---|---|---|---|---|
| Zero Dependencies | Yes | No (JVM) | Yes | No (Rust) |
| Pure Python | Yes | No | Yes | No |
| Semantic Search | Yes | Yes (plugins) | No | Yes |
| HNSW Vector Search | Yes | Yes | No | Yes |
| Hybrid Fusion | Yes (Resonance) | RRF | No | No |
| Setup Effort | pip install |
Heavy infra | pip install |
Compile |
| Test Coverage | 3,233 tests | N/A | Limited | Good |
| HTTP API Built-in | Yes | Yes | No | No |
Contributions are welcome! Please see CONTRIBUTING.md for guidelines.
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Make your changes and add tests
- Run the test suite (
python -m pytestorpython -m unittest discover) - Ensure pre-commit hooks pass
- Submit a pull request
See CHANGELOG.md for a detailed history of changes.
See SECURITY.md for our security policy and how to report vulnerabilities.
This project is licensed under the MIT License — see the LICENSE file for details.
RBSP — Built with pure Python, powered by resonance.