Python Client¶

Release binding: v0.1.0-enterprise-ready · AMI ami-010806d4d3445660e · 2026-05-19

The Python client is shipped with the appliance and the customer packet; it is not yet published to a public package registry. TypeScript and Go clients are available on request until published.

The client speaks to the engine on the appliance's own loopback interface, so it is used on the appliance (operations, migration jobs, notebooks running on the instance). Remote applications call the gate at https://<host>:8443 over HTTPS with a tenant key; every gate route is plain JSON and needs no SDK. Loopback port values are listed in the Operations Guide.

Construction¶

import numpy as np
from holonomix import HolonomiX

hx = HolonomiX(url="http://127.0.0.1:8000", namespace="team-a", timeout=30.0)

Methods¶

Method	Purpose
`put(key, data, *, metadata=None, namespace=None)`	Ingest an array or bytes; arrays are serialized as `.npy`, bytes are base64-encoded
`get(key, *, namespace=None, version=None)`	Retrieve representation metadata; cores stay native
`query(key_a, key_b, *, metric="cosine", namespace=None)`	Core-native similarity between two stored keys
`query_top_k(query_key, *, k=10, metric="cosine", namespace=None, filters=None)`	Top-K most similar entries to a stored key
`query_vector(query_data, *, k=10, metric="cosine", namespace=None, filters=None)`	Top-K similarity search with an external query vector
`query_exact(query_data, *, k=10, metric="cosine", namespace=None, require_fp64=False, chunk_rows=None, corpus_name=None)`	Exact brute-force top-K with an ML-DSA-65 receipt
`verify_receipt(receipt, *, pinned_public_key_sha256=None, expected_corpus_sha256=None, expected_query_sha256=None)`	Verify an ML-DSA-65 receipt
`search(filters, *, namespace=None)`	Search by metadata filters
`serve(key, *, target="dense", namespace=None, version=None, device="cuda:0")`	Serve a materialized or GPU-resident form
`close()`	Close the transport; the client is also a context manager

Example: store, query, sign, verify¶

import numpy as np
from holonomix import HolonomiX

with HolonomiX(url="http://127.0.0.1:8000", namespace="team-a") as hx:
    vec = np.random.rand(768).astype(np.float32)

    result = hx.put("doc-001", vec, metadata={"source": "example"})
    print(result.verdict)

    hits = hx.query_vector(vec, k=5, metric="cosine")

    exact = hx.query_exact(vec, k=5)
    check = hx.verify_receipt(exact.receipt)
    print(check.verified)

put returns the stored version, the Oracle verdict, and the entry's compression_ratio. query_exact returns indices, scores, the receipt, and self_verified. verify_receipt returns verified, the algorithm, key and corpus digests, and the per-check breakdown.

Metric names are cosine, dot, and l2.