summa-client-python 2.0.0__py3-none-any.whl

summa_client_python/types.py

@@ -0,0 +1,305 @@
+"""Type definitions for Summa client.
+
+All search-related types mirror the proto API structure exactly.
+Query is a dict with exactly one key matching the proto Query oneof variant.
+"""
+
+from dataclasses import dataclass, field
+from typing import Any, Literal, Required, TypedDict
+
+# =============================================================================
+# Multi-value score combiner (mirrors proto MultiValueCombiner)
+# =============================================================================
+
+Combiner = Literal["log_sum_exp", "max", "avg", "sum", "weighted_top_k"]
+
+# =============================================================================
+# Query types (mirrors proto Query oneof)
+# =============================================================================
+
+
+class TermQuery(TypedDict, total=False):
+    field: Required[str]
+    term: Required[str]
+    tokenizer_hint: str
+
+
+class MatchQuery(TypedDict, total=False):
+    field: Required[str]
+    text: Required[str]
+    # Passed to the field's tokenizer; a dynamic stemmer reads it as a
+    # comma-separated language list ("ru,en"). Static tokenizers ignore it.
+    tokenizer_hint: str
+
+
+class PhraseQuery(TypedDict, total=False):
+    field: Required[str]
+    text: Required[str]
+    slop: int
+    tokenizer_hint: str
+
+
+class BooleanQuery(TypedDict, total=False):
+    must: list["Query"]
+    should: list["Query"]
+    must_not: list["Query"]
+
+
+class BoostQuery(TypedDict):
+    query: "Query"
+    boost: float
+
+
+class AllQuery(TypedDict):
+    pass
+
+
+class SparseVectorQuery(TypedDict, total=False):
+    field: str  # required but total=False for optional fields
+    indices: list[int]
+    values: list[float]
+    text: str
+    combiner: Combiner
+    heap_factor: float
+    lsp_gamma: int
+    combiner_temperature: float
+    combiner_top_k: int
+    combiner_decay: float
+    weight_threshold: float
+    max_query_dims: int
+    pruning: float
+    seismic_cut: int
+    seismic_factor: float
+    exhaustive: bool
+
+
+class DenseVectorQuery(TypedDict, total=False):
+    field: str  # required but total=False for optional fields
+    vector: list[float]
+    nprobe: int
+    combiner: Combiner
+    combiner_temperature: float
+    combiner_top_k: int
+    combiner_decay: float
+
+
+class BinaryDenseVectorQuery(TypedDict, total=False):
+    field: str  # required but total=False for optional fields
+    vector: bytes  # packed-bit query vector (ceil(dim/8) bytes)
+    combiner: Combiner
+    combiner_temperature: float
+    combiner_top_k: int
+    combiner_decay: float
+
+
+class RangeQuery(TypedDict, total=False):
+    field: str  # required but total=False for optional fields
+    min_u64: int
+    max_u64: int
+    min_i64: int
+    max_i64: int
+    min_f64: float
+    max_f64: float
+
+
+# Query is a dict with exactly one key matching a protobuf Query variant,
+# including text, Boolean, vector, range/prefix, all, and fusion queries.
+Query = dict[str, Any]
+
+# =============================================================================
+# Reranker (mirrors proto Reranker)
+# =============================================================================
+
+
+class Reranker(TypedDict, total=False):
+    field: str
+    vector: list[float]
+    combiner: Combiner
+    combiner_temperature: float
+    combiner_top_k: int
+    combiner_decay: float
+    matryoshka_dims: int
+    binary_vector: bytes  # packed-bit query vector (for binary dense fields)
+    rrf_k: float  # Reciprocal Rank Fusion k (0 = disabled, typical: 60)
+
+
+# =============================================================================
+# Response types
+# =============================================================================
+
+
+@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 DocAddress:
+    """Unique document address: segment + local doc_id."""
+
+    segment_id: str
+    doc_id: int
+
+
+@dataclass
+class OrdinalScore:
+    """Score contribution from a specific ordinal in a multi-valued field."""
+
+    ordinal: int
+    score: float
+
+
+@dataclass
+class PassageScores:
+    ordinal: int
+    scores: dict[str, float]
+    l1_score: float | None = None
+
+
+@dataclass
+class CandidateScores:
+    document: dict[str, float]
+    passages: list[PassageScores]
+    scored_passages: int
+
+
+@dataclass
+class RrfContribution:
+    query_index: int
+    query_name: str
+    rank: int
+    score: float
+    ordinal: int | None = None
+
+
+@dataclass
+class SearchHit:
+    """A single search result."""
+
+    address: DocAddress
+    score: float
+    fields: dict[str, Any] = field(default_factory=dict)
+    ordinal_scores: list[OrdinalScore] = field(default_factory=list)
+    candidate_scores: CandidateScores | None = None
+    rrf_score: float | None = None
+    rrf_contributions: list[RrfContribution] = field(default_factory=list)
+
+
+@dataclass
+class SearchTimings:
+    """Detailed timing breakdown for search phases (all values in microseconds)."""
+
+    search_us: int
+    rerank_us: int
+    load_us: int
+    total_us: int
+    candidate_scoring_us: int = 0
+
+
+@dataclass
+class FusionCandidate:
+    address: DocAddress
+    score: float
+    ordinal_scores: list[OrdinalScore] = field(default_factory=list)
+
+
+@dataclass
+class FusionCandidateList:
+    query_index: int
+    candidates: list[FusionCandidate] = field(default_factory=list)
+
+
+@dataclass
+class QueryTrace:
+    query_index: int
+    query_name: str
+    query: dict[str, Any]
+    scope: int
+    score_only: bool
+    candidate_depth: int
+    total_seen: int
+    candidates: list[FusionCandidate] = field(default_factory=list)
+
+
+@dataclass
+class ShardSearchTrace:
+    shard_id: str
+    backend_id: str
+    index_name: str
+    queries: list[QueryTrace]
+    selected: list[FusionCandidate]
+    ranking_method: str
+    truncated: bool
+    filters: list[dict[str, Any]] = field(default_factory=list)
+
+
+@dataclass
+class SearchTrace:
+    shards: list[ShardSearchTrace] = field(default_factory=list)
+
+
+@dataclass
+class SearchResponse:
+    """Search response with hits and metadata."""
+
+    hits: list[SearchHit]
+    total_hits: int
+    took_ms: int
+    timings: SearchTimings | None = None
+    ranking_method: str = ""
+    seeded_document_passages: bool = False
+    truncated: bool = False
+    fusion_candidates: list[FusionCandidateList] = field(default_factory=list)
+    trace: SearchTrace | None = None
+
+
+@dataclass
+class VectorFieldStats:
+    """Per-field vector statistics."""
+
+    field_name: str
+    vector_type: str  # "dense" or "sparse"
+    total_vectors: int
+    dimension: int
+
+
+@dataclass
+class IndexInfo:
+    """Information about an index."""
+
+    index_name: str
+    num_docs: int
+    num_segments: int
+    schema: str
+    vector_stats: list[VectorFieldStats] = field(default_factory=list)
+    physical_num_docs: int = 0
+    num_deleted_docs: int = 0
+    deleted_ratio: float = 0.0
+    candidate_scoring_version: int = 0
+    unprepared_candidate_fields: list[str] = field(default_factory=list)
+
+
+class DocumentMutationError(TypedDict):
+    """Rejected operation at a zero-based position in the input batch."""
+
+    index: int
+    error: str
+
+
+@dataclass
+class DocumentMutationResult:
+    """Staged operations (not affected rows); commit publishes accepted work."""
+
+    accepted_count: int
+    errors: list[DocumentMutationError] = field(default_factory=list)

summa_client_python-2.0.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,8 @@
+summa_client_python/__init__.py,sha256=kfG49vFn87L6nIxeJ25QI2jum9cBhZ1pIVEtfHHFe-k,1561
+summa_client_python/client.py,sha256=YUjdGJMvfXmqGw_hNKW1wJnbNuWvqW6WqtBO_5ci6Mg,42956
+summa_client_python/summa_pb2.py,sha256=1ZScK1c7ewzeNe93DyaRq-nUqhyUtZlBrN0d3LUOk0M,30881
+summa_client_python/summa_pb2_grpc.py,sha256=DBvzr2NKYukpdQhF7rW58Xnd5zy9TfuanoGedy_9lEQ,28792
+summa_client_python/types.py,sha256=FPCDsWYl8usGM7IAXeQURSEl3GaRMgi4KJ794rN__gY,7588
+summa_client_python-2.0.0.dist-info/METADATA,sha256=Xp827Dg8mZOU5R49uwNn1kVQU9mEsNRmiWx5hTFmA0Y,6719
+summa_client_python-2.0.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+summa_client_python-2.0.0.dist-info/RECORD,,

summa_client_python-2.0.0.dist-info/WHEEL

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