rest

Documentation

Overview

Package rest provides a generic REST API generator for Augustus.

This package implements the Generator interface for making HTTP requests to REST APIs. It supports configurable endpoints, HTTP methods, request templates with variable substitution, and flexible response parsing including JSONPath.

Index

• func NewRest(cfg registry.Config) (generators.Generator, error)
• type Config
  • func ApplyOptions(cfg Config, opts ...Option) Config
  • func ConfigFromMap(m registry.Config) (Config, error)
  • func DefaultConfig() Config
• type Option
  • func WithAPIKey(key string) Option
  • func WithHeaders(headers map[string]string) Option
  • func WithMethod(method string) Option
  • func WithRateLimit(rps float64) Option
  • func WithRateLimitCodes(codes map[int]bool) Option
  • func WithReqTemplate(template string) Option
  • func WithRequestTimeout(timeout time.Duration) Option
  • func WithResponseJSON(parseJSON bool) Option
  • func WithResponseJSONField(field string) Option
  • func WithSSEFilterField(field string) Option
  • func WithSSEFilterValue(value string) Option
  • func WithSSEMode(mode string) Option
  • func WithSSETextField(field string) Option
  • func WithSkipCodes(codes map[int]bool) Option
  • func WithURI(uri string) Option
• type Rest
  • func (r *Rest) ClearHistory()
  • func (r *Rest) Description() string
  • func (r *Rest) Generate(ctx context.Context, conv *attempt.Conversation, n int) ([]attempt.Message, error)
  • func (r *Rest) LastRawResponse() []byte
  • func (r *Rest) Name() string

Functions

func NewRest

func NewRest(cfg registry.Config) (generators.Generator, error)

NewRest creates a new REST generator from configuration.

Types

type Config

type Config struct {
	// Required
	URI string

	// Optional with defaults
	Method            string
	Headers           map[string]string
	ReqTemplate       string
	ResponseJSON      bool
	ResponseJSONField string
	RequestTimeout    time.Duration
	RateLimitCodes    map[int]bool
	SkipCodes         map[int]bool
	APIKey            string
	RateLimit         float64 // Requests per second (0 = unlimited)

	// SSE configuration (optional, enables configurable SSE parsing)
	SSETextField   string // JSONPath for text extraction from SSE events (e.g., "$.content.text")
	SSEMode        string // "delta" (concat all chunks) or "last" (take last non-empty value)
	SSEFilterField string // JSONPath for filtering SSE events (e.g., "$.content.type")
	SSEFilterValue string // Value to match for sse_filter_field (e.g., "CHAT_TEXT")
}

Config holds typed configuration for the REST generator.

func ApplyOptions

func ApplyOptions(cfg Config, opts ...Option) Config

ApplyOptions applies functional options to a Config.

func ConfigFromMap

func ConfigFromMap(m registry.Config) (Config, error)

ConfigFromMap parses a registry.Config map into a typed Config.

func DefaultConfig

func DefaultConfig() Config

DefaultConfig returns a Config with sensible defaults.

type Option

type Option = registry.Option[Config]

Option is a functional option for Config.

func WithAPIKey

func WithAPIKey(key string) Option

WithAPIKey sets the API key.

func WithHeaders

func WithHeaders(headers map[string]string) Option

WithHeaders sets the HTTP headers.

func WithMethod

func WithMethod(method string) Option

WithMethod sets the HTTP method.

func WithRateLimit

func WithRateLimit(rps float64) Option

WithRateLimit sets the rate limit in requests per second.

func WithRateLimitCodes

func WithRateLimitCodes(codes map[int]bool) Option

WithRateLimitCodes sets the rate limit HTTP status codes.

func WithReqTemplate

func WithReqTemplate(template string) Option

WithReqTemplate sets the request template.

func WithRequestTimeout

func WithRequestTimeout(timeout time.Duration) Option

WithRequestTimeout sets the request timeout.

func WithResponseJSON

func WithResponseJSON(parseJSON bool) Option

WithResponseJSON sets whether to parse JSON responses.

func WithResponseJSONField

func WithResponseJSONField(field string) Option

WithResponseJSONField sets the JSON field to extract.

func WithSSEFilterField

func WithSSEFilterField(field string) Option

WithSSEFilterField sets the JSONPath for filtering SSE events.

func WithSSEFilterValue

func WithSSEFilterValue(value string) Option

WithSSEFilterValue sets the value to match for the SSE filter field.

func WithSSEMode

func WithSSEMode(mode string) Option

WithSSEMode sets the SSE accumulation mode ("delta" or "last").

func WithSSETextField

func WithSSETextField(field string) Option

WithSSETextField sets the JSONPath for text extraction from SSE events.

func WithSkipCodes

func WithSkipCodes(codes map[int]bool) Option

WithSkipCodes sets the HTTP status codes to skip (return empty response).

func WithURI

func WithURI(uri string) Option

WithURI sets the API URI.

type Rest

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

Rest is a generic REST API generator that makes HTTP requests to configured endpoints. It supports request templating, JSON response parsing, and various HTTP methods.

func (*Rest) ClearHistory

func (r *Rest) ClearHistory()

ClearHistory is a no-op for REST generator (stateless).

func (*Rest) Description

func (r *Rest) Description() string

Description returns a human-readable description.

func (*Rest) Generate

func (r *Rest) Generate(ctx context.Context, conv *attempt.Conversation, n int) ([]attempt.Message, error)

Generate sends the conversation's last prompt to the REST API and returns responses.

func (*Rest) LastRawResponse

func (r *Rest) LastRawResponse() []byte

LastRawResponse returns the raw HTTP response body from the most recent API call. This implements the hooks.RawResponseProvider interface.

func (*Rest) Name

func (r *Rest) Name() string

Name returns the generator's fully qualified name.