summa-client-python 2.0.0__tar.gz

summa_client_python-2.0.0/.gitignore

@@ -0,0 +1,55 @@
+# Build artifacts
+target/
+/dist/
+
+# Local agent scratch and reproducible review/benchmark evidence
+/.context/
+
+# Data files (generated indexes, processed data)
+/data/
+*.zst
+dump.*
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+.windsurf/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Node.js
+node_modules/
+summa-web/dist/
+summa-web/dist-model-lab/
+summa-model-lab/dist/
+
+# Python
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+.venv/
+venv/
+*.egg-info/
+summa-python/target/
+
+# Rust
+*.rs.bk
+Cargo.lock.bak
+
+# WASM build output (regenerated on build)
+summa-wasm/pkg/
+
+# Maturin
+summa-python/target/
+
+# Environment
+.env
+.env.local
+
+# Local raw benchmark evidence; reports and hash manifests remain versioned
+/docs/benchmark-results/**/*.zip

summa_client_python-2.0.0/PKG-INFO

@@ -0,0 +1,193 @@
+Metadata-Version: 2.5
+Name: summa-client-python
+Version: 2.0.0
+Summary: Async Python client for Summa search server
+Project-URL: Homepage, https://github.com/SpaceFrontiers/summa
+Project-URL: Repository, https://github.com/SpaceFrontiers/summa
+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
+
+# Summa Python client
+
+Async Python client for the
+[Summa](https://github.com/SpaceFrontiers/summa) gRPC search server.
+
+## Installation
+
+```bash
+pip install summa-client-python
+```
+
+Python 3.10 or newer is required.
+
+## Quick start
+
+```python
+import asyncio
+
+from summa_client_python import SummaClient
+
+
+async def main():
+    async with SummaClient("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": "Summa 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/summa_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/summa_client_python/types.py) and the
+[wire contract](../summa-proto/summa.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/summa-server`. Regenerate bindings after
+[protocol changes](../summa-proto/README.md#regeneration-and-validation).

summa_client_python-2.0.0/README.md

@@ -0,0 +1,169 @@
+# Summa Python client
+
+Async Python client for the
+[Summa](https://github.com/SpaceFrontiers/summa) gRPC search server.
+
+## Installation
+
+```bash
+pip install summa-client-python
+```
+
+Python 3.10 or newer is required.
+
+## Quick start
+
+```python
+import asyncio
+
+from summa_client_python import SummaClient
+
+
+async def main():
+    async with SummaClient("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": "Summa 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/summa_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/summa_client_python/types.py) and the
+[wire contract](../summa-proto/summa.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/summa-server`. Regenerate bindings after
+[protocol changes](../summa-proto/README.md#regeneration-and-validation).

summa_client_python-2.0.0/pyproject.toml

@@ -0,0 +1,54 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "summa-client-python"
+version = "2.0.0"
+description = "Async Python client for Summa search server"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [
+    { name = "izihawa" }
+]
+keywords = ["search", "full-text-search", "grpc", "async"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Database :: Database Engines/Servers",
+    "Topic :: Text Processing :: Indexing",
+]
+dependencies = [
+    "grpcio>=1.76.0",
+    "protobuf>=6.33.4",
+]
+
+[project.urls]
+Homepage = "https://github.com/SpaceFrontiers/summa"
+Repository = "https://github.com/SpaceFrontiers/summa"
+
+[dependency-groups]
+dev = [
+    "grpcio-tools>=1.76.0",
+    "ruff==0.16.0",
+]
+
+test = [
+    "pytest>=8.0.0",
+    "pytest-asyncio>=0.24.0",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/summa_client_python"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "/src",
+]

summa_client_python-2.0.0/src/summa_client_python/__init__.py

@@ -0,0 +1,75 @@
+"""Async Python client for Summa search server."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+from .client import SummaClient
+from .types import (
+    AllQuery,
+    BinaryDenseVectorQuery,
+    BooleanQuery,
+    BoostQuery,
+    CandidateScores,
+    Combiner,
+    DenseVectorQuery,
+    DocAddress,
+    Document,
+    DocumentMutationError,
+    DocumentMutationResult,
+    FusionCandidate,
+    FusionCandidateList,
+    IndexInfo,
+    MatchQuery,
+    OrdinalScore,
+    PassageScores,
+    QueryTrace,
+    RangeQuery,
+    Reranker,
+    RrfContribution,
+    SearchHit,
+    SearchResponse,
+    SearchTimings,
+    SearchTrace,
+    ShardSearchTrace,
+    SparseVectorQuery,
+    TermQuery,
+    VectorFieldStats,
+)
+
+__all__ = [
+    "SummaClient",
+    "AllQuery",
+    "BinaryDenseVectorQuery",
+    "BooleanQuery",
+    "BoostQuery",
+    "Combiner",
+    "CandidateScores",
+    "FusionCandidate",
+    "FusionCandidateList",
+    "PassageScores",
+    "RrfContribution",
+    "QueryTrace",
+    "SearchTrace",
+    "ShardSearchTrace",
+    "DenseVectorQuery",
+    "DocAddress",
+    "Document",
+    "DocumentMutationResult",
+    "DocumentMutationError",
+    "IndexInfo",
+    "MatchQuery",
+    "OrdinalScore",
+    "RangeQuery",
+    "Reranker",
+    "SearchHit",
+    "SearchResponse",
+    "SearchTimings",
+    "SparseVectorQuery",
+    "TermQuery",
+    "VectorFieldStats",
+]
+
+try:
+    __version__ = version("summa-client-python")
+except PackageNotFoundError:
+    # Source-only imports (without an installed wheel/editable distribution).
+    __version__ = "0.0.0+unknown"