athyr

package
v0.1.0 Latest Latest
Warning

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

 Go to latest Published: Jan 10, 2026 License: MIT Imports: 20 Imported by: 0

Documentation

Overview

Package athyr provides a Go SDK for building agents on the Athyr platform. Agents use this package to connect, communicate, and access platform services.

Index

Constants

This section is empty.

Variables

View Source 
var (
	ErrNotConnected     = errors.New("agent not connected")
	ErrAlreadyConnected = errors.New("agent already connected")
)

Sentinel errors for agent operations.

View Source 
var (
	ErrNotFound         = &AthyrError{Code: ErrCodeNotFound}
	ErrUnavailable      = &AthyrError{Code: ErrCodeUnavailable}
	ErrInvalidArgument  = &AthyrError{Code: ErrCodeInvalidArgument}
	ErrInternal         = &AthyrError{Code: ErrCodeInternal}
	ErrUnauthenticated  = &AthyrError{Code: ErrCodeUnauthenticated}
	ErrPermissionDenied = &AthyrError{Code: ErrCodePermissionDenied}
	ErrAlreadyExists    = &AthyrError{Code: ErrCodeAlreadyExists}
	ErrDeadlineExceeded = &AthyrError{Code: ErrCodeDeadlineExceeded}
)

Sentinel errors for use with errors.Is.

Functions

func BadRequest 

func BadRequest(format string, args ...any) error

BadRequest creates a client error (invalid input).

func Internal 

func Internal(format string, args ...any) error

Internal creates a server error.

func IsAlreadyExists 

func IsAlreadyExists(err error) bool

IsAlreadyExists reports whether the error indicates a resource already exists.

func IsBadRequest 

func IsBadRequest(err error) bool

IsBadRequest reports whether the error indicates an invalid argument.

func IsDeadlineExceeded 

func IsDeadlineExceeded(err error) bool

IsDeadlineExceeded reports whether the error indicates a timeout.

func IsInternal 

func IsInternal(err error) bool

IsInternal reports whether the error indicates an internal server error.

func IsNotFound 

func IsNotFound(err error) bool

IsNotFound reports whether the error indicates a not found condition.

func IsPermissionDenied 

func IsPermissionDenied(err error) bool

IsPermissionDenied reports whether the error indicates insufficient permissions.

func IsUnauthenticated 

func IsUnauthenticated(err error) bool

IsUnauthenticated reports whether the error indicates missing authentication.

func IsUnavailable 

func IsUnavailable(err error) bool

IsUnavailable reports whether the error indicates the service is unavailable.

func NotFound 

func NotFound(format string, args ...any) error

NotFound creates a not found error.

func Run 

func Run[Req, Resp any](ctx context.Context, addr, subject string, handler Handler[Req, Resp], opts ...ServiceOption) error

Run is a convenience function to run a single service.

func RunRaw 

func RunRaw(ctx context.Context, addr, subject string, handler RawHandler, opts ...ServiceOption) error

RunRaw runs a single raw service.

func Unavailable 

func Unavailable(format string, args ...any) error

Unavailable creates a temporary failure error (retry later).

Types

type Agent 

type Agent interface {
	// Lifecycle
	Connect(ctx context.Context) error
	Close() error
	AgentID() string
	Connected() bool
	State() ConnectionState

	// Messaging
	Publish(ctx context.Context, subject string, data []byte) error
	Subscribe(ctx context.Context, subject string, handler MessageHandler) (Subscription, error)
	QueueSubscribe(ctx context.Context, subject, queue string, handler MessageHandler) (Subscription, error)
	Request(ctx context.Context, subject string, data []byte) ([]byte, error)

	// LLM
	Complete(ctx context.Context, req CompletionRequest) (*CompletionResponse, error)
	CompleteStream(ctx context.Context, req CompletionRequest, handler StreamHandler) error
	Models(ctx context.Context) ([]Model, error)

	// Memory
	CreateSession(ctx context.Context, profile SessionProfile, systemPrompt string) (*Session, error)
	GetSession(ctx context.Context, sessionID string) (*Session, error)
	DeleteSession(ctx context.Context, sessionID string) error
	AddHint(ctx context.Context, sessionID, hint string) error

	// KV
	KV(bucket string) KVBucket
}

Agent provides access to the Athyr platform.

func MustConnect 

func MustConnect(addr string, opts ...AgentOption) Agent

MustConnect creates and connects an agent, panicking on error. Use this for initialization code where connection failure is unrecoverable.

Example: 

agent := athyr.MustConnect("localhost:9090",
    athyr.WithAgentCard(athyr.AgentCard{Name: "my-agent"}),
)
defer agent.Close()

func NewAgent 

func NewAgent(addr string, opts ...AgentOption) (Agent, error)

NewAgent creates a new Athyr agent.

type AgentCard 

type AgentCard struct {
	Name         string            // Display name
	Description  string            // Purpose and functionality
	Version      string            // Agent software version
	Capabilities []string          // List of capability names
	Metadata     map[string]string // Extensible key-value pairs
}

AgentCard describes an agent's identity and capabilities.

type AgentOption 

type AgentOption func(*agentOptions)

AgentOption configures a Agent.

func WithAgentCard 

func WithAgentCard(card AgentCard) AgentOption

WithAgentCard sets the agent card for registration.

func WithAutoReconnect 

func WithAutoReconnect(maxRetries int, baseBackoff time.Duration) AgentOption

WithAutoReconnect enables automatic reconnection on connection loss. maxRetries specifies the maximum number of reconnection attempts (0 = infinite). baseBackoff specifies the initial backoff duration between attempts. Backoff increases exponentially with jitter, capped at maxBackoff (default: 30s).

Example: 

agent, _ := athyr.NewAgent("athyr.example.com:9090",
    athyr.WithAutoReconnect(10, time.Second), // 10 retries, 1s base backoff
)

func WithCapabilities 

func WithCapabilities(caps ...string) AgentOption

WithCapabilities sets the agent's capabilities. Capabilities describe what the agent can do (e.g., "chat", "analysis").

func WithConnectionCallback 

func WithConnectionCallback(cb ConnectionCallback) AgentOption

WithConnectionCallback sets a callback invoked when connection state changes. The callback receives the new state and any associated error. Use this to monitor connection health and react to disconnections.

Example: 

agent, _ := athyr.NewAgent("athyr.example.com:9090",
    athyr.WithConnectionCallback(func(state athyr.ConnectionState, err error) {
        if state == athyr.StateReconnecting {
            log.Println("Connection lost, reconnecting...")
        }
    }),
)

func WithHeartbeatInterval 

func WithHeartbeatInterval(d time.Duration) AgentOption

WithHeartbeatInterval sets how often heartbeats are sent.

func WithInsecure 

func WithInsecure() AgentOption

WithInsecure disables TLS for development and testing. WARNING: Do not use in production. Traffic will be unencrypted.

Example: 

agent, _ := athyr.NewAgent("localhost:9090",
    athyr.WithInsecure(),
)

func WithLogger 

func WithLogger(logger Logger) AgentOption

WithLogger sets a logger for observability. The logger interface is compatible with slog.Logger, zap.SugaredLogger, and similar. By default, no logging is performed.

Example with slog: 

agent, _ := athyr.NewAgent("localhost:9090",
    athyr.WithLogger(slog.Default()),
)

func WithMaxBackoff 

func WithMaxBackoff(d time.Duration) AgentOption

WithMaxBackoff sets the maximum backoff duration for reconnection attempts. Default is 30 seconds.

Example: 

agent, _ := athyr.NewAgent("athyr.example.com:9090",
    athyr.WithAutoReconnect(0, time.Second),
    athyr.WithMaxBackoff(time.Minute),
)

func WithRequestTimeout 

func WithRequestTimeout(d time.Duration) AgentOption

WithRequestTimeout sets the default timeout for requests.

func WithSystemTLS 

func WithSystemTLS() AgentOption

WithSystemTLS configures TLS using the system certificate pool. Use this for production when connecting to servers with publicly trusted certificates.

Example: 

agent, _ := athyr.NewAgent("athyr.example.com:9090",
    athyr.WithSystemTLS(),
)

func WithTLS 

func WithTLS(certFile string) AgentOption

WithTLS configures TLS using a CA certificate file. The cert file should be a PEM-encoded CA certificate. If certFile is empty, the system certificate pool is used.

Example: 

agent, _ := athyr.NewAgent("athyr.example.com:9090",
    athyr.WithTLS("/etc/ssl/certs/athyr-ca.pem"),
)

func WithTLSConfig 

func WithTLSConfig(cfg *tls.Config) AgentOption

WithTLSConfig configures TLS with a custom tls.Config. Use this for advanced scenarios like mutual TLS or custom verification.

Example: 

agent, _ := athyr.NewAgent("athyr.example.com:9090",
    athyr.WithTLSConfig(&tls.Config{
        MinVersion: tls.VersionTLS13,
    }),
)

type AthyrError 

type AthyrError struct {
	Code    ErrorCode // Error category
	Message string    // Human-readable message
	Op      string    // Operation that failed (e.g., "Complete", "KV.Get")
	Cause   error     // Underlying error (e.g., gRPC error)
}

AthyrError represents an error from SDK operations. It wraps underlying errors (typically gRPC errors) with additional context.

func (*AthyrError) Error 

func (e *AthyrError) Error() string

func (*AthyrError) Is 

func (e *AthyrError) Is(target error) bool

Is supports errors.Is by matching on error code.

func (*AthyrError) Unwrap 

func (e *AthyrError) Unwrap() error

Unwrap returns the underlying error for errors.Unwrap support.

type CompletionConfig 

type CompletionConfig struct {
	Temperature float64  // 0.0-1.0, higher = more random
	MaxTokens   int      // Maximum tokens to generate
	TopP        float64  // Nucleus sampling
	Stop        []string // Stop sequences
}

CompletionConfig holds optional parameters for completions.

type CompletionRequest 

type CompletionRequest struct {
	Model         string           // Required: model identifier
	Messages      []Message        // Conversation history
	Config        CompletionConfig // Optional parameters
	SessionID     string           // Optional: for memory injection
	IncludeMemory bool             // Whether to inject memory context
	Tools         []Tool           // Available tools the LLM can call
	ToolChoice    string           // "auto", "none", "required", or specific tool name
}

CompletionRequest is a request for LLM completion.

type CompletionResponse 

type CompletionResponse struct {
	Content      string
	Model        string
	Backend      string
	Usage        TokenUsage
	FinishReason string // "stop", "length", "tool_calls"
	Latency      time.Duration
	ToolCalls    []ToolCall // Tool calls requested by LLM
}

CompletionResponse is the result of an LLM completion.

type ConnectionCallback 

type ConnectionCallback func(state ConnectionState, err error)

ConnectionCallback is called when connection state changes. The error is non-nil when transitioning to StateDisconnected or StateReconnecting.

type ConnectionState 

type ConnectionState int

ConnectionState represents the agent's connection status. 

const (
	StateDisconnected ConnectionState = iota
	StateConnecting
	StateConnected
	StateReconnecting
)

func (ConnectionState) String 

func (s ConnectionState) String() string

type Context 

type Context interface {
	context.Context

	// Agent returns the underlying agent connection.
	Agent() Agent

	// Subject returns the subject this request arrived on.
	Subject() string

	// ReplySubject returns where to send the response (used internally).
	ReplySubject() string
}

Context is passed to service handlers, providing access to the agent and request metadata.

type ErrorCode 

type ErrorCode string

ErrorCode represents a category of error from SDK operations. 

const (
	ErrCodeNotFound         ErrorCode = "not_found"
	ErrCodeUnavailable      ErrorCode = "unavailable"
	ErrCodeInvalidArgument  ErrorCode = "invalid_argument"
	ErrCodeInternal         ErrorCode = "internal"
	ErrCodeUnauthenticated  ErrorCode = "unauthenticated"
	ErrCodePermissionDenied ErrorCode = "permission_denied"
	ErrCodeAlreadyExists    ErrorCode = "already_exists"
	ErrCodeDeadlineExceeded ErrorCode = "deadline_exceeded"
	ErrCodeUnknown          ErrorCode = "unknown"
)

type Handler 

type Handler[Req, Resp any] func(ctx Context, req Req) (Resp, error)

Handler is a typed request handler function. The SDK automatically handles JSON marshaling/unmarshaling.

type KVBucket 

type KVBucket interface {
	Get(ctx context.Context, key string) (*KVEntry, error)
	Put(ctx context.Context, key string, value []byte) (uint64, error)
	Delete(ctx context.Context, key string) error
	List(ctx context.Context, prefix string) ([]string, error)
}

KVBucket provides key-value operations on a specific bucket.

type KVEntry 

type KVEntry struct {
	Value    []byte
	Revision uint64
}

KVEntry represents a value retrieved from the KV store.

type Logger 

type Logger interface {
	Debug(msg string, args ...any)
	Info(msg string, args ...any)
	Warn(msg string, args ...any)
	Error(msg string, args ...any)
}

Logger defines a minimal logging interface compatible with slog.Logger. This allows plugging in any logging framework (slog, zap, zerolog, etc.).

Example with slog: 

agent, _ := athyr.NewAgent("localhost:9090",
    athyr.WithLogger(slog.Default()),
)

Example with zap: 

zapLogger, _ := zap.NewProduction()
agent, _ := athyr.NewAgent("localhost:9090",
    athyr.WithLogger(zapLogger.Sugar()),
)

type Message 

type Message struct {
	Role       string     // "system", "user", "assistant", "tool"
	Content    string     // Text content
	ToolCalls  []ToolCall // Tool calls made by assistant (role="assistant")
	ToolCallID string     // ID of the tool call this responds to (role="tool")
}

Message represents a chat message in LLM conversations.

type MessageHandler 

type MessageHandler func(msg SubscribeMessage)

MessageHandler processes incoming subscription messages.

type MetricsCallback 

type MetricsCallback func(subject string, duration time.Duration, err error)

MetricsCallback receives timing and error info for each request. Used with the Metrics middleware to collect observability data.

type Middleware 

type Middleware func(RawHandler) RawHandler

Middleware wraps a RawHandler to add cross-cutting concerns.

func Chain 

func Chain(mw ...Middleware) Middleware

Chain combines multiple middleware into one. Middleware are applied in order: first middleware is outermost.

func LogRequests 

func LogRequests(logger *log.Logger) Middleware

LogRequests returns middleware that logs requests and responses. It logs the subject, duration, and any errors.

func Metrics 

func Metrics(callback MetricsCallback) Middleware

Metrics returns middleware that tracks request metrics. The callback is invoked after each request with the subject, duration, and any error.

func RateLimit 

func RateLimit(maxConcurrent int) Middleware

RateLimit returns middleware that limits concurrent requests. Requests beyond the limit receive Unavailable error immediately.

func Recover 

func Recover(logger *log.Logger) Middleware

Recover returns middleware that recovers from panics. It converts panics to Internal errors and optionally logs them.

func Retry 

func Retry(maxAttempts int, backoff time.Duration) Middleware

Retry returns middleware that retries failed requests. Only retries if the error is retryable (Unavailable or temporary).

func Timeout 

func Timeout(d time.Duration) Middleware

Timeout returns middleware that enforces a request timeout. If the handler doesn't complete within the duration, it returns Unavailable.

func Validate 

func Validate(validator func(data []byte) error) Middleware

Validate returns middleware that validates requests before processing. If the validator returns an error, the request is rejected with BadRequest.

type Model 

type Model struct {
	ID        string
	Name      string
	Backend   string
	Available bool
}

Model represents an available LLM model.

type RawHandler 

type RawHandler func(ctx Context, data []byte) ([]byte, error)

RawHandler handles requests with raw bytes for full control.

type Server 

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

Server manages multiple services and their lifecycle.

func Handle 

func Handle[Req, Resp any](s *Server, subject string, handler Handler[Req, Resp], opts ...ServiceOption) *Server

Handle adds a typed handler for a subject. This is a convenience method that creates and adds a Service.

func NewServer 

func NewServer(addr string, opts ...ServerOption) *Server

NewServer creates a new server that will connect to the given address.

func (*Server) Add 

func (s *Server) Add(svc *Service) *Server

Add adds a pre-built service to the server.

func (*Server) HandleRaw 

func (s *Server) HandleRaw(subject string, handler RawHandler, opts ...ServiceOption) *Server

HandleRaw adds a raw handler for a subject.

func (*Server) Run 

func (s *Server) Run(ctx context.Context) error

Run starts the server and blocks until context is cancelled or signal received. It connects to Athyr, subscribes all services, and handles graceful shutdown.

type ServerOption 

type ServerOption func(*Server)

ServerOption configures a Server.

func WithAgentDescription 

func WithAgentDescription(desc string) ServerOption

WithAgentDescription sets the agent description.

func WithAgentName 

func WithAgentName(name string) ServerOption

WithAgentName sets the agent name for registration.

func WithMiddleware 

func WithMiddleware(mw ...Middleware) ServerOption

WithMiddleware adds global middleware applied to all services.

func WithServerInsecure 

func WithServerInsecure() ServerOption

WithServerInsecure disables TLS for development and testing.

func WithServerTLS 

func WithServerTLS(certFile string) ServerOption

WithServerTLS configures TLS using a CA certificate file.

func WithServerTLSConfig 

func WithServerTLSConfig(cfg *tls.Config) ServerOption

WithServerTLSConfig configures TLS with a custom tls.Config.

func WithVersion 

func WithVersion(version string) ServerOption

WithVersion sets the agent version.

type Service 

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

Service represents a single endpoint that an agent exposes.

func NewRawService 

func NewRawService(subject string, handler RawHandler, opts ...ServiceOption) *Service

NewRawService creates a service with a raw byte handler. Use this when you need full control over serialization.

func NewService 

func NewService[Req, Resp any](subject string, handler Handler[Req, Resp], opts ...ServiceOption) *Service

NewService creates a service with a typed handler. Request and response types are automatically JSON marshaled.

func (*Service) BuildHandler 

func (s *Service) BuildHandler(globalMiddleware []Middleware) RawHandler

BuildHandler applies middleware and returns the final handler.

type ServiceError 

type ServiceError struct {
	Code    string
	Message string
	Details any
}

ServiceError is a structured error with code and details.

func (*ServiceError) Error 

func (e *ServiceError) Error() string

type ServiceOption 

type ServiceOption func(*Service)

ServiceOption configures a Service.

func WithName 

func WithName(name string) ServiceOption

WithName sets a display name for the service.

func WithQueueGroup 

func WithQueueGroup(group string) ServiceOption

WithQueueGroup sets the queue group for load balancing. Multiple instances with the same queue group share the load.

func WithServiceMiddleware 

func WithServiceMiddleware(mw ...Middleware) ServiceOption

WithServiceMiddleware adds middleware to this specific service.

type Session 

type Session struct {
	ID           string
	AgentID      string
	SystemPrompt string // Agent personality/instructions
	Messages     []SessionMessage
	Summary      string
	Hints        []string
	Profile      SessionProfile
	CreatedAt    time.Time
	UpdatedAt    time.Time
}

Session represents a memory session.

type SessionMessage 

type SessionMessage struct {
	Role      string
	Content   string
	Timestamp time.Time
	Tokens    int
}

SessionMessage represents a message stored in session memory.

type SessionProfile 

type SessionProfile struct {
	Type                   string // "rolling_window"
	MaxTokens              int
	SummarizationThreshold int
}

SessionProfile configures memory session behavior.

func DefaultSessionProfile 

func DefaultSessionProfile() SessionProfile

DefaultSessionProfile returns sensible defaults.

type StreamChunk 

type StreamChunk struct {
	Content   string
	Done      bool
	Usage     *TokenUsage // Only on final chunk
	Model     string      // Only on final chunk
	Backend   string      // Only on final chunk
	Error     string      // Error message if failed
	ToolCalls []ToolCall  // Tool calls (complete on final chunk only)
}

StreamChunk represents a single chunk in a streaming response.

type StreamError 

type StreamError struct {
	Err                error  // Original error
	Backend            string // Backend that failed
	AccumulatedContent string // Content streamed before failure
	PartialResponse    bool   // True if some content was streamed
}

StreamError represents a streaming failure with context about what was already streamed. This allows agents to make informed retry decisions.

func (*StreamError) Error 

func (e *StreamError) Error() string

func (*StreamError) Unwrap 

func (e *StreamError) Unwrap() error

type StreamHandler 

type StreamHandler func(chunk StreamChunk) error

StreamHandler is called for each chunk in a streaming response.

type SubscribeMessage 

type SubscribeMessage struct {
	Subject string
	Data    []byte
	Reply   string // Reply subject for request/reply pattern
}

SubscribeMessage represents a message received from a subscription.

type Subscription 

type Subscription interface {
	Unsubscribe() error
}

Subscription represents an active message subscription.

type TokenUsage 

type TokenUsage struct {
	PromptTokens     int
	CompletionTokens int
	TotalTokens      int
}

TokenUsage tracks token consumption.

type Tool 

type Tool struct {
	Name        string          // Function name (e.g., "get_weather")
	Description string          // What the tool does
	Parameters  json.RawMessage // JSON Schema defining input parameters
}

Tool defines a function that the LLM can call.

type ToolCall 

type ToolCall struct {
	ID        string          // Unique identifier for this call
	Name      string          // Tool name to invoke
	Arguments json.RawMessage // JSON arguments
}

ToolCall represents the LLM's request to invoke a tool.

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.