hermes-client-python 1.0.4__py3-none-any.whl

hermes_client_python/__init__.py

@@ -0,0 +1,14 @@
+"""Async Python client for Hermes search server."""
+
+from .client import HermesClient
+from .types import Document, IndexInfo, SearchHit, SearchResponse
+
+__all__ = [
+    "HermesClient",
+    "Document",
+    "SearchHit",
+    "SearchResponse",
+    "IndexInfo",
+]
+
+__version__ = "1.0.2"

hermes_client_python/client.py

@@ -0,0 +1,403 @@
+"""Async Hermes client implementation."""
+
+from __future__ import annotations
+
+import json
+from collections.abc import AsyncIterator
+from typing import Any
+
+import grpc
+from grpc import aio
+
+from . import hermes_pb2 as pb
+from . import hermes_pb2_grpc as pb_grpc
+from .types import Document, IndexInfo, SearchHit, SearchResponse
+
+
+class HermesClient:
+    """Async client for Hermes search server.
+
+    Example:
+        async with HermesClient("localhost:50051") as client:
+            # Create index
+            await client.create_index("articles", '''
+                index articles {
+                    title: text indexed stored
+                    body: text indexed stored
+                }
+            ''')
+
+            # Index documents
+            await client.index_documents("articles", [
+                {"title": "Hello", "body": "World"},
+                {"title": "Foo", "body": "Bar"},
+            ])
+            await client.commit("articles")
+
+            # Search
+            results = await client.search("articles", term=("title", "hello"))
+            for hit in results.hits:
+                print(hit.doc_id, hit.score)
+    """
+
+    def __init__(self, address: str = "localhost:50051"):
+        """Initialize client.
+
+        Args:
+            address: Server address in format "host:port"
+        """
+        self.address = address
+        self._channel: aio.Channel | None = None
+        self._index_stub: pb_grpc.IndexServiceStub | None = None
+        self._search_stub: pb_grpc.SearchServiceStub | None = None
+
+    async def connect(self) -> None:
+        """Connect to the server."""
+        self._channel = aio.insecure_channel(self.address)
+        self._index_stub = pb_grpc.IndexServiceStub(self._channel)
+        self._search_stub = pb_grpc.SearchServiceStub(self._channel)
+
+    async def close(self) -> None:
+        """Close the connection."""
+        if self._channel:
+            await self._channel.close()
+            self._channel = None
+            self._index_stub = None
+            self._search_stub = None
+
+    async def __aenter__(self) -> HermesClient:
+        await self.connect()
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb) -> None:
+        await self.close()
+
+    def _ensure_connected(self) -> None:
+        if self._index_stub is None or self._search_stub is None:
+            raise RuntimeError(
+                "Client not connected. Use 'async with' or call connect() first."
+            )
+
+    # =========================================================================
+    # Index Management
+    # =========================================================================
+
+    async def create_index(self, index_name: str, schema: str) -> bool:
+        """Create a new index.
+
+        Args:
+            index_name: Name of the index
+            schema: Schema definition in SDL or JSON format
+
+        Returns:
+            True if successful
+
+        Example SDL schema:
+            index myindex {
+                title: text indexed stored
+                body: text indexed stored
+                score: f64 stored
+            }
+
+        Example JSON schema:
+            {
+                "fields": [
+                    {"name": "title", "type": "text", "indexed": true, "stored": true}
+                ]
+            }
+        """
+        self._ensure_connected()
+        request = pb.CreateIndexRequest(index_name=index_name, schema=schema)
+        response = await self._index_stub.CreateIndex(request)
+        return response.success
+
+    async def delete_index(self, index_name: str) -> bool:
+        """Delete an index.
+
+        Args:
+            index_name: Name of the index to delete
+
+        Returns:
+            True if successful
+        """
+        self._ensure_connected()
+        request = pb.DeleteIndexRequest(index_name=index_name)
+        response = await self._index_stub.DeleteIndex(request)
+        return response.success
+
+    async def get_index_info(self, index_name: str) -> IndexInfo:
+        """Get information about an index.
+
+        Args:
+            index_name: Name of the index
+
+        Returns:
+            IndexInfo with document count, segments, and schema
+        """
+        self._ensure_connected()
+        request = pb.GetIndexInfoRequest(index_name=index_name)
+        response = await self._search_stub.GetIndexInfo(request)
+        return IndexInfo(
+            index_name=response.index_name,
+            num_docs=response.num_docs,
+            num_segments=response.num_segments,
+            schema=response.schema,
+        )
+
+    # =========================================================================
+    # Document Indexing
+    # =========================================================================
+
+    async def index_documents(
+        self, index_name: str, documents: list[dict[str, Any]]
+    ) -> tuple[int, int]:
+        """Index multiple documents in batch.
+
+        Args:
+            index_name: Name of the index
+            documents: List of documents (dicts with field names as keys)
+
+        Returns:
+            Tuple of (indexed_count, error_count)
+        """
+        self._ensure_connected()
+
+        named_docs = []
+        for doc in documents:
+            fields = {k: _to_field_value(v) for k, v in doc.items()}
+            named_docs.append(pb.NamedDocument(fields=fields))
+
+        request = pb.BatchIndexDocumentsRequest(
+            index_name=index_name, documents=named_docs
+        )
+        response = await self._index_stub.BatchIndexDocuments(request)
+        return response.indexed_count, response.error_count
+
+    async def index_document(self, index_name: str, document: dict[str, Any]) -> None:
+        """Index a single document.
+
+        Args:
+            index_name: Name of the index
+            document: Document as dict with field names as keys
+        """
+        await self.index_documents(index_name, [document])
+
+    async def index_documents_stream(
+        self, index_name: str, documents: AsyncIterator[dict[str, Any]]
+    ) -> int:
+        """Stream documents for indexing.
+
+        Args:
+            index_name: Name of the index
+            documents: Async iterator of documents
+
+        Returns:
+            Number of indexed documents
+        """
+        self._ensure_connected()
+
+        async def request_iterator():
+            async for doc in documents:
+                fields = {k: _to_field_value(v) for k, v in doc.items()}
+                yield pb.IndexDocumentRequest(index_name=index_name, fields=fields)
+
+        response = await self._index_stub.IndexDocuments(request_iterator())
+        return response.indexed_count
+
+    async def commit(self, index_name: str) -> int:
+        """Commit pending changes.
+
+        Args:
+            index_name: Name of the index
+
+        Returns:
+            Total number of documents in the index
+        """
+        self._ensure_connected()
+        request = pb.CommitRequest(index_name=index_name)
+        response = await self._index_stub.Commit(request)
+        return response.num_docs
+
+    async def force_merge(self, index_name: str) -> int:
+        """Force merge all segments.
+
+        Args:
+            index_name: Name of the index
+
+        Returns:
+            Number of segments after merge
+        """
+        self._ensure_connected()
+        request = pb.ForceMergeRequest(index_name=index_name)
+        response = await self._index_stub.ForceMerge(request)
+        return response.num_segments
+
+    # =========================================================================
+    # Search
+    # =========================================================================
+
+    async def search(
+        self,
+        index_name: str,
+        *,
+        term: tuple[str, str] | None = None,
+        boolean: dict[str, list[tuple[str, str]]] | None = None,
+        limit: int = 10,
+        offset: int = 0,
+        fields_to_load: list[str] | None = None,
+    ) -> SearchResponse:
+        """Search for documents.
+
+        Args:
+            index_name: Name of the index
+            term: Term query as (field, term) tuple
+            boolean: Boolean query with "must", "should", "must_not" keys
+            limit: Maximum number of results
+            offset: Offset for pagination
+            fields_to_load: List of fields to include in results
+
+        Returns:
+            SearchResponse with hits
+
+        Examples:
+            # Term query
+            results = await client.search("articles", term=("title", "hello"))
+
+            # Boolean query
+            results = await client.search("articles", boolean={
+                "must": [("title", "hello")],
+                "should": [("body", "world")],
+            })
+        """
+        self._ensure_connected()
+
+        query = _build_query(term=term, boolean=boolean)
+
+        request = pb.SearchRequest(
+            index_name=index_name,
+            query=query,
+            limit=limit,
+            offset=offset,
+            fields_to_load=fields_to_load or [],
+        )
+
+        response = await self._search_stub.Search(request)
+
+        hits = [
+            SearchHit(
+                doc_id=hit.doc_id,
+                score=hit.score,
+                fields={k: _from_field_value(v) for k, v in hit.fields.items()},
+            )
+            for hit in response.hits
+        ]
+
+        return SearchResponse(
+            hits=hits,
+            total_hits=response.total_hits,
+            took_ms=response.took_ms,
+        )
+
+    async def get_document(self, index_name: str, doc_id: int) -> Document | None:
+        """Get a document by ID.
+
+        Args:
+            index_name: Name of the index
+            doc_id: Document ID
+
+        Returns:
+            Document or None if not found
+        """
+        self._ensure_connected()
+        request = pb.GetDocumentRequest(index_name=index_name, doc_id=doc_id)
+        try:
+            response = await self._search_stub.GetDocument(request)
+            fields = {k: _from_field_value(v) for k, v in response.fields.items()}
+            return Document(fields=fields)
+        except grpc.RpcError as e:
+            if e.code() == grpc.StatusCode.NOT_FOUND:
+                return None
+            raise
+
+
+# =============================================================================
+# Helper functions
+# =============================================================================
+
+
+def _to_field_value(value: Any) -> pb.FieldValue:
+    """Convert Python value to protobuf FieldValue."""
+    if isinstance(value, str):
+        return pb.FieldValue(text=value)
+    elif isinstance(value, bool):
+        return pb.FieldValue(u64=1 if value else 0)
+    elif isinstance(value, int):
+        if value >= 0:
+            return pb.FieldValue(u64=value)
+        else:
+            return pb.FieldValue(i64=value)
+    elif isinstance(value, float):
+        return pb.FieldValue(f64=value)
+    elif isinstance(value, bytes):
+        return pb.FieldValue(bytes_value=value)
+    elif isinstance(value, (list, dict)):
+        # Assume JSON for complex types
+        return pb.FieldValue(json_value=json.dumps(value))
+    else:
+        return pb.FieldValue(text=str(value))
+
+
+def _from_field_value(fv: pb.FieldValue) -> Any:
+    """Convert protobuf FieldValue to Python value."""
+    which = fv.WhichOneof("value")
+    if which == "text":
+        return fv.text
+    elif which == "u64":
+        return fv.u64
+    elif which == "i64":
+        return fv.i64
+    elif which == "f64":
+        return fv.f64
+    elif which == "bytes_value":
+        return fv.bytes_value
+    elif which == "json_value":
+        return json.loads(fv.json_value)
+    elif which == "sparse_vector":
+        return {
+            "indices": list(fv.sparse_vector.indices),
+            "values": list(fv.sparse_vector.values),
+        }
+    elif which == "dense_vector":
+        return list(fv.dense_vector.values)
+    return None
+
+
+def _build_query(
+    *,
+    term: tuple[str, str] | None = None,
+    boolean: dict[str, list[tuple[str, str]]] | None = None,
+) -> pb.Query:
+    """Build a protobuf Query from parameters."""
+    if term is not None:
+        field, value = term
+        return pb.Query(term=pb.TermQuery(field=field, term=value))
+
+    if boolean is not None:
+        must = [
+            pb.Query(term=pb.TermQuery(field=f, term=t))
+            for f, t in boolean.get("must", [])
+        ]
+        should = [
+            pb.Query(term=pb.TermQuery(field=f, term=t))
+            for f, t in boolean.get("should", [])
+        ]
+        must_not = [
+            pb.Query(term=pb.TermQuery(field=f, term=t))
+            for f, t in boolean.get("must_not", [])
+        ]
+        return pb.Query(
+            boolean=pb.BooleanQuery(must=must, should=should, must_not=must_not)
+        )
+
+    # Default: match all (empty boolean query)
+    return pb.Query(boolean=pb.BooleanQuery())

hermes_client_python/hermes_pb2.py

@@ -0,0 +1,106 @@
+# Generated by the protocol buffer compiler.  DO NOT EDIT!
+# NO CHECKED-IN PROTOBUF GENCODE
+# source: hermes.proto
+# Protobuf Python Version: 6.31.1
+"""Generated protocol buffer code."""
+
+from google.protobuf import descriptor as _descriptor
+from google.protobuf import descriptor_pool as _descriptor_pool
+from google.protobuf import runtime_version as _runtime_version
+from google.protobuf import symbol_database as _symbol_database
+from google.protobuf.internal import builder as _builder
+
+_runtime_version.ValidateProtobufRuntimeVersion(
+    _runtime_version.Domain.PUBLIC, 6, 31, 1, "", "hermes.proto"
+)
+# @@protoc_insertion_point(imports)
+
+_sym_db = _symbol_database.Default()
+
+
+DESCRIPTOR = _descriptor_pool.Default().AddSerializedFile(
+    b'\n\x0chermes.proto\x12\x06hermes"\xa2\x01\n\x05Query\x12!\n\x04term\x18\x01 \x01(\x0b\x32\x11.hermes.TermQueryH\x00\x12\'\n\x07\x62oolean\x18\x02 \x01(\x0b\x32\x14.hermes.BooleanQueryH\x00\x12#\n\x05\x62oost\x18\x03 \x01(\x0b\x32\x12.hermes.BoostQueryH\x00\x12\x1f\n\x03\x61ll\x18\x04 \x01(\x0b\x32\x10.hermes.AllQueryH\x00\x42\x07\n\x05query"(\n\tTermQuery\x12\r\n\x05\x66ield\x18\x01 \x01(\t\x12\x0c\n\x04term\x18\x02 \x01(\t"k\n\x0c\x42ooleanQuery\x12\x1b\n\x04must\x18\x01 \x03(\x0b\x32\r.hermes.Query\x12\x1d\n\x06should\x18\x02 \x03(\x0b\x32\r.hermes.Query\x12\x1f\n\x08must_not\x18\x03 \x03(\x0b\x32\r.hermes.Query"9\n\nBoostQuery\x12\x1c\n\x05query\x18\x01 \x01(\x0b\x32\r.hermes.Query\x12\r\n\x05\x62oost\x18\x02 \x01(\x02"\n\n\x08\x41llQuery"x\n\rSearchRequest\x12\x12\n\nindex_name\x18\x01 \x01(\t\x12\x1c\n\x05query\x18\x02 \x01(\x0b\x32\r.hermes.Query\x12\r\n\x05limit\x18\x03 \x01(\r\x12\x0e\n\x06offset\x18\x04 \x01(\r\x12\x16\n\x0e\x66ields_to_load\x18\x05 \x03(\t"\x9c\x01\n\tSearchHit\x12\x0e\n\x06\x64oc_id\x18\x01 \x01(\r\x12\r\n\x05score\x18\x02 \x01(\x02\x12-\n\x06\x66ields\x18\x03 \x03(\x0b\x32\x1d.hermes.SearchHit.FieldsEntry\x1a\x41\n\x0b\x46ieldsEntry\x12\x0b\n\x03key\x18\x01 \x01(\t\x12!\n\x05value\x18\x02 \x01(\x0b\x32\x12.hermes.FieldValue:\x02\x38\x01"\xdb\x01\n\nFieldValue\x12\x0e\n\x04text\x18\x01 \x01(\tH\x00\x12\r\n\x03u64\x18\x02 \x01(\x04H\x00\x12\r\n\x03i64\x18\x03 \x01(\x03H\x00\x12\r\n\x03\x66\x36\x34\x18\x04 \x01(\x01H\x00\x12\x15\n\x0b\x62ytes_value\x18\x05 \x01(\x0cH\x00\x12-\n\rsparse_vector\x18\x06 \x01(\x0b\x32\x14.hermes.SparseVectorH\x00\x12+\n\x0c\x64\x65nse_vector\x18\x07 \x01(\x0b\x32\x13.hermes.DenseVectorH\x00\x12\x14\n\njson_value\x18\x08 \x01(\tH\x00\x42\x07\n\x05value"/\n\x0cSparseVector\x12\x0f\n\x07indices\x18\x01 \x03(\r\x12\x0e\n\x06values\x18\x02 \x03(\x02"\x1d\n\x0b\x44\x65nseVector\x12\x0e\n\x06values\x18\x01 \x03(\x02"V\n\x0eSearchResponse\x12\x1f\n\x04hits\x18\x01 \x03(\x0b\x32\x11.hermes.SearchHit\x12\x12\n\ntotal_hits\x18\x02 \x01(\r\x12\x0f\n\x07took_ms\x18\x03 \x01(\x04"8\n\x12GetDocumentRequest\x12\x12\n\nindex_name\x18\x01 \x01(\t\x12\x0e\n\x06\x64oc_id\x18\x02 \x01(\r"\x91\x01\n\x13GetDocumentResponse\x12\x37\n\x06\x66ields\x18\x01 \x03(\x0b\x32\'.hermes.GetDocumentResponse.FieldsEntry\x1a\x41\n\x0b\x46ieldsEntry\x12\x0b\n\x03key\x18\x01 \x01(\t\x12!\n\x05value\x18\x02 \x01(\x0b\x32\x12.hermes.FieldValue:\x02\x38\x01")\n\x13GetIndexInfoRequest\x12\x12\n\nindex_name\x18\x01 \x01(\t"b\n\x14GetIndexInfoResponse\x12\x12\n\nindex_name\x18\x01 \x01(\t\x12\x10\n\x08num_docs\x18\x02 \x01(\r\x12\x14\n\x0cnum_segments\x18\x03 \x01(\r\x12\x0e\n\x06schema\x18\x04 \x01(\t"8\n\x12\x43reateIndexRequest\x12\x12\n\nindex_name\x18\x01 \x01(\t\x12\x0e\n\x06schema\x18\x02 \x01(\t"&\n\x13\x43reateIndexResponse\x12\x0f\n\x07success\x18\x01 \x01(\x08"\x85\x01\n\rNamedDocument\x12\x31\n\x06\x66ields\x18\x01 \x03(\x0b\x32!.hermes.NamedDocument.FieldsEntry\x1a\x41\n\x0b\x46ieldsEntry\x12\x0b\n\x03key\x18\x01 \x01(\t\x12!\n\x05value\x18\x02 \x01(\x0b\x32\x12.hermes.FieldValue:\x02\x38\x01"Z\n\x1a\x42\x61tchIndexDocumentsRequest\x12\x12\n\nindex_name\x18\x01 \x01(\t\x12(\n\tdocuments\x18\x02 \x03(\x0b\x32\x15.hermes.NamedDocument"I\n\x1b\x42\x61tchIndexDocumentsResponse\x12\x15\n\rindexed_count\x18\x01 \x01(\r\x12\x13\n\x0b\x65rror_count\x18\x02 \x01(\r"\xa7\x01\n\x14IndexDocumentRequest\x12\x12\n\nindex_name\x18\x01 \x01(\t\x12\x38\n\x06\x66ields\x18\x02 \x03(\x0b\x32(.hermes.IndexDocumentRequest.FieldsEntry\x1a\x41\n\x0b\x46ieldsEntry\x12\x0b\n\x03key\x18\x01 \x01(\t\x12!\n\x05value\x18\x02 \x01(\x0b\x32\x12.hermes.FieldValue:\x02\x38\x01"/\n\x16IndexDocumentsResponse\x12\x15\n\rindexed_count\x18\x01 \x01(\r"#\n\rCommitRequest\x12\x12\n\nindex_name\x18\x01 \x01(\t"3\n\x0e\x43ommitResponse\x12\x0f\n\x07success\x18\x01 \x01(\x08\x12\x10\n\x08num_docs\x18\x02 \x01(\r"\'\n\x11\x46orceMergeRequest\x12\x12\n\nindex_name\x18\x01 \x01(\t";\n\x12\x46orceMergeResponse\x12\x0f\n\x07success\x18\x01 \x01(\x08\x12\x14\n\x0cnum_segments\x18\x02 \x01(\r"(\n\x12\x44\x65leteIndexRequest\x12\x12\n\nindex_name\x18\x01 \x01(\t"&\n\x13\x44\x65leteIndexResponse\x12\x0f\n\x07success\x18\x01 \x01(\x08\x32\xdb\x01\n\rSearchService\x12\x37\n\x06Search\x12\x15.hermes.SearchRequest\x1a\x16.hermes.SearchResponse\x12\x46\n\x0bGetDocument\x12\x1a.hermes.GetDocumentRequest\x1a\x1b.hermes.GetDocumentResponse\x12I\n\x0cGetIndexInfo\x12\x1b.hermes.GetIndexInfoRequest\x1a\x1c.hermes.GetIndexInfoResponse2\xce\x03\n\x0cIndexService\x12\x46\n\x0b\x43reateIndex\x12\x1a.hermes.CreateIndexRequest\x1a\x1b.hermes.CreateIndexResponse\x12P\n\x0eIndexDocuments\x12\x1c.hermes.IndexDocumentRequest\x1a\x1e.hermes.IndexDocumentsResponse(\x01\x12^\n\x13\x42\x61tchIndexDocuments\x12".hermes.BatchIndexDocumentsRequest\x1a#.hermes.BatchIndexDocumentsResponse\x12\x37\n\x06\x43ommit\x12\x15.hermes.CommitRequest\x1a\x16.hermes.CommitResponse\x12\x43\n\nForceMerge\x12\x19.hermes.ForceMergeRequest\x1a\x1a.hermes.ForceMergeResponse\x12\x46\n\x0b\x44\x65leteIndex\x12\x1a.hermes.DeleteIndexRequest\x1a\x1b.hermes.DeleteIndexResponseb\x06proto3'
+)
+
+_globals = globals()
+_builder.BuildMessageAndEnumDescriptors(DESCRIPTOR, _globals)
+_builder.BuildTopDescriptorsAndMessages(DESCRIPTOR, "hermes_pb2", _globals)
+if not _descriptor._USE_C_DESCRIPTORS:
+    DESCRIPTOR._loaded_options = None
+    _globals["_SEARCHHIT_FIELDSENTRY"]._loaded_options = None
+    _globals["_SEARCHHIT_FIELDSENTRY"]._serialized_options = b"8\001"
+    _globals["_GETDOCUMENTRESPONSE_FIELDSENTRY"]._loaded_options = None
+    _globals["_GETDOCUMENTRESPONSE_FIELDSENTRY"]._serialized_options = b"8\001"
+    _globals["_NAMEDDOCUMENT_FIELDSENTRY"]._loaded_options = None
+    _globals["_NAMEDDOCUMENT_FIELDSENTRY"]._serialized_options = b"8\001"
+    _globals["_INDEXDOCUMENTREQUEST_FIELDSENTRY"]._loaded_options = None
+    _globals["_INDEXDOCUMENTREQUEST_FIELDSENTRY"]._serialized_options = b"8\001"
+    _globals["_QUERY"]._serialized_start = 25
+    _globals["_QUERY"]._serialized_end = 187
+    _globals["_TERMQUERY"]._serialized_start = 189
+    _globals["_TERMQUERY"]._serialized_end = 229
+    _globals["_BOOLEANQUERY"]._serialized_start = 231
+    _globals["_BOOLEANQUERY"]._serialized_end = 338
+    _globals["_BOOSTQUERY"]._serialized_start = 340
+    _globals["_BOOSTQUERY"]._serialized_end = 397
+    _globals["_ALLQUERY"]._serialized_start = 399
+    _globals["_ALLQUERY"]._serialized_end = 409
+    _globals["_SEARCHREQUEST"]._serialized_start = 411
+    _globals["_SEARCHREQUEST"]._serialized_end = 531
+    _globals["_SEARCHHIT"]._serialized_start = 534
+    _globals["_SEARCHHIT"]._serialized_end = 690
+    _globals["_SEARCHHIT_FIELDSENTRY"]._serialized_start = 625
+    _globals["_SEARCHHIT_FIELDSENTRY"]._serialized_end = 690
+    _globals["_FIELDVALUE"]._serialized_start = 693
+    _globals["_FIELDVALUE"]._serialized_end = 912
+    _globals["_SPARSEVECTOR"]._serialized_start = 914
+    _globals["_SPARSEVECTOR"]._serialized_end = 961
+    _globals["_DENSEVECTOR"]._serialized_start = 963
+    _globals["_DENSEVECTOR"]._serialized_end = 992
+    _globals["_SEARCHRESPONSE"]._serialized_start = 994
+    _globals["_SEARCHRESPONSE"]._serialized_end = 1080
+    _globals["_GETDOCUMENTREQUEST"]._serialized_start = 1082
+    _globals["_GETDOCUMENTREQUEST"]._serialized_end = 1138
+    _globals["_GETDOCUMENTRESPONSE"]._serialized_start = 1141
+    _globals["_GETDOCUMENTRESPONSE"]._serialized_end = 1286
+    _globals["_GETDOCUMENTRESPONSE_FIELDSENTRY"]._serialized_start = 625
+    _globals["_GETDOCUMENTRESPONSE_FIELDSENTRY"]._serialized_end = 690
+    _globals["_GETINDEXINFOREQUEST"]._serialized_start = 1288
+    _globals["_GETINDEXINFOREQUEST"]._serialized_end = 1329
+    _globals["_GETINDEXINFORESPONSE"]._serialized_start = 1331
+    _globals["_GETINDEXINFORESPONSE"]._serialized_end = 1429
+    _globals["_CREATEINDEXREQUEST"]._serialized_start = 1431
+    _globals["_CREATEINDEXREQUEST"]._serialized_end = 1487
+    _globals["_CREATEINDEXRESPONSE"]._serialized_start = 1489
+    _globals["_CREATEINDEXRESPONSE"]._serialized_end = 1527
+    _globals["_NAMEDDOCUMENT"]._serialized_start = 1530
+    _globals["_NAMEDDOCUMENT"]._serialized_end = 1663
+    _globals["_NAMEDDOCUMENT_FIELDSENTRY"]._serialized_start = 625
+    _globals["_NAMEDDOCUMENT_FIELDSENTRY"]._serialized_end = 690
+    _globals["_BATCHINDEXDOCUMENTSREQUEST"]._serialized_start = 1665
+    _globals["_BATCHINDEXDOCUMENTSREQUEST"]._serialized_end = 1755
+    _globals["_BATCHINDEXDOCUMENTSRESPONSE"]._serialized_start = 1757
+    _globals["_BATCHINDEXDOCUMENTSRESPONSE"]._serialized_end = 1830
+    _globals["_INDEXDOCUMENTREQUEST"]._serialized_start = 1833
+    _globals["_INDEXDOCUMENTREQUEST"]._serialized_end = 2000
+    _globals["_INDEXDOCUMENTREQUEST_FIELDSENTRY"]._serialized_start = 625
+    _globals["_INDEXDOCUMENTREQUEST_FIELDSENTRY"]._serialized_end = 690
+    _globals["_INDEXDOCUMENTSRESPONSE"]._serialized_start = 2002
+    _globals["_INDEXDOCUMENTSRESPONSE"]._serialized_end = 2049
+    _globals["_COMMITREQUEST"]._serialized_start = 2051
+    _globals["_COMMITREQUEST"]._serialized_end = 2086
+    _globals["_COMMITRESPONSE"]._serialized_start = 2088
+    _globals["_COMMITRESPONSE"]._serialized_end = 2139
+    _globals["_FORCEMERGEREQUEST"]._serialized_start = 2141
+    _globals["_FORCEMERGEREQUEST"]._serialized_end = 2180
+    _globals["_FORCEMERGERESPONSE"]._serialized_start = 2182
+    _globals["_FORCEMERGERESPONSE"]._serialized_end = 2241
+    _globals["_DELETEINDEXREQUEST"]._serialized_start = 2243
+    _globals["_DELETEINDEXREQUEST"]._serialized_end = 2283
+    _globals["_DELETEINDEXRESPONSE"]._serialized_start = 2285
+    _globals["_DELETEINDEXRESPONSE"]._serialized_end = 2323
+    _globals["_SEARCHSERVICE"]._serialized_start = 2326
+    _globals["_SEARCHSERVICE"]._serialized_end = 2545
+    _globals["_INDEXSERVICE"]._serialized_start = 2548
+    _globals["_INDEXSERVICE"]._serialized_end = 3010
+# @@protoc_insertion_point(module_scope)

hermes_client_python/hermes_pb2_grpc.py

@@ -0,0 +1,511 @@
+# Generated by the gRPC Python protocol compiler plugin. DO NOT EDIT!
+"""Client and server classes corresponding to protobuf-defined services."""
+
+import grpc
+
+from . import hermes_pb2 as hermes__pb2
+
+GRPC_GENERATED_VERSION = "1.76.0"
+GRPC_VERSION = grpc.__version__
+_version_not_supported = False
+
+try:
+    from grpc._utilities import first_version_is_lower
+
+    _version_not_supported = first_version_is_lower(
+        GRPC_VERSION, GRPC_GENERATED_VERSION
+    )
+except ImportError:
+    _version_not_supported = True
+
+if _version_not_supported:
+    raise RuntimeError(
+        f"The grpc package installed is at version {GRPC_VERSION},"
+        + " but the generated code in hermes_pb2_grpc.py depends on"
+        + f" grpcio>={GRPC_GENERATED_VERSION}."
+        + f" Please upgrade your grpc module to grpcio>={GRPC_GENERATED_VERSION}"
+        + f" or downgrade your generated code using grpcio-tools<={GRPC_VERSION}."
+    )
+
+
+class SearchServiceStub:
+    """Search service"""
+
+    def __init__(self, channel):
+        """Constructor.
+
+        Args:
+            channel: A grpc.Channel.
+        """
+        self.Search = channel.unary_unary(
+            "/hermes.SearchService/Search",
+            request_serializer=hermes__pb2.SearchRequest.SerializeToString,
+            response_deserializer=hermes__pb2.SearchResponse.FromString,
+            _registered_method=True,
+        )
+        self.GetDocument = channel.unary_unary(
+            "/hermes.SearchService/GetDocument",
+            request_serializer=hermes__pb2.GetDocumentRequest.SerializeToString,
+            response_deserializer=hermes__pb2.GetDocumentResponse.FromString,
+            _registered_method=True,
+        )
+        self.GetIndexInfo = channel.unary_unary(
+            "/hermes.SearchService/GetIndexInfo",
+            request_serializer=hermes__pb2.GetIndexInfoRequest.SerializeToString,
+            response_deserializer=hermes__pb2.GetIndexInfoResponse.FromString,
+            _registered_method=True,
+        )
+
+
+class SearchServiceServicer:
+    """Search service"""
+
+    def Search(self, request, context):
+        """Search for documents"""
+        context.set_code(grpc.StatusCode.UNIMPLEMENTED)
+        context.set_details("Method not implemented!")
+        raise NotImplementedError("Method not implemented!")
+
+    def GetDocument(self, request, context):
+        """Get document by ID"""
+        context.set_code(grpc.StatusCode.UNIMPLEMENTED)
+        context.set_details("Method not implemented!")
+        raise NotImplementedError("Method not implemented!")
+
+    def GetIndexInfo(self, request, context):
+        """Get index info"""
+        context.set_code(grpc.StatusCode.UNIMPLEMENTED)
+        context.set_details("Method not implemented!")
+        raise NotImplementedError("Method not implemented!")
+
+
+def add_SearchServiceServicer_to_server(servicer, server):
+    rpc_method_handlers = {
+        "Search": grpc.unary_unary_rpc_method_handler(
+            servicer.Search,
+            request_deserializer=hermes__pb2.SearchRequest.FromString,
+            response_serializer=hermes__pb2.SearchResponse.SerializeToString,
+        ),
+        "GetDocument": grpc.unary_unary_rpc_method_handler(
+            servicer.GetDocument,
+            request_deserializer=hermes__pb2.GetDocumentRequest.FromString,
+            response_serializer=hermes__pb2.GetDocumentResponse.SerializeToString,
+        ),
+        "GetIndexInfo": grpc.unary_unary_rpc_method_handler(
+            servicer.GetIndexInfo,
+            request_deserializer=hermes__pb2.GetIndexInfoRequest.FromString,
+            response_serializer=hermes__pb2.GetIndexInfoResponse.SerializeToString,
+        ),
+    }
+    generic_handler = grpc.method_handlers_generic_handler(
+        "hermes.SearchService", rpc_method_handlers
+    )
+    server.add_generic_rpc_handlers((generic_handler,))
+    server.add_registered_method_handlers("hermes.SearchService", rpc_method_handlers)
+
+
+# This class is part of an EXPERIMENTAL API.
+class SearchService:
+    """Search service"""
+
+    @staticmethod
+    def Search(
+        request,
+        target,
+        options=(),
+        channel_credentials=None,
+        call_credentials=None,
+        insecure=False,
+        compression=None,
+        wait_for_ready=None,
+        timeout=None,
+        metadata=None,
+    ):
+        return grpc.experimental.unary_unary(
+            request,
+            target,
+            "/hermes.SearchService/Search",
+            hermes__pb2.SearchRequest.SerializeToString,
+            hermes__pb2.SearchResponse.FromString,
+            options,
+            channel_credentials,
+            insecure,
+            call_credentials,
+            compression,
+            wait_for_ready,
+            timeout,
+            metadata,
+            _registered_method=True,
+        )
+
+    @staticmethod
+    def GetDocument(
+        request,
+        target,
+        options=(),
+        channel_credentials=None,
+        call_credentials=None,
+        insecure=False,
+        compression=None,
+        wait_for_ready=None,
+        timeout=None,
+        metadata=None,
+    ):
+        return grpc.experimental.unary_unary(
+            request,
+            target,
+            "/hermes.SearchService/GetDocument",
+            hermes__pb2.GetDocumentRequest.SerializeToString,
+            hermes__pb2.GetDocumentResponse.FromString,
+            options,
+            channel_credentials,
+            insecure,
+            call_credentials,
+            compression,
+            wait_for_ready,
+            timeout,
+            metadata,
+            _registered_method=True,
+        )
+
+    @staticmethod
+    def GetIndexInfo(
+        request,
+        target,
+        options=(),
+        channel_credentials=None,
+        call_credentials=None,
+        insecure=False,
+        compression=None,
+        wait_for_ready=None,
+        timeout=None,
+        metadata=None,
+    ):
+        return grpc.experimental.unary_unary(
+            request,
+            target,
+            "/hermes.SearchService/GetIndexInfo",
+            hermes__pb2.GetIndexInfoRequest.SerializeToString,
+            hermes__pb2.GetIndexInfoResponse.FromString,
+            options,
+            channel_credentials,
+            insecure,
+            call_credentials,
+            compression,
+            wait_for_ready,
+            timeout,
+            metadata,
+            _registered_method=True,
+        )
+
+
+class IndexServiceStub:
+    """Index service"""
+
+    def __init__(self, channel):
+        """Constructor.
+
+        Args:
+            channel: A grpc.Channel.
+        """
+        self.CreateIndex = channel.unary_unary(
+            "/hermes.IndexService/CreateIndex",
+            request_serializer=hermes__pb2.CreateIndexRequest.SerializeToString,
+            response_deserializer=hermes__pb2.CreateIndexResponse.FromString,
+            _registered_method=True,
+        )
+        self.IndexDocuments = channel.stream_unary(
+            "/hermes.IndexService/IndexDocuments",
+            request_serializer=hermes__pb2.IndexDocumentRequest.SerializeToString,
+            response_deserializer=hermes__pb2.IndexDocumentsResponse.FromString,
+            _registered_method=True,
+        )
+        self.BatchIndexDocuments = channel.unary_unary(
+            "/hermes.IndexService/BatchIndexDocuments",
+            request_serializer=hermes__pb2.BatchIndexDocumentsRequest.SerializeToString,
+            response_deserializer=hermes__pb2.BatchIndexDocumentsResponse.FromString,
+            _registered_method=True,
+        )
+        self.Commit = channel.unary_unary(
+            "/hermes.IndexService/Commit",
+            request_serializer=hermes__pb2.CommitRequest.SerializeToString,
+            response_deserializer=hermes__pb2.CommitResponse.FromString,
+            _registered_method=True,
+        )
+        self.ForceMerge = channel.unary_unary(
+            "/hermes.IndexService/ForceMerge",
+            request_serializer=hermes__pb2.ForceMergeRequest.SerializeToString,
+            response_deserializer=hermes__pb2.ForceMergeResponse.FromString,
+            _registered_method=True,
+        )
+        self.DeleteIndex = channel.unary_unary(
+            "/hermes.IndexService/DeleteIndex",
+            request_serializer=hermes__pb2.DeleteIndexRequest.SerializeToString,
+            response_deserializer=hermes__pb2.DeleteIndexResponse.FromString,
+            _registered_method=True,
+        )
+
+
+class IndexServiceServicer:
+    """Index service"""
+
+    def CreateIndex(self, request, context):
+        """Create a new index (supports both structured schema and SDL string)"""
+        context.set_code(grpc.StatusCode.UNIMPLEMENTED)
+        context.set_details("Method not implemented!")
+        raise NotImplementedError("Method not implemented!")
+
+    def IndexDocuments(self, request_iterator, context):
+        """Add documents to index (streaming)"""
+        context.set_code(grpc.StatusCode.UNIMPLEMENTED)
+        context.set_details("Method not implemented!")
+        raise NotImplementedError("Method not implemented!")
+
+    def BatchIndexDocuments(self, request, context):
+        """Add documents in batch"""
+        context.set_code(grpc.StatusCode.UNIMPLEMENTED)
+        context.set_details("Method not implemented!")
+        raise NotImplementedError("Method not implemented!")
+
+    def Commit(self, request, context):
+        """Commit pending changes"""
+        context.set_code(grpc.StatusCode.UNIMPLEMENTED)
+        context.set_details("Method not implemented!")
+        raise NotImplementedError("Method not implemented!")
+
+    def ForceMerge(self, request, context):
+        """Force merge segments"""
+        context.set_code(grpc.StatusCode.UNIMPLEMENTED)
+        context.set_details("Method not implemented!")
+        raise NotImplementedError("Method not implemented!")
+
+    def DeleteIndex(self, request, context):
+        """Delete an index"""
+        context.set_code(grpc.StatusCode.UNIMPLEMENTED)
+        context.set_details("Method not implemented!")
+        raise NotImplementedError("Method not implemented!")
+
+
+def add_IndexServiceServicer_to_server(servicer, server):
+    rpc_method_handlers = {
+        "CreateIndex": grpc.unary_unary_rpc_method_handler(
+            servicer.CreateIndex,
+            request_deserializer=hermes__pb2.CreateIndexRequest.FromString,
+            response_serializer=hermes__pb2.CreateIndexResponse.SerializeToString,
+        ),
+        "IndexDocuments": grpc.stream_unary_rpc_method_handler(
+            servicer.IndexDocuments,
+            request_deserializer=hermes__pb2.IndexDocumentRequest.FromString,
+            response_serializer=hermes__pb2.IndexDocumentsResponse.SerializeToString,
+        ),
+        "BatchIndexDocuments": grpc.unary_unary_rpc_method_handler(
+            servicer.BatchIndexDocuments,
+            request_deserializer=hermes__pb2.BatchIndexDocumentsRequest.FromString,
+            response_serializer=hermes__pb2.BatchIndexDocumentsResponse.SerializeToString,
+        ),
+        "Commit": grpc.unary_unary_rpc_method_handler(
+            servicer.Commit,
+            request_deserializer=hermes__pb2.CommitRequest.FromString,
+            response_serializer=hermes__pb2.CommitResponse.SerializeToString,
+        ),
+        "ForceMerge": grpc.unary_unary_rpc_method_handler(
+            servicer.ForceMerge,
+            request_deserializer=hermes__pb2.ForceMergeRequest.FromString,
+            response_serializer=hermes__pb2.ForceMergeResponse.SerializeToString,
+        ),
+        "DeleteIndex": grpc.unary_unary_rpc_method_handler(
+            servicer.DeleteIndex,
+            request_deserializer=hermes__pb2.DeleteIndexRequest.FromString,
+            response_serializer=hermes__pb2.DeleteIndexResponse.SerializeToString,
+        ),
+    }
+    generic_handler = grpc.method_handlers_generic_handler(
+        "hermes.IndexService", rpc_method_handlers
+    )
+    server.add_generic_rpc_handlers((generic_handler,))
+    server.add_registered_method_handlers("hermes.IndexService", rpc_method_handlers)
+
+
+# This class is part of an EXPERIMENTAL API.
+class IndexService:
+    """Index service"""
+
+    @staticmethod
+    def CreateIndex(
+        request,
+        target,
+        options=(),
+        channel_credentials=None,
+        call_credentials=None,
+        insecure=False,
+        compression=None,
+        wait_for_ready=None,
+        timeout=None,
+        metadata=None,
+    ):
+        return grpc.experimental.unary_unary(
+            request,
+            target,
+            "/hermes.IndexService/CreateIndex",
+            hermes__pb2.CreateIndexRequest.SerializeToString,
+            hermes__pb2.CreateIndexResponse.FromString,
+            options,
+            channel_credentials,
+            insecure,
+            call_credentials,
+            compression,
+            wait_for_ready,
+            timeout,
+            metadata,
+            _registered_method=True,
+        )
+
+    @staticmethod
+    def IndexDocuments(
+        request_iterator,
+        target,
+        options=(),
+        channel_credentials=None,
+        call_credentials=None,
+        insecure=False,
+        compression=None,
+        wait_for_ready=None,
+        timeout=None,
+        metadata=None,
+    ):
+        return grpc.experimental.stream_unary(
+            request_iterator,
+            target,
+            "/hermes.IndexService/IndexDocuments",
+            hermes__pb2.IndexDocumentRequest.SerializeToString,
+            hermes__pb2.IndexDocumentsResponse.FromString,
+            options,
+            channel_credentials,
+            insecure,
+            call_credentials,
+            compression,
+            wait_for_ready,
+            timeout,
+            metadata,
+            _registered_method=True,
+        )
+
+    @staticmethod
+    def BatchIndexDocuments(
+        request,
+        target,
+        options=(),
+        channel_credentials=None,
+        call_credentials=None,
+        insecure=False,
+        compression=None,
+        wait_for_ready=None,
+        timeout=None,
+        metadata=None,
+    ):
+        return grpc.experimental.unary_unary(
+            request,
+            target,
+            "/hermes.IndexService/BatchIndexDocuments",
+            hermes__pb2.BatchIndexDocumentsRequest.SerializeToString,
+            hermes__pb2.BatchIndexDocumentsResponse.FromString,
+            options,
+            channel_credentials,
+            insecure,
+            call_credentials,
+            compression,
+            wait_for_ready,
+            timeout,
+            metadata,
+            _registered_method=True,
+        )
+
+    @staticmethod
+    def Commit(
+        request,
+        target,
+        options=(),
+        channel_credentials=None,
+        call_credentials=None,
+        insecure=False,
+        compression=None,
+        wait_for_ready=None,
+        timeout=None,
+        metadata=None,
+    ):
+        return grpc.experimental.unary_unary(
+            request,
+            target,
+            "/hermes.IndexService/Commit",
+            hermes__pb2.CommitRequest.SerializeToString,
+            hermes__pb2.CommitResponse.FromString,
+            options,
+            channel_credentials,
+            insecure,
+            call_credentials,
+            compression,
+            wait_for_ready,
+            timeout,
+            metadata,
+            _registered_method=True,
+        )
+
+    @staticmethod
+    def ForceMerge(
+        request,
+        target,
+        options=(),
+        channel_credentials=None,
+        call_credentials=None,
+        insecure=False,
+        compression=None,
+        wait_for_ready=None,
+        timeout=None,
+        metadata=None,
+    ):
+        return grpc.experimental.unary_unary(
+            request,
+            target,
+            "/hermes.IndexService/ForceMerge",
+            hermes__pb2.ForceMergeRequest.SerializeToString,
+            hermes__pb2.ForceMergeResponse.FromString,
+            options,
+            channel_credentials,
+            insecure,
+            call_credentials,
+            compression,
+            wait_for_ready,
+            timeout,
+            metadata,
+            _registered_method=True,
+        )
+
+    @staticmethod
+    def DeleteIndex(
+        request,
+        target,
+        options=(),
+        channel_credentials=None,
+        call_credentials=None,
+        insecure=False,
+        compression=None,
+        wait_for_ready=None,
+        timeout=None,
+        metadata=None,
+    ):
+        return grpc.experimental.unary_unary(
+            request,
+            target,
+            "/hermes.IndexService/DeleteIndex",
+            hermes__pb2.DeleteIndexRequest.SerializeToString,
+            hermes__pb2.DeleteIndexResponse.FromString,
+            options,
+            channel_credentials,
+            insecure,
+            call_credentials,
+            compression,
+            wait_for_ready,
+            timeout,
+            metadata,
+            _registered_method=True,
+        )

hermes_client_python/types.py

@@ -0,0 +1,48 @@
+"""Type definitions for Hermes client."""
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class Document:
+    """A document with field values."""
+
+    fields: dict[str, Any] = field(default_factory=dict)
+
+    def __getitem__(self, key: str) -> Any:
+        return self.fields[key]
+
+    def __setitem__(self, key: str, value: Any) -> None:
+        self.fields[key] = value
+
+    def get(self, key: str, default: Any = None) -> Any:
+        return self.fields.get(key, default)
+
+
+@dataclass
+class SearchHit:
+    """A single search result."""
+
+    doc_id: int
+    score: float
+    fields: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class SearchResponse:
+    """Search response with hits and metadata."""
+
+    hits: list[SearchHit]
+    total_hits: int
+    took_ms: int
+
+
+@dataclass
+class IndexInfo:
+    """Information about an index."""
+
+    index_name: str
+    num_docs: int
+    num_segments: int
+    schema: str

hermes_client_python-1.0.4.dist-info/METADATA

@@ -0,0 +1,232 @@
+Metadata-Version: 2.4
+Name: hermes-client-python
+Version: 1.0.4
+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 Client
+
+Async Python client for [Hermes](https://github.com/SpaceFrontiers/hermes) search server.
+
+## Installation
+
+```bash
+pip install hermes-client-python
+```
+
+## Quick Start
+
+```python
+import asyncio
+from hermes_client_python import HermesClient
+
+async def main():
+    async with HermesClient("localhost:50051") as client:
+        # Create index with SDL schema
+        await client.create_index("articles", '''
+            index articles {
+                title: text indexed stored
+                body: text indexed stored
+                score: f64 stored
+            }
+        ''')
+
+        # Index documents
+        await client.index_documents("articles", [
+            {"title": "Hello World", "body": "First article", "score": 1.5},
+            {"title": "Goodbye World", "body": "Last article", "score": 2.0},
+        ])
+
+        # Commit changes
+        await client.commit("articles")
+
+        # Search
+        results = await client.search("articles", term=("title", "hello"), limit=10)
+        for hit in results.hits:
+            print(f"Doc {hit.doc_id}: score={hit.score}, fields={hit.fields}")
+
+        # Get document by ID
+        doc = await client.get_document("articles", 0)
+        print(doc.fields)
+
+        # Delete index
+        await client.delete_index("articles")
+
+asyncio.run(main())
+```
+
+## API Reference
+
+### HermesClient
+
+```python
+client = HermesClient(address="localhost:50051")
+```
+
+#### Connection
+
+```python
+# Using context manager (recommended)
+async with HermesClient("localhost:50051") as client:
+    ...
+
+# Manual connection
+client = HermesClient("localhost:50051")
+await client.connect()
+# ... use client ...
+await client.close()
+```
+
+#### Index Management
+
+```python
+# Create index with SDL schema
+await client.create_index("myindex", '''
+    index myindex {
+        title: text indexed stored
+        body: text indexed stored
+    }
+''')
+
+# Create index with JSON schema
+await client.create_index("myindex", '''
+{
+    "fields": [
+        {"name": "title", "type": "text", "indexed": true, "stored": true},
+        {"name": "body", "type": "text", "indexed": true, "stored": true}
+    ]
+}
+''')
+
+# Get index info
+info = await client.get_index_info("myindex")
+print(f"Documents: {info.num_docs}, Segments: {info.num_segments}")
+
+# Delete index
+await client.delete_index("myindex")
+```
+
+#### Document Indexing
+
+```python
+# Index multiple documents (batch)
+indexed, errors = await client.index_documents("myindex", [
+    {"title": "Doc 1", "body": "Content 1"},
+    {"title": "Doc 2", "body": "Content 2"},
+])
+
+# Index single document
+await client.index_document("myindex", {"title": "Doc", "body": "Content"})
+
+# Stream documents (for large datasets)
+async def doc_generator():
+    for i in range(10000):
+        yield {"title": f"Doc {i}", "body": f"Content {i}"}
+
+count = await client.index_documents_stream("myindex", doc_generator())
+
+# Commit changes (required to make documents searchable)
+num_docs = await client.commit("myindex")
+
+# Force merge segments (for optimization)
+num_segments = await client.force_merge("myindex")
+```
+
+#### Searching
+
+```python
+# Term query
+results = await client.search("myindex", term=("title", "hello"), limit=10)
+
+# Boolean query
+results = await client.search("myindex", boolean={
+    "must": [("title", "hello")],
+    "should": [("body", "world")],
+    "must_not": [("title", "spam")],
+})
+
+# With pagination
+results = await client.search("myindex", term=("title", "hello"), limit=10, offset=20)
+
+# With field loading
+results = await client.search(
+    "myindex",
+    term=("title", "hello"),
+    fields_to_load=["title", "body"]
+)
+
+# Access results
+for hit in results.hits:
+    print(f"Doc {hit.doc_id}: {hit.score}")
+    print(f"  Title: {hit.fields.get('title')}")
+
+print(f"Total hits: {results.total_hits}")
+print(f"Took: {results.took_ms}ms")
+```
+
+#### Document Retrieval
+
+```python
+# Get document by ID
+doc = await client.get_document("myindex", doc_id=42)
+if doc:
+    print(doc.fields["title"])
+```
+
+## Field Types
+
+| Type            | Python Type     | Description                           |
+| --------------- | --------------- | ------------------------------------- |
+| `text`          | `str`           | Full-text searchable string           |
+| `u64`           | `int` (>= 0)    | Unsigned 64-bit integer               |
+| `i64`           | `int`           | Signed 64-bit integer                 |
+| `f64`           | `float`         | 64-bit floating point                 |
+| `bytes`         | `bytes`         | Binary data                           |
+| `json`          | `dict` / `list` | JSON object (auto-serialized)         |
+| `dense_vector`  | `list[float]`   | Dense vector for semantic search      |
+| `sparse_vector` | `dict`          | Sparse vector with indices and values |
+
+## Error Handling
+
+```python
+import grpc
+
+try:
+    await client.search("nonexistent", term=("field", "value"))
+except grpc.RpcError as e:
+    if e.code() == grpc.StatusCode.NOT_FOUND:
+        print("Index not found")
+    else:
+        raise
+```
+
+## Development
+
+Generate protobuf stubs:
+
+```bash
+pip install grpcio-tools
+python generate_proto.py
+```
+
+## License
+
+MIT

hermes_client_python-1.0.4.dist-info/RECORD

@@ -0,0 +1,8 @@
+hermes_client_python/__init__.py,sha256=qUaFnTSVr4fSOXfRHJIu8ur5IJEChfIJPOqTC0MiIMw,282
+hermes_client_python/client.py,sha256=E12sJL7d7pih2kamiQXarvmdRESqN5WgKVVek1HF6xQ,12850
+hermes_client_python/hermes_pb2.py,sha256=6mPuThsTsivqjEBtT7Zi4G3z4X3x3RbIzTkJex_bYdo,10672
+hermes_client_python/hermes_pb2_grpc.py,sha256=Oehwc9-0IlluummU8rJJ-ftbEK9AK2ZOBJyj7MnymkQ,16863
+hermes_client_python/types.py,sha256=e6_amiC4F9AkOSzAB9woAfLf9gooN9Y-rzJShrR9YEo,954
+hermes_client_python-1.0.4.dist-info/METADATA,sha256=KLT944lRtT_grd1Yj1gVqfAMwJ6iOAafwgK1YxO_dnQ,6120
+hermes_client_python-1.0.4.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+hermes_client_python-1.0.4.dist-info/RECORD,,

hermes_client_python-1.0.4.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any