ask-web-search 0.4.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 56161d32f9534d056405cc0fd382fd6c07be300ae35084e0bea4a5017b1fe353
-  data.tar.gz: cefb6a830bff2b3998174d2b9f9d75d4bcf42f00958766b55bc9d4679c2d8c17
+  metadata.gz: 8843934817bb67da278cc649beebc5beb3ed6af85653209511108f72f06b1da5
+  data.tar.gz: c2f2ab3b68106eb47806824b7e8d86153cf934159024535be0c7eb3b3bbc4f5b
 SHA512:
-  metadata.gz: 1d0b196f7b4be2b6f0da74c271aa2c2446c5d5d6ec45b16a0b4b9eac2a46abf37e8461895c1f679b3b78041f5d472c6ed6590a6a6347da1e2db636e422485a29
-  data.tar.gz: fe6766f5f91bd11b82ea6d555c01248bbdbc93c152b657ce042c1011967d75994bfff13dce23730360bdde5eed3c14e28859749764f34c12fee81afaebf04fb2
+  metadata.gz: df4ec625002df7c953171cea42654a4b4b5ab10fa365cea9ab149991100913d5b8982d1d14d1204a1a596f00c847dc1cb95714309383cb3496913aa7d8137c78
+  data.tar.gz: d1212989bbf9cc31e15acd4f43153fff0c57c23038ccb46a4c557955d62d129ed9ecd0cfaf21c92508d1b985cbb5742dd1849cc2dbc235fa6f49b9109ddfd8a8

data/README.md

@@ -61,6 +61,38 @@ Results are returned as a numbered markdown-like string:
 
 If no results are found, returns `"No results found."`.
 
+## Freshness windows and verticals
+
+`search` (and `search_results` / `search_raw`, and both tool framings)
+accept two optional parameters:
+
+```ruby
+Ask::WebSearch.search("ruby 4.0 release notes", time_range: "month")
+Ask::WebSearch.search("fed policy", categories: "news")
+Ask::WebSearch.search("retrieval augmented generation", categories: "science")
+```
+
+- **`time_range:`** restricts results to a SearXNG freshness window —
+  `day`, `week`, `month`, or `year`. Anything else raises `ArgumentError`
+  naming the valid values. When a windowed search comes back cleanly
+  empty, the result says so — "No results found within the day freshness
+  window. Retry with a broader time_range or without one." — instead of a
+  bare "No results found.", and engine-failure diagnostics suggest a
+  broader window. Caveat: SearXNG delegates date filtering to the engines,
+  and as of SearXNG 2026.6.x every date-capable engine returns zero
+  results under a date filter, so windows currently fail soft with that
+  message. No gem change is needed when the engines are fixed upstream.
+- **`categories:`** scopes the search to a SearXNG category — `news`,
+  `science` (research papers), or any category the instance configures.
+  Accepts a string or anything Array-able (`[:news, :science]` →
+  `news,science`). Values pass through unvalidated: instances configure
+  their own category set, and an unknown category degrades to a clean
+  empty result rather than a failure. The instance must have vertical
+  engines enabled — the `searxng/` compose config in this repository
+  enables bing news + google news (news) and arxiv + pubmed (science);
+  without them SearXNG silently resolves the request against the general
+  engines.
+
 ## Full documentation
 
 The full ask-rb documentation lives at https://ask-rb.github.io/ask-docs.

data/lib/ask/web_search/tool.rb

@@ -24,13 +24,23 @@ module Ask
       params(
         type: "object",
         properties: {
-          query: { type: "string", description: "The search query" }
+          query: { type: "string", description: "The search query" },
+          time_range: {
+            type: "string",
+            enum: Ask::WebSearch::TIME_RANGES,
+            description: "Freshness window: only results from the past day, week, month, or year. Use for recency-sensitive queries (news, prices, releases); omit otherwise."
+          },
+          categories: {
+            type: "string",
+            enum: %w[general news science],
+            description: "Vertical to search: general web results (default), news, or science (research papers). Use news for current events, science for papers."
+          }
         },
         required: ["query"]
       )
 
-      def execute(query:)
-        Ask::Result.ok(data: Ask::WebSearch.search(query))
+      def execute(query:, time_range: nil, categories: nil)
+        Ask::Result.ok(data: Ask::WebSearch.search(query, time_range: time_range, categories: categories))
       end
     end
   end

data/lib/ask/web_search/version.rb

@@ -1,5 +1,5 @@
 module Ask
   module WebSearch
-    VERSION = "0.4.0"
+    VERSION = "0.6.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
@@ -26,6 +36,12 @@ module Ask
     DEFAULT_MAX_RETRIES = 3
     RETRY_BACKOFF = [0.5, 1.0, 2.0].freeze
 
+    # SearXNG's freshness windows — the valid values of its time_range
+    # search parameter. Anything else is rejected up front, so a bad value
+    # fails with a message listing these instead of silently searching
+    # unfiltered.
+    TIME_RANGES = %w[day week month year].freeze
+
     def self.max_retries
       return @max_retries if defined?(@max_retries)
 
@@ -36,19 +52,55 @@ 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.
-    def self.search(query)
-      format_results(search_results(query))
+    # 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.
+    #
+    # time_range: restricts results to a freshness window — one of
+    # TIME_RANGES (day, week, month, year). With a window set, a clean
+    # zero-result search says so ("No results found within the day
+    # freshness window...") instead of a bare "No results found.", so the
+    # agent widens the window rather than concluding the web is silent.
+    # categories: scopes the search to a SearXNG vertical — e.g. "news"
+    # or "science" (research papers); instances configure their own set,
+    # so values pass through unvalidated. A string or anything Array-able
+    # ("news,science" form).
+    def self.search(query, time_range: nil, categories: nil)
+      time_range = normalize_time_range(time_range)
+      categories = normalize_categories(categories)
+      response = search_raw(query, time_range: time_range, categories: categories)
+      raise AllEnginesFailedError, format_engine_error(query, response, time_range: time_range) if response[:results].empty? &&
+                                                                          response[:unresponsive].any?
+
+      return format_results(response[:results]) unless response[:results].empty? && time_range
+
+      "No results found within the #{time_range} freshness window. Retry with a broader time_range or without one."
     end
 
     # The raw result list: { url:, title:, content: } entries from the
     # 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)
-      uri = URI("#{searxng_url}/search?q=#{URI.encode_www_form_component(query)}&format=json")
+    # backoff. Set max_retries to 0 to disable. See #search for
+    # time_range / categories.
+    def self.search_results(query, time_range: nil, categories: nil)
+      search_raw(query, time_range: time_range, categories: categories)[: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.
+    # time_range / categories are normalized here — the single point that
+    # builds the request — and are idempotent, so callers may pass raw or
+    # already-normalized values.
+    def self.search_raw(query, time_range: nil, categories: nil)
+      params = { q: query, format: "json" }
+      params[:time_range] = normalize_time_range(time_range) if time_range
+      params[:categories] = normalize_categories(categories) if categories
+      uri = URI("#{searxng_url}/search")
+      uri.query = URI.encode_www_form(params)
       retries = max_retries || 0
       attempt = 0
       begin
@@ -61,7 +113,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 +122,50 @@ 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. When a freshness window was set, the
+    # hint suggests broadening it.
+    def self.format_engine_error(query, response, time_range: nil)
+      lines = ["No search results for #{query.inspect} — all #{response[:unresponsive].size} engine(s) failed:"]
+      response[:unresponsive].each do |name, reason|
+        lines << "- #{name}: #{reason}"
+      end
+      hint = "Try: a simpler query, or ask-web-fetch for a known URL."
+      hint = "Try: a simpler query, a broader time_range, or ask-web-fetch for a known URL." if time_range
+      lines << hint
+      lines.join("\n")
+    end
+    private_class_method :format_engine_error
+
+    # Validates +time_range+ against TIME_RANGES (nil/blank → nil, symbols
+    # accepted). Raises ArgumentError for anything else — the request is
+    # never sent.
+    def self.normalize_time_range(time_range)
+      value = time_range.to_s.strip.downcase
+      return nil if value.empty?
+
+      raise ArgumentError, "invalid time_range #{time_range.inspect} — use one of: #{TIME_RANGES.join(', ')}" unless TIME_RANGES.include?(value)
+
+      value
+    end
+
+    # Normalizes +categories+ to SearXNG's comma-separated form —
+    # ["news", :science] → "news,science"; nil/blank → nil. Values pass
+    # through unvalidated: SearXNG instances configure their own category
+    # set, and a bad one degrades to a clean empty result, not a failure.
+    def self.normalize_categories(categories)
+      value = Array(categories).map { |c| c.to_s.strip.downcase }.reject(&:empty?).uniq.join(",")
+      value.empty? ? nil : value
+    end
+
+    # 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 +173,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.6.0
 platform: ruby
 authors:
 - Kaka Ruto