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

hermes_client_python-1.4.11.dist-info/METADATA

@@ -0,0 +1,232 @@
+Metadata-Version: 2.4
+Name: hermes-client-python
+Version: 1.4.11
+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.4.11.dist-info/RECORD

@@ -0,0 +1,8 @@
+hermes_client_python/__init__.py,sha256=qUaFnTSVr4fSOXfRHJIu8ur5IJEChfIJPOqTC0MiIMw,282
+hermes_client_python/client.py,sha256=wPkMQk43YgvGaFX8ZAWu6h5mxXKvyfGzXXFVGNcyurs,19009
+hermes_client_python/hermes_pb2.py,sha256=GryWk909ocMfKLqlueNQNtDoFmuwj7hvY5ibq4HJduc,10532
+hermes_client_python/hermes_pb2_grpc.py,sha256=aFn4mHdGUWnFBtfzHue9i-kATCNVlE1pjIeW9QXhXIA,17463
+hermes_client_python/types.py,sha256=e6_amiC4F9AkOSzAB9woAfLf9gooN9Y-rzJShrR9YEo,954
+hermes_client_python-1.4.11.dist-info/METADATA,sha256=5492c_z4BlBO9xBTjn6OJvmM9hNPdcSf52CayszuVhY,6121
+hermes_client_python-1.4.11.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+hermes_client_python-1.4.11.dist-info/RECORD,,

hermes_client_python-1.4.11.dist-info/WHEEL

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