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



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

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



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

def options
  @options
end

Instance Method Details

#max_response_bytes ⇒ Integer (protected)

Returns Maximum accepted response size.

Returns:

  • (Integer) —

    Maximum accepted response size



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

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



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

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



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

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



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

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.



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

def validate_configuration!
  # Override in subclasses.
end

#validate_query(query) ⇒ String (protected)

Returns Validated query.

Parameters:

  • query (String) —

    Search query

Returns:

  • (String) —

    Validated query



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

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