Documentation

VP.login() — interactive device flow

Class method. Opens a browser-based device-code flow, prompts you to confirm, then returns an authenticated client. By default it writes the credentials to ~/.veep/credentials.json so subsequent scripts can use VP.from_creds().

from veep import VP

vp = VP.login()              # prints a code, opens https://www.vectorpanda.com/cli-auth
# vp is now authenticated and ~/.veep/credentials.json is written

VP.from_creds() — reuse saved credentials

Class method. Reads ~/.veep/credentials.json (written by a prior VP.login() or vp.save()) and returns an authenticated client. The path used for non-interactive runs.

vp = VP.from_creds()
print(vp.host)            # https://api.vectorpanda.com (or VEEP_HOST override)

VP(api_key=…) — explicit constructor

Direct constructor. Reads the API key from the VEEP_API_KEY environment variable (or pass api_key= explicitly). The host argument falls back to VEEP_HOST, then to https://api.vectorpanda.com. Raises AuthError when no key is available. This is the recommended shape for CI and other non-interactive environments.

# export VEEP_API_KEY=veep_live_... (set in your shell or CI secrets)
vp = VP()

vp.save() — persist credentials

Writes the current api_key and host to ~/.veep/credentials.json with mode 0600. Useful when you constructed VP programmatically and want subsequent shells to pick it up via VP.from_creds().

# vp constructed any of the ways above
vp.save()

# later, from a different process:
vp2 = VP.from_creds()

vp.ping() — liveness check

Hits the cluster's /api/v1/health endpoint and returns True on a 2xx response. The endpoint is unauthenticated by design — it tells you whether the cluster is reachable, not whether your API key is valid. Use vp.whoami() for the auth check.

assert vp.ping() is True

vp.whoami() — identity / auth check

Authenticated equivalent of ping(). Returns the resolved client_id and client_name. Raises AuthError on a missing or invalid API key. Use this when you want to confirm a key is valid before doing real work, without the side effects of collections.list().

info = vp.whoami()
print(info["client_id"], info["client_name"])

collections.create() — create a collection

Creates a new collection. tier defaults to "hot" (RAM-resident). The schema fields are optional — by default the SDK infers them from the first upload.

vp.collections.create("movies", tier="hot")

# with explicit schema hints
vp.collections.create(
    "movies",
    tier="warm",
    id_field="id",
    vector_field="vector",
)

target_recall sets how accurate this collection's searches have to be, between 0.50 and 0.999. It defaults to 0.95.

Recall is the share of the true nearest neighbours a search actually returns — at 0.95, a search asking for the closest 100 rows typically finds 95 of the true closest 100. Vector Panda serves the fastest configuration whose measured recall meets your target, so raising it buys accuracy and lowering it buys speed.

Leave it alone unless you have a reason. 0.95 is the right answer for most search and recommendation work. Raise it toward 0.999 when a missed row is expensive — deduplication, compliance lookups, anything where "close enough" isn't. Lower it toward 0.80 when you want the cheapest possible latency and an occasional missed row costs you nothing.

# accuracy matters more than speed
vp.collections.create("legal-docs", target_recall=0.99)

# speed matters more than the occasional missed row
vp.collections.create("related-posts", target_recall=0.85)

Change it later with collections.update().

if_exists controls what happens when a collection with this name already exists:

• "ignore" (default) — log a warning and return the existing collection. Re-running a setup script doesn't fail. The tier and schema args are not applied to the existing collection.
• "replace" — DESTRUCTIVE. Delete the existing collection (and all its stored vectors) before creating the fresh one. Use only when you intentionally want a clean slate.
• "error" — raise CollectionAlreadyExistsError. Strict opt-in for callers that need fail-fast on conflict.

from veep.exceptions import CollectionAlreadyExistsError

# idempotent re-run (default) — returns existing if it's there
vp.collections.create("movies")

# wipe + recreate (DELETES ALL STORED VECTORS)
vp.collections.create("movies", if_exists="replace")

# strict mode — raises CollectionAlreadyExistsError on conflict
try:
    vp.collections.create("movies", if_exists="error")
except CollectionAlreadyExistsError:
    pass  # the collection already exists — handle however you like

collections.list() — list every collection

Returns every collection visible to the API key. Each Collection exposes name, status, tier, target_recall, and tier-specific metadata.

for c in vp.collections.list():
    print(c.name, c.status, c.tier)

collections.get() — fetch one

Returns a single Collection by name, or raises CollectionNotFoundError.

col = vp.collections.get("movies")
print(col.name, col.tier, col.status)

collections.status() — short status string

Returns just the lifecycle string: awaiting_artifacts (no data yet), processing, distributing, awaiting_workers, or ready. Cheap polling target after an upload.

import time

while vp.collections.status("movies") != "ready":
    time.sleep(2)

collections.update() — change the recall target

Changes a collection's recall target and returns the updated Collection. Takes effect immediately: Vector Panda re-evaluates how it serves this collection against the new target, without you re-uploading anything.

Raising the target can make queries slower, because the configuration that meets the higher bar may be a slower one. Lowering it can make them faster. Your data is untouched either way.

# tighten the target after seeing a few misses you cared about
col = vp.collections.update("movies", target_recall=0.99)
print(col.target_recall)  # 0.99

# loosen it when latency matters more
vp.collections.update("movies", target_recall=0.90)

Raises ValidationError outside 0.50–0.999, and CollectionNotFoundError if the collection doesn't exist.

collections.delete() — drop a collection

The example uses a throwaway "scratch" collection so the page's other examples (which all reference "movies") keep working. Substitute the name you actually want to drop.

Drops the collection and every vector in it. Irreversible.

vp.collections.create("scratch", if_exists="replace")
vp.collections.delete("scratch")

schema.get() — current schema

Returns a SchemaInfo with state, id_field, vector_field, dimension, and format.

schema = vp.schema.get("movies")
print(schema.state, schema.id_field, schema.vector_field, schema.dimension)

schema.confirm() — pin the schema

Locks in the field names and (optionally) format/dimension. Only needed if you skipped id_field / vector_field in collections.create() and want to commit them before the first upload.

vp.schema.confirm(
    "movies",
    id_field="id",
    vector_field="vector",
)

schema.update() — change a field name

Updates one or both schema fields after the schema is already confirmed. Pass reprocess=True to re-extract artifacts under the new schema.

vectors.upsert() — four ways to upload

One method, four input shapes. Pick whichever fits your data layout.

import pyarrow as pa
from veep import samples

df = samples.dataframe().head(100)            # pandas DataFrame, fully embedded
df.to_parquet("plots.parquet", index=False)
arrow_table = pa.Table.from_pandas(df)

# 1. From a pandas DataFrame
vp.vectors.upsert("movies", dataframe=df)

# 2. From a file on disk (.parquet, .csv, .npy, ...)
vp.vectors.upsert("movies", "plots.parquet")

# 3. From a pyarrow Table
vp.vectors.upsert("movies", table=arrow_table)

# 4. Inline rows (small batches, ~ms latency via WAL fast path)
vp.vectors.upsert("movies", vectors=[
    {"id": "m-extra-1", "vector": samples.encode("Aliens"),
     "metadata": {"title": "Aliens", "year": 1986, "genre": "horror"}},
])

vectors.replace() — overwrite an upload

Like upsert() with a file path, but instead of adding rows it replaces the contents of the same server-side file. Idempotent for same-content reuploads.

vp.vectors.replace("movies", "plots.parquet")

vectors.query() — similarity search

Runs a vector similarity search. Results are returned in descending score order. Cosine similarity scores fall in [0, 1]: 1.0 is identical, 0.0 is orthogonal.

q = samples.encode("a hobbit destroys a magic ring")

results = vp.vectors.query(
    "movies",
    vector=q,
    top_k=5,
    min_score=0.4,
    filter={"genre": "fantasy"},
)
for r in results:
    print(f"{r.score:.3f}  {r.metadata.get('title','?')}")

vectors.query_batch() — many queries in one round trip

Sends a list of query specs in a single request. Each entry is a dict with the same fields as query(): collection, vector, top_k, etc. Returns one QueryResults per input, in order.

prompts = [
    "a hobbit destroys a magic ring",
    "scientists clone dinosaurs and the dinosaurs escape",
    "an off-duty cop is trapped in a high-rise at christmas",
]
batch = vp.vectors.query_batch([
    {"collection": "movies", "vector": samples.encode(p), "top_k": 1}
    for p in prompts
])
for p, hits in zip(prompts, batch):
    print(p, "->", hits[0].metadata)

vectors.fetch() — by ID

Looks up a single row by its ID. Returns a FetchResult with found, vector, and metadata.

row = vp.vectors.fetch("movies", "m-42")
if row.found:
    print(row.metadata, len(row.vector))

vectors.update() — modify rows in place

Replaces existing rows by ID. Each entry has the same shape as inline upsert(). Returns a dict containing updated_count.

new_vec = samples.encode("Aliens, the director's cut")
vp.vectors.update("movies", [
    {"id": "m-extra-1", "vector": new_vec,
     "metadata": {"title": "Aliens (Director's Cut)", "year": 1986, "genre": "horror"}},
])

vectors.delete() — by file or by IDs

Deletes either an entire uploaded file or a specific list of row IDs. Pass exactly one of filename (positional) or ids=.

# by file
vp.vectors.delete("movies", "plots.parquet")

# by IDs
vp.vectors.delete("movies", ids=["m-42", "m-43"])

vectors.list_files() — what's been uploaded

Returns one FileInfo per uploaded file, with name, size, and metadata. Useful for confirming an upload landed before issuing queries.

for f in vp.vectors.list_files("movies"):
    print(f.name, f.size)

samples.dataframe() — bundled corpus

Returns a 5,000-row pandas DataFrame of Wikipedia movie plots, each with a 384-dimensional embedding from all-MiniLM-L6-v2. Columns: id, title, year, genre, plot, vector.

from veep import samples

df = samples.dataframe()
print(len(df), df.columns.tolist())
# 5000 ['id', 'title', 'year', 'genre', 'plot', 'vector']

samples.encode() — encoder for query text

Embeds a single string with the same all-MiniLM-L6-v2 ONNX model used by the bundled corpus. Returns a 384-dimensional list of floats. Useful for query vectors when you want them to land in the same vector space as samples.dataframe().

q = samples.encode("a hobbit destroys a magic ring")
assert len(q) == 384

Base URL & authentication

https://api.vectorpanda.com

Every request authenticates with an API key. Most endpoints accept the key via the Authorization header; POST /api/v1/query additionally accepts an api_key field in the JSON body.

POST/api/v1/query

Run a similarity search. Same semantics as vp.vectors.query().

curl https://api.vectorpanda.com/api/v1/query \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "veep_live_...",
    "collection": "movies",
    "vector": [0.12, 0.04, ...],
    "top_k": 5,
    "min_score": 0.4,
    "filter": {"genre": "fantasy"}
  }'

Response shape:

{
  "results": [
    {"id": "m-42", "score": 0.84, "metadata": {"title": "Aliens"}},
    ...
  ]
}

GET/api/v1/health

Cluster health. No authentication. Returns 200 OK when the coordinator is up. Use this for status pages and uptime probes.

curl https://api.vectorpanda.com/api/v1/health

GET/api/v1/whoami

Identity / auth check. Authenticated; returns the resolved client_id and client_name in JSON. Returns 401 with the standard error envelope when the key is missing or invalid.

curl https://api.vectorpanda.com/api/v1/whoami \
  -H "Authorization: Bearer veep_live_..."

Collections

Files (uploads)

Schema