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

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
File Size Uploaded Provenance Actions
pavedb-0.9.8.tar.gz 514.9 kB Without provenance Details for pavedb-0.9.8.tar.gz

Built distribution (wheel)

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

Total release size: 757.3 kB

Release files / pavedb-0.9.8.tar.gz

Download URL pavedb-0.9.8.tar.gz
Size 514.9 kB
Tags Source
SHA-256 checksum
How to use checksums
1b3f871fb167e9469150784bfb1b68f15497850d421b6650415c21a22e26ffb1
BLAKE2b-256 checksum
How to use checksums
34f9c00cfce7482cad4ba2a26362dbcd39cdc68440be568e271388c41d1cb9c2
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-py3-none-any.whl

Download URL pavedb-0.9.8-py3-none-any.whl
Size 242.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
322cd318f11fddbc4b3e28fe88b6004fc8475526f49762489381157d23230e21
BLAKE2b-256 checksum
How to use checksums
00e67b68d18c96e0e24178739120854f6a0d4a14645e3eba2ea2bc4b29125f4e
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

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