prescient 0.5.0 → 0.7.0

data/lib/prescient/tool/searxng.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+require 'httparty'
+require 'net/http'
+require 'timeout'
+require 'uri'
+
+# SearXNG web-search tool adapter.
+class Prescient::Tool::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 = ['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 { |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',
+      }
+    }.first(limit)
+  end
+end

data/lib/prescient/tool.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+# Namespace for external capability adapters.
+module Prescient::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

data/lib/prescient/version.rb

@@ -2,5 +2,5 @@
 
 module Prescient
   # Current Prescient gem version.
-  VERSION = '0.5.0'
+  VERSION = '0.7.0'
 end

data/lib/prescient.rb

@@ -2,6 +2,7 @@
 
 require_relative 'prescient/version'
 require_relative 'prescient/errors'
+Prescient.autoload :Tool, 'prescient/tool'
 require_relative 'prescient/pgvector'
 require_relative 'prescient/base'
 require_relative 'prescient/provider/ollama'
@@ -14,7 +15,6 @@ require_relative 'prescient/provider/deepseek'
 require_relative 'prescient/provider/xai'
 require_relative 'prescient/configuration_loader'
 require_relative 'prescient/client'
-require_relative 'prescient/cli'
 
 # Main Prescient module for AI provider abstraction
 #
@@ -35,6 +35,10 @@ require_relative 'prescient/cli'
 #   embedding = client.generate_embedding("Some text to embed")
 #   puts embedding.length # => 1536 (for OpenAI text-embedding-3-small)
 module Prescient
+  autoload :Tool, 'prescient/tool'
+  autoload :API, 'prescient/api'
+  autoload :CLI, 'prescient/cli'
+
   # Configure Prescient with custom settings and providers
   #
   # @example Configure with custom provider
@@ -59,6 +63,13 @@ module Prescient
     @_configuration ||= Configuration.new
   end
 
+  # Look up a configured external tool.
+  # @param name [Symbol, String] Tool name
+  # @return [Prescient::Tool::Base, nil] Configured tool instance
+  def self.tool(name)
+    configuration.tool(name)
+  end
+
   # Reset configuration to defaults
   #
   # @return [Configuration] New configuration instance
@@ -82,6 +93,7 @@ module Prescient
                     else
                       Configuration.new.tap do |config|
                         configure_default_providers(config, env)
+                        configure_default_tools(config, env)
                       end
                     end
 
@@ -117,6 +129,9 @@ module Prescient
     # @return [Hash] Registered providers configuration
     attr_reader :providers
 
+    # @return [Hash] Registered tools configuration
+    attr_reader :tools
+
     # Initialize configuration with default values
     def initialize
       @default_provider = :ollama
@@ -127,6 +142,8 @@ module Prescient
       @sensitive_keys = []
       @providers = {}
       @provider_instances = {} # : Hash[Symbol, untyped]
+      @tools = {}
+      @tool_instances = {} # : Hash[Symbol, untyped]
     end
 
     # Configure additional keys to remove from provider information.
@@ -175,6 +192,52 @@ module Prescient
       @provider_instances[provider_name] ||= provider_config[:class].new(**provider_options)
     end
 
+    # Register an external tool.
+    # @param name [Symbol] Unique identifier for the tool
+    # @param tool_class [Class] Tool adapter class
+    # @param options [Hash] Tool-specific configuration options
+    # @return [void]
+    def add_tool(name, tool_class, **options)
+      tool_name = name.to_sym
+      @tools[tool_name] = {
+        class:   tool_class,
+        options: options,
+      }
+      @tool_instances.delete(tool_name)
+    end
+
+    # Register ordered implementations for one logical external tool.
+    # @param name [Symbol] Unique logical capability identifier
+    # @param adapters [Array<Hash>] Adapter class and option configurations
+    # @return [void]
+    def add_tool_group(name, adapters)
+      tool_name = name.to_sym
+      @tools[tool_name] = { adapters: adapters }
+      @tool_instances.delete(tool_name)
+    end
+
+    # Instantiate a tool by name.
+    # @param name [Symbol, String] Tool name
+    # @return [Prescient::Tool::Base, nil] Tool instance or nil
+    def tool(name)
+      tool_name = name.to_sym
+      tool_config = @tools[tool_name]
+      return nil unless tool_config
+
+      if tool_config[:adapters]
+        @tool_instances[tool_name] ||= Prescient::Tool::Group.new(
+          adapters: tool_config[:adapters].map do |adapter|
+            adapter_options = adapter[:options] # : Hash[Symbol, untyped]
+            adapter[:class].new(**adapter_options)
+          end,
+        )
+        return @tool_instances[tool_name]
+      end
+
+      tool_options = tool_config[:options] # : Hash[Symbol, untyped]
+      @tool_instances[tool_name] ||= tool_config[:class].new(**tool_options)
+    end
+
     # Get list of providers that currently pass {Prescient::Base#available?}.
     #
     # Providers are included when their health check reports `reachable: true`,
@@ -204,6 +267,12 @@ module Prescient
       configure_huggingface(config, env)
     end
 
+    def configure_default_tools(config, env)
+      return unless env['SEARXNG_URL']
+
+      config.add_tool(:web_search, Prescient::Tool::SearXNG, url: env['SEARXNG_URL'])
+    end
+
     def configure_ollama(config, env)
       config.add_provider(
         :ollama,
@@ -305,5 +374,6 @@ module Prescient
   # Default configuration
   configure do |config|
     configure_default_providers(config, ENV)
+    configure_default_tools(config, ENV)
   end
 end

data/schema/prescient.configuration.schema.json

@@ -58,6 +58,12 @@
       "additionalProperties": {
         "$ref": "#/$defs/provider"
       }
+    },
+    "tools": {
+      "type": "object",
+      "additionalProperties": {
+        "$ref": "#/$defs/tool"
+      }
     }
   },
   "$defs": {
@@ -148,6 +154,119 @@
           "type": "string"
         }
       }
+    },
+    "tool": {
+      "type": "object",
+      "additionalProperties": false,
+      "anyOf": [
+        {
+          "required": [
+            "type"
+          ]
+        },
+        {
+          "required": [
+            "adapters"
+          ]
+        }
+      ],
+      "properties": {
+        "adapters": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "$ref": "#/$defs/tool"
+          }
+        },
+        "type": {
+          "type": "string",
+          "enum": [
+            "searxng",
+            "searchapi"
+          ]
+        },
+        "api_key": {
+          "type": "string"
+        },
+        "api_key_env": {
+          "type": "string"
+        },
+        "engine": {
+          "type": "string"
+        },
+        "engine_env": {
+          "type": "string"
+        },
+        "location": {
+          "type": "string"
+        },
+        "location_env": {
+          "type": "string"
+        },
+        "hl": {
+          "type": "string"
+        },
+        "hl_env": {
+          "type": "string"
+        },
+        "gl": {
+          "type": "string"
+        },
+        "gl_env": {
+          "type": "string"
+        },
+        "url": {
+          "type": "string",
+          "format": "uri-reference"
+        },
+        "url_env": {
+          "type": "string"
+        },
+        "language": {
+          "type": "string"
+        },
+        "language_env": {
+          "type": "string"
+        },
+        "categories": {
+          "oneOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            }
+          ]
+        },
+        "categories_env": {
+          "type": "string"
+        },
+        "timeout": {
+          "type": "number",
+          "exclusiveMinimum": 0
+        },
+        "timeout_env": {
+          "type": "string"
+        },
+        "max_results": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 20
+        },
+        "max_results_env": {
+          "type": "string"
+        },
+        "max_response_bytes": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "max_response_bytes_env": {
+          "type": "string"
+        }
+      }
     }
   }
 }

data/searxng/settings.yml

@@ -0,0 +1,18 @@
+# Development settings for the SearXNG service in docker-compose.yml.
+use_default_settings: true
+
+general:
+  debug: false
+  instance_name: Prescient SearXNG
+
+search:
+  formats:
+    - html
+    - json
+
+server:
+  secret_key: prescient-development-secret
+  bind_address: 0.0.0.0
+  base_url: http://localhost:8080/
+  limiter: false
+  image_proxy: false

data/sig/prescient.rbs

@@ -33,6 +33,49 @@ module Prescient
   class ProviderError < Error
   end
 
+  class ToolError < Error
+  end
+
+  class ToolConfigurationError < ToolError
+  end
+
+  class ToolConnectionError < ToolError
+  end
+
+  class ToolInvalidResponseError < ToolError
+  end
+
+  module Tool
+    class Base
+      DEFAULT_TIMEOUT: Integer
+      DEFAULT_MAX_RESULTS: Integer
+      MAX_QUERY_LENGTH: Integer
+      DEFAULT_MAX_RESPONSE_BYTES: Integer
+
+      attr_reader options: Hash[Symbol, untyped]
+
+      def initialize: (**untyped) -> void
+      def search: (String, **untyped) -> Hash[Symbol, untyped]
+    end
+
+    class Group < Base
+      attr_reader adapters: Array[Base]
+      def initialize: (adapters: Array[Base]) -> void
+      def search: (String, **untyped) -> Hash[Symbol, untyped]
+    end
+
+    class SearXNG < Base
+      def initialize: (**untyped) -> void
+      def search: (String, ?limit: Integer?, ?timeout: Numeric?) -> Hash[Symbol, untyped]
+    end
+
+    class SearchApi < Base
+      API_URL: String
+      def initialize: (**untyped) -> void
+      def search: (String, ?limit: Integer?, ?timeout: Numeric?) -> Hash[Symbol, untyped]
+    end
+  end
+
   class Base
     attr_reader options: Hash[Symbol, untyped]
     attr_reader provider_name: String
@@ -257,11 +300,15 @@ module Prescient
     attr_accessor fallback_providers: Array[Symbol]
     attr_reader sensitive_keys: Array[Symbol]
     attr_reader providers: Hash[Symbol, Hash[Symbol, untyped]]
+    attr_reader tools: Hash[Symbol, Hash[Symbol, untyped]]
 
     def initialize: () -> void
     def sensitive_keys=: (Array[Symbol | String]) -> Array[Symbol]
     def add_provider: (Symbol | String, Class, **untyped) -> void
     def provider: (Symbol | String) -> untyped
+    def add_tool: (Symbol | String, Class, **untyped) -> void
+    def add_tool_group: (Symbol | String, Array[Hash[Symbol, untyped]]) -> void
+    def tool: (Symbol | String) -> untyped
     def available_providers: () -> Array[Symbol]
   end
 
@@ -298,11 +345,23 @@ module Prescient
     def run: () -> Integer
   end
 
+  class API
+    DEFAULT_MAX_BODY_BYTES: Integer
+    MAX_BATCH_SIZE: Integer
+    API_VERSION: String
+    ROUTES: Hash[Array[String], Symbol]
+
+    def initialize: (?authentication: untyped, ?max_body_bytes: Integer) -> void
+    def call: (Hash[String, untyped]) -> [Integer, Hash[String, String], Array[String]]
+  end
+
   class ConfigurationLoader
     CONFIGURATION_VERSION: Integer
     TOP_LEVEL_KEYS: Array[String]
     PROVIDER_TYPES: Hash[String, untyped]
     COMMON_PROVIDER_KEYS: Array[String]
+    TOOL_TYPES: Hash[String, untyped]
+    COMMON_TOOL_KEYS: Array[String]
     PROMPT_TEMPLATE_KEYS: Array[String]
     ATTR_KEYS: Array[String]
 
@@ -325,11 +384,14 @@ module Prescient
   def self.client: (?Symbol, ?enable_fallback: bool, ?provider_options: Hash[Symbol, untyped]) -> Client
   def self.generate_embedding: (String, ?provider: Symbol, ?enable_fallback: bool, **untyped) -> Array[Float]
   def self.generate_response: (String, ?Array[untyped], ?provider: Symbol, ?enable_fallback: bool, **untyped) -> Hash[Symbol, untyped]
+  def self.search_and_generate: (String, ?tool: Symbol | String, ?provider: Symbol, ?limit: Integer?, ?enable_fallback: bool, ?provider_options: Hash[Symbol, untyped], **untyped) -> Hash[Symbol, untyped]
   def self.health_check: (?provider: Symbol) -> Hash[Symbol, untyped]
+  def self.tool: (Symbol | String) -> untyped
 
   private
 
   def self.configure_default_providers: (Configuration, untyped) -> void
+  def self.configure_default_tools: (Configuration, untyped) -> void
   def self.configure_ollama: (Configuration, untyped) -> void
   def self.configure_openai: (Configuration, untyped) -> void
   def self.configure_anthropic: (Configuration, untyped) -> void