Class: Prescient::Tool::Base

Inherits:
Object
  • Object
show all
Defined in:
lib/prescient/tool.rb

Overview

Base contract for explicit external tool invocation.

Direct Known Subclasses

Group, SearXNG, SearchApi

Constant Summary collapse

DEFAULT_TIMEOUT =

Returns Default request timeout in seconds.

Returns:

  • (Integer) —

    Default request timeout in seconds

5
DEFAULT_MAX_RESULTS =

Returns Default maximum number of returned results.

Returns:

  • (Integer) —

    Default maximum number of returned results

5
MAX_QUERY_LENGTH =

Returns Maximum accepted search query length.

Returns:

  • (Integer) —

    Maximum accepted search query length

2_000
DEFAULT_MAX_RESPONSE_BYTES =

Returns Maximum accepted tool response size in bytes.

Returns:

  • (Integer) —

    Maximum accepted tool response size in bytes

1_048_576

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(**options) ⇒ Base

Returns a new instance of Base.

Parameters:

  • options (Hash) —

    Tool-specific configuration options



23
24
25
26
 
# File 'lib/prescient/tool.rb', line 23

def initialize(**options)
  @options = options
  validate_configuration!
end

Instance Attribute Details

#options ⇒ Hash<Symbol, untyped> (readonly)

Returns Tool configuration options.

Returns:

  • (Hash<Symbol, untyped>) —

    Tool configuration options



20
21
22
 
# File 'lib/prescient/tool.rb', line 20

def options
  @options
end

Instance Method Details

#max_response_bytes ⇒ Integer (protected)

Returns Maximum accepted response size.

Returns:

  • (Integer) —

    Maximum accepted response size



84
85
86
87
88
89
90
91
92
 
# File 'lib/prescient/tool.rb', line 84

def max_response_bytes
  value = @options.fetch(:max_response_bytes, DEFAULT_MAX_RESPONSE_BYTES)
  unless value.is_a?(Integer) && value.positive?
    raise Prescient::ToolConfigurationError,
          'max_response_bytes must be a positive integer'
  end

  value
end

#request_timeout(value) ⇒ Numeric (protected)

Returns Validated timeout.

Parameters:

  • value (Object) —

    Requested timeout

Returns:

  • (Numeric) —

    Validated timeout



74
75
76
77
78
79
80
81
 
# File 'lib/prescient/tool.rb', line 74

def request_timeout(value)
  timeout = value.nil? ? @options.fetch(:timeout, DEFAULT_TIMEOUT) : value
  unless timeout.is_a?(Numeric) && timeout.positive?
    raise Prescient::ToolConfigurationError, 'timeout must be a positive number'
  end

  timeout
end

#result_limit(value) ⇒ Integer (protected)

Returns Validated result limit.

Parameters:

  • value (Object) —

    Requested result limit

Returns:

  • (Integer) —

    Validated result limit



63
64
65
66
67
68
69
70
 
# File 'lib/prescient/tool.rb', line 63

def result_limit(value)
  limit = value.nil? ? @options.fetch(:max_results, DEFAULT_MAX_RESULTS) : value
  unless limit.is_a?(Integer) && limit.positive?
    raise Prescient::ToolConfigurationError, 'max_results must be a positive integer'
  end

  [limit, 20].min
end

#search(query, **options) ⇒ Hash

Execute a search using the tool.

Parameters:

  • query (String) —

    Search query

  • options (Hash) —

    Per-request options

Returns:

  • (Hash) —

    Normalized tool result

Raises:

  • (NotImplementedError) —

    If the adapter does not support searching



33
34
35
 
# File 'lib/prescient/tool.rb', line 33

def search(query, **options)
  raise NotImplementedError, "#{self.class} must implement #search"
end

#validate_configuration! ⇒ void (protected)

This method returns an undefined value.

Validate adapter configuration.



41
42
43
 
# File 'lib/prescient/tool.rb', line 41

def validate_configuration!
  # Override in subclasses.
end

#validate_query(query) ⇒ String (protected)

Returns Validated query.

Parameters:

  • query (String) —

    Search query

Returns:

  • (String) —

    Validated query



47
48
49
50
51
52
53
54
55
56
57
58
59
 
# File 'lib/prescient/tool.rb', line 47

def validate_query(query)
  unless query.is_a?(String) && !query.strip.empty?
    raise Prescient::ToolConfigurationError, 'search query must be a non-empty string'
  end

  cleaned_query = query.strip
  if cleaned_query.length > MAX_QUERY_LENGTH
    raise Prescient::ToolConfigurationError,
          "search query cannot contain more than #{MAX_QUERY_LENGTH} characters"
  end

  cleaned_query
end