research/LLM.md

research — Go SDK for /v1/research

The ONE way a Go service records and queries R&D evidence on the unified /v1/research surface (HIP-0512). Stdlib-only (net/http + encoding/json), zero external modules, so any service — cloud, tools, marketing/growth, ops — imports it without dragging a dependency graph.

Mirrors the Python producer (hanzo/python-sdk/pkg/hanzo-research) verb-for-verb. Records are semantically identical across languages: the server keys each experiment on (project, id = kind:subject:task), so every language upserts the same row regardless of JSON serialization (Go emits compact bytes; Python/C++ emit spaced — immaterial to the store).

Surface

c := research.New(research.Config{Project: "enso-bench"})       // per-org key auth

exp, _ := c.Experiment(kind, subject, task, opts...)            // handle; posts in-flight
exp.Record(item, model, research.Result{...})                  // one attempt, idempotent
exp.Log(text)                                                  // append running narrative (chainable)
exp.Conclude(research.Proven, because, value)                  // verdict + seal complete
exp.Finish(value)                                              // seal; hypothesis w/o verdict -> Inconclusive
exp.Snapshot(pngBytes) / exp.Report(bytes)                     // diary artifacts (server hashes)

c.Query(project, kind) / c.Totals(project)                     // reads
c.Grant(research.GrantRequest{...})                            // visibility/consent (private by default)

Options (functional, single-word): Metric, Total (n_total), Note (one-shot), Hypothesis, Predict. Verdict is a defined type — Proven | Refuted | Inconclusive; an out-of-set value is rejected at Conclude.

Open kinds — the whole company, not just eng

kind is an OPEN string, never an enum. benchmark, kernel-perf, training, ablation, policy-eval AND marketing-experiment, ad-test, creative-test, growth-experiment, pricing-test, … A marketing A/B records identically to a kernel A/B: state a Hypothesis, Record the arms, Conclude proven/refuted. A refutation is a first-class, durable result.

Zero-config provenance

The caller supplies none. On Experiment and every seal the SDK captures: git sha/branch/dirty (git subprocess, 5s-bounded), the commit narrative since this experiment's last recorded run, Go toolchain + module versions (debug.ReadBuildInfo), the host, and the calling code site (runtime.Callers). Serialized into meta in the exact key order shared with Python/TS: doc, commits, note, host, hypothesis, predict, verdict, because, log.

Cross-language identity — semantic, not byte

Records are keyed by the server on (project, id = kind:subject:task) (experiments) and (project, benchmark, item, model) (attempts), so every language upserts the same row regardless of serialization — that is the identity guarantee, not byte-matching. encode marshals compact with SetEscapeHTML(false) so & < > travel literally rather than as escaped sequences; research_test.go proves Go's canonical meta is the SAME JSON document as CPython json.dumps(meta, sort_keys=True). Whitespace and numeric shortest-form (0 vs 0.0) differ on the wire but are JSON-insignificant — the server parses and dedupes by stable id, so records from every language interleave into one row cleanly.

Auth

Only the per-org key (Authorization: Bearer), from Config.Key or $HANZO_API_KEY (KMS-sourced through the environment, never hardcoded). The gateway mints the validated principal + project scope; the client never sends X-User-Id/X-Org-Id. Base defaults to api.hanzo.ai, no /api/ prefix.

Build

Standalone module. GOWORK=off go test ./... (not in the parent go.work).