Python SDK - Vector Panda

Installation

Requires Python 3.9+. Currently published to Test PyPI (alpha).

# Install from Test PyPI (alpha)
pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ veep

# With Parquet upload support (adds pyarrow)
pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ "veep[parquet]"

Client

Client(api_key=None, host=None, timeout=120.0)

Create a client instance. The API key is required — pass it directly or set the VEEP_API_KEY environment variable. Raises AuthError if no key is provided.

Parameter	Type	Default	Description
`api_key`	str \| None	VEEP_API_KEY env	Your API key
`host`	str \| None	VEEP_HOST env or api.vectorpanda.com	API base URL
`timeout`	float	120.0	Request timeout in seconds

from veep import Client

# Explicit key
client = Client(api_key="sk_live_...")

# From environment
# export VEEP_API_KEY=sk_live_...
client = Client()

Free tier

Every API key gets 250,000 free vector slots at 512 dimensions (scales with dimension size). No credit card required. Hot tier requires a payment method — free accounts are warm-only. See Pricing & Free Tier for details.

query()

client.query(collection, vector, *, top_k=10, similarity_threshold=0.7, distance_metric="cosine", include_metadata=False, use_index=None, index_params=None)

Search a collection for vectors similar to the query vector. Returns a QueryResults object.

Parameter	Type	Default	Description
`collection`	str	required	Collection name
`vector`	list[float]	required	Query vector
`top_k`	int	10	Maximum results to return
`similarity_threshold`	float	0.7	Minimum similarity score
`distance_metric`	str	"cosine"	"cosine", "euclidean", or "dot_product"
`include_metadata`	bool	False	Include metadata in results
`use_index`	str \| None	None	Index type (e.g. "pca")
`index_params`	dict \| None	None	Index-specific parameters

results = client.query(
    "products",
    vector=[0.1, 0.2, 0.3],
    top_k=5,
    include_metadata=True,
)

for r in results:
    print(f"{r.key}: {r.score:.4f} {r.metadata}")

upload()

client.upload(collection, file_path, *, vector_column="emb", key_column=None)

Upload a file to a collection. Supported formats: Parquet (.parquet), CSV (.csv), and binary vectors (.fvecs, .bvecs, .ivecs). For Parquet files, install the [parquet] extra for client-side validation: pip install veep[parquet].

Parameter	Type	Default	Description
`collection`	str	required	Collection name
`file_path`	str \| Path	required	Path to file (.parquet, .csv, .fvecs, .bvecs, .ivecs)
`vector_column`	str	"emb"	Column containing embedding vectors
`key_column`	str \| None	None	Column for vector keys (auto-generated if omitted)

client.upload("products", "embeddings.parquet")

# With custom column names
client.upload(
    "products",
    "embeddings.parquet",
    vector_column="embedding",
    key_column="product_id",
)

Validation

The SDK validates the file before uploading: it checks the file exists, has a .parquet extension, and contains the specified vector column.

delete()

client.delete(collection, file_name)

Delete a previously uploaded file from a collection.

Parameter	Type	Description
`collection`	str	Collection name
`file_name`	str	Name of the file to delete

client.delete("products", "embeddings.parquet")

collections()

client.collections()

List all collections accessible to your API key. Returns a list of Collection objects.

cols = client.collections()
for col in cols:
    print(f"{col.name}: {col.vector_count} vectors ({col.tier})")

health()

client.health()

Check API connectivity. Returns True if the service is reachable, False otherwise. Uses a 5-second timeout regardless of the client timeout setting.

if client.health():
    print("Connected")
else:
    print("Cannot reach Vector Panda API")

Result

A single search result returned by query().

Field	Type	Description
`key`	str	Vector identifier
`score`	float	Similarity score
`metadata`	dict	Metadata fields (empty if not requested)

QueryResults

Container returned by query(). Iterable, indexable, and supports len().

results = client.query("col", vector=vec)

len(results)       # number of results
results[0]         # first Result
results[0].key     # "doc_42"
results[0].score   # 0.9812

for r in results:  # iterate
    print(r)

Also exposes results.worker_stats (list of dicts) for debugging distributed query performance.

Collection

Returned by collections().

Field	Type	Description
`name`	str	Collection name
`tier`	str	"hot", "warm", or "paused"
`is_active`	bool	Whether the collection is currently queryable
`vector_count`	int	Total vectors stored
`storage_gb`	float	Storage used in GB

Exceptions

All exceptions inherit from VeepError.

Exception	Cause
`VeepError`	Base class for all SDK errors
`AuthError`	Missing or invalid API key
`NotFoundError`	Collection or file not found
`ServerError`	Server returned 5xx. Has `.status_code` attribute
`UploadError`	File missing, wrong extension, or missing vector column

from veep import AuthError, ServerError

try:
    results = client.query("col", vector=vec)
except AuthError:
    print("Bad API key")
except ServerError as e:
    print(f"HTTP {e.status_code}: {e}")