Class: Prescient::Tool::SearchApi

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

Overview

SearchApi web-search tool adapter.

Constant Summary collapse

API_URL =

SearchApi's stable search endpoint.

'https://www.searchapi.io/api/v1/search'
NETWORK_ERRORS =

Network failures that should be reported as connection errors.

[Net::OpenTimeout, Net::ReadTimeout, Timeout::Error, SocketError,
Errno::ECONNREFUSED].freeze

Constants inherited from Base

Base::DEFAULT_MAX_RESPONSE_BYTES, Base::DEFAULT_MAX_RESULTS, Base::DEFAULT_TIMEOUT, Base::MAX_QUERY_LENGTH

Instance Attribute Summary

Attributes inherited from Base

#options

Instance Method Summary collapse

Methods inherited from Base

#max_response_bytes, #request_timeout, #result_limit, #validate_query

Constructor Details

#initialize(**options) ⇒ SearchApi

Returns a new instance of SearchApi.

Parameters:

  • options (Hash) —

    SearchApi configuration options

Options Hash (**options):

  • :api_key (String) —

    SearchApi API key

  • :engine (String) —

    SearchApi engine, defaulting to Google

  • :location (String) —

    Optional search location

  • :hl (String) —

    Optional interface language

  • :gl (String) —

    Optional country code



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

def initialize(**options)
  super
  @api_key = required_api_key(options[:api_key])
end

Instance Method Details

#search(query, limit: nil, timeout: nil) ⇒ Hash

Search SearchApi and return normalized result metadata.

Parameters:

  • query (String) —

    Search query

  • limit (Integer, nil) (defaults to: nil) —

    Maximum number of results

  • timeout (Numeric, nil) (defaults to: nil) —

    Request timeout in seconds

Returns:

  • (Hash) —

    Normalized search result envelope



31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
 
# File 'lib/prescient/tool/search_api.rb', line 31

def search(query, limit: nil, timeout: nil)
  normalized_query = validate_query(query)
  requested_limit = result_limit(limit)
  requested_timeout = request_timeout(timeout)
  response = HTTParty.get(
    API_URL,
    headers: request_headers,
    query:   request_parameters(normalized_query, requested_limit),
    timeout: requested_timeout,
  )
  validate_response!(response)

  {
    tool:    'web_search',
    query:   normalized_query,
    source:  'searchapi',
    results: normalize_results(response.parsed_response, requested_limit),
  }
rescue Prescient::Error
  raise
rescue *NETWORK_ERRORS => e
  raise Prescient::ToolConnectionError, "SearchApi request failed: #{e.class}"
rescue StandardError => e
  raise Prescient::ToolError, "SearchApi request failed: #{e.message}"
end

#validate_configuration! ⇒ void (protected)

This method returns an undefined value.

Validate SearchApi-specific configuration.



61
62
63
64
65
66
 
# File 'lib/prescient/tool/search_api.rb', line 61

def validate_configuration!
  required_api_key(@options[:api_key])
  max_response_bytes
  result_limit(nil)
  request_timeout(nil)
end