hermes-client-python 1.8.145__tar.gz → 1.8.147__tar.gz

hermes_client_python-1.8.147/PKG-INFO

@@ -0,0 +1,191 @@
+Metadata-Version: 2.5
+Name: hermes-client-python
+Version: 1.8.147
+Summary: Async Python client for Hermes search server
+Project-URL: Homepage, https://github.com/SpaceFrontiers/hermes
+Project-URL: Repository, https://github.com/SpaceFrontiers/hermes
+Author: izihawa
+License-Expression: MIT
+Keywords: async,full-text-search,grpc,search
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Database :: Database Engines/Servers
+Classifier: Topic :: Text Processing :: Indexing
+Requires-Python: >=3.10
+Requires-Dist: grpcio>=1.76.0
+Requires-Dist: protobuf>=6.33.4
+Description-Content-Type: text/markdown
+
+# Hermes Python client
+
+Async Python client for the
+[Hermes](https://github.com/SpaceFrontiers/hermes) gRPC search server.
+
+## Installation
+
+```bash
+pip install hermes-client-python
+```
+
+Python 3.10 or newer is required.
+
+## Quick start
+
+```python
+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
+
+```python
+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](src/hermes_client_python/types.py).
+
+### Delete and upsert documents
+
+With a text primary key, delete by exact key or supply a complete replacement:
+
+```python
+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](../docs/content-deduplication.md) 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](../docs/row-deletion.md).
+
+### Compact deleted rows
+
+```python
+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](src/hermes_client_python/types.py) and the
+[wire contract](../hermes-proto/hermes.proto) for options.
+
+```python
+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](../docs/candidate-rescoring.md) 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:
+
+```bash
+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](../hermes-proto/README.md#regeneration-and-validation).

hermes_client_python-1.8.147/README.md

@@ -0,0 +1,167 @@
+# Hermes Python client
+
+Async Python client for the
+[Hermes](https://github.com/SpaceFrontiers/hermes) gRPC search server.
+
+## Installation
+
+```bash
+pip install hermes-client-python
+```
+
+Python 3.10 or newer is required.
+
+## Quick start
+
+```python
+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
+
+```python
+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](src/hermes_client_python/types.py).
+
+### Delete and upsert documents
+
+With a text primary key, delete by exact key or supply a complete replacement:
+
+```python
+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](../docs/content-deduplication.md) 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](../docs/row-deletion.md).
+
+### Compact deleted rows
+
+```python
+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](src/hermes_client_python/types.py) and the
+[wire contract](../hermes-proto/hermes.proto) for options.
+
+```python
+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](../docs/candidate-rescoring.md) 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:
+
+```bash
+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](../hermes-proto/README.md#regeneration-and-validation).

{hermes_client_python-1.8.145 → hermes_client_python-1.8.147}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "hermes-client-python"
-version = "1.8.145"
+version = "1.8.147"
 description = "Async Python client for Hermes search server"
 readme = "README.md"
 license = "MIT"

hermes_client_python-1.8.145/PKG-INFO

@@ -1,380 +0,0 @@
-Metadata-Version: 2.5
-Name: hermes-client-python
-Version: 1.8.145
-Summary: Async Python client for Hermes search server
-Project-URL: Homepage, https://github.com/SpaceFrontiers/hermes
-Project-URL: Repository, https://github.com/SpaceFrontiers/hermes
-Author: izihawa
-License-Expression: MIT
-Keywords: async,full-text-search,grpc,search
-Classifier: Development Status :: 4 - Beta
-Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Classifier: Topic :: Database :: Database Engines/Servers
-Classifier: Topic :: Text Processing :: Indexing
-Requires-Python: >=3.10
-Requires-Dist: grpcio>=1.76.0
-Requires-Dist: protobuf>=6.33.4
-Description-Content-Type: text/markdown
-
-# Hermes Python client
-
-Async Python client for the
-[Hermes](https://github.com/SpaceFrontiers/hermes) gRPC search server.
-
-## Installation
-
-```bash
-pip install hermes-client-python
-```
-
-Python 3.10 or newer is required.
-
-## Quick start
-
-```python
-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 title: text<simple> [indexed, stored]
-                field body: text<simple> [indexed, stored]
-            }
-            """,
-        )
-
-        indexed, error_count, errors = await client.index_documents(
-            "articles",
-            [
-                {"title": "Hello World", "body": "First article"},
-                {"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")
-
-        await client.delete_index("articles")
-
-
-asyncio.run(main())
-```
-
-The context manager calls `connect()` and `close()` automatically. For manual
-lifecycle management:
-
-```python
-client = HermesClient("localhost:50051")
-await client.connect()
-try:
-    ...
-finally:
-    await client.close()
-```
-
-## Index management
-
-```python
-await client.create_index("articles", schema_sdl)
-names = await client.list_indexes()
-info = await client.get_index_info("articles")
-print(info.num_docs, info.num_segments, info.vector_stats)
-
-await client.force_merge("articles")
-await client.reorder("articles")
-await client.retrain_vector_index("articles")
-await client.delete_index("articles")
-```
-
-`commit()` is required before newly indexed documents become searchable.
-
-### Batch and streaming indexing
-
-```python
-indexed, error_count, errors = await client.index_documents(
-    "articles",
-    [
-        {"title": "One", "tags": ["search", "rust"]},
-        {"title": "Two", "tags": ["python"]},
-    ],
-)
-
-
-async def documents():
-    for number in range(10_000):
-        yield {"title": f"Document {number}"}
-
-
-streamed, stream_errors = await client.index_documents_stream("articles", documents())
-```
-
-Repeated list values become repeated field entries. Flat numeric lists are
-dense vectors; lists of `(dimension, weight)` pairs are sparse vectors.
-
-## Searching
-
-Every search takes one `query` object whose single key matches a Hermes query
-variant:
-
-```python
-# Exact term
-await client.search(
-    "articles",
-    query={"term": {"field": "title", "term": "hermes"}},
-)
-
-# Tokenized full-text match
-await client.search(
-    "articles",
-    query={"match": {"field": "body", "text": "fast retrieval"}},
-)
-
-# Recursive boolean query
-await client.search(
-    "articles",
-    query={
-        "boolean": {
-            "must": [{"match": {"field": "body", "text": "retrieval"}}],
-            "must_not": [{"term": {"field": "title", "term": "draft"}}],
-        }
-    },
-)
-
-# Dense vector query and optional reranking
-await client.search(
-    "articles",
-    query={
-        "dense_vector": {
-            "field": "embedding",
-            "vector": [0.1, 0.2, 0.3],
-            "nprobe": 16,
-        }
-    },
-    reranker={"field": "embedding", "vector": [0.1, 0.2, 0.3]},
-    candidate_limit=20,
-    limit=10,
-    fields_to_load=["title"],
-)
-
-# Hybrid union fusion
-await client.search(
-    "articles",
-    query={
-        "fusion": {
-            "method": "rrf",
-            "rrf_k": 60,
-            "queries": [
-                {
-                    "query": {
-                        "sparse_vector": {
-                            "field": "sparse_embedding",
-                            "indices": [1, 5],
-                            "values": [0.8, 0.2],
-                        }
-                    },
-                    "weight": 1.0,
-                },
-                {
-                    "query": {
-                        "dense_vector": {
-                            "field": "embedding",
-                            "vector": [0.1, 0.2, 0.3],
-                        }
-                    },
-                    "weight": 1.0,
-                },
-            ],
-        }
-    },
-)
-```
-
-Other supported variants are `phrase`, `binary_dense_vector`, `boost`, `range`,
-`prefix`, and `all`. Search results expose the full `DocAddress` needed by
-`get_document()`:
-
-```python
-hit = results.hits[0]
-document = await client.get_document("articles", hit.address)
-```
-
-## Deadlines and errors
-
-Every RPC accepts an optional `timeout` in seconds. A per-call value overrides
-the client default:
-
-```python
-async with HermesClient("localhost:50051", default_timeout=5.0) as client:
-    results = await client.search(
-        "articles",
-        query={"all": {}},
-        timeout=0.5,
-    )
-    await client.force_merge("articles", timeout=3600)
-```
-
-gRPC failures raise `grpc.RpcError` (normally
-`grpc.aio.AioRpcError`). `get_document()` is the exception: it returns `None`
-for `NOT_FOUND`.
-
-```python
-import grpc
-
-try:
-    await client.search("missing", query={"all": {}})
-except grpc.RpcError as error:
-    if error.code() == grpc.StatusCode.NOT_FOUND:
-        print("index not found")
-    else:
-        raise
-```
-
-## Development
-
-From `hermes-client-python`:
-
-```bash
-uv sync --group dev --group test
-uv run ruff check .
-uv run ruff format --check .
-uv run pytest tests/test_client_unit.py
-```
-
-The remaining tests are integration tests and expect a debug
-`target/debug/hermes-server` binary. Regenerate checked-in protobuf stubs after
-changing `hermes-proto/hermes.proto`:
-
-```bash
-uv run --group dev python generate_proto.py
-```
-
-## License
-
-MIT
-
-## Ranking diagnostics and recall traces
-
-Both options default to false and preserve the requested ranking:
-
-```python
-response = await client.search(
-    "articles",
-    query={
-        "fusion": {
-            "queries": [
-                {
-                    "name": "title",
-                    "query": {"match": {"field": "title", "text": "rust"}},
-                },
-                {"name": "body", "query": {"match": {"field": "body", "text": "rust"}}},
-            ]
-        }
-    },
-    include_rrf_scores=True,
-    tracing=True,
-)
-for hit in response.hits:
-    print(hit.score, hit.rrf_score, hit.rrf_contributions)
-for shard in response.trace.shards:
-    for branch in shard.queries:
-        print(shard.shard_id, branch.query_name, branch.candidates)
-```
-
-`rrf_score` and per-branch votes use organic nomination ranks merged across all
-shards, independently of L1 or reranker scores. Ranks start at 1. `ordinal=None`
-is document context; ordinal 0 is a real passage. Backfilled and score-only
-features contribute no votes.
-
-The trace retains every shard's bounded branch nominations and selected results,
-including candidates absent from the final page, plus query trees and common
-filters. Candidates contain addresses, raw scores and ordinals; stored fields
-are loaded only for returned hits. Tracing does not expand retrieval depth or
-rerun individual Boolean clauses. Oversized diagnostics and unsupported backends
-fail explicitly. See the [scoring and tracing contract](../docs/candidate-rescoring.md).
-
-For a named, scoped L1 query, specify the complete scoring formula:
-
-```python
-l1 = {"formula": "0.2 * title + 0.8 * log1p(body) + 3 * rrf"}
-```
-
-`formula` is the only L1 scoring interface. Coefficients, offsets and RRF
-multipliers go in the expression; the former coefficient fields are removed.
-Arithmetic, powers, logarithms, `sqrt`, `abs`, `exp`, `min`/`max` and trigonometry
-are supported. Use `{body.bm25}` for punctuated branch names. `log` and `ln` are
-natural logarithms; `log2` and `log10` select those bases. Missing branch values
-use configured missing defaults, otherwise zero. Backfill remains optional.
-
-The formula runs before passage selection and the document combiner. A formula
-using `rrf` makes the broker obtain the complete bounded candidate and passage
-union before global inference. Exports that exceed budgets fail explicitly.
-Expressions are bounded to 4 KiB, 256 tokens and 32 parenthesis levels. Invalid
-variables, invalid syntax and non-finite predictions fail explicitly. Servers
-and brokers must support `formula_v1` (`candidate_scoring_version=3`).
-
-### Compact deleted rows
-
-```python
-await client.force_merge("articles")  # Copy encoded data and retain tombstones.
-await client.force_merge("articles", compact=True)  # Remove deleted rows physically.
-info = await client.get_index_info("articles")
-print(info.num_deleted_docs, info.physical_num_docs, info.deleted_ratio)
-```
-
-Compaction also works when there is only one segment. It preserves surviving
-values and may change document addresses and BM25 statistics.
-
-### Delete and upsert documents
-
-Declare one text field `[primary]` in the schema. Deletion removes the document
-and all of its chunks; upserts replace the entire document, including indexed-only
-fields, and insert when the key is absent.
-
-```python
-await client.delete_document("articles", "obsolete-key")
-await client.upsert_document(
-    "articles",
-    {"id": "article-42", "body": ["replacement chunk one", "replacement chunk two"]},
-)
-await client.commit("articles")
-
-result = await client.delete_documents("articles", ["old-a", "old-b"])
-print(result.accepted_count, result.errors)  # errors: [{"index": 0, "error": "..."}]
-await client.commit("articles")  # publishes accepted operations
-```
-
-`upsert_documents` takes a list of complete replacement documents and returns the
-same `DocumentMutationResult`. Single-document helpers raise on rejection. Missing
-deletion keys are accepted. Commit before deleting/upserting a key with a pending
-insertion or replacement. Limits are 100,000 deletion keys / 8 MiB key bytes and
-1,000 replacement documents / 32 MiB encoded bytes, or one replacement / 200 MiB
-including the request envelope. Mutations use the usual timeout
-argument; an expired RPC may have staged work, so do not blindly retry replacements.
-Broker commits are atomic within each partition. Physical cleanup remains
-`await client.force_merge("articles", compact=True)`.

hermes_client_python-1.8.145/README.md

@@ -1,356 +0,0 @@
-# Hermes Python client
-
-Async Python client for the
-[Hermes](https://github.com/SpaceFrontiers/hermes) gRPC search server.
-
-## Installation
-
-```bash
-pip install hermes-client-python
-```
-
-Python 3.10 or newer is required.
-
-## Quick start
-
-```python
-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 title: text<simple> [indexed, stored]
-                field body: text<simple> [indexed, stored]
-            }
-            """,
-        )
-
-        indexed, error_count, errors = await client.index_documents(
-            "articles",
-            [
-                {"title": "Hello World", "body": "First article"},
-                {"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")
-
-        await client.delete_index("articles")
-
-
-asyncio.run(main())
-```
-
-The context manager calls `connect()` and `close()` automatically. For manual
-lifecycle management:
-
-```python
-client = HermesClient("localhost:50051")
-await client.connect()
-try:
-    ...
-finally:
-    await client.close()
-```
-
-## Index management
-
-```python
-await client.create_index("articles", schema_sdl)
-names = await client.list_indexes()
-info = await client.get_index_info("articles")
-print(info.num_docs, info.num_segments, info.vector_stats)
-
-await client.force_merge("articles")
-await client.reorder("articles")
-await client.retrain_vector_index("articles")
-await client.delete_index("articles")
-```
-
-`commit()` is required before newly indexed documents become searchable.
-
-### Batch and streaming indexing
-
-```python
-indexed, error_count, errors = await client.index_documents(
-    "articles",
-    [
-        {"title": "One", "tags": ["search", "rust"]},
-        {"title": "Two", "tags": ["python"]},
-    ],
-)
-
-
-async def documents():
-    for number in range(10_000):
-        yield {"title": f"Document {number}"}
-
-
-streamed, stream_errors = await client.index_documents_stream("articles", documents())
-```
-
-Repeated list values become repeated field entries. Flat numeric lists are
-dense vectors; lists of `(dimension, weight)` pairs are sparse vectors.
-
-## Searching
-
-Every search takes one `query` object whose single key matches a Hermes query
-variant:
-
-```python
-# Exact term
-await client.search(
-    "articles",
-    query={"term": {"field": "title", "term": "hermes"}},
-)
-
-# Tokenized full-text match
-await client.search(
-    "articles",
-    query={"match": {"field": "body", "text": "fast retrieval"}},
-)
-
-# Recursive boolean query
-await client.search(
-    "articles",
-    query={
-        "boolean": {
-            "must": [{"match": {"field": "body", "text": "retrieval"}}],
-            "must_not": [{"term": {"field": "title", "term": "draft"}}],
-        }
-    },
-)
-
-# Dense vector query and optional reranking
-await client.search(
-    "articles",
-    query={
-        "dense_vector": {
-            "field": "embedding",
-            "vector": [0.1, 0.2, 0.3],
-            "nprobe": 16,
-        }
-    },
-    reranker={"field": "embedding", "vector": [0.1, 0.2, 0.3]},
-    candidate_limit=20,
-    limit=10,
-    fields_to_load=["title"],
-)
-
-# Hybrid union fusion
-await client.search(
-    "articles",
-    query={
-        "fusion": {
-            "method": "rrf",
-            "rrf_k": 60,
-            "queries": [
-                {
-                    "query": {
-                        "sparse_vector": {
-                            "field": "sparse_embedding",
-                            "indices": [1, 5],
-                            "values": [0.8, 0.2],
-                        }
-                    },
-                    "weight": 1.0,
-                },
-                {
-                    "query": {
-                        "dense_vector": {
-                            "field": "embedding",
-                            "vector": [0.1, 0.2, 0.3],
-                        }
-                    },
-                    "weight": 1.0,
-                },
-            ],
-        }
-    },
-)
-```
-
-Other supported variants are `phrase`, `binary_dense_vector`, `boost`, `range`,
-`prefix`, and `all`. Search results expose the full `DocAddress` needed by
-`get_document()`:
-
-```python
-hit = results.hits[0]
-document = await client.get_document("articles", hit.address)
-```
-
-## Deadlines and errors
-
-Every RPC accepts an optional `timeout` in seconds. A per-call value overrides
-the client default:
-
-```python
-async with HermesClient("localhost:50051", default_timeout=5.0) as client:
-    results = await client.search(
-        "articles",
-        query={"all": {}},
-        timeout=0.5,
-    )
-    await client.force_merge("articles", timeout=3600)
-```
-
-gRPC failures raise `grpc.RpcError` (normally
-`grpc.aio.AioRpcError`). `get_document()` is the exception: it returns `None`
-for `NOT_FOUND`.
-
-```python
-import grpc
-
-try:
-    await client.search("missing", query={"all": {}})
-except grpc.RpcError as error:
-    if error.code() == grpc.StatusCode.NOT_FOUND:
-        print("index not found")
-    else:
-        raise
-```
-
-## Development
-
-From `hermes-client-python`:
-
-```bash
-uv sync --group dev --group test
-uv run ruff check .
-uv run ruff format --check .
-uv run pytest tests/test_client_unit.py
-```
-
-The remaining tests are integration tests and expect a debug
-`target/debug/hermes-server` binary. Regenerate checked-in protobuf stubs after
-changing `hermes-proto/hermes.proto`:
-
-```bash
-uv run --group dev python generate_proto.py
-```
-
-## License
-
-MIT
-
-## Ranking diagnostics and recall traces
-
-Both options default to false and preserve the requested ranking:
-
-```python
-response = await client.search(
-    "articles",
-    query={
-        "fusion": {
-            "queries": [
-                {
-                    "name": "title",
-                    "query": {"match": {"field": "title", "text": "rust"}},
-                },
-                {"name": "body", "query": {"match": {"field": "body", "text": "rust"}}},
-            ]
-        }
-    },
-    include_rrf_scores=True,
-    tracing=True,
-)
-for hit in response.hits:
-    print(hit.score, hit.rrf_score, hit.rrf_contributions)
-for shard in response.trace.shards:
-    for branch in shard.queries:
-        print(shard.shard_id, branch.query_name, branch.candidates)
-```
-
-`rrf_score` and per-branch votes use organic nomination ranks merged across all
-shards, independently of L1 or reranker scores. Ranks start at 1. `ordinal=None`
-is document context; ordinal 0 is a real passage. Backfilled and score-only
-features contribute no votes.
-
-The trace retains every shard's bounded branch nominations and selected results,
-including candidates absent from the final page, plus query trees and common
-filters. Candidates contain addresses, raw scores and ordinals; stored fields
-are loaded only for returned hits. Tracing does not expand retrieval depth or
-rerun individual Boolean clauses. Oversized diagnostics and unsupported backends
-fail explicitly. See the [scoring and tracing contract](../docs/candidate-rescoring.md).
-
-For a named, scoped L1 query, specify the complete scoring formula:
-
-```python
-l1 = {"formula": "0.2 * title + 0.8 * log1p(body) + 3 * rrf"}
-```
-
-`formula` is the only L1 scoring interface. Coefficients, offsets and RRF
-multipliers go in the expression; the former coefficient fields are removed.
-Arithmetic, powers, logarithms, `sqrt`, `abs`, `exp`, `min`/`max` and trigonometry
-are supported. Use `{body.bm25}` for punctuated branch names. `log` and `ln` are
-natural logarithms; `log2` and `log10` select those bases. Missing branch values
-use configured missing defaults, otherwise zero. Backfill remains optional.
-
-The formula runs before passage selection and the document combiner. A formula
-using `rrf` makes the broker obtain the complete bounded candidate and passage
-union before global inference. Exports that exceed budgets fail explicitly.
-Expressions are bounded to 4 KiB, 256 tokens and 32 parenthesis levels. Invalid
-variables, invalid syntax and non-finite predictions fail explicitly. Servers
-and brokers must support `formula_v1` (`candidate_scoring_version=3`).
-
-### Compact deleted rows
-
-```python
-await client.force_merge("articles")  # Copy encoded data and retain tombstones.
-await client.force_merge("articles", compact=True)  # Remove deleted rows physically.
-info = await client.get_index_info("articles")
-print(info.num_deleted_docs, info.physical_num_docs, info.deleted_ratio)
-```
-
-Compaction also works when there is only one segment. It preserves surviving
-values and may change document addresses and BM25 statistics.
-
-### Delete and upsert documents
-
-Declare one text field `[primary]` in the schema. Deletion removes the document
-and all of its chunks; upserts replace the entire document, including indexed-only
-fields, and insert when the key is absent.
-
-```python
-await client.delete_document("articles", "obsolete-key")
-await client.upsert_document(
-    "articles",
-    {"id": "article-42", "body": ["replacement chunk one", "replacement chunk two"]},
-)
-await client.commit("articles")
-
-result = await client.delete_documents("articles", ["old-a", "old-b"])
-print(result.accepted_count, result.errors)  # errors: [{"index": 0, "error": "..."}]
-await client.commit("articles")  # publishes accepted operations
-```
-
-`upsert_documents` takes a list of complete replacement documents and returns the
-same `DocumentMutationResult`. Single-document helpers raise on rejection. Missing
-deletion keys are accepted. Commit before deleting/upserting a key with a pending
-insertion or replacement. Limits are 100,000 deletion keys / 8 MiB key bytes and
-1,000 replacement documents / 32 MiB encoded bytes, or one replacement / 200 MiB
-including the request envelope. Mutations use the usual timeout
-argument; an expired RPC may have staged work, so do not blindly retry replacements.
-Broker commits are atomic within each partition. Physical cleanup remains
-`await client.force_merge("articles", compact=True)`.