Python SDK

The official Python client for HX-SDP. Supports all five verbs, context-manager lifecycle, and NumPy-native data handling.

Installation

pip install holonomix

Quick start

import numpy as np
from holonomix import HolonomiX

with HolonomiX(url="https://gate.holonomx.com", api_key="hx_live_...") as hx:
    # Store
    result = hx.put("my-key", np.random.randn(4096), metadata={"source": "sensor"})
    print(f"Compressed {result.compression_ratio:.1f}x → {result.verdict}")

    # Retrieve
    info = hx.get("my-key")
    print(f"{info.n_cores} cores, ranks={info.ranks}")

    # Similarity search
    top = hx.query_top_k("my-key", k=5)
    for key, score in top.results:
        print(f"  {key}: {score:.4f}")

    # Reconstruct
    dense = hx.serve("my-key")
    print(dense.data.shape)

Constructor

HolonomiX(
    url: str = "http://localhost:8100",
    *,
    namespace: str = "default",
    timeout: float = 30.0,
    api_key: str | None = None,  # Falls back to HX_API_KEY env var
)

Parameter	Type	Default	Description
url	str	http://localhost:8100	Base URL of the HX-Gate or HX-Engine
namespace	str	default	Default namespace for all operations
timeout	float	30.0	HTTP request timeout in seconds
api_key	str | None	None	API key; if None, reads HX_API_KEY env var

---

Methods

put(key, data, *, metadata=None, namespace=None) → PutResult

Compress and store a NumPy array or raw bytes.

Parameter	Type	Required	Description
key	str	Yes	Unique key within the namespace
data	np.ndarray | bytes	Yes	Data to compress and store
metadata	dict | None	No	Arbitrary JSON metadata
namespace	str | None	No	Override default namespace

Returns: PutResult

Field	Type	Description
key	str	Stored key
namespace	str	Target namespace
version	int	Auto-incremented version
compressed	bool	Whether QTT compression was applied
verdict	str	Oracle assessment: exact, safe, weak, passthrough
compression_ratio	float	Original bytes ÷ stored bytes
original_bytes	int	Input data size
stored_core_bytes	int	TT-core bytes on disk
n_cores	int	Number of TT-cores

---

get(key, *, namespace=None, version=None) → GetResult

Retrieve metadata and compression fingerprint (no dense reconstruction).

Parameter	Type	Required	Description
key	str	Yes	Entry key
namespace	str | None	No	Override default namespace
version	int | None	No	Specific version (default: latest)

Returns: GetResult

Field	Type	Description
key	str	Entry key
namespace	str	Namespace
version	int	Version number
oracle_verdict	str	Oracle quality assessment
compression_ratio	float	Compression ratio
n_cores	int	Number of TT-cores
ranks	list[int]	Bond dimension per core
max_rank	int	Maximum bond dimension
total_core_bytes	int	Total TT-core bytes
original_bytes	int	Original data size
metadata	dict	User-attached metadata
fingerprint	dict	Error metrics (frobenius, max_abs, relative)
created_at	float	Unix timestamp

---

query(key_a, key_b, *, metric="cosine", namespace=None) → QueryResult

Compute pairwise similarity in the compressed domain.

Parameter	Type	Required	Description
key_a	str	Yes	First key
key_b	str	Yes	Second key
metric	str	No	cosine, euclidean, or dot
namespace	str | None	No	Override default namespace

Returns: QueryResult

Field	Type	Description
key_a	str	First key
key_b	str	Second key
metric	str	Metric used
score	float	Similarity score

---

query_top_k(query_key, *, k=10, metric="cosine", namespace=None, filters=None) → TopKResult

Find the K most similar entries to a stored key.

Parameter	Type	Required	Description
query_key	str	Yes	Reference key
k	int	No	Number of results (default: 10)
metric	str	No	cosine, euclidean, or dot
namespace	str | None	No	Override default namespace
filters	dict | None	No	Metadata filters to narrow candidates

Returns: TopKResult

Field	Type	Description
query_key	str	Reference key
metric	str	Metric used
n_candidates	int	Number of entries compared
results	list[tuple[str, float]]	Ranked (key, score) pairs

---

query_vector(query_data, *, k=10, metric="cosine", namespace=None, filters=None) → TopKResult

Find the K most similar entries to an external vector. The engine decomposes the vector via TT-SVD on arrival.

Parameter	Type	Required	Description
query_data	np.ndarray	Yes	Query vector
k	int	No	Number of results (default: 10)
metric	str	No	cosine, euclidean, or dot
namespace	str | None	No	Override default namespace
filters	dict | None	No	Metadata filters

Returns: TopKResult (same schema as query_top_k)

---

search(filters, *, namespace=None) → SearchResult

Search for keys matching metadata filters.

Parameter	Type	Required	Description
filters	dict	Yes	Metadata key-value filters (exact match)
namespace	str | None	No	Override default namespace

Returns: SearchResult

Field	Type	Description
namespace	str	Namespace searched
results	list[dict]	Matching entries with key and metadata
count	int	Total matches

---

serve(key, *, target="dense", namespace=None, version=None, device="cuda:0") → ServeResult | GPUServeResult

Reconstruct the stored data or load TT-cores to GPU VRAM.

Parameter	Type	Required	Description
key	str	Yes	Entry key
target	str	No	dense (CPU ndarray) or gpu (VRAM cores)
namespace	str | None	No	Override default namespace
version	int | None	No	Specific version
device	str	No	GPU device for target=gpu

Returns: ServeResult when target="dense", GPUServeResult when target="gpu"

ServeResult fields: key, namespace, version, data (np.ndarray)

GPUServeResult fields: key, namespace, version, device, n_cores, gpu_core_bytes

---

close() → None

Close the HTTP transport. Called automatically when using the context manager.

Context manager

with HolonomiX(...) as hx:
    hx.put(...)
# Transport closed automatically

Error handling

All methods raise HolonomiXError (or subclasses) on failure:

from holonomix import HolonomiXError

try:
    hx.get("nonexistent")
except HolonomiXError as e:
    print(e.status_code, e.detail)