Skip to main content

Summa Python client

Async Python client for the Summa gRPC search server.

Installation

pip install summa-client-python

Python 3.10 or newer is required.

Quick start

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

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.

Delete and upsert documents

With a text primary key, delete by exact key or supply a complete replacement:

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 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.

Compact deleted rows

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 and the wire contract for options.

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 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:

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.

Metadata

Release files for summa-client-python 2.2.4

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for summa-client-python 2.2.4
File Size Uploaded Provenance Actions
summa_client_python-2.2.4.tar.gz 24.4 kB Without provenance Details for summa_client_python-2.2.4.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for summa-client-python 2.2.4
File Interpreter ABI Platform Actions
summa_client_python-2.2.4-py3-none-any.whl Python 3 none any Details for summa_client_python-2.2.4-py3-none-any.whl

Total release size: 50.3 kB

Release files / summa_client_python-2.2.4.tar.gz

Download URL summa_client_python-2.2.4.tar.gz
Size 24.4 kB
Tags Source
SHA-256 checksum
How to use checksums
00de9d4a21b43d416cbb8331aff0fceaab2adca0686bc4210d8b4db91e1bbc45
BLAKE2b-256 checksum
How to use checksums
e9a11a0ed6b36a7f2900c08d2b8921e06f6627bd70068bc4db0abd9a3ef90393
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.13.7 {"installer":{"name":"uv","version":"0.13.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / summa_client_python-2.2.4-py3-none-any.whl

Download URL summa_client_python-2.2.4-py3-none-any.whl
Size 25.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
7a7c782c0635093395f22d4103d05408539d7aae800f0f48fcc6d37d987a26d3
BLAKE2b-256 checksum
How to use checksums
d61e44c8e9bc64e94f1dda4d5f42565b74b651007d56e520903c9bbe98be2263
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.13.7 {"installer":{"name":"uv","version":"0.13.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Security for summa-client-python 2.2.4

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page