prescient 0.6.0 → 0.8.0

data/lib/prescient/client.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+# Main Prescient module for AI provider abstraction
 module Prescient
   # Client class for interacting with AI providers
   #
@@ -104,10 +105,10 @@ module Prescient
     #   and recursively sanitized :options
     def provider_info
       {
-        name:      @provider_name,
-        class:     @provider.class.name.split('::').last,
+        name: @provider_name,
+        class: @provider.class.name.split("::").last,
         available: available?,
-        options:   sanitize_options(@provider.options),
+        options: sanitize_options(@provider.options)
       }
     end
 
@@ -210,7 +211,7 @@ module Prescient
         Prescient::ConnectionError,
         Prescient::RateLimitError,
         Prescient::ModelNotAvailableError,
-        Prescient::ProviderError,
+        Prescient::ProviderError
       ].any? { |error_class| error.is_a?(error_class) }
     end
   end
@@ -247,6 +248,32 @@ module Prescient
     client(provider, enable_fallback: enable_fallback).generate_response(prompt, context_items, **options)
   end
 
+  # Search with an explicit external tool and optionally use the normalized
+  # results as context for a configured AI provider.
+  #
+  # @param query [String] Search query and generation prompt
+  # @param tool [Symbol, String] Configured external tool name
+  # @param provider [Symbol, nil] Provider to use for generation
+  # @param limit [Integer, nil] Maximum number of search results
+  # @param enable_fallback [Boolean] Whether provider fallback is enabled
+  # @param provider_options [Hash] Temporary provider configuration overrides
+  # @return [Hash] Normalized provider response
+  def self.search_and_generate(query, tool: :web_search, provider: nil, limit: nil,
+                               enable_fallback: true, provider_options: {}, **options)
+    search_tool = self.tool(tool)
+    raise Prescient::ToolConfigurationError, "tool not configured: #{tool}" unless search_tool
+
+    search_result = search_tool.search(query, limit: limit)
+    context_items = search_result[:results]
+    raise Prescient::ToolInvalidResponseError, "tool results must be an array" unless context_items.is_a?(Array)
+
+    client(provider, enable_fallback:, provider_options:).generate_response(
+      query,
+      context_items,
+      **options
+    )
+  end
+
   # Return the health status of a configured provider.
   #
   # @param provider [Symbol, nil] Provider to check