Module: AgentHarness::ErrorTaxonomy

Defined in:
lib/agent_harness/error_taxonomy.rb

Overview

Error classification system for categorizing and handling errors

Provides a standardized way to classify errors from different providers into actionable categories for retry logic, provider switching, and error reporting.

Constant Summary collapse

CATEGORIES =

Error categories with their metadata

{
  rate_limited: {
    description: "Rate limit exceeded",
    action: :switch_provider,
    retryable: false
  },
  auth_expired: {
    description: "Authentication failed or expired",
    action: :switch_provider,
    retryable: false
  },
  quota_exceeded: {
    description: "Usage quota exceeded",
    action: :switch_provider,
    retryable: false
  },
  transient: {
    description: "Temporary error",
    action: :retry_with_backoff,
    retryable: true
  },
  permanent: {
    description: "Unrecoverable error",
    action: :escalate,
    retryable: false
  },
  timeout: {
    description: "Operation timed out",
    action: :retry_with_backoff,
    retryable: true
  },
  unknown: {
    description: "Unknown error",
    action: :retry_with_backoff,
    retryable: true
  }
}.freeze

Class Method Summary collapse

Class Method Details

.action_for(category) ⇒ Symbol

Get recommended action for error category

Parameters:

  • category (Symbol) —

    the error category

Returns:

  • (Symbol) —

    recommended action



79
80
81
 
# File 'lib/agent_harness/error_taxonomy.rb', line 79

def action_for(category)
  CATEGORIES.dig(category, :action) || :escalate
end

.categories ⇒ Array<Symbol>

Get all category names

Returns:

  • (Array<Symbol>) —

    list of category names



102
103
104
 
# File 'lib/agent_harness/error_taxonomy.rb', line 102

def categories
  CATEGORIES.keys
end

.classify(error, patterns = {}) ⇒ Symbol

Classify an error based on provider patterns

Parameters:

  • error (Exception) —

    the error to classify

  • patterns (Hash<Symbol, Array<Regexp>>) (defaults to: {}) —

    provider-specific patterns

Returns:

  • (Symbol) —

    error category



55
56
57
58
59
60
61
62
63
64
65
 
# File 'lib/agent_harness/error_taxonomy.rb', line 55

def classify(error, patterns = {})
  message = error.message.to_s.downcase

  # Check provider-specific patterns first
  patterns.each do |category, regexes|
    return category if regexes.any? { |r| message.match?(r) }
  end

  # Fall back to generic patterns
  classify_generic(message)
end

.classify_message(message) ⇒ Symbol

Classify a message string into error category

Parameters:

  • message (String) —

    the error message

Returns:

  • (Symbol) —

    error category



71
72
73
 
# File 'lib/agent_harness/error_taxonomy.rb', line 71

def classify_message(message)
  classify_generic(message.to_s.downcase)
end

.description_for(category) ⇒ String

Get description for error category

Parameters:

  • category (Symbol) —

    the error category

Returns:

  • (String) —

    human-readable description



95
96
97
 
# File 'lib/agent_harness/error_taxonomy.rb', line 95

def description_for(category)
  CATEGORIES.dig(category, :description) || "Unknown error"
end

.retryable?(category) ⇒ Boolean

Check if error category is retryable

Parameters:

  • category (Symbol) —

    the error category

Returns:

  • (Boolean) —

    true if the error can be retried



87
88
89
 
# File 'lib/agent_harness/error_taxonomy.rb', line 87

def retryable?(category)
  CATEGORIES.dig(category, :retryable) || false
end