Hermes Python client
Async Python client for the Hermes gRPC search server.
Installation
pip install hermes-client-python
Python 3.10 or newer is required.
Quick start
import asyncio
from hermes_client_python import HermesClient
async def main():
async with HermesClient("localhost:50051") as client:
await client.create_index(
"articles",
"""
index articles {
field id: text<raw> [primary, stored]
field title: text<simple> [indexed, stored]
field body: text<simple> [indexed, stored]
}
""",
)
indexed, error_count, errors = await client.index_documents(
"articles",
[
{"id": "1", "title": "Hello World", "body": "First article"},
{"id": "2", "title": "Hermes Search", "body": "Fast retrieval"},
],
)
if error_count:
raise RuntimeError(errors)
print(f"Indexed {indexed} documents")
await client.commit("articles")
results = await client.search(
"articles",
query={"match": {"field": "title", "text": "hello"}},
fields_to_load=["title", "body"],
)
for hit in results.hits:
print(hit.address, hit.score, hit.fields)
if results.hits:
document = await client.get_document("articles", results.hits[0].address)
print(document.fields if document else "document not found")
asyncio.run(main())
The context manager connects and closes the channel. Manual callers use
await client.connect() / await client.close().
Index management
await client.list_indexes()
info = await client.get_index_info("articles")
await client.reorder("articles")
await client.retrain_vector_index("articles")
index_documents returns (indexed_count, error_count, errors);
index_documents_stream takes an async iterable and returns counts. Inspect
errors, then commit() to publish accepted work. Repeated values are lists;
flat numeric lists are dense vectors, (dimension, weight) pairs are sparse
vectors. See client types.
Delete and upsert documents
With a text primary key, delete by exact key or supply a complete replacement:
await client.delete_document("articles", "2")
await client.upsert_document("articles", {"id": "1", "title": "Updated title"})
await client.commit("articles")
delete_documents / upsert_documents return DocumentMutationResult with
accepted_count and errors: [{index, error}]. Single-item helpers raise on
rejection. Missing deletes succeed; upserts insert missing keys. Staged rows can
be replaced/deleted again before commit; the latest accepted version wins.
Optional content hashes skip unchanged writes.
Limits: 100,000 deletion keys / 8 MiB key bytes; 1,000 replacements / 32 MiB encoded protobuf, or one replacement / 200 MiB including the request envelope. Broker commits are atomic per partition. See mutation semantics.
Compact deleted rows
await client.force_merge("articles") # Retain tombstones.
await client.force_merge("articles", compact=True) # Physically remove deleted rows.
Compaction handles singleton segments and may change addresses and BM25 scores.
Index info exposes num_docs, physical_num_docs, num_deleted_docs, and
deleted_ratio. Use primary keys for durable identity.
Searching
search(index_name, query=..., limit=10, fields_to_load=[...]) accepts one query
variant: term, match, phrase, boolean, sparse_vector, dense_vector,
binary_dense_vector, boost, range, prefix, all, or fusion.
See query types and the
wire contract for options.
results = await client.search(
"articles",
query={"boolean": {
"must": [{"match": {"field": "title", "text": "search"}}],
"must_not": [{"term": {"field": "title", "term": "draft"}}],
}},
fields_to_load=["title"],
)
get_document(index_name, hit.address) uses the full segment/document address
and returns None on NOT_FOUND.
Ranking diagnostics and recall traces
Search options include_rrf_scores=True and tracing=True default to false.
RRF diagnostics describe organic branch nominations; traces retain bounded
candidates and query trees, including hits outside the final page. Neither
changes retrieval depth or ranking. Oversized exports fail explicitly.
For named branches, use l1={"formula": "0.2 * title + 0.8 * body + 3 * rrf"}.
The formula is the only L1 scoring interface; old coefficient fields are removed.
See candidate scoring for backfill, passage
selection, expression limits, capability versions, and distributed behavior.
Deadlines and errors
RPCs accept timeout in seconds, overriding the constructor's default_timeout.
gRPC failures raise grpc.aio.AioRpcError, except document NOT_FOUND as above.
An expired mutation may already be staged, and an accepted commit continues
after disconnection. Resolve the outcome before retrying replacements.
Development
From this directory:
uv sync --group dev --group test
uv run ruff check .
uv run ruff format --check .
uv run pytest tests/test_client_unit.py
uv run --group dev python generate_proto.py
Integration tests require target/debug/hermes-server. Regenerate bindings after
protocol changes.
1 maintainer
Metadata
1 maintainer
Release files for hermes-client-python 1.8.149
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 | |
|---|---|---|---|---|
| hermes_client_python-1.8.149.tar.gz | 24.2 kB | Without provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| hermes_client_python-1.8.149-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 49.9 kB
Release files / hermes_client_python-1.8.149.tar.gz
| Download URL | hermes_client_python-1.8.149.tar.gz |
|---|---|
| Size | 24.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
4fba04aeff5752a1c7a711a7c07fea0809a8796a1bcc44a9a9508410c29e75f5
|
|
BLAKE2b-256 checksum How to use checksums |
b4646a093675890bac452b479fd958c1effe0da53dc820cc0eaeed246110292f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.12.18 {"installer":{"name":"uv","version":"0.12.18","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / hermes_client_python-1.8.149-py3-none-any.whl
| Download URL | hermes_client_python-1.8.149-py3-none-any.whl |
|---|---|
| Size | 25.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
b117b1f3a588c6d4792167c24742984f6ab9b7083788a3e3da00c0f9618127e6
|
|
BLAKE2b-256 checksum How to use checksums |
acce62d8fd3571d52c842a606e1e95c39e1c477d2bdcd2979d11bc47a3dabb91
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.12.18 {"installer":{"name":"uv","version":"0.12.18","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Security for hermes-client-python 1.8.149
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.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A 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.
