PaveDB Python SDK API Reference

This reference is generated from pavesdk.__all__, the SDK public API boundary.

pavesdk.BaseClient

Transport-neutral client surface shared by HTTP and local providers.

BaseClient.close

close(self) -> None

Release resources held by this client.

BaseClient.create_collection

create_collection(
    self,
    name: str,
    *,
    tenant: str | None = None,
    display_name: str | None = None,
    embedder_type: str | None = None,
    embed_model: str | None = None,
    embedder_config: Mapping[str, Any] | None = None,
) -> Collection

Create a collection and return its tenant-scoped handle.

BaseClient.collection

collection(self, name: str, *, tenant: str | None = None) -> Collection

Return a handle for an existing collection.

BaseClient.list_collections

list_collections(self, *, tenant: str | None = None) -> list[Collection]

List collection handles for a tenant.

BaseClient.list_tenants

list_tenants(self) -> list[str]

List tenants visible to this client.

BaseClient.embedders

embedders(self, *, tenant: str | None = None) -> JsonMap

Return the configured embedders for a tenant.

BaseClient.delete_collection

delete_collection(self, name: str, *, tenant: str | None = None) -> JsonMap

Delete a collection and return the server response.

BaseClient.dump_archive

dump_archive(self, path: str | os.PathLike[str] | None = None) -> Any

Return an archive, or write it to path and return that path.

BaseClient.restore_archive

restore_archive(self, archive_bytes: bytes) -> JsonMap

Restore an archive payload and return the server response.

pavesdk.Collection

Handle for one tenant-scoped PaveDB collection.

Collection(client: BaseClient, tenant: str, name: str)

Create a handle for an existing tenant-scoped collection.

Collection.ingest

ingest(
    self,
    file: str | os.PathLike[str],
    *,
    docid: str | None = None,
    metadata: Metadata | None = None,
    csv_options: Mapping[str, Any] | None = None,
) -> JsonMap

Upload a document file to this collection.

Collection.add

add(
    self,
    text: str | None = None,
    *,
    vector: list[float] | None = None,
    docid: str | None = None,
    metadata: Metadata | None = None,
) -> JsonMap

Add text or a precomputed vector to this collection.

Collection.add_many

add_many(self, documents: list[object]) -> JsonMap

Add a batch of text or vector documents to this collection.

Collection.search

search(
    self,
    q: str | None = None,
    k: int = 5,
    *,
    vector: list[float] | None = None,
    filters: FilterSpec | None = None,
    include_common: bool | None = None,
) -> list[JsonMap]

Search this collection by text or a precomputed vector.

Collection.get

get(self, docid: str) -> JsonMap

Return one document by its document ID.

Collection.list_documents

list_documents(self) -> list[JsonMap]

List documents in this collection.

Collection.delete

delete(self, docid: str) -> JsonMap

Delete one document by its document ID.

Collection.detail

detail(self) -> JsonMap

Return this collection’s metadata and summary.

Collection.list_chunks

list_chunks(self, docid: str) -> list[JsonMap]

List indexed chunks for a document.

Collection.get_chunk

get_chunk(self, rid: str) -> JsonMap

Return one indexed chunk by its record ID.

Collection.get_chunk_content

get_chunk_content(self, rid: str) -> JsonMap

Return the raw content and content type for one chunk.

Collection.queries

queries(self, limit: int = 50, offset: int = 0) -> list[JsonMap]

List recorded queries for this collection.

Collection.get_query

get_query(self, qid: str) -> JsonMap

Return one recorded query by its ID.

Collection.replay

replay(self, qid: str) -> list[JsonMap]

Replay a recorded query and return its current matches.

Collection.rename

rename(self, new_name: str) -> Collection

Rename this collection and return the same handle.

Collection.update

update(self, *, display_name: str) -> JsonMap

Update this collection’s display name.

pavesdk.Conflict

Request conflicts with existing state.

pavesdk.HttpClient

Synchronous client for the PaveDB /v1 HTTP API.

HttpClient(
    base_url: str,
    *,
    api_key: str | None = None,
    tenant: str = 'default',
    timeout: float | httpx.Timeout = 30.0,
    headers: Mapping[str, str] | None = None,
    http_client: httpx.Client | None = None,
)

Create a client with optional bearer authentication and transport.

HttpClient.close

close(self) -> None

Close the HTTP connection pool when this client owns it.

pavesdk.InvalidRequest

Request shape or arguments are invalid.

pavesdk.LocalClientUnavailable

A local target was requested without a local provider installed.

pavesdk.NotFoundError

Requested resource was not found.

pavesdk.PaveError

Base PaveDB client error.

pavesdk.PAVEDB_API_PREFIX

'/v1'

pavesdk.PAVEDB_API_VERSION

'v1'

pavesdk.Unavailable

The server or an underlying dependency is unavailable.

pavesdk.__version__

Installed pavedb-sdk distribution version.

pavesdk.batch_item

batch_item(document: object) -> JsonMap

Normalize one text or vector item for Collection.add_many.

pavesdk.connect

connect(
    target: str | os.PathLike[str] | None = None,
    *,
    api_key: str | None = None,
    tenant: str = 'default',
    timeout: float | httpx.Timeout = 30.0,
) -> HttpClient | Any

Connect to an HTTP server or an installed local PaveDB provider.

Omit target for an ephemeral local store. HTTP URLs return HttpClient.