Add bindings-backed Go SDK implementation

AGENTS.md

@@ -20,6 +20,7 @@ examples/
   javascript/      — Standalone TS usage examples
   javascript-web/  — Browser/Vite examples (no Node runtime)
   c/               — C binding examples
+  go/              — Standalone Go SDK usage examples
   bun/             — Bun runtime example
   python-classification/ — Text classification with Moss
   voice-agents/    - End-to-end voice agents (LiveKit-based)
@@ -149,6 +150,7 @@ asks for an experimental landing spot.
 | `javascript/` | TypeScript (Node) | `comprehensive_sample.ts`, `cached_load_sample.ts`, `custom_authenticator_sample.ts` |
 | `javascript-web/` | TypeScript (browser/Vite) | `comprehensive_sample.ts`, `metadata_filtering_sample.ts` |
 | `c/` | C | `example_usage.c`, `metadata_filtering.c`, `session_usage.c` |
+| `go/` | Go | `basic/main.go`, `custom-embeddings/main.go` |
 | `bun/` | Bun | Bun-native runtime example |
 | `python-classification/` | Python | `classify_sample.py` — zero-shot text classification via Moss |
 | `voice-agents/airline-pnr/` | Python (LiveKit) | Ambient retrieval: every user turn auto-queries a per-PNR Moss index before the LLM speaks |

README.md

@@ -137,6 +137,7 @@ examples/
 │   └── custom_embedding_sample.ts
 ├── javascript-web/          # Browser / WASM SDK samples
 ├── c/                       # C SDK samples (libmoss)
+├── go/                      # Go SDK samples
 ├── voice-agents/            # End-to-end voice agents (ambient + multi-agent)
 │   ├── airline-pnr/         # Ambient retrieval; per-PNR Moss indexes, swap mid-call
 │   └── mortgage-lending/    # Multi-agent flow with shared session state

examples/go/README.md

@@ -0,0 +1,28 @@
+# Moss Go Examples
+
+Runnable examples for the Moss Go SDK.
+
+## Examples
+
+- [`basic/main.go`](./basic/main.go) creates an index, loads it, queries it, and deletes it.
+- [`custom-embeddings/main.go`](./custom-embeddings/main.go) uses caller-provided vectors for documents and queries.
+
+## Run
+
+Set your Moss credentials:
+
+```bash
+export MOSS_PROJECT_ID=...
+export MOSS_PROJECT_KEY=...
+```
+
+Runtime operations require the `libmoss` C SDK and the `libmoss` build tag:
+
+```bash
+export CGO_CFLAGS="-I<libmoss-sdk-root>/include"
+export CGO_LDFLAGS="-L<libmoss-sdk-root>/lib"
+export LD_LIBRARY_PATH="<libmoss-sdk-root>/lib"
+
+go run -tags libmoss ./basic
+go run -tags libmoss ./custom-embeddings
+```

examples/go/basic/main.go

@@ -0,0 +1,76 @@
+package main
+
+import (
+	"context"
+	"fmt"
+	"log"
+	"os"
+	"time"
+
+	"github.com/usemoss/moss/sdks/go/sdk"
+)
+
+func main() {
+	projectID := os.Getenv("MOSS_PROJECT_ID")
+	projectKey := os.Getenv("MOSS_PROJECT_KEY")
+	if projectID == "" || projectKey == "" {
+		log.Fatal("set MOSS_PROJECT_ID and MOSS_PROJECT_KEY")
+	}
+
+	ctx := context.Background()
+	client := moss.NewClient(projectID, projectKey)
+	defer func() {
+		if err := client.Close(); err != nil {
+			log.Printf("close warning: %v", err)
+		}
+	}()
+	indexName := fmt.Sprintf("go-basic-%d", time.Now().Unix())
+
+	docs := []moss.DocumentInfo{
+		{
+			ID:   "doc-1",
+			Text: "Refunds are processed within five to seven business days.",
+			Metadata: map[string]string{
+				"topic": "refunds",
+			},
+		},
+		{
+			ID:   "doc-2",
+			Text: "Orders can be tracked from the account dashboard.",
+			Metadata: map[string]string{
+				"topic": "shipping",
+			},
+		},
+	}
+
+	result, err := client.CreateIndex(ctx, indexName, docs, nil)
+	if err != nil {
+		log.Fatal(err)
+	}
+	fmt.Println("create job:", result.JobID)
+
+	if _, err := client.LoadIndex(ctx, indexName, &moss.LoadIndexOptions{}); err != nil {
+		log.Fatal(err)
+	}
+
+	search, err := client.Query(ctx, indexName, "how long do refunds take?", &moss.QueryOptions{
+		TopK: 3,
+	})
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	fmt.Println("query:", search.Query)
+	for _, doc := range search.Docs {
+		fmt.Printf("%s %.3f %s\n", doc.ID, doc.Score, doc.Text)
+	}
+
+	if err := cleanup(ctx, client, indexName); err != nil {
+		log.Printf("cleanup warning: %v", err)
+	}
+}
+
+func cleanup(ctx context.Context, client *moss.Client, indexName string) error {
+	_, err := client.DeleteIndex(ctx, indexName)
+	return err
+}

examples/go/custom-embeddings/main.go

@@ -0,0 +1,73 @@
+package main
+
+import (
+	"context"
+	"fmt"
+	"log"
+	"os"
+	"time"
+
+	"github.com/usemoss/moss/sdks/go/sdk"
+)
+
+func main() {
+	projectID := os.Getenv("MOSS_PROJECT_ID")
+	projectKey := os.Getenv("MOSS_PROJECT_KEY")
+	if projectID == "" || projectKey == "" {
+		log.Fatal("set MOSS_PROJECT_ID and MOSS_PROJECT_KEY")
+	}
+
+	ctx := context.Background()
+	client := moss.NewClient(projectID, projectKey)
+	defer func() {
+		if err := client.Close(); err != nil {
+			log.Printf("close warning: %v", err)
+		}
+	}()
+	indexName := fmt.Sprintf("go-custom-%d", time.Now().Unix())
+
+	docs := []moss.DocumentInfo{
+		{
+			ID:        "refunds",
+			Text:      "Refunds are processed within five business days.",
+			Embedding: []float32{1, 0, 0, 0},
+		},
+		{
+			ID:        "shipping",
+			Text:      "Track your order from the shipping dashboard.",
+			Embedding: []float32{0, 1, 0, 0},
+		},
+	}
+
+	result, err := client.CreateIndex(ctx, indexName, docs, nil)
+	if err != nil {
+		log.Fatal(err)
+	}
+	fmt.Println("create job:", result.JobID)
+
+	if _, err := client.LoadIndex(ctx, indexName, &moss.LoadIndexOptions{}); err != nil {
+		log.Fatal(err)
+	}
+
+	query := []float32{1, 0, 0, 0}
+	search, err := client.Query(ctx, indexName, "", &moss.QueryOptions{
+		Embedding: query,
+		TopK:      2,
+	})
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	for _, doc := range search.Docs {
+		fmt.Printf("%s %.3f %s\n", doc.ID, doc.Score, doc.Text)
+	}
+
+	if err := cleanup(ctx, client, indexName); err != nil {
+		log.Printf("cleanup warning: %v", err)
+	}
+}
+
+func cleanup(ctx context.Context, client *moss.Client, indexName string) error {
+	_, err := client.DeleteIndex(ctx, indexName)
+	return err
+}

examples/go/go.mod

@@ -0,0 +1,11 @@
+module github.com/usemoss/moss/examples/go
+
+go 1.22.2
+
+require github.com/usemoss/moss/sdks/go/sdk v0.0.0
+
+require github.com/usemoss/moss/sdks/go/bindings v0.0.0 // indirect
+
+replace github.com/usemoss/moss/sdks/go/sdk => ../../sdks/go/sdk
+
+replace github.com/usemoss/moss/sdks/go/bindings => ../../sdks/go/bindings

sdks/go/README.md

@@ -0,0 +1,20 @@
+# Moss Go SDK
+
+The Go work now has the same two-layer direction as the other Moss SDKs:
+
+- `sdks/go/sdk/` contains the public Go SDK
+- `sdks/go/bindings/` wraps the native `libmoss` runtime via CGO
+
+Current status:
+
+- bindings-backed manage operations for mutations and metadata reads
+- local `LoadIndex` / `UnloadIndex` / local `Query` via `libmoss`
+- examples under `examples/go/` and unit tests
+- env-gated integration test scaffold
+
+Important note:
+
+- all runtime operations require the `libmoss` C SDK plus `-tags libmoss`
+
+The public SDK module lives under [`sdks/go/sdk/`](./sdk/), and the native
+bindings module lives under [`sdks/go/bindings/`](./bindings/).

sdks/go/bindings/README.md

@@ -0,0 +1,41 @@
+# Moss Go Bindings
+
+This package wraps the native `libmoss` runtime for Go via CGO.
+
+It mirrors the role of the other language bindings packages in this repository:
+
+- native runtime access
+- local index loading
+- local query execution
+- cloud-backed manage operations exposed through the native client
+
+## Status
+
+The real bindings implementation is compiled only with the `libmoss` build tag.
+Without that tag, this package builds a stub that returns a clear
+`ErrBindingsUnavailable` error.
+
+## Local build workflow
+
+Download the matching `libmoss` C SDK release archive for your platform from:
+
+- <https://github.com/usemoss/moss/releases/tag/c-sdk-v0.9.0>
+
+For Linux `x86_64`, extract the archive somewhere local so you have:
+
+```text
+<sdk-root>/
+├── include/libmoss.h
+└── lib/libmoss.so
+```
+
+Then build with:
+
+```bash
+export CGO_CFLAGS="-I<sdk-root>/include"
+export CGO_LDFLAGS="-L<sdk-root>/lib"
+export LD_LIBRARY_PATH="<sdk-root>/lib"
+go test -tags libmoss ./...
+```
+
+The Go SDK module can then be built with the same flags and tag.

sdks/go/bindings/errors.go

@@ -0,0 +1,6 @@
+package mosscore
+
+import "errors"
+
+var ErrBindingsUnavailable = errors.New("mosscore: libmoss bindings are unavailable; build with -tags libmoss and configure the libmoss C SDK")
+var ErrClientClosed = errors.New("mosscore: client is closed")

sdks/go/bindings/go.mod

@@ -0,0 +1,3 @@
+module github.com/usemoss/moss/sdks/go/bindings
+
+go 1.22.2