GoVec Python SDK
The Python client for GoVec, a compact vector search engine with HNSW, int8 quantization and hybrid search. Talk to it over REST or gRPC through the same API.
Features
- The whole server API: insert, batch insert, search with metadata filters and hybrid dense + sparse scoring, get, delete, stats, info, flush and reset.
- REST or gRPC, one argument apart. Both return the same results and raise the same exceptions; the test suite runs every operation against a real server over both.
- Sync or async.
AsyncGoVecClienthas the same methods asGoVecClient, awaited, for FastAPI services, async RAG pipelines and agent frameworks. - Typed. Responses are dataclasses, and the package ships
py.typed. - Batch inserts that scale: large lists are chunked for you, with per-vector errors reported instead of failing the whole batch.
- Safe against newer servers. Fields a newer GoVec adds are ignored, not fatal.
Installation
pip install govec
# or
uv add govec
Requires Python 3.12 or newer. You also need a GoVec server; the quickest way is Docker:
docker run -p 9697:9697 -v govec-data:/data ghcr.io/pradyothsp/govec:latest
Quick start
from govec import GoVecClient
with GoVecClient.connect(host="localhost", port=9697, api_key="", protocol="rest", tls=False) as client:
client.insert(vector_id="doc-1", dense_vector=[0.12, 0.91, 0.20], metadata={"title": "Getting started"})
client.insert(vector_id="doc-2", dense_vector=[0.80, 0.10, 0.31], metadata={"title": "Release notes"})
for hit in client.search(dense_vector=[0.10, 0.88, 0.18], k=2):
print(hit.id, round(hit.score, 3), hit.meta)
doc-1 1.0 {'title': 'Getting started'}
doc-2 0.287 {'title': 'Release notes'}
In a real application the vectors come from an embedding model (OpenAI, Sentence Transformers, ...); GoVec stores and searches them. Every vector in an index must have the same number of dimensions.
Connecting
GoVecClient.connect(host, port, api_key, protocol, tls=True, timeout=10.0, batch_timeout=60.0)
| Argument | Meaning |
|---|---|
host, port |
Where the server listens. GoVec's defaults are 9697 for REST and 9698 for gRPC. |
api_key |
The server's server.api_key, sent as a bearer token. Pass "" when auth is off (the default). |
protocol |
"rest" or "grpc". gRPC must be enabled on the server (GOVEC_GRPC_ENABLED=true). |
tls |
True (default) for https/TLS; pass False for a plain local server. |
timeout |
Seconds each request may take before GoVecTimeoutError. Default 10. None waits indefinitely. |
batch_timeout |
The same for each batch insert_many sends, which takes longer than a query. Default 60. |
connect() contacts the server straight away, so a wrong address fails there rather than
on the first call. GoVecClient(...) takes the same arguments and does the same thing.
To use gRPC, change two arguments; nothing else in your code changes:
with GoVecClient.connect(host="localhost", port=9698, api_key="", protocol="grpc", tls=False) as client:
...
Closing the client
A client holds an open connection, so close it when you're done. How depends on how long you need it.
For scripts, jobs, notebooks and tests, use a context manager. The connection is closed when the block ends, even if an exception is raised:
with GoVecClient.connect(host="localhost", port=9697, api_key="", protocol="rest", tls=False) as client:
client.search(dense_vector=[0.10, 0.88, 0.18], k=5)
For long-running services, create one client at startup, reuse it, and close it at shutdown. Don't open a client per request: each one repeats the startup handshake and a new connection. For an async service, see Async.
client = GoVecClient.connect(host="localhost", port=9697, api_key="", protocol="rest", tls=False)
...
client.close()
close() is safe to call more than once.
Async
AsyncGoVecClient has the same methods, arguments and return values as GoVecClient;
each one is awaited. Connect with await, or with async with to close it when the block
ends:
from govec import AsyncGoVecClient
async with AsyncGoVecClient.connect(host="localhost", port=9697, api_key="", protocol="rest", tls=False) as client:
hits = await client.search(dense_vector=[0.10, 0.88, 0.18], k=5)
In an async service, use it instead of GoVecClient: a sync call blocks the event loop,
and every other request on the server waits for it. With FastAPI:
from contextlib import asynccontextmanager
from fastapi import FastAPI
from govec import AsyncGoVecClient
@asynccontextmanager
async def lifespan(app: FastAPI):
app.state.govec = await AsyncGoVecClient.connect(host="localhost", port=9697, api_key="", protocol="rest", tls=False)
yield
await app.state.govec.aclose()
app = FastAPI(lifespan=lifespan)
- Connect through
connect().AsyncGoVecClient(...)is not how you get a client;connect()runs the handshake first, so every client you hold is connected. Forgetting theawaitis caught by a type checker: whatconnect()returns has nosearch. - Close with
await client.aclose(), which is safe to call more than once. - asyncio only. gRPC's async API doesn't run on trio, so neither does the client.
insert_manystill sends its batches one after another, as the sync client does: sending them at once would change which write wins when an ID appears in two batches.
Guide
The examples below use a connected client, as in the quick start.
Inserting vectors
client.insert(vector_id="doc-1", dense_vector=[0.12, 0.91, 0.20], metadata={"lang": "en", "year": 2024})
Inserting an existing ID replaces it. For many vectors, build InsertRequests and use
insert_many, which sends them in chunks of batch_size:
from govec import InsertRequest
result = client.insert_many(
[InsertRequest(id=f"doc-{i}", vector=vec) for i, vec in enumerate(vectors)],
batch_size=500,
)
print(result.inserted_count)
for failure in result.errors:
print(failure.id, failure.error)
Searching
hits = client.search(dense_vector=[0.10, 0.88, 0.18], k=5)
Each hit has id, score (higher is closer) and meta (None if the vector has no
metadata).
Filter by metadata. Every key must match exactly:
client.search(dense_vector=[0.10, 0.88, 0.18], k=5, filter={"lang": "en"})
Hybrid search. Add a sparse vector (for example from BM25 or SPLADE) to both the insert and the query; the server blends the dense and sparse scores:
from govec import SparseVector
client.insert(
vector_id="doc-3",
dense_vector=[0.3, 0.3, 0.3],
sparse_vector=SparseVector(indices=[7, 42], values=[1.0, 0.5]),
)
client.search(
dense_vector=[0.3, 0.3, 0.3],
sparse_vector=SparseVector(indices=[42], values=[1.0]),
k=3,
)
Reading and deleting
record = client.get_by_id(vector_id="doc-1") # vector, sparse_vector and metadata, or None if missing
client.delete(vector_id="doc-1") # raises GoVecAPIError if the ID doesn't exist
Administration
client.info() # server version, index type, quantization, metric, dimensions
client.get_stats() # number of stored vectors
client.health() # liveness
client.flush() # write a snapshot to disk now
client.reset() # delete every vector -- irreversible
API reference
The same on both clients; on AsyncGoVecClient each method is awaited, and close() is
aclose().
| Method | Returns |
|---|---|
insert(vector_id, dense_vector, sparse_vector=None, metadata=None) |
True |
insert_many(requests, batch_size=500) |
BatchInsertResponse: inserted_count, errors |
search(dense_vector=None, sparse_vector=None, k=10, filter=None) |
list[SearchResponse]: id, score, meta |
get_by_id(vector_id) |
GetByIdResponse or None |
delete(vector_id) |
True |
info() |
InfoResponse: version, index_type, quantization, distance_metric, dimensions, vector_count, enable_mmap |
get_stats() |
GetStatsResponse: vector_count |
health() / flush() / reset() |
a response with status |
close() |
closes the connection; safe to call twice |
Error handling
Both transports raise the same exceptions, all subclasses of GoVecError:
| Exception | Raised when |
|---|---|
GoVecAPIError |
the server rejected the request, e.g. a vector with the wrong dimensions. message says why; status_code is the HTTP status over REST and the gRPC status code over gRPC. |
GoVecConnectionError |
the server can't be reached |
GoVecTimeoutError |
the server didn't answer within timeout (batch_timeout for an insert_many batch). Raise it, or try a smaller k or a narrower filter. |
GoVecClientClosedError |
the client was used after close() (aclose()) |
Input the client can check itself raises ValueError before anything is sent: NaN or
infinity anywhere in a vector, metadata or filter (the server would otherwise store or
search zeros), a vector of the wrong width when the server has mmap on, a batch_size
below 1, or a timeout that isn't positive.
from govec import GoVecAPIError, GoVecError
try:
client.insert(vector_id="doc-9", dense_vector=[0.1, 0.2]) # wrong width for a 3-dimensional index
except GoVecAPIError as e:
print(e.status_code, e.message)
except GoVecError:
... # connection problems, timeouts
Compatibility
| SDK | GoVec server | Python |
|---|---|---|
| 0.1.2 – 0.2.0 | 0.1.0 and newer | 3.12 – 3.14 |
| 0.1.0 – 0.1.1 | 0.1.0 and newer, except a gRPC search with k=0 on 0.2.0 and newer (rejected; upgrade the SDK) |
3.12 – 3.14 |
client.info().version tells you which server release you're connected to.
Two transport differences to know, both from protobuf:
- Metadata numbers come back as floats over gRPC:
{"year": 2024}returns as2024.0. REST preserves integers. - Vectors come back at 32-bit precision over gRPC: GoVec stores 32-bit floats, so
get_by_idover gRPC returns0.12as0.11999999731779099. REST rounds it back to0.12.
Contributing
Issues and pull requests are welcome; see CONTRIBUTING.md.
License
Metadata
Release files for govec 0.2.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| govec-0.2.0.tar.gz | 36.1 kB | With provenance | Details for govec-0.2.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| govec-0.2.0-py3-none-any.whl | Python 3 | none | any | Details for govec-0.2.0-py3-none-any.whl |
Total release size: 75.5 kB
Release files / govec-0.2.0.tar.gz
| Download URL | govec-0.2.0.tar.gz |
|---|---|
| Size | 36.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
145f152adfaa223c5e2f2c142285a311754a32d6c4417de5aa7c11ece2d5858f
|
|
BLAKE2b-256 checksum How to use checksums |
62fc8cd0031e8720079e201ea4ffdae41400010290022b5d75430c8a717028e8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 9, 2026.
Transparency logRelease files / govec-0.2.0-py3-none-any.whl
| Download URL | govec-0.2.0-py3-none-any.whl |
|---|---|
| Size | 39.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
9232ed7f9d6b5be5933eab13ef85bb8aa56a7f655cd47f439456794ffbbfa972
|
|
BLAKE2b-256 checksum How to use checksums |
02994daa0dcce5fce839535291e74847f6d078c3519cd1e58282b7ca4839abc4
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 9, 2026.
Transparency logSecurity for govec 0.2.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for govec-0.2.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 9, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.