client

package
v0.5.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 26, 2026 License: MIT Imports: 11 Imported by: 0

Documentation

Overview

Package client is ladyM's Go SDK for the HTTP data-plane (`ladym serve --http`): one method per /api/* endpoint — the nine MCP-tool endpoints (remember/recall/record_event/search via recall code_only/consolidate/ stats/link/forget, plus login) and the management-console CRUD for memories and users — with database-level Basic auth (users table).

It is the first language client; other languages live alongside it under client/<lang>/ (e.g. client/python/); the wire contract is api/api.go and api/crud.go.

Usage: 

c := client.New("http://127.0.0.1:8080", client.WithAuth("alice", "s3cret"))
res, err := c.Remember(ctx, "the sky is blue", []string{"fact"}, "")

The client sets no default timeout — callers bound each call with their own context (the CLI wraps 30s/120s; see cli/remote.go). Non-2xx responses surface as *Error{StatusCode, Message} with Message taken from the server's {"error": ...} body; network failures are single-line actionable errors ("cannot reach ladym server at ...").

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Client 

type Client struct {
	// contains filtered or unexported fields
}

Client talks to one `ladym serve --http` data-plane.

func New 

func New(baseURL string, opts ...Option) *Client

New returns a Client for baseURL (e.g. "http://127.0.0.1:8080"; a trailing slash is stripped). No default timeout: callers bound calls via ctx.

func (*Client) Consolidate 

func (c *Client) Consolidate(ctx context.Context, workspace string) (*ConsolidateResult, error)

Consolidate runs one System2 consolidation cycle. It can take far longer than a plain read — callers should use a generous context deadline.

func (*Client) CreateUser 

func (c *Client) CreateUser(ctx context.Context, username, password, workspace string, admin bool) (*schema.User, error)

CreateUser creates one account (admin only). An empty password creates a passwordless user.

func (*Client) DeleteMemory 

func (c *Client) DeleteMemory(ctx context.Context, id string) error

DeleteMemory deletes one memory by id; a missing id is a 404 *Error.

func (*Client) DeleteUser 

func (c *Client) DeleteUser(ctx context.Context, username string) error

DeleteUser deletes one account (admin only; the server rejects deleting the calling account itself). A missing username is a 404 *Error.

func (*Client) Forget 

func (c *Client) Forget(ctx context.Context, id string) error

Forget deletes a memory by id (no-op when missing, MCP semantics; for 404-on-missing semantics use DeleteMemory). 

func (c *Client) Link(ctx context.Context, src, dst, relation string) (string, error)

Link creates an associative edge src -[relation]-> dst and returns the edge id. An empty relation defaults to "related_to" server-side.

func (*Client) ListMemories 

func (c *Client) ListMemories(ctx context.Context, f MemoryFilter) (*MemoryList, error)

ListMemories lists memories with workspace/layer/type filters.

func (*Client) ListUsers 

func (c *Client) ListUsers(ctx context.Context) ([]*schema.User, error)

ListUsers lists all accounts (admin only). The returned Users never carry a password hash.

func (*Client) Login 

func (c *Client) Login(ctx context.Context) (*schema.User, error)

Login verifies the client's own credentials against the users table and returns the account (username/workspace/admin; the password hash never leaves the server). No session is created — the data-plane is stateless.

func (*Client) Ping 

func (c *Client) Ping(ctx context.Context) error

Ping probes /healthz (exempt from auth); nil means the server and its store are reachable.

func (*Client) Recall 

func (c *Client) Recall(ctx context.Context, query string, opts RecallOptions) (*schema.RecallResponse, error)

Recall queries memories. The response decodes straight into schema.RecallResponse — the api package already mirrors its JSON shape.

func (*Client) RecordEvent 

func (c *Client) RecordEvent(ctx context.Context, agent, action, observation, outcome string, tags []string, workspace string) (*RecordEventResult, error)

RecordEvent writes an L1 episodic event.

func (*Client) Remember 

func (c *Client) Remember(ctx context.Context, content string, tags []string, workspace string) (*RememberResult, error)

Remember writes a semantic fact (server labels the source "http").

func (*Client) RememberWithSource 

func (c *Client) RememberWithSource(ctx context.Context, content, source string, tags []string, workspace string) (*RememberResult, error)

RememberWithSource is Remember with an explicit source label (the CLI passes "cli"; an empty source lets the server default to "http").

func (*Client) Stats 

func (c *Client) Stats(ctx context.Context, workspace string) (*schema.Stats, error)

Stats returns aggregate statistics (workspace-scoped when the server forces one on the authenticated user).

func (*Client) UpdateMemory 

func (c *Client) UpdateMemory(ctx context.Context, id string, patch MemoryPatch) error

UpdateMemory patches content/summary/tags of one memory. A content change re-embeds server-side.

func (*Client) UpdateUser 

func (c *Client) UpdateUser(ctx context.Context, username string, patch UserPatch) (*schema.User, error)

UpdateUser patches one account's password/workspace/admin (admin only).

type ConsolidateResult 

type ConsolidateResult struct {
	KeptEpisodes       int            `json:"kept_episodes"`
	PromotedToSemantic int            `json:"promoted_to_semantic"`
	Actions            map[string]int `json:"actions"`
}

ConsolidateResult is the /api/consolidate report.

type Error 

type Error struct {
	StatusCode int
	Message    string
}

Error is a non-2xx response from the server. Message is the server's {"error": ...} field, falling back to the trimmed body for non-JSON error pages (proxies etc.), always single-line.

func (*Error) Error 

func (e *Error) Error() string

type MemoryFilter 

type MemoryFilter struct {
	Workspace string
	Layer     string
	Type      string
	Limit     int
	Offset    int
}

MemoryFilter filters/paginates ListMemories. Zero Limit/Offset are omitted so the server defaults apply (limit 50, offset 0).

type MemoryList 

type MemoryList struct {
	Memories []*schema.Memory `json:"memories"`
	Total    int              `json:"total"`
}

MemoryList is one page of GET /api/memories. Total is the filtered count before pagination.

type MemoryPatch 

type MemoryPatch struct {
	Content *string  `json:"content,omitempty"`
	Summary *string  `json:"summary,omitempty"`
	Tags    []string `json:"tags,omitempty"`
}

MemoryPatch is a partial memory update; nil fields are left unchanged.

type Option 

type Option func(*Client)

Option customizes a Client.

func WithAuth 

func WithAuth(username, password string) Option

WithAuth sets the Basic-auth credentials. A username with an empty password is valid — it matches a passwordless server account. With no WithAuth at all, no Authorization header is sent (no-auth deployments).

func WithHTTPClient 

func WithHTTPClient(hc *http.Client) Option

WithHTTPClient swaps the underlying http.Client (proxies, TLS, tracing).

func WithTimeout 

func WithTimeout(d time.Duration) Option

WithTimeout sets http.Client.Timeout. Prefer a per-call context deadline; this is a blunt instrument for simple callers.

type RecallOptions 

type RecallOptions struct {
	Workspace string
	TopK      int
	CodeOnly  bool
}

RecallOptions tunes Recall. TopK 0 lets the server default (8); CodeOnly restricts to code items (the server maps it to SearchCode, so there is no separate SearchCode client method).

type RecordEventResult 

type RecordEventResult struct {
	ID    string `json:"id"`
	Layer string `json:"layer"`
	Type  string `json:"type"`
}

RecordEventResult is the /api/record_event response.

type RememberResult 

type RememberResult struct {
	ID     string `json:"id"`
	Hash   string `json:"hash"`
	Gated  string `json:"gated"`
	Reason string `json:"reason"`
}

RememberResult is the /api/remember response. On an attention-gate drop nothing is persisted: ID/Hash are empty, Gated is "dropped" and Reason explains why (see Dropped).

func (*RememberResult) Dropped 

func (r *RememberResult) Dropped() bool

Dropped reports whether the server's attention gate dropped the write.

type UserPatch 

type UserPatch struct {
	Password  *string `json:"password,omitempty"`
	Workspace *string `json:"workspace,omitempty"`
	Admin     *bool   `json:"admin,omitempty"`
}

UserPatch is a partial account update; nil fields are left unchanged. An explicitly empty Password makes the account passwordless.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.