Skip to content

Quickstart

Store vectors and run your first similarity search in under a minute.

1. Install

pip install holonomix

npm install @holonomix/sdk

go get github.com/tigantic/holonomix-go

2. Connect

from holonomix import HolonomiX

hx = HolonomiX(
    url="https://gate.holonomx.com",
    namespace="default",
)
# Set your API key via HX_API_KEY env var or pass api_key= kwarg

import { HolonomiXClient } from "@holonomix/sdk";

const hx = new HolonomiXClient({
  baseUrl: "https://gate.holonomx.com",
  apiKey: "hx_live_...",
});

import "github.com/tigantic/holonomix-go"

client := holonomix.NewClient("https://gate.holonomx.com", "hx_live_...")

3. Store a vector

import numpy as np

embedding = np.random.randn(1536).astype(np.float32)

result = hx.put("doc-001", embedding, metadata={"source": "arxiv"})
print(f"Stored: {result.n_cores} cores, {result.compression_ratio:.0f}x compression")

const result = await hx.putBytes({
  namespace: "default",
  key: "doc-001",
  data_b64: btoa(String.fromCharCode(...new Uint8Array(vectorBuffer))),
  metadata: { source: "arxiv" },
});
console.log(`Stored: ${result.n_cores} cores, ${result.compression_ratio}x`);

result, err := client.PutBytes(ctx, &holonomix.PutBytesRequest{
    Namespace: "default",
    Key:       "doc-001",
    DataB64:   base64.StdEncoding.EncodeToString(vectorBytes),
    Metadata:  map[string]interface{}{"source": "arxiv"},
})
fmt.Printf("Stored: %d cores, %.0fx compression\n", result.NCores, result.CompressionRatio)

top_k = hx.query_top_k("doc-001", k=10, metric="cosine")
for key, score in top_k.results:
    print(f"  {key}: {score:.4f}")

const { results } = await hx.queryTopK({
  query_key: "doc-001",
  k: 10,
});
results.forEach(([key, score]) => console.log(`  ${key}: ${score.toFixed(4)}`));

topK, err := client.QueryTopK(ctx, &holonomix.QueryTopKRequest{
    QueryKey: "doc-001",
    K:        10,
})
for _, r := range topK.Results {
    fmt.Printf("  %s: %.4f\n", r.Key, r.Score)
}

5. Retrieve

info = hx.get("doc-001")
print(f"Verdict: {info.oracle_verdict}, Ranks: {info.ranks}")

# Reconstruct the dense vector
dense = hx.serve("doc-001")
print(f"Shape: {dense.data.shape}")

const info = await hx.get("default", "doc-001");
console.log(`Verdict: ${info.oracle_verdict}, Ranks: ${info.ranks}`);

const dense = await hx.serve("default", "doc-001");

info, _ := client.Get(ctx, "default", "doc-001")
fmt.Printf("Verdict: %s, Ranks: %v\n", info.OracleVerdict, info.Ranks)

dense, _ := client.Serve(ctx, "default", "doc-001")

Next steps