prescient 0.6.0 → 0.8.0

data/lib/prescient.rb

@@ -1,19 +1,22 @@
 # frozen_string_literal: true
 
-require_relative 'prescient/version'
-require_relative 'prescient/errors'
-require_relative 'prescient/pgvector'
-require_relative 'prescient/base'
-require_relative 'prescient/provider/ollama'
-require_relative 'prescient/provider/anthropic'
-require_relative 'prescient/provider/openai'
-require_relative 'prescient/provider/huggingface'
-require_relative 'prescient/provider/gemini'
-require_relative 'prescient/provider/mistral'
-require_relative 'prescient/provider/deepseek'
-require_relative 'prescient/provider/xai'
-require_relative 'prescient/configuration_loader'
-require_relative 'prescient/client'
+require_relative "prescient/version"
+require_relative "prescient/errors"
+Prescient.autoload :Tool, "prescient/tool"
+Prescient.autoload :DocumentSource, "prescient/document_source"
+Prescient.autoload :Agent, "prescient/agent"
+require_relative "prescient/pgvector"
+require_relative "prescient/base"
+require_relative "prescient/provider/ollama"
+require_relative "prescient/provider/anthropic"
+require_relative "prescient/provider/openai"
+require_relative "prescient/provider/huggingface"
+require_relative "prescient/provider/gemini"
+require_relative "prescient/provider/mistral"
+require_relative "prescient/provider/deepseek"
+require_relative "prescient/provider/xai"
+require_relative "prescient/configuration_loader"
+require_relative "prescient/client"
 
 # Main Prescient module for AI provider abstraction
 #
@@ -33,9 +36,13 @@ require_relative 'prescient/client'
 # @example Embedding generation
 #   embedding = client.generate_embedding("Some text to embed")
 #   puts embedding.length # => 1536 (for OpenAI text-embedding-3-small)
+# rubocop:disable Metrics/ModuleLength
 module Prescient
-  autoload :API, 'prescient/api'
-  autoload :CLI, 'prescient/cli'
+  autoload :Tool, "prescient/tool"
+  autoload :DocumentSource, "prescient/document_source"
+  autoload :API, "prescient/api"
+  autoload :CLI, "prescient/cli"
+  autoload :MCP, "prescient/mcp"
 
   # Configure Prescient with custom settings and providers
   #
@@ -58,14 +65,21 @@ module Prescient
   #
   # @return [Configuration] The current configuration
   def self.configuration
-    @_configuration ||= Configuration.new
+    @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
   def self.reset_configuration!
-    @_configuration = Configuration.new
+    @configuration = Configuration.new
   end
 
   # Load configuration from a YAML file and replace the current configuration.
@@ -78,16 +92,17 @@ module Prescient
   # @param env [Hash] Environment variables used while loading configuration
   # @return [Configuration] The loaded configuration
   def self.load_configuration(path = nil, env: ENV)
-    effective_path = path || env['PRESCIENT_CONFIG']
+    effective_path = path || env["PRESCIENT_CONFIG"]
     configuration = if effective_path
                       ConfigurationLoader.load_file(effective_path, env:)
                     else
                       Configuration.new.tap do |config|
                         configure_default_providers(config, env)
+                        configure_default_tools(config, env)
                       end
                     end
 
-    @_configuration = configuration
+    @configuration = configuration
   end
 
   # Configuration class for managing Prescient settings and providers
@@ -96,7 +111,7 @@ module Prescient
   # provider registration and instantiation.
   class Configuration
     # @return [Array<Symbol>] Built-in provider option keys removed from output
-    DEFAULT_SENSITIVE_KEYS = [:api_key, :password, :token, :secret].freeze
+    DEFAULT_SENSITIVE_KEYS = %i[api_key password token secret].freeze
 
     # @return [Symbol] The default provider to use when none specified
     attr_accessor :default_provider
@@ -119,6 +134,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
@@ -129,6 +147,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.
@@ -158,8 +178,8 @@ module Prescient
     def add_provider(name, provider_class, **options)
       provider_name = name.to_sym
       @providers[provider_name] = {
-        class:   provider_class,
-        options: options,
+        class: provider_class,
+        options: options
       }
       @provider_instances.delete(provider_name)
     end
@@ -177,6 +197,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`,
@@ -206,100 +272,106 @@ 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,
         Prescient::Provider::Ollama,
-        url:             env.fetch('OLLAMA_URL', 'http://localhost:11434'),
-        embedding_model: env.fetch('OLLAMA_EMBEDDING_MODEL', 'nomic-embed-text'),
-        chat_model:      env.fetch('OLLAMA_CHAT_MODEL', 'llama3.2:3b'),
+        url: env.fetch("OLLAMA_URL", "http://localhost:11434"),
+        embedding_model: env.fetch("OLLAMA_EMBEDDING_MODEL", "nomic-embed-text"),
+        chat_model: env.fetch("OLLAMA_CHAT_MODEL", "llama3.2:3b")
       )
     end
 
     def configure_openai(config, env)
-      return unless env['OPENAI_API_KEY']
+      return unless env["OPENAI_API_KEY"]
 
       config.add_provider(
         :openai,
         Prescient::Provider::OpenAI,
-        api_key:         env['OPENAI_API_KEY'],
-        embedding_model: env.fetch('OPENAI_EMBEDDING_MODEL', 'text-embedding-3-small'),
-        chat_model:      env.fetch('OPENAI_CHAT_MODEL', 'gpt-4.1-mini'),
+        api_key: env["OPENAI_API_KEY"],
+        embedding_model: env.fetch("OPENAI_EMBEDDING_MODEL", "text-embedding-3-small"),
+        chat_model: env.fetch("OPENAI_CHAT_MODEL", "gpt-4.1-mini")
       )
     end
 
     def configure_anthropic(config, env)
-      return unless env['ANTHROPIC_API_KEY']
+      return unless env["ANTHROPIC_API_KEY"]
 
       config.add_provider(
         :anthropic,
         Prescient::Provider::Anthropic,
-        api_key: env['ANTHROPIC_API_KEY'],
-        model:   env.fetch('ANTHROPIC_MODEL', 'claude-sonnet-4-20250514'),
+        api_key: env["ANTHROPIC_API_KEY"],
+        model: env.fetch("ANTHROPIC_MODEL", "claude-sonnet-4-20250514")
       )
     end
 
     def configure_gemini(config, env)
-      return unless env['GEMINI_API_KEY']
+      return unless env["GEMINI_API_KEY"]
 
       config.add_provider(
         :gemini,
         Prescient::Provider::Gemini,
-        api_key:         env['GEMINI_API_KEY'],
-        embedding_model: env.fetch('GEMINI_EMBEDDING_MODEL', 'gemini-embedding-001'),
-        chat_model:      env.fetch('GEMINI_CHAT_MODEL', 'gemini-2.5-flash'),
+        api_key: env["GEMINI_API_KEY"],
+        embedding_model: env.fetch("GEMINI_EMBEDDING_MODEL", "gemini-embedding-001"),
+        chat_model: env.fetch("GEMINI_CHAT_MODEL", "gemini-2.5-flash")
       )
     end
 
     def configure_huggingface(config, env)
-      return unless env['HUGGINGFACE_API_KEY']
+      return unless env["HUGGINGFACE_API_KEY"]
 
       config.add_provider(
         :huggingface,
         Prescient::Provider::HuggingFace,
-        api_key:         env['HUGGINGFACE_API_KEY'],
+        api_key: env["HUGGINGFACE_API_KEY"],
         embedding_model: env.fetch(
-          'HUGGINGFACE_EMBEDDING_MODEL',
-          'sentence-transformers/all-MiniLM-L6-v2',
-        ),
-        chat_model:      env.fetch(
-          'HUGGINGFACE_CHAT_MODEL',
-          'google/gemma-2-2b-it',
+          "HUGGINGFACE_EMBEDDING_MODEL",
+          "sentence-transformers/all-MiniLM-L6-v2"
         ),
+        chat_model: env.fetch(
+          "HUGGINGFACE_CHAT_MODEL",
+          "google/gemma-2-2b-it"
+        )
       )
     end
 
     def configure_deepseek(config, env)
-      return unless env['DEEPSEEK_API_KEY']
+      return unless env["DEEPSEEK_API_KEY"]
 
       config.add_provider(
         :deepseek,
         Prescient::Provider::DeepSeek,
-        api_key:    env['DEEPSEEK_API_KEY'],
-        chat_model: env.fetch('DEEPSEEK_CHAT_MODEL', 'deepseek-v4-flash'),
+        api_key: env["DEEPSEEK_API_KEY"],
+        chat_model: env.fetch("DEEPSEEK_CHAT_MODEL", "deepseek-v4-flash")
       )
     end
 
     def configure_xai(config, env)
-      return unless env['XAI_API_KEY']
+      return unless env["XAI_API_KEY"]
 
       config.add_provider(
         :xai,
         Prescient::Provider::XAI,
-        api_key:    env['XAI_API_KEY'],
-        chat_model: env.fetch('XAI_CHAT_MODEL', 'grok-4.5'),
+        api_key: env["XAI_API_KEY"],
+        chat_model: env.fetch("XAI_CHAT_MODEL", "grok-4.5")
       )
     end
 
     def configure_mistral(config, env)
-      return unless env['MISTRAL_API_KEY']
+      return unless env["MISTRAL_API_KEY"]
 
       config.add_provider(
         :mistral,
         Prescient::Provider::Mistral,
-        api_key:         env['MISTRAL_API_KEY'],
-        embedding_model: env.fetch('MISTRAL_EMBEDDING_MODEL', 'mistral-embed'),
-        chat_model:      env.fetch('MISTRAL_CHAT_MODEL', 'mistral-large-latest'),
+        api_key: env["MISTRAL_API_KEY"],
+        embedding_model: env.fetch("MISTRAL_EMBEDDING_MODEL", "mistral-embed"),
+        chat_model: env.fetch("MISTRAL_CHAT_MODEL", "mistral-large-latest")
       )
     end
   end
@@ -307,5 +379,7 @@ module Prescient
   # Default configuration
   configure do |config|
     configure_default_providers(config, ENV)
+    configure_default_tools(config, ENV)
   end
 end
+# rubocop:enable Metrics/ModuleLength

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