ask-web-search 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 56161d32f9534d056405cc0fd382fd6c07be300ae35084e0bea4a5017b1fe353
-  data.tar.gz: cefb6a830bff2b3998174d2b9f9d75d4bcf42f00958766b55bc9d4679c2d8c17
+  metadata.gz: d8bd1c41d870cf5aa9f13332ba6b2d43fbcf6d6bbebb13e5390f2d9e8c0f6529
+  data.tar.gz: b1cc5035874cd122e9d4a8d1c4feec1bc1d146d12842714cbfe4672c43a4dba6
 SHA512:
-  metadata.gz: 1d0b196f7b4be2b6f0da74c271aa2c2446c5d5d6ec45b16a0b4b9eac2a46abf37e8461895c1f679b3b78041f5d472c6ed6590a6a6347da1e2db636e422485a29
-  data.tar.gz: fe6766f5f91bd11b82ea6d555c01248bbdbc93c152b657ce042c1011967d75994bfff13dce23730360bdde5eed3c14e28859749764f34c12fee81afaebf04fb2
+  metadata.gz: b80273643aa1f7e4a875832dcef9bfec8a2df3886af9be0f92651f55e8b6873364b59586a9bfa9e6ba5eb95394b686425ca7e7032ad69677ba1fab085fb42498
+  data.tar.gz: abae84930f02b3adbe06a136b676a79bb8e3ae2416aa7c94fd94da2d22862672ae35818b92434cb03a163e7a2770f63bfcfd7d10766a447a5f4de97fdf35a57d

data/lib/ask/web_search/version.rb

@@ -1,5 +1,5 @@
 module Ask
   module WebSearch
-    VERSION = "0.4.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
@@ -36,11 +46,18 @@ module Ask
       @max_retries = val
     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.
+    # 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
@@ -48,6 +65,13 @@ module Ask
     # 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")
       retries = max_retries || 0
       attempt = 0
@@ -61,7 +85,7 @@ module Ask
         res = http.request(req)
         raise "SearXNG returned #{res.code}: #{res.body}" unless res.code.start_with?("2")
 
-        parse_results(JSON.parse(res.body))
+        parse_response(JSON.parse(res.body))
       rescue StandardError
         raise if attempt > retries
 
@@ -70,7 +94,26 @@ module Ask
       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"] }
@@ -78,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.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Kaka Ruto