@spec add_many(PaveDBClient.Client.t(), String.t(), String.t(), list()) ::
  {:ok, map()} | {:error, PaveDBClient.Error.t()}

Adds several raw text documents to a collection.

Each item may be a string, a map with text or vector plus docid and metadata, or {text, docid, metadata}.

@spec add_text(PaveDBClient.Client.t(), String.t(), String.t(), String.t(), keyword()) ::
  {:ok, map()} | {:error, PaveDBClient.Error.t()}

Adds one raw text document to a collection.

@spec add_vector(
  PaveDBClient.Client.t(),
  String.t(),
  String.t(),
  [number()],
  keyword()
) ::
  {:ok, map()} | {:error, PaveDBClient.Error.t()}

Adds one precomputed embedding to a collection.

PaveDB takes either text or a raw vector, never both.

@spec collection(PaveDBClient.Client.t(), String.t(), keyword()) ::
  PaveDBClient.Collection.t()

Builds a tenant-scoped collection handle without making a request.

@spec collection_detail(PaveDBClient.Client.t(), String.t(), String.t()) ::
  {:ok, map()} | {:error, PaveDBClient.Error.t()}

Fetches a collection's settings plus document and chunk counts.

@spec connect(
  String.t() | nil,
  keyword()
) :: PaveDBClient.Client.t()

Builds a client for a running PaveDB HTTP server.

The base URL falls back to PAVEDB_URL, then to http://localhost:8086. See PaveDBClient.Client.new/2 for the options.

@spec create_collection(PaveDBClient.Client.t(), String.t(), keyword()) ::
  {:ok, PaveDBClient.Collection.t()} | {:error, PaveDBClient.Error.t()}

Creates a collection and returns a collection handle.

@spec create_collection(
  PaveDBClient.Client.t(),
  String.t(),
  String.t(),
  map() | keyword()
) ::
  {:ok, map()} | {:error, PaveDBClient.Error.t()}

Creates or configures a tenant collection.

@spec delete_collection(PaveDBClient.Client.t(), String.t(), String.t()) ::
  {:ok, map()} | {:error, PaveDBClient.Error.t()}

Deletes a collection and every document in it.

@spec delete_document(PaveDBClient.Client.t(), String.t(), String.t(), String.t()) ::
  {:ok, map()} | {:error, PaveDBClient.Error.t()}

Deletes one document by id.

@spec format_error(PaveDBClient.Error.t() | term()) :: String.t()

Formats a structured client error for logs or operator messages.

@spec get_chunk(PaveDBClient.Client.t(), String.t(), String.t(), String.t()) ::
  {:ok, map()} | {:error, PaveDBClient.Error.t()}

Fetches one chunk by its record id.

@spec get_chunk_content(PaveDBClient.Client.t(), String.t(), String.t(), String.t()) ::
  {:ok, map()} | {:error, PaveDBClient.Error.t()}

Fetches one chunk's raw text content.

Returns %{"content" => body, "content_type" => type}; the endpoint answers with the raw body rather than a JSON envelope.

@spec get_document(PaveDBClient.Client.t(), String.t(), String.t(), String.t()) ::
  {:ok, map()} | {:error, PaveDBClient.Error.t()}

Fetches one document by id.

@spec get_query(PaveDBClient.Client.t(), String.t(), String.t(), String.t()) ::
  {:ok, map()} | {:error, PaveDBClient.Error.t()}

Fetches one logged search, including its original result ids.

@spec health(PaveDBClient.Client.t()) ::
  {:ok, map()} | {:error, PaveDBClient.Error.t()}

Checks server health through the root /health endpoint.

/health lives outside the /v1 API and needs no auth, so it doubles as a basic connection check. Returns the readiness envelope (status, version).

@spec ingest_file(
  PaveDBClient.Client.t(),
  String.t(),
  String.t(),
  Path.t(),
  keyword()
) ::
  {:ok, map()} | {:error, PaveDBClient.Error.t()}

Uploads a local file to a collection.

@spec list_chunks(PaveDBClient.Client.t(), String.t(), String.t(), String.t()) ::
  {:ok, map()} | {:error, PaveDBClient.Error.t()}

Lists the chunks a document was split into.

@spec list_collections(
  PaveDBClient.Client.t(),
  keyword()
) :: {:ok, map()} | {:error, PaveDBClient.Error.t()}

Lists a tenant's collections.

@spec list_documents(PaveDBClient.Client.t(), String.t(), String.t()) ::
  {:ok, [map()]} | {:error, PaveDBClient.Error.t()}

Lists documents in a collection.

@spec list_queries(PaveDBClient.Client.t(), String.t(), String.t(), keyword()) ::
  {:ok, map()} | {:error, PaveDBClient.Error.t()}

Lists logged searches for a collection, newest first.

@spec move_collection(PaveDBClient.Client.t(), String.t(), String.t(), String.t()) ::
  {:ok, map()} | {:error, PaveDBClient.Error.t()}

Renames a collection, changing its slug and URL.

@spec new(
  String.t() | nil,
  keyword()
) :: PaveDBClient.Client.t()

Alias for connect/2.

@spec replay_query(PaveDBClient.Client.t(), String.t(), String.t(), String.t()) ::
  {:ok, map()} | {:error, PaveDBClient.Error.t()}

Replays one logged search against the collection's current data.

@spec search(PaveDBClient.Client.t(), String.t(), String.t(), String.t(), keyword()) ::
  {:ok, map()} | {:error, PaveDBClient.Error.t()}

Searches a collection and returns the full PaveDB response envelope.

@spec search_shared(PaveDBClient.Client.t(), String.t(), keyword()) ::
  {:ok, map()} | {:error, PaveDBClient.Error.t()}

Searches the one collection PaveDB is configured to share across tenants.

Takes :k and :filters. The endpoint needs no tenant or collection, and answers with an empty match list when the server has no shared scope enabled. There is no raw-vector form: the server drops v on this endpoint, so only text queries reach it.

@spec search_vector(
  PaveDBClient.Client.t(),
  String.t(),
  String.t(),
  [number()],
  keyword()
) ::
  {:ok, map()} | {:error, PaveDBClient.Error.t()}

Searches a collection with a precomputed query vector.

PaveDB takes either a text query or a raw vector, never both.

@spec update_collection(PaveDBClient.Client.t(), String.t(), String.t(), keyword()) ::
  {:ok, map()} | {:error, PaveDBClient.Error.t()}

Updates a collection's editable metadata (currently display_name).

@spec version() :: String.t()

Returns the package version.