Skip to main content

DBless

Lightweight, no-database PDF search engine — pure Python, no servers, no setup.

PyPI version Python License: MIT


💡 What is DBless?

DBless is a lightweight document search engine that works entirely in-memory — no database, no server, no external dependencies beyond numpy. Point it at a PDF and start searching in seconds.

Why DBless?

  • 🚀 Zero setup — no database to install or configure
  • 🎯 Definition-aware — understands "What is X?" style queries
  • 🪶 Lightweight — only requires numpy and pymupdf
  • 📄 Multi-domain — works on legal, medical, corporate, and technical PDFs
  • ⚡ Fast — sub-100ms search on CPU

📚 Documentation Contents


🚀 Quick Start

from dbless.engine import DBlessEngine

# 1. Load and index a PDF
engine = DBlessEngine.from_pdf(
    "document.pdf",
    chunk_size=100,   # words per chunk
    overlap=20        # overlap between chunks
)

# 2. Search
results = engine.search("What is machine learning?", k=5)

# 3. Print results
for result in results:
    print(f"Score : {result['score']:.2f}")
    print(f"Snippet: {result['snippet']}")
    print("---")

📦 Installation

pip install dbless

Or install from source:

git clone https://github.com/rahulreddy9725/Dbless.git
cd Dbless
pip install -e .

🔧 API Reference

DBlessEngine.from_pdf(path, chunk_size, overlap, vector_dim, factor_rank)

Loads a PDF, chunks it, embeds it, and builds the search index.

Parameter Type Default Description
path str / Path required Path to the PDF file
chunk_size int 600 Number of words per chunk
overlap int 150 Word overlap between consecutive chunks
vector_dim int 512 Hash vector dimensionality
factor_rank int 128 SVD factorization rank

Returns: DBlessEngine instance


engine.search(query, k)

Search the indexed PDF for the most relevant chunks.

Parameter Type Default Description
query str required Natural language query
k int 5 Number of results to return

Returns: list[dict] — each result contains:

Key Description
text Full chunk text
snippet Best-matching sentence(s) from the chunk
score Relevance score (0–100)
page Page number in the PDF
chunk_id Chunk index

Example:

results = engine.search("What are exceptions?", k=3)
for r in results:
    print(r["snippet"])   # best answer sentence
    print(r["score"])     # relevance score 0-100
    print(r["page"])      # page number

🖥️ CLI Usage

DBless ships with a command-line tool:

# Index a PDF and show chunk count
dbless index document.pdf

# Query a PDF and get top results
dbless query document.pdf "What is machine learning?" -k 5

⚙️ How It Works

Step Description
1. Chunk PDF is split into overlapping word-based chunks
2. Embed Each chunk is hashed into a sparse numpy vector
3. IDF Weight Term frequency weighting applied across all chunks
4. SVD Compress Dimensionality reduced via matrix factorization
5. Quantize Vectors quantized to Int8 for memory efficiency
6. Search Query vector matched via dot product + BM25 boosting
7. Re-rank Definition-style queries get special re-ranking

🧪 Testing

pytest tests/

Test coverage includes:

  • ✅ PDF ingestion and chunking
  • ✅ Vector quantization accuracy
  • ✅ Phrase and keyword search
  • ✅ End-to-end engine from PDF to results

📊 Performance

Metric Value
Memory per 100-page PDF ~10–50 MB
Search speed < 100ms on CPU
Top-3 accuracy (definitions) 85–95%
Python support 3.8 – 3.12

🤝 Contributing

Contributions are welcome!

  1. Fork the repository
  2. Create a feature branch: git checkout -b feature/my-feature
  3. Commit your changes: git commit -m "Add my feature"
  4. Push and open a Pull Request

Please open an issue first for major changes.


📄 License

MIT License — see LICENSE for details.



Built with ❤️ by Rahul Reddy

Metadata

Release files for dbless 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for dbless 0.1.0
File Size Uploaded Provenance Actions
dbless-0.1.0.tar.gz 4.0 MB Without provenance Details for dbless-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for dbless 0.1.0
File Interpreter ABI Platform Actions
dbless-0.1.0-py3-none-any.whl Python 3 none any Details for dbless-0.1.0-py3-none-any.whl

Total release size: 4.0 MB

Release files / dbless-0.1.0.tar.gz

Download URL dbless-0.1.0.tar.gz
Size 4.0 MB
Tags Source
SHA-256 checksum
How to use checksums
ad4c42955549324d05795c46a2a195ffd7c9b781eb4a11be8fa68b62ce49298e
BLAKE2b-256 checksum
How to use checksums
98801154a11ed001ea3532ecf6b4dcc58b82f39cb136631151f02ed56566e59a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.11.0

Release files / dbless-0.1.0-py3-none-any.whl

Download URL dbless-0.1.0-py3-none-any.whl
Size 21.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
039607cc5aa0a90e81da8038087b7611e1f17de5e815d095beefcb9fc6a1ec1e
BLAKE2b-256 checksum
How to use checksums
c8c3c438c376967c0adbbd843afbc4f9739600b5fb287ac015868e36e6ca935c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.11.0

Security for dbless 0.1.0

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.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page