ask-web-search 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fe356e9cdc2a7ee736d51ad93d36dfcaaef72168b0a4b3d98bc19945b919dd4a
-  data.tar.gz: e334c6903ab48de0a78fee36c07933487dcab49648cc31bbe3adfd46653de01a
+  metadata.gz: d8bd1c41d870cf5aa9f13332ba6b2d43fbcf6d6bbebb13e5390f2d9e8c0f6529
+  data.tar.gz: b1cc5035874cd122e9d4a8d1c4feec1bc1d146d12842714cbfe4672c43a4dba6
 SHA512:
-  metadata.gz: d1fc95c583e7fc95a15ef32b7e1253302c6e2ba1edee41781445c912a1d8631cba839dac044fb94a1cc20d51d219960102cccec5d75eecbf1cef92de0f92e559
-  data.tar.gz: f56f4d8df11e3de5de981e0f5d182d8491cb12840f12dc4e546986fd9c4f6b82668313cd4270468215f460e5a29ece4ecb0e28bc4c301c88dfd39dc1656ae7e6
+  metadata.gz: b80273643aa1f7e4a875832dcef9bfec8a2df3886af9be0f92651f55e8b6873364b59586a9bfa9e6ba5eb95394b686425ca7e7032ad69677ba1fab085fb42498
+  data.tar.gz: abae84930f02b3adbe06a136b676a79bb8e3ae2416aa7c94fd94da2d22862672ae35818b92434cb03a163e7a2770f63bfcfd7d10766a447a5f4de97fdf35a57d

data/lib/ask/web_search/version.rb

@@ -1,5 +1,5 @@
 module Ask
   module WebSearch
-    VERSION = "0.3.0"
+    VERSION = "0.5.0"
   end
 end

data/lib/ask/web_search.rb

@@ -12,6 +12,16 @@ module Ask
   # framing — name, parameter schema, result wrapping — lives with the
   # consumers (the MCP server, the agents) that call this library.
   module WebSearch
+    # Search errors that carry engine diagnostics — the agent needs to
+    # know *which* engines failed and *why* (CAPTCHA, timeout, suspended)
+    # instead of just "No results found."
+    class Error < StandardError; end
+
+    # SearXNG answered but every engine failed (CAPTCHA, timeout,
+    # suspended). The message lists which engines failed and why, plus
+    # what the agent can try next.
+    class AllEnginesFailedError < Error; end
+
     # Local SearXNG endpoint. Defaults to the standard local instance;
     # override with SEARXNG_URL or WebSearch.searxng_url=.
     def self.searxng_url
@@ -22,29 +32,88 @@ module Ask
       @searxng_url = url
     end
 
-    # Searches +query+ and returns the results as numbered markdown
-    # ("No results found." when SearXNG found nothing). Raises on
-    # connection/HTTP failures — the caller decides how to surface them.
+    # Retry configuration. Set max_retries to 0 to disable retries.
+    DEFAULT_MAX_RETRIES = 3
+    RETRY_BACKOFF = [0.5, 1.0, 2.0].freeze
+
+    def self.max_retries
+      return @max_retries if defined?(@max_retries)
+
+      @max_retries = DEFAULT_MAX_RETRIES
+    end
+
+    def self.max_retries=(val)
+      @max_retries = val
+    end
+
+    # Searches +query+ and returns the results as numbered markdown.
+    # "No results found." only when SearXNG answered cleanly with zero
+    # results and no engine failures. When engines failed, raises
+    # AllEnginesFailedError with per-engine diagnostics (see
+    # #format_engine_error). Raises on connection/HTTP failures — the
+    # caller decides how to surface them.
     def self.search(query)
-      format_results(search_results(query))
+      response = search_raw(query)
+      raise AllEnginesFailedError, format_engine_error(query, response) if response[:results].empty? &&
+                                                                          response[:unresponsive].any?
+
+      format_results(response[:results])
     end
 
     # The raw result list: { url:, title:, content: } entries from the
-    # results and infoboxes, deduplicated by url.
+    # results and infoboxes, deduplicated by url. Retries up to
+    # max_retries times on connection/HTTP failures with exponential
+    # backoff. Set max_retries to 0 to disable.
     def self.search_results(query)
+      search_raw(query)[:results]
+    end
+
+    # The full SearXNG response: { results: [...], unresponsive: [[name,
+    # reason], ...] }. Same retry logic as #search_results, but preserves
+    # the engine diagnostics the caller needs to explain an empty result.
+    def self.search_raw(query)
       uri = URI("#{searxng_url}/search?q=#{URI.encode_www_form_component(query)}&format=json")
-      http = Net::HTTP.new(uri.host, uri.port)
-      http.open_timeout = 5
-      http.read_timeout = 10
-      req = Net::HTTP::Get.new(uri)
-      req["User-Agent"] = "ask-web-search/#{Ask::WebSearch::VERSION}"
-      res = http.request(req)
-      raise "SearXNG returned #{res.code}: #{res.body}" unless res.code.start_with?("2")
-
-      parse_results(JSON.parse(res.body))
+      retries = max_retries || 0
+      attempt = 0
+      begin
+        attempt += 1
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.open_timeout = 5
+        http.read_timeout = 10
+        req = Net::HTTP::Get.new(uri)
+        req["User-Agent"] = "ask-web-search/#{Ask::WebSearch::VERSION}"
+        res = http.request(req)
+        raise "SearXNG returned #{res.code}: #{res.body}" unless res.code.start_with?("2")
+
+        parse_response(JSON.parse(res.body))
+      rescue StandardError
+        raise if attempt > retries
+
+        sleep RETRY_BACKOFF[[attempt - 1, RETRY_BACKOFF.size - 1].min]
+        retry
+      end
     end
 
-    def self.parse_results(data)
+    # Formats the engine failure into an actionable message: which engines
+    # failed and why, plus what the agent can try next. Keeps the raw
+    # SearXNG reason strings (CAPTCHA, timeout, suspended) — the caller
+    # can see exactly what happened.
+    def self.format_engine_error(query, response)
+      lines = ["No search results for #{query.inspect} — all #{response[:unresponsive].size} engine(s) failed:"]
+      response[:unresponsive].each do |name, reason|
+        lines << "- #{name}: #{reason}"
+      end
+      lines << "Try: a simpler query, or ask-web-fetch for a known URL."
+      lines.join("\n")
+    end
+    private_class_method :format_engine_error
+
+    # Parses the full SearXNG JSON response into { results:, unresponsive: }.
+    # results are { url:, title:, content: } entries from results and
+    # infoboxes, deduplicated by url. unresponsive is the raw
+    # [[engine_name, reason], ...] list SearXNG returns for failed
+    # engines (e.g. [["duckduckgo", "CAPTCHA"], ["mojeek", "timeout"]]).
+    def self.parse_response(data)
       results = []
       data.fetch("results", []).each do |r|
         results << { url: r["url"], title: r["title"], content: r["content"] }
@@ -52,7 +121,15 @@ module Ask
       data.fetch("infoboxes", []).each do |ib|
         results << { url: ib["id"], title: ib["infobox"], content: ib["content"] }
       end
-      results.uniq { |r| r[:url] }
+      {
+        results: results.uniq { |r| r[:url] },
+        unresponsive: Array(data.fetch("unresponsive_engines", []))
+      }
+    end
+    private_class_method :parse_response
+
+    def self.parse_results(data)
+      parse_response(data)[:results]
     end
     private_class_method :parse_results
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ask-web-search
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Kaka Ruto
@@ -116,7 +116,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.3
+rubygems_version: 4.0.18
 specification_version: 4
 summary: Web search library for the ask-rb ecosystem
 test_files: []