Inspectability release line

PaveDB in one page

PaveDB is the inspectable retrieval database: small enough to embed, complete enough to operate. You hand it files, it chunks, embeds and indexes them, and it answers semantic queries with the exact snippet that matched and where it came from. By default, text searches keep their query record and replay trail as well as their source provenance.

Use the same engine embedded in Python, self-host it over HTTP, or point the same clients at managed PaveDB. One interface carries the prototype into production without replacing the retrieval stack.

When you run it yourself: one process, one data directory. No cluster to operate, no external database.

The model

Four nouns, in order of containment:

A collection pins its embedder when you create it. That binding is enforced: vectors produced by a different model are rejected rather than mixed into an index where they would silently degrade results.

By default, each text search is written to a query log with its parameters, timing and result ids, and can be replayed later. Raw-vector searches are not replayable because their query vectors are not stored.

The pieces

You will touch some subset of these; they all drive the same service layer.

• pavesrv — the HTTP server. The REST API is the wire protocol everything else speaks.
• pavecli — the CLI. Same operations, useful for setup, inspection and scripting.
• Python SDK (pavedb-sdk) — connect() returns handles for collections and searches. Works against a URL, or against a local directory with no server at all.
• Elixir client — HTTP only.
• Store and embedder — internal, but you choose them by configuration: which vector backend holds the index, which model produces the vectors.

If you are deciding where to start: use the local CLI for an offline instance, or run the server and drive it with an HTTP client.

Doing the basic things

The shortest useful path, in any of the interfaces:

1. Create a collection — choose a name and, if you do not want the default, an embedder.
2. Ingest — hand it a file or a string with a docid. Re-ingesting the same docid replaces that document; no restart, no reindex step.
3. Search — send a query and a k. Each hit carries its score, its text and the provenance of the chunk it came from.
4. Inspect — for a logged text search, pull the query back out, inspect it, and replay it.

Concrete commands and payloads live in the CLI reference and the OpenAPI document; this page deliberately does not repeat them.

Running it for real

Three things decide whether a deployment is sound:

• Auth. auth.mode=static with a key per tenant. The server refuses to start unauthenticated outside dev mode — that refusal is the feature.
• The data directory. One directory holds every tenant, collection, index and log. One supported local entry point owns it at a time. Back it up as a unit; it is the whole state.
• Health. /health/live answers without touching the model; /health/ready verifies the data directory is writable. Point your orchestrator at the second one.

The production checklist turns these into steps.

Embedded, HTTP, managed

It is one engine behind three doors. Embedded, your Python process opens the data directory itself. Self-hosted, pavesrv opens it and every client speaks HTTP. Managed PaveDB runs the same server for you. The SDK’s connect() takes a path or a URL, so moving between them is a one-line change, and an archive taken from one restores into another.

Growing means a bigger machine, or more instances with a data directory each, for example one per workload or per group of tenants. PaveDB does not spread one index or one query across machines, and several processes never share a data directory.

Where to go next

The references above are generated from the code, so they do not drift. This guide is written by hand and stays deliberately short: it orients you, the references answer you, and the book goes deep.

Start here

Choose your path

Short paths, each ending somewhere you can build from. Every reference page stays available from the navigation.

Python Embed PaveDB in your process, or point it at HTTP.

1. Examples
2. API reference
3. Build

Start → Elixir Call a running PaveDB service from Elixir.

1. Examples
2. API reference
3. Build

Start → TypeScript Call a running PaveDB service from JavaScript or TypeScript.

1. Examples
2. API reference
3. Build

Start → Operations Run, configure, and operate an instance.

1. Running it
2. CLI
3. Configuration
4. REST API

Start →

Public draft coming soon Inspectable Retrieval with PaveDB Run the same engine embedded or as a service. Learn to inspect sources, compare query replays and operate your retrieval system. The full draft will be available by email. About the book →