ask-web-search 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d8bd1c41d870cf5aa9f13332ba6b2d43fbcf6d6bbebb13e5390f2d9e8c0f6529
-  data.tar.gz: b1cc5035874cd122e9d4a8d1c4feec1bc1d146d12842714cbfe4672c43a4dba6
+  metadata.gz: 8843934817bb67da278cc649beebc5beb3ed6af85653209511108f72f06b1da5
+  data.tar.gz: c2f2ab3b68106eb47806824b7e8d86153cf934159024535be0c7eb3b3bbc4f5b
 SHA512:
-  metadata.gz: b80273643aa1f7e4a875832dcef9bfec8a2df3886af9be0f92651f55e8b6873364b59586a9bfa9e6ba5eb95394b686425ca7e7032ad69677ba1fab085fb42498
-  data.tar.gz: abae84930f02b3adbe06a136b676a79bb8e3ae2416aa7c94fd94da2d22862672ae35818b92434cb03a163e7a2770f63bfcfd7d10766a447a5f4de97fdf35a57d
+  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.5.0"
+    VERSION = "0.6.0"
   end
 end

data/lib/ask/web_search.rb

@@ -36,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)
 
@@ -52,27 +58,49 @@ module Ask
     # 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)
-      response = search_raw(query)
-      raise AllEnginesFailedError, format_engine_error(query, response) if response[:results].empty? &&
+    #
+    # 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?
 
-      format_results(response[:results])
+      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)
-      search_raw(query)[:results]
+    # 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.
-    def self.search_raw(query)
-      uri = URI("#{searxng_url}/search?q=#{URI.encode_www_form_component(query)}&format=json")
+    # 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
@@ -97,17 +125,41 @@ module Ask
     # 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)
+    # 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
-      lines << "Try: a simpler query, or ask-web-fetch for a known URL."
+      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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ask-web-search
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Kaka Ruto