Go SDK

The official Go client for HX-SDP. Context-aware, zero dependencies beyond the standard library.

Status: Coming Soon

The Go SDK is under active development. This page documents the planned API surface. Star the repository to be notified on release.

Installation

go get github.com/tigantic/holonomix-go

Quick start

package main

import (
    "context"
    "fmt"
    "log"

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

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

    ctx := context.Background()

    // Store
    data := make([]float64, 4096)
    result, err := client.Put(ctx, "my-key", data, &holonomix.PutOptions{
        Metadata: map[string]interface{}{"source": "sensor"},
    })
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("Compressed %.1fx → %s\n", result.CompressionRatio, result.Verdict)

    // Retrieve
    info, err := client.Get(ctx, "my-key", nil)
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("%d cores, max rank %d\n", info.NCores, info.MaxRank)

    // Top-K search
    top, err := client.QueryTopK(ctx, "my-key", &holonomix.TopKOptions{K: 5})
    if err != nil {
        log.Fatal(err)
    }
    for _, r := range top.Results {
        fmt.Printf("  %s: %.4f\n", r.Key, r.Score)
    }
}

Constructor

func NewClient(baseURL string, apiKey string, opts ...ClientOption) *Client

// Options
func WithNamespace(ns string) ClientOption     // Default: "default"
func WithTimeout(d time.Duration) ClientOption // Default: 30s
func WithHTTPClient(c *http.Client) ClientOption

Methods

Put(ctx, key, data, opts) → (*PutResult, error)

type PutOptions struct {
    Metadata  map[string]interface{}
    Namespace string  // Override default
}

type PutResult struct {
    Key              string  `json:"key"`
    Namespace        string  `json:"namespace"`
    Version          int     `json:"version"`
    Compressed       bool    `json:"compressed"`
    Verdict          string  `json:"verdict"`
    CompressionRatio float64 `json:"compression_ratio"`
    OriginalBytes    int64   `json:"original_bytes"`
    StoredCoreBytes  int64   `json:"stored_core_bytes"`
    NCores           int     `json:"n_cores"`
}

Get(ctx, key, opts) → (*GetResult, error)

type GetOptions struct {
    Namespace string
    Version   *int
}

type GetResult struct {
    Key              string                 `json:"key"`
    Namespace        string                 `json:"namespace"`
    Version          int                    `json:"version"`
    OracleVerdict    string                 `json:"oracle_verdict"`
    CompressionRatio float64                `json:"compression_ratio"`
    NCores           int                    `json:"n_cores"`
    Ranks            []int                  `json:"ranks"`
    MaxRank          int                    `json:"max_rank"`
    TotalCoreBytes   int64                  `json:"total_core_bytes"`
    OriginalBytes    int64                  `json:"original_bytes"`
    Metadata         map[string]interface{} `json:"metadata"`
    Fingerprint      map[string]float64     `json:"fingerprint"`
    CreatedAt        float64                `json:"created_at"`
}

Query(ctx, keyA, keyB, opts) → (*QueryResult, error)

type QueryOptions struct {
    Metric    string  // "cosine" (default), "euclidean", "dot"
    Namespace string
}

type QueryResult struct {
    KeyA   string  `json:"key_a"`
    KeyB   string  `json:"key_b"`
    Metric string  `json:"metric"`
    Score  float64 `json:"score"`
}

QueryTopK(ctx, queryKey, opts) → (*TopKResult, error)

type TopKOptions struct {
    K         int
    Metric    string
    Namespace string
    Filters   map[string]interface{}
}

type TopKResult struct {
    QueryKey    string        `json:"query_key"`
    Metric      string        `json:"metric"`
    NCandidates int           `json:"n_candidates"`
    Results     []MatchResult `json:"results"`
}

type MatchResult struct {
    Key   string  `json:"key"`
    Score float64 `json:"score"`
}

QueryVector(ctx, data, opts) → (*TopKResult, error)

result, err := client.QueryVector(ctx, queryVec, &holonomix.TopKOptions{K: 5})

Search(ctx, filters, opts) → (*SearchResult, error)

type SearchResult struct {
    Namespace string                   `json:"namespace"`
    Results   []map[string]interface{} `json:"results"`
    Count     int                      `json:"count"`
}

Serve(ctx, key, opts) → (*ServeResult, error)

type ServeOptions struct {
    Namespace string
    Version   *int
}

type ServeResult struct {
    Key       string    `json:"key"`
    Namespace string    `json:"namespace"`
    Version   int       `json:"version"`
    Data      []float64 `json:"data"`
}

Error handling

result, err := client.Get(ctx, "nonexistent", nil)
if err != nil {
    var apiErr *holonomix.APIError
    if errors.As(err, &apiErr) {
        fmt.Printf("HTTP %d: %s\n", apiErr.StatusCode, apiErr.Detail)
    }
}