Python client

A server, used from Python with the same calls as Vectrix. Needs the client extra: pip install "vectrixdb[client]". See Use it from Python, TypeScript, Go or Rust for the walk-through and the other languages.

vectrixdb.client

Talk to a VectrixDB server from Python, with the same calls as Vectrix.

from vectrixdb import connect

db = connect("https://vectors.example.com", key="...")
db.add_document("handbook", open("handbook.pdf", "rb").read(), "handbook.pdf")
for hit in db.search("handbook", "how long do refunds take"):
    print(hit.score, hit.citation, hit.text)

Code written for a local Vectrix moves to a server by changing the line that opens it: search returns the same Results with the same Result objects, citations included. AsyncVectrixClient is the same surface with await.

The client needs httpx (pip install "vectrixdb[client]"). It sends the key in the api-key header, or a company sign-in token as a bearer token, retries a 429 or a 503 up to three times honouring Retry-After, and raises one refusal type per status, all of them RequestError:

try:
    db.describe("nope")
except NotFoundError as refused:
    print(refused.status, refused.message)

Behind a company's gateway, proxy or private CA:

db = connect(
    "https://gateway.example.com",
    key=KEY,
    key_header="Ocp-Apim-Subscription-Key",
    prefix="/acme",
    gateway_paths="api/v1=/files/search, auth=/files/auth",
    verify="/etc/ssl/company-ca.pem",
)

A key never travels over plain HTTP to another machine (allow_http=True says it may), and no redirect is followed, so a key goes only to the address it was given for. HTTPS_PROXY and NO_PROXY are honoured.

Every language's client offers this surface; sdk/CONTRACT.md in the repository is the shared description.

VectrixClient

Bases: _Calls

A VectrixDB server, used from Python.

Parameters:

Name	Type	Description	Default
url	str	Where the server is, https://vectors.example.com. Behind a gateway that publishes each part under a path of its own, the gateway's address, with prefix and gateway_paths.	required
key	Optional[str]	An API key, sent in the api-key header.	None
token	Optional[str]	A company sign-in token, sent as a bearer token instead of a key.	None
timeout	float	Seconds to wait for each request.	30.0
transport	Any	An httpx transport, for tests that talk to an app in-process.	None
allow_http	bool	Send the key or token over plain HTTP to another machine. Off, only https:// or this machine.	False
key_header	str	The header the key goes in, for a gateway with its own: Ocp-Apim-Subscription-Key. The server's VECTRIXDB_KEY_HEADER.	'api-key'
token_header	str	The header the token goes in, as Bearer <token>.	'authorization'
headers	Optional[Mapping[str, str]]	More headers for every request, such as a gateway's subscription key alongside a person's token.	None
prefix	Optional[str]	The path every route lives under, as the server's VECTRIXDB_PREFIX.	None
gateway_paths	Union[None, str, Mapping[str, str]]	Each route's gateway path, as the server's VECTRIXDB_GATEWAY_PATHS: api/v1=/files/search, auth=/files/auth.	None
verify	Any	A CA bundle to trust, for a private CA; "system" for the operating system's own store, where a managed machine keeps the company's authority; or an ssl.SSLContext. Certificates are always checked.	True
cert	Any	A client certificate for a gateway that asks for one: a path, or (certificate, key).	None
user_agent	Optional[str]	A wrapper's name and version, acme-vectors/1.4, put before this client's own in User-Agent, so a gateway's log says which tool made each call.	None

health()

Whether the process answers.

ready()

Whether the models are loaded; health() on a server with no /ready.

whoami()

Who the server takes this client for.

collections()

The collections this key may see.

describe(name)

One collection.

create_collection(name, dimension=384, text_index=True, metric='cosine', description=None)

A new collection; text_index makes hybrid search possible.

add_document(collection, data, filename=None, *, doc_id=None, metadata=None, chunk=None, chunk_size=None, overlap=None)

Send a file's bytes; the server reads, cuts and embeds it.

add_texts(collection, points)

Add texts the server embeds: [{"id": ..., "text": ..., "metadata": {...}}].

search(collection, query, limit=10, filter=None, rerank=False, mode='meaning')

Search by meaning, or mode="hybrid" for meaning and exact words.

documents(collection)

The documents the server keeps for a collection.

open_document(collection, doc_id)

The Markdown a document was indexed from.

delete_document(collection, doc_id)

Remove a document; returns how many chunks went.

add_source(collection, address, kind=None, every=None)

A page or feed the collection keeps in sync with.

AsyncVectrixClient

Bases: _Calls

VectrixClient with await; see that class for the arguments.

Collection dataclass

A collection as the server describes it.

Document dataclass

A document the server keeps, as documents() lists it.

Added dataclass

What add_document did.

Source dataclass

A place a collection keeps in sync with.

Refreshed dataclass

What refresh_sources did.

RequestError

Bases: VectrixError

The server refused a request. status says how, message says why.

AuthError

Bases: RequestError

401: no key, or a wrong one.

ForbiddenError

Bases: RequestError

403: the key's role or scope says no.

NotFoundError

Bases: RequestError

404: no such collection, document or source.

ConflictError

Bases: RequestError

409: it already exists.

TooLargeError

Bases: RequestError

413: the upload is bigger than the server takes.

InvalidError

Bases: RequestError

422: a field is wrong; detail lists which.

BusyError

Bases: RequestError

429 or 503, still, after the retries.

ConnectionFailed

Bases: VectrixError

The server could not be reached at all.

connect(url, key=None, token=None, *, timeout=30.0, **options)

A server, by address and key: connect("https://vectors.example.com", key="...").

options are VectrixClient's: key_header, prefix, gateway_paths, verify, cert, headers, allow_http, user_agent.