Go SDK

The pod-os-go-client library connects to Pod-OS Gateways over AIP TCP, encodes/decodes messages, and covers Evolutionary Neural Memory Intents, validation, reconnection, and Socket Actor health checks.

Repository: github.com/PointOfData/pod-os-go-client

Install

go get github.com/PointOfData/pod-os-go-client

Connect

Dial the gateway load-balancer endpoint and set GatewayActorName to that gateway's FQN. Use a unique ClientName per connection; From must be ClientName@<dialed-gateway-FQN> (client.FromAddress()).

import (
    "context"
    "log"

    podos "github.com/PointOfData/pod-os-go-client"
    "github.com/PointOfData/pod-os-go-client/config"
    "github.com/PointOfData/pod-os-go-client/message"
    "github.com/google/uuid"
)

cfg := config.Config{
    Host:                 "gateway-nlb.example.com",
    Port:                 "62312",
    GatewayActorName:     "zeroth.customer.example.com",
    ClientName:           "my-app-" + uuid.NewString()[:8],
    EnableConcurrentMode: true,
}

client, err := podos.NewClient(context.Background(), cfg)
if err != nil {
    log.Fatal(err)
}
defer client.Close()

Send a message

msg := &message.Message{
    Envelope: message.Envelope{
        To:         "Foobar@zeroth.customer.example.com",
        From:       client.FromAddress(),
        Intent:     message.IntentType.GetEvent,
        ClientName: client.ClientName(),
        MessageId:  uuid.NewString(),
    },
    // Intent-specific NeuralMemory / Payload fields...
}

resp, err := client.SendMessage(context.Background(), msg)

See Add data and Query data for ENM Intent examples.

Reading links

GetEvent and GetEventsForTags put []message.Linked on Response.EventRecords[].Links. Strength is the returned or matched object toward its neighbor. StoreBatchLinks and LinkEvent still send message.LinkFields (StrengthA, StrengthB) on NeuralMemory.BatchLinks[].Link and NeuralMemory.Link. Field-by-field usage: Query data. Requires github.com/PointOfData/pod-os-go-client v0.12.2 or later (keeps both viewer rows on GetEvent and GetEventsForTags when ENM reuses one _link event id).

Message validation

Opt-in via PODOS_VALIDATE=1. Call msg.Validate() before encode; use message.ValidateRawMessage(raw) on wire bytes. Errors expose engineer text (errs.Error()) and LLM JSON (errs.LLMJson() with struct_path, wire_field, rule, fix, example_code).

export PODOS_VALIDATE=1

Knowledge prompts

Embedded docs for coding agents:

import "github.com/PointOfData/pod-os-go-client/knowledge"

names := knowledge.ListDocuments()
doc, err := knowledge.GetDocument("neural-memory")

Details: SDK Knowledge Prompts.

Socket Actor health

Enable concurrent mode, then:

podos.RespondToHealthChecks(client)

Probes use envelope-only StatusRequest (110) / Status (3). See the repository README for custom reply handlers and monitor-side probes.

Other API surface

Related

• SDKs and APIs — all language clients
• Testing with podos — live Intent verification
• Full reference: pod-os-go-client README