Python SDK reference

Core Python SDK clients, namespaces, configuration, filters, batching, and errors.

The Python SDK package is actian-vectorai-client; import APIs from actian_vectorai.

Clients

Use VectorAIClient for synchronous code and AsyncVectorAIClient for async applications.

from actian_vectorai import VectorAIClient, AsyncVectorAIClient

client = VectorAIClient("localhost:6574")

Both clients expose the same primary namespaces.

Namespace	Purpose
client.collections	Create, list, inspect, update, delete, recreate, and get-or-create collections.
client.points	Upsert, retrieve, delete, update vectors and payloads, search, query, count, and scroll points.
client.vde	Open and close collections, inspect state and stats, rebuild indexes, optimize, compact, flush, and import datasets.
Auth helpers	Manage access tokens and API keys through REST-backed admin operations.

Configuration

The SDK loads .env files and ACTIAN_VECTORAI_* environment variables automatically. Constructor arguments override environment values.

from actian_vectorai import Settings, settings

print(settings.url)

custom = Settings(
    url="localhost:6574",
    rest_url="http://localhost:6573",
    timeout=30.0,
    max_retries=3,
)

Use ACTIAN_VECTORAI_ACCESS_TOKEN or VectorAIClient(access_token="...") for Bearer authentication.

Collections and points

from actian_vectorai import VectorAIClient, VectorParams, Distance, PointStruct

with VectorAIClient("localhost:6574") as client:
    client.collections.create(
        "products",
        vectors_config=VectorParams(size=128, distance=Distance.Cosine),
    )

    client.points.upsert("products", [
        PointStruct(id=1, vector=[0.1] * 128, payload={"category": "books"}),
    ])

    results = client.points.search("products", vector=[0.1] * 128, limit=5)

Filters

Use the Filter DSL for payload predicates.

from actian_vectorai import Field, FilterBuilder

filter_ = (
    FilterBuilder()
    .must(Field("category").eq("books"))
    .must(Field("price").lte(50.0))
    .build()
)

results = client.points.search("products", vector=query, limit=10, filter=filter_)

Hybrid search and batching

The SDK includes client-side reciprocal rank fusion, distribution-based score fusion, and smart batching.

from actian_vectorai import reciprocal_rank_fusion, distribution_based_score_fusion

dense = client.points.search("products", vector=dense_query, limit=50)
sparse = client.points.search("products", vector=sparse_query, limit=50)
merged = reciprocal_rank_fusion([dense, sparse])

Use client.upload_points(...) for simple bulk upload or SmartBatcher when you need automatic flushing and batch sizing controls.

Embeddings and telemetry

Install optional extras when needed:

pip install "actian-vectorai-client[openai]"
pip install "actian-vectorai-client[telemetry]"

OpenAIEmbedder provides OpenAI embedding helpers, and telemetry extras enable structured observability integrations.

Errors and transport

The SDK maps gRPC and REST failures to typed exceptions such as validation, authentication, connection, collection, point, timeout, and server errors. Configure TLS, retries, timeouts, and connection pool size through constructor options or environment variables.