prescient 0.6.0 → 0.8.0

data/lib/prescient/tool/search_api.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+require "httparty"
+require "net/http"
+require "timeout"
+
+module Prescient
+  module Tool
+    # SearchApi web-search tool adapter.
+    class SearchApi < Prescient::Tool::Base
+      # SearchApi's stable search endpoint.
+      API_URL = "https://www.searchapi.io/api/v1/search"
+      # Network failures that should be reported as connection errors.
+      NETWORK_ERRORS = [Net::OpenTimeout, Net::ReadTimeout, Timeout::Error, SocketError,
+                        Errno::ECONNREFUSED].freeze
+
+      # @param options [Hash] SearchApi configuration options
+      # @option options [String] :api_key SearchApi API key
+      # @option options [String] :engine SearchApi engine, defaulting to Google
+      # @option options [String] :location Optional search location
+      # @option options [String] :hl Optional interface language
+      # @option options [String] :gl Optional country code
+      def initialize(**options)
+        super
+        @api_key = required_api_key(options[:api_key])
+      end
+
+      # Search SearchApi and return normalized result metadata.
+      # @param query [String] Search query
+      # @param limit [Integer, nil] Maximum number of results
+      # @param timeout [Numeric, nil] Request timeout in seconds
+      # @return [Hash] Normalized search result envelope
+      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
+
+      protected
+
+      # Validate SearchApi-specific configuration.
+      # @return [void]
+      def validate_configuration!
+        required_api_key(@options[:api_key])
+        max_response_bytes
+        result_limit(nil)
+        request_timeout(nil)
+      end
+
+      private
+
+      def required_api_key(value)
+        return value if value.is_a?(String) && !value.empty?
+
+        raise Prescient::ToolConfigurationError, "SearchApi requires an api_key"
+      end
+
+      def request_headers
+        { "Authorization" => "Bearer #{@api_key}" }
+      end
+
+      def request_parameters(query, limit)
+        parameters = {
+          engine: @options.fetch(:engine, "google"),
+          q: query,
+          num: limit
+        }
+        %i[location hl gl].each do |key|
+          parameters[key] = @options[key] if @options[key]
+        end
+        parameters
+      end
+
+      def validate_response!(response)
+        if response.respond_to?(:body) && response.body.to_s.bytesize > max_response_bytes
+          raise Prescient::ToolInvalidResponseError, "SearchApi response exceeds configured size limit"
+        end
+
+        return if response.success?
+
+        error_class = case response.code.to_i
+                      when 401, 403 then Prescient::AuthenticationError
+                      when 429 then Prescient::RateLimitError
+                      when 500..599 then Prescient::ToolConnectionError
+                      else Prescient::ToolError
+                      end
+        raise error_class, "SearchApi returned HTTP #{response.code}"
+      end
+
+      def normalize_results(payload, limit)
+        raw_results = payload.is_a?(Hash) ? payload["organic_results"] : nil
+        unless raw_results.is_a?(Array)
+          raise Prescient::ToolInvalidResponseError, "SearchApi response did not contain organic_results"
+        end
+
+        raw_results.filter_map do |result|
+          next unless result.is_a?(Hash)
+          next unless result["link"].is_a?(String) && !result["link"].empty?
+
+          {
+            title: result["title"].to_s,
+            url: result["link"],
+            snippet: result["snippet"].to_s,
+            source: "searchapi"
+          }
+        end.first(limit)
+      end
+    end
+  end
+end

data/lib/prescient/tool/searxng.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+require "httparty"
+require "net/http"
+require "timeout"
+require "uri"
+
+module Prescient
+  module Tool
+    # SearXNG web-search tool adapter.
+    class SearXNG < Prescient::Tool::Base
+      # Network failures that should be reported as connection errors.
+      NETWORK_ERRORS = [Net::OpenTimeout, Net::ReadTimeout, Timeout::Error, SocketError, Errno::ECONNREFUSED].freeze
+
+      # @param options [Hash] SearXNG configuration options
+      # @option options [String] :url SearXNG base URL
+      # @option options [String] :language Optional search language
+      # @option options [String, Array<String>] :categories Optional categories
+      def initialize(**options)
+        super
+        @base_url = normalized_base_url(options.fetch(:url))
+      end
+
+      # Search SearXNG and return normalized result metadata.
+      # @param query [String] Search query
+      # @param limit [Integer, nil] Maximum number of results
+      # @param timeout [Numeric, nil] Request timeout in seconds
+      # @return [Hash] Normalized search result envelope
+      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(
+          search_url,
+          query: request_parameters(normalized_query),
+          timeout: requested_timeout
+        )
+        validate_response!(response)
+
+        {
+          tool: "web_search",
+          query: normalized_query,
+          source: "searxng",
+          results: normalize_results(response.parsed_response, requested_limit)
+        }
+      rescue Prescient::Error
+        raise
+      rescue *NETWORK_ERRORS => e
+        raise Prescient::ToolConnectionError, "SearXNG request failed: #{e.class}"
+      rescue StandardError => e
+        raise Prescient::ToolError, "SearXNG request failed: #{e.message}"
+      end
+
+      protected
+
+      # Validate SearXNG-specific configuration.
+      # @return [void]
+      def validate_configuration!
+        normalized_base_url(@options.fetch(:url))
+        max_response_bytes
+        result_limit(nil)
+        request_timeout(nil)
+      rescue KeyError
+        raise Prescient::ToolConfigurationError, "SearXNG requires a url"
+      end
+
+      private
+
+      def normalized_base_url(value)
+        uri = URI.parse(value.to_s)
+        valid_scheme = %w[http https].include?(uri.scheme)
+        if !valid_scheme || uri.host.nil? || uri.userinfo
+          raise Prescient::ToolConfigurationError, "SearXNG url must be an HTTP(S) URL without credentials"
+        end
+
+        uri.to_s.delete_suffix("/")
+      rescue URI::InvalidURIError
+        raise Prescient::ToolConfigurationError, "SearXNG url must be a valid HTTP(S) URL"
+      end
+
+      def search_url
+        "#{@base_url}/search"
+      end
+
+      def request_parameters(query)
+        parameters = { q: query, format: "json" }
+        parameters[:language] = @options[:language] if @options[:language]
+        parameters[:categories] = Array(@options[:categories]).join(",") if @options[:categories]
+        parameters
+      end
+
+      def validate_response!(response)
+        if response.respond_to?(:body) && response.body.to_s.bytesize > max_response_bytes
+          raise Prescient::ToolInvalidResponseError, "SearXNG response exceeds configured size limit"
+        end
+
+        return if response.success?
+
+        error_class = case response.code.to_i
+                      when 401, 403 then Prescient::AuthenticationError
+                      when 429 then Prescient::RateLimitError
+                      when 500..599 then Prescient::ToolConnectionError
+                      else Prescient::ToolError
+                      end
+        raise error_class, "SearXNG returned HTTP #{response.code}"
+      end
+
+      def normalize_results(payload, limit)
+        raw_results = payload.is_a?(Hash) ? payload["results"] : nil
+        unless raw_results.is_a?(Array)
+          raise Prescient::ToolInvalidResponseError, "SearXNG response did not contain results"
+        end
+
+        raw_results.filter_map do |result|
+          next unless result.is_a?(Hash)
+          next unless result["url"].is_a?(String) && !result["url"].empty?
+
+          {
+            title: result["title"].to_s,
+            url: result["url"],
+            snippet: result["content"].to_s,
+            source: "searxng"
+          }
+        end.first(limit)
+      end
+    end
+  end
+end

data/lib/prescient/tool.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+module Prescient
+  # Namespace for external capability adapters.
+  module Tool
+    autoload :SearXNG, "prescient/tool/searxng"
+    autoload :SearchApi, "prescient/tool/search_api"
+
+    # Base contract for explicit external tool invocation.
+    class Base
+      # @return [Integer] Default request timeout in seconds
+      DEFAULT_TIMEOUT = 5
+      # @return [Integer] Default maximum number of returned results
+      DEFAULT_MAX_RESULTS = 5
+      # @return [Integer] Maximum accepted search query length
+      MAX_QUERY_LENGTH = 2_000
+      # @return [Integer] Maximum accepted tool response size in bytes
+      DEFAULT_MAX_RESPONSE_BYTES = 1_048_576
+
+      # @return [Hash<Symbol, untyped>] Tool configuration options
+      attr_reader :options
+
+      # @param options [Hash] Tool-specific configuration options
+      def initialize(**options)
+        @options = options
+        validate_configuration!
+      end
+
+      # Execute a search using the tool.
+      # @param query [String] Search query
+      # @param options [Hash] Per-request options
+      # @return [Hash] Normalized tool result
+      # @raise [NotImplementedError] If the adapter does not support searching
+      def search(query, **options)
+        raise NotImplementedError, "#{self.class} must implement #search"
+      end
+
+      protected
+
+      # Validate adapter configuration.
+      # @return [void]
+      def validate_configuration!
+        # Override in subclasses.
+      end
+
+      # @param query [String] Search query
+      # @return [String] Validated query
+      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
+
+      # @param value [Object] Requested result limit
+      # @return [Integer] Validated result limit
+      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
+
+      # @param value [Object] Requested timeout
+      # @return [Numeric] Validated timeout
+      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
+
+      # @return [Integer] Maximum accepted response size
+      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
+    end
+
+    # Ordered implementations for one logical tool capability.
+    class Group < Base
+      # @return [Array<Base>] Ordered capability implementations
+      attr_reader :adapters
+
+      # @param adapters [Array<Base>] Ordered capability implementations
+      def initialize(adapters:)
+        super
+        @adapters = adapters
+        raise Prescient::ToolConfigurationError, "tool group requires an adapter" if @adapters.empty?
+      end
+
+      # Execute the first successful adapter, falling back only for transient
+      # connection and rate-limit failures.
+      # @param query [String] Search query
+      # @param options [Hash] Per-request options
+      # @return [Hash] Normalized tool result
+      def search(query, **options)
+        failures = []
+        @adapters.each do |adapter|
+          return adapter.search(query, **options)
+        rescue Prescient::ToolConnectionError, Prescient::RateLimitError => e
+          failures << e
+        end
+
+        raise failures.last
+      end
+    end
+  end
+end

data/lib/prescient/version.rb

@@ -2,5 +2,5 @@
 
 module Prescient
   # Current Prescient gem version.
-  VERSION = '0.6.0'
+  VERSION = "0.8.0"
 end