scorer

package
v0.12.0 Latest Latest
Warning

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

 Go to latest Published: Sep 2, 2025 License: MIT Imports: 20 Imported by: 0

Documentation

Overview

Package scorer provides a production-ready Go library for scoring text content using OpenAI's GPT API to determine relevance for various use cases.

The library provides batch processing, concurrent execution, and flexible prompt customization with comprehensive error handling and resilience patterns.

Features:

  • Batch processing of text items (10 items per API call for efficiency)
  • Concurrent processing with configurable parallelism
  • Interface-first design for testing and extensibility
  • Custom prompt templates with Go template support
  • Circuit breaker pattern for resilience
  • Retry logic with exponential backoff
  • Prometheus metrics integration
  • Content validation and sanitization utilities

Basic usage: 

cfg := scorer.Config{
    OpenAIKey:     os.Getenv("OPENAI_API_KEY"),
    MaxConcurrent: 5,
}
s, err := scorer.NewScorer(cfg)
if err != nil {
    log.Fatal(err)
}
results, err := s.ScoreTexts(ctx, items)

Index

Constants

This section is empty.

Variables

View Source 
var (
	ErrMissingAPIKey     = errors.New("OpenAI API key is required")
	ErrInvalidConfig     = errors.New("invalid configuration")
	ErrEmptyInput        = errors.New("input items cannot be empty")
	ErrContentTooLong    = errors.New("content exceeds maximum length")
	ErrContentTooShort   = errors.New("content is too short")
	ErrContentWhitespace = errors.New("content contains only whitespace")
)

Error definitions

Functions

func CalculateRetryDelay 

func CalculateRetryDelay(attempt int, config *RetryConfig) time.Duration

CalculateRetryDelay calculates the delay for a given retry attempt

func GetMetricsHandler 

func GetMetricsHandler() http.Handler

GetMetricsHandler returns an HTTP handler for Prometheus metrics

func GetRetryStats 

func GetRetryStats(err error) (attempts int, finalError error)

GetRetryStats returns statistics about retry operations

func IsRetryableError 

func IsRetryableError(err error) bool

IsRetryableError determines if an error should trigger a retry

func RegisterCustomMetrics 

func RegisterCustomMetrics(collector prometheus.Collector) error

RegisterCustomMetrics allows registration of custom metrics

func SanitizeContent added in v0.12.0 

func SanitizeContent(content string) string

SanitizeContent cleans and normalizes text content

func ShouldTripCircuit 

func ShouldTripCircuit(err error) bool

ShouldTripCircuit determines if an error should cause the circuit to trip

func ValidateAndSanitize added in v0.12.0 

func ValidateAndSanitize(items []TextItem, opts ValidationOptions) ([]TextItem, []ValidationResult, error)

ValidateAndSanitize performs both validation and sanitization

Types

type CircuitBreakerConfig 

type CircuitBreakerConfig struct {
	MaxRequests   uint32                                      // Max requests in half-open state
	Interval      time.Duration                               // Interval for closed state
	Timeout       time.Duration                               // Timeout for open state
	ReadyToTrip   func(counts gobreaker.Counts) bool          // Custom trip condition
	OnStateChange func(name string, from, to gobreaker.State) // State change callback
}

CircuitBreakerConfig holds circuit breaker settings

type CircuitBreakerWrapper 

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

CircuitBreakerWrapper wraps an OpenAI client with circuit breaker functionality

func NewCircuitBreakerWrapper 

func NewCircuitBreakerWrapper(client OpenAIClient, config *CircuitBreakerConfig) *CircuitBreakerWrapper

NewCircuitBreakerWrapper creates a new circuit breaker wrapper around an OpenAI client

func (*CircuitBreakerWrapper) Counts 

func (w *CircuitBreakerWrapper) Counts() gobreaker.Counts

Counts returns the current counts of the circuit breaker

func (*CircuitBreakerWrapper) CreateChatCompletion 

func (w *CircuitBreakerWrapper) CreateChatCompletion(ctx context.Context, req openai.ChatCompletionRequest) (openai.ChatCompletionResponse, error)

CreateChatCompletion executes the API call through the circuit breaker

func (*CircuitBreakerWrapper) GetHealth 

func (w *CircuitBreakerWrapper) GetHealth() HealthStatus

GetHealth returns the health status of the circuit breaker

func (*CircuitBreakerWrapper) State 

func (w *CircuitBreakerWrapper) State() gobreaker.State

State returns the current state of the circuit breaker

type Config 

type Config struct {
	APIKey               string                // OpenAI API key (required)
	Model                string                // OpenAI model to use
	PromptText           string                // Custom prompt template
	MaxConcurrent        int                   // Maximum concurrent API calls
	MaxContentLength     int                   // Maximum content length per text item (0 = use default)
	EnableCircuitBreaker bool                  // Enable circuit breaker pattern
	EnableRetry          bool                  // Enable retry with backoff
	Timeout              time.Duration         // Request timeout
	CircuitBreakerConfig *CircuitBreakerConfig // Circuit breaker configuration
	RetryConfig          *RetryConfig          // Retry configuration
}

Config holds the configuration for the scorer

func NewDefaultConfig 

func NewDefaultConfig(apiKey string) Config

NewDefaultConfig creates a config with sensible defaults

func NewProductionConfig 

func NewProductionConfig(apiKey string) Config

NewProductionConfig creates a production-ready config with all resilience features

func (Config) Validate 

func (c Config) Validate() error

Validate checks if the config is valid

func (Config) WithCircuitBreaker 

func (c Config) WithCircuitBreaker() Config

WithCircuitBreaker enables circuit breaker with default settings

func (Config) WithCircuitBreakerConfig 

func (c Config) WithCircuitBreakerConfig(config *CircuitBreakerConfig) Config

WithCircuitBreakerConfig enables circuit breaker with custom settings

func (Config) WithMaxConcurrent 

func (c Config) WithMaxConcurrent(max int) Config

WithMaxConcurrent sets the maximum concurrent requests

func (Config) WithModel 

func (c Config) WithModel(model string) Config

WithModel sets the OpenAI model

func (Config) WithPromptTemplate 

func (c Config) WithPromptTemplate(templateText string) Config

WithPromptTemplate sets a custom prompt template

func (Config) WithRetry 

func (c Config) WithRetry() Config

WithRetry enables retry with default exponential backoff

func (Config) WithRetryConfig 

func (c Config) WithRetryConfig(config *RetryConfig) Config

WithRetryConfig enables retry with custom settings

func (Config) WithRetryStrategy 

func (c Config) WithRetryStrategy(strategy RetryStrategy, maxAttempts int) Config

WithRetryStrategy enables retry with specified strategy

func (Config) WithTimeout 

func (c Config) WithTimeout(timeout time.Duration) Config

WithTimeout sets the request timeout

type HealthStatus 

type HealthStatus struct {
	Healthy bool                   // Overall health status
	Status  string                 // Human-readable status message
	Details map[string]interface{} // Additional health details
}

HealthStatus represents the health state of the scorer

type IntegratedScorer 

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

IntegratedScorer combines all resilience patterns and features

func (*IntegratedScorer) GetHealth 

func (s *IntegratedScorer) GetHealth(ctx context.Context) HealthStatus

GetHealth returns comprehensive health status

func (*IntegratedScorer) ScoreTexts 

func (s *IntegratedScorer) ScoreTexts(ctx context.Context, items []TextItem, opts ...ScoringOption) ([]ScoredItem, error)

ScoreTexts implements TextScorer with full integration

func (*IntegratedScorer) ScoreTextsWithOptions 

func (s *IntegratedScorer) ScoreTextsWithOptions(ctx context.Context, items []TextItem, opts ...ScoringOption) ([]ScoredItem, error)

ScoreTextsWithOptions implements TextScorer with metrics and monitoring

type MetricsRecorder 

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

MetricsRecorder provides methods to record metrics

func NewMetricsRecorder 

func NewMetricsRecorder(enabled bool) *MetricsRecorder

NewMetricsRecorder creates a new metrics recorder

func (*MetricsRecorder) RecordAPICall 

func (m *MetricsRecorder) RecordAPICall(endpoint string, status string, seconds float64)

RecordAPICall records an API call duration

func (*MetricsRecorder) RecordBatchSize 

func (m *MetricsRecorder) RecordBatchSize(size int)

RecordBatchSize records the size of a batch

func (*MetricsRecorder) RecordCircuitBreakerState 

func (m *MetricsRecorder) RecordCircuitBreakerState(name string, state int)

RecordCircuitBreakerState records circuit breaker state

func (*MetricsRecorder) RecordCircuitBreakerTrip 

func (m *MetricsRecorder) RecordCircuitBreakerTrip(name string)

RecordCircuitBreakerTrip records a circuit breaker trip

func (*MetricsRecorder) RecordConcurrentRequests 

func (m *MetricsRecorder) RecordConcurrentRequests(delta float64)

RecordConcurrentRequests updates concurrent request count

func (*MetricsRecorder) RecordError 

func (m *MetricsRecorder) RecordError(errorType string)

RecordError records an error

func (*MetricsRecorder) RecordItemsScored 

func (m *MetricsRecorder) RecordItemsScored(count int)

RecordItemsScored records the number of items scored

func (*MetricsRecorder) RecordQueuedRequests 

func (m *MetricsRecorder) RecordQueuedRequests(delta float64)

RecordQueuedRequests updates queued request count

func (*MetricsRecorder) RecordRequest 

func (m *MetricsRecorder) RecordRequest(status string, model string)

RecordRequest records a request metric

func (*MetricsRecorder) RecordRequestDuration 

func (m *MetricsRecorder) RecordRequestDuration(seconds float64, model string)

RecordRequestDuration records request duration

func (*MetricsRecorder) RecordRetry 

func (m *MetricsRecorder) RecordRetry(reason string)

RecordRetry records a retry

func (*MetricsRecorder) RecordRetryAttempt 

func (m *MetricsRecorder) RecordRetryAttempt(attempts int)

RecordRetryAttempt records retry attempts

func (*MetricsRecorder) RecordScore 

func (m *MetricsRecorder) RecordScore(score int)

RecordScore records a score

func (*MetricsRecorder) RecordTokensUsed 

func (m *MetricsRecorder) RecordTokensUsed(tokenType string, count int)

RecordTokensUsed records tokens used

type OpenAIClient 

type OpenAIClient interface {
	CreateChatCompletion(context.Context, openai.ChatCompletionRequest) (openai.ChatCompletionResponse, error)
}

OpenAIClient defines the interface for interacting with OpenAI API

type RetryConfig 

type RetryConfig struct {
	MaxAttempts  int           // Maximum number of retry attempts
	Strategy     RetryStrategy // Backoff strategy to use
	InitialDelay time.Duration // Initial delay between retries
	MaxDelay     time.Duration // Maximum delay between retries
}

RetryConfig holds retry settings

type RetryStrategy 

type RetryStrategy string

RetryStrategy defines the backoff strategy for retries 

const (
	RetryStrategyExponential RetryStrategy = "exponential"
	RetryStrategyConstant    RetryStrategy = "constant"
	RetryStrategyFibonacci   RetryStrategy = "fibonacci"

	// Content length limits
	DefaultMaxContentLength = 10000 // Default maximum content length in characters
	MinContentLength        = 1     // Minimum content length to be valid
)

type RetryWrapper 

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

RetryWrapper wraps an OpenAI client with retry logic

func NewRetryWrapper 

func NewRetryWrapper(client OpenAIClient, config *RetryConfig) *RetryWrapper

NewRetryWrapper creates a new retry wrapper around an OpenAI client

func (*RetryWrapper) CreateChatCompletion 

func (w *RetryWrapper) CreateChatCompletion(ctx context.Context, req openai.ChatCompletionRequest) (openai.ChatCompletionResponse, error)

CreateChatCompletion executes the API call with retry logic

type ScoredItem 

type ScoredItem struct {
	Item   TextItem // Original text item
	Score  int      // Score between 0-100
	Reason string   // AI explanation for the score
}

ScoredItem represents a text item with its AI-generated score

type Scorer 

type Scorer interface {
	// ScoreTexts scores a slice of text items
	ScoreTexts(ctx context.Context, items []TextItem, opts ...ScoringOption) ([]ScoredItem, error)

	// ScoreTextsWithOptions scores text items with runtime options
	ScoreTextsWithOptions(ctx context.Context, items []TextItem, opts ...ScoringOption) ([]ScoredItem, error)

	// GetHealth returns the current health status of the scorer
	GetHealth(ctx context.Context) HealthStatus
}

Scorer provides methods to score generic text items

func BuildCustomScorer 

func BuildCustomScorer(cfg Config) (Scorer, error)

BuildCustomScorer creates a scorer with custom configuration

func BuildProductionScorer 

func BuildProductionScorer(apiKey string) (Scorer, error)

BuildProductionScorer creates a production-ready scorer with all features

func CombineWithCircuitBreaker 

func CombineWithCircuitBreaker(scorer Scorer, retryConfig *RetryConfig, cbConfig *CircuitBreakerConfig) Scorer

CombineWithCircuitBreaker creates a scorer with both retry and circuit breaker

func NewCircuitBreakerScorer 

func NewCircuitBreakerScorer(scorer Scorer, config *CircuitBreakerConfig) Scorer

NewCircuitBreakerScorer creates a new circuit breaker wrapper for a Scorer

func NewIntegratedScorer 

func NewIntegratedScorer(cfg Config) (Scorer, error)

NewIntegratedScorer creates a fully integrated scorer with all features

func NewRetryScorer 

func NewRetryScorer(scorer Scorer, config *RetryConfig) Scorer

NewRetryScorer creates a new retry wrapper for a Scorer

func NewScorer 

func NewScorer(cfg Config) (Scorer, error)

NewScorer creates a new instance of the Scorer

func WithMetrics 

func WithMetrics(scorer Scorer, metrics *MetricsRecorder) Scorer

WithMetrics wraps any TextScorer with metrics recording

func WrapWithCircuitBreaker 

func WrapWithCircuitBreaker(scorer Scorer, config *CircuitBreakerConfig) Scorer

WrapWithCircuitBreaker wraps an existing Scorer with circuit breaker functionality

type ScoringOption 

type ScoringOption func(*scoringOptions)

ScoringOption is a functional option for configuring scoring behavior

func WithExtraContext 

func WithExtraContext(context map[string]interface{}) ScoringOption

WithExtraContext adds extra context data for template substitution

func WithModel 

func WithModel(model string) ScoringOption

WithModel sets the model for this scoring request

func WithPromptTemplate 

func WithPromptTemplate(prompt string) ScoringOption

WithPromptTemplate sets a custom prompt template for this scoring request

type ScoringOptions 

type ScoringOptions struct {
	Model        string                 // Model to use for this request
	PromptText   string                 // Custom prompt for this request
	ExtraContext map[string]interface{} // Additional context data
}

ScoringOptions is the exported version for testing (uppercase)

type TextItem 

type TextItem struct {
	ID       string                 // Unique identifier for the text item
	Content  string                 // The text content to be scored
	Metadata map[string]interface{} // Optional metadata for context
}

TextItem represents a generic text item to be scored

func SanitizeTextItems added in v0.12.0 

func SanitizeTextItems(items []TextItem) []TextItem

SanitizeTextItems sanitizes content for a batch of text items

type ValidationOptions added in v0.12.0 

type ValidationOptions struct {
	MaxLength       int
	MinLength       int
	AllowEmpty      bool
	AllowWhitespace bool
	TrimWhitespace  bool
}

ValidationOptions configures content validation behavior

func DefaultValidationOptions added in v0.12.0 

func DefaultValidationOptions() ValidationOptions

DefaultValidationOptions returns sensible defaults for content validation

type ValidationResult added in v0.12.0 

type ValidationResult struct {
	Valid       bool
	Issues      []string
	Suggestions []string
}

ValidationResult contains the results of content validation

func ValidateContent added in v0.12.0 

func ValidateContent(content string, opts ValidationOptions) ValidationResult

ValidateContent validates a single text item's content

func ValidateTextItems added in v0.12.0 

func ValidateTextItems(items []TextItem, opts ValidationOptions) ([]ValidationResult, error)

ValidateTextItems validates a batch of text items

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.