Skip to main content

PaveDB — Retrieval you can inspect. Infrastructure you can own.

PaveDB is an inspectable retrieval database for AI applications. By default, text searches keep their source provenance, stored query record, and replay trail.

Start embedded in Python, self-host the same engine over HTTP, or point the same clients at managed PaveDB. The API stays stable and the archive remains portable, so the prototype is not a throwaway and the hosted path keeps an exit.

Highlights

  • One engine and interface from embedded prototype to self-hosted or managed production
  • Query history and replay for text searches, enabled by default
  • Deterministic provenance: every text-backed hit returns a document id, snippet, and source-specific page, row, or offset
  • Multi-tenant collections: /collections/{tenant}/{name}
  • Upload and search TXT, CSV, and PDF
  • Metadata filters on search ({"filters": {"docid": "DOC-1"}})
  • Embedded Python, REST, and CLI entry points
  • Health/metrics endpoints + Prometheus exporter
  • Local and hosted embedding choices; default stack is FAISS + SBERT

Requirements

  • Python 3.10–3.14

Install (PyPI)

python -m venv .venv
source .venv/bin/activate
pip install pavedb

CPU-only deployments can use the PyTorch CPU wheel index:

pip install "pavedb[cpu]" \
  --index-url https://download.pytorch.org/whl/cpu \
  --extra-index-url https://pypi.org/simple

Quickstart

Embedded, with no server or config:

from pavesdk.client import connect

db = connect("./data")
books = db.create_collection("books")
books.add("Captain Nemo commands the Nautilus.", docid="note-1")
hits = books.search("submarine captain", k=3)
db.close()

Serve the same engine over HTTP:

# Start the server (installed entry point)
pavesrv

pavesrv is the supported server entry point. The packaged pave.main:app target rejects direct ASGI loading because it bypasses startup policy. Close an embedded client before serving its data directory: one supported local entry point owns a directory at a time.

Auth defaults to static. none is refused outside dev mode. For production, set a key:

export PAVEDB_AUTH__MODE=static
export PAVEDB_AUTH__GLOBAL_KEY="your-secret"

Minimal config (optional)

By default PaveDB runs with sensible local defaults. For a user install, customize ~/pavedb/config.yml:

vector_store:
  type: faiss
embedder:
  default: native
  instances:
    native:
      type: sbert
auth:
  mode: static
  global_key: ${PAVEDB_GLOBAL_KEY}

Then export:

export PAVEDB_GLOBAL_KEY="your-secret"

If you keep the file elsewhere, point the runtime at it explicitly:

export PAVEDB_CONFIG=/path/to/config.yml

CLI example

pavecli create-collection demo/books
pavecli ingest demo/books demo/20k_leagues.txt --docid=verne-20k \
  --metadata='{"lang":"en"}'
pavecli search demo/books "captain nemo" -k 5

REST example

# Create a collection
curl -X POST http://localhost:8086/v1/collections/demo/books \
  -H "Authorization: Bearer your-secret"

# Upload a TXT document
curl -X POST http://localhost:8086/v1/collections/demo/books/documents \
  -H "Authorization: Bearer your-secret" \
  -F "file=@demo/20k_leagues.txt" -F "docid=verne-20k" \
  -F 'metadata={"lang":"en"}'

# Search (GET, no filters)
curl -G --data-urlencode "q=hello" \
  -H "Authorization: Bearer your-secret" \
  http://localhost:8086/v1/collections/demo/books/search

# Search (POST, with filters)
curl -X POST http://localhost:8086/v1/collections/demo/books/search \
  -H "Authorization: Bearer your-secret" \
  -H "Content-Type: application/json" \
  -d '{"q":"captain nemo","k":5,"filters":{"docid":"verne-20k"}}'

License

AGPL-3.0-or-later — (C) 2025, 2026 Rodrigo Rodrigues da Silva rodrigo@flowlexi.com

Metadata

Release files for pavedb 0.9.8.1

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

Source distribution (sdist)

Source distribution for pavedb 0.9.8.1
File Size Uploaded Provenance Actions
pavedb-0.9.8.1.tar.gz 517.3 kB Without provenance Details for pavedb-0.9.8.1.tar.gz

Built distribution (wheel)

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

Total release size: 759.7 kB

Release files / pavedb-0.9.8.1.tar.gz

Download URL pavedb-0.9.8.1.tar.gz
Size 517.3 kB
Tags Source
SHA-256 checksum
How to use checksums
9ef550ae3f85bc096bb4f58f861f8f281c3f6370a48934b95d684c16822b4037
BLAKE2b-256 checksum
How to use checksums
d03dfcac91ed262ca7ae5e89333f466bb41f16d64f5a12b7abf4e1095d0e048a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.11.16

Release files / pavedb-0.9.8.1-py3-none-any.whl

Download URL pavedb-0.9.8.1-py3-none-any.whl
Size 242.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
4ca6e007e83feae83807823615cf1f333d75cc04c6f59fa200b2630b3f7f8afe
BLAKE2b-256 checksum
How to use checksums
ed14122046f2b6949f2848dea8a21f5f90c298543dc123e55b16cf11fb61d5a1
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.11.16

Security for pavedb 0.9.8.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.

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