ask-web-search 0.8.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1b83b3aa3b4e051445e316284580fa85a0d478bb5256b60c87e14031e60c6130
-  data.tar.gz: '0168f632c9d32eb42996d55f197cf2a322ad86f839b7698788c9f0cfc2e8ba87'
+  metadata.gz: b1b6fbfe4321cb25a1da21bfcdb45c3a4817c50c27edae5adc429b6383950a2d
+  data.tar.gz: fb594f9d216c1a474248f5c2ac2209404fae1566d14c8863bb2e1202c3dcfa5b
 SHA512:
-  metadata.gz: 5e5cb4c7817665ca81783898ea4709e7883786f5db18778ec09a7375ef4f2abadecc77c001900a48aea277e3b18859e11a9b2c1f1cc97ecb8ded1fb6e29478f7
-  data.tar.gz: 889707ff4c5f114ffbd2340cd667de622c281374e20fdee3023280706b8bad91ad3d46b02091274779a2e1ce8ed7acbb5bcad7669cb0f616765af50d6244a282
+  metadata.gz: b2517586f4020e29f66c2d0130cb315395db80209896ef1203af37f2c92c2b6b59b8b9380bf4646c3217677eb70b4bec22a30ceb92460dc072aba8f8c2f12bee
+  data.tar.gz: e273bea7c63d08c06957e9b7cf8562b951a563ad8dc0c6d42258389995f2d057a58743db01c6fc53082fc9f568551ab614e737fb744c5b4ea4a84c6c61466fb7

data/README.md

@@ -9,21 +9,9 @@ depends only on ask-tools.
 
 ## Backends
 
-Two interchangeable backends, chosen automatically at call time:
+Two interchangeable backends:
 
-1. **TinyFish (recommended — no self-hosting).** Get a free API key at
-   [agent.tinyfish.ai](https://agent.tinyfish.ai/api-keys) and export it:
-
-   ```sh
-   export TINYFISH_API_KEY=...
-   ```
-
-   That's the whole setup — no Docker, no SearXNG instance. Live
-   browser-rendered results, freshness windows, and the news /
-   research-paper verticals all work out of the box.
-
-2. **SearXNG (self-hosted).** For users who want queries to stay local,
-   and as the automatic fallback when TinyFish fails: a running
+1. **SearXNG (the default — for everyone).** Queries go to a local
    [SearXNG](https://docs.searxng.org/) instance, default
    `http://localhost:8888`. Start one with Docker:
 
@@ -34,14 +22,32 @@ Two interchangeable backends, chosen automatically at call time:
    Or use the provided `docker-compose.yml` in the `searxng` directory of
    this repository.
 
-Routing rules:
+2. **TinyFish (opt-in — for people who'd rather hold an API key than set
+   up SearXNG).** Two steps: select the backend, and provide a key.
+
+   ```sh
+   export SEARCH_BACKEND=tinyfish
+   ```
+
+   Get a free key (no credit card) at
+   [agent.tinyfish.ai](https://agent.tinyfish.ai/api-keys) and store it —
+   either in `~/.ask/credentials.yml` via ask-auth (one line:
+   `tinyfish_api_key: <key>`, file is 0600) or `export
+   TINYFISH_API_KEY=...`. Selecting tinyfish without a key raises an
+   onboarding error that says exactly that; holding a key without
+   selecting does nothing — SearXNG stays the default.
+
+Selection precedence (first match wins):
+
+1. `TINYFISH_SEARCH=0` — a hard-off that forces SearXNG
+2. `Ask::WebSearch.backend = :tinyfish | :searxng` (in code)
+3. `SEARCH_BACKEND=tinyfish | searxng` (env)
+4. default → SearXNG
 
-- `TINYFISH_API_KEY` set → TinyFish primary; if TinyFish fails **and** a
-  SearXNG endpoint is explicitly configured, the call falls back to
-  SearXNG automatically (combined errors surface both failures).
-- No key → SearXNG only, exactly as in 0.6.x.
-- `TINYFISH_SEARCH=0` disables TinyFish outright (SearXNG only, even
-  with a key).
+When the tinyfish backend fails (network, rate limit) and a SearXNG
+endpoint is explicitly configured, the call falls back to SearXNG
+automatically — combined errors surface both failures. Invalid backend
+names raise `ArgumentError` listing the valid ones.
 
 ## Installation
 
@@ -52,7 +58,8 @@ gem "ask-web-search"
 ## Configuration
 
 ```sh
-export TINYFISH_API_KEY=...   # TinyFish (recommended): free key, instant search
+export SEARCH_BACKEND=tinyfish   # opt in to TinyFish (default: searxng)
+export TINYFISH_API_KEY=...      # TinyFish key (or tinyfish_api_key: in ~/.ask/credentials.yml)
 export SEARXNG_URL=http://localhost:8888   # SearXNG endpoint (default shown)
 ```
 

data/lib/ask/web_search/version.rb

@@ -1,5 +1,5 @@
 module Ask
   module WebSearch
-    VERSION = "0.8.0"
+    VERSION = "0.9.0"
   end
 end

data/lib/ask/web_search.rb

@@ -7,13 +7,15 @@ require_relative "web_search/version"
 
 module Ask
   # Searches the web and returns the results as clean, numbered markdown
-  # for LLM consumption. Two interchangeable backends: TinyFish's hosted
-  # search API — primary when TINYFISH_API_KEY is set, so newcomers need
-  # no self-hosted infrastructure — and a local SearXNG instance for
-  # self-hosters, which is also the automatic fallback when TinyFish
-  # fails. The capability layer: one entry point (WebSearch.search).
-  # Tool framing — name, parameter schema, result wrapping — lives with
-  # the consumers (the MCP server, the agents) that call this library.
+  # for LLM consumption. Two interchangeable backends: a local SearXNG
+  # instance — the default path for everyone — and TinyFish's hosted
+  # search API, strictly opt-in (SEARCH_BACKEND=tinyfish + a free API
+  # key) for users who'd rather hold a key than run SearXNG. When the
+  # tinyfish backend fails, an explicitly configured SearXNG endpoint is
+  # still the automatic fallback. The capability layer: one entry point
+  # (WebSearch.search). Tool 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)
@@ -46,12 +48,15 @@ module Ask
     # unfiltered.
     TIME_RANGES = %w[day week month year].freeze
 
-    # TinyFish's hosted search endpoint — the primary backend for anyone
-    # holding a (free) TINYFISH_API_KEY, so no SearXNG instance is needed.
-    # The bare host root per the official docs curl example; the
-    # /client.search.query path seen on the marketing pages 404s.
+    # TinyFish's hosted search endpoint — available when the tinyfish
+    # backend is selected (SEARCH_BACKEND=tinyfish). The bare host root
+    # per the official docs curl example; the /client.search.query path
+    # seen on the marketing pages 404s.
     TINYFISH_SEARCH_URL = "https://api.search.tinyfish.ai"
 
+    # The selectable backends (see .backend for how one is chosen).
+    BACKENDS = %w[searxng tinyfish].freeze
+
     # Our time_range → TinyFish's recency_minutes (SearXNG's month/year
     # are approximate engine filters anyway; these are the equivalents).
     TIME_RANGE_TO_MINUTES = {
@@ -72,6 +77,41 @@ module Ask
       "research_paper" => "research_paper"
     }.freeze
 
+    # The search backend — :searxng (the default path for everyone) or
+    # :tinyfish (opt-in for users who'd rather hold an API key than run
+    # SearXNG). Selection precedence:
+    #
+    #   1. TINYFISH_SEARCH=0 — a hard-off that forces :searxng
+    #   2. backend= setter (Ask::WebSearch.backend = :tinyfish)
+    #   3. SEARCH_BACKEND env ("searxng" | "tinyfish")
+    #   4. default :searxng
+    def self.backend
+      return :searxng if ENV["TINYFISH_SEARCH"] == "0"
+      return @backend if defined?(@backend) && @backend
+
+      raw = ENV["SEARCH_BACKEND"]
+      return :searxng if raw.to_s.empty?
+
+      normalize_backend(raw)
+    end
+
+    # Selects the backend in code (:searxng / :tinyfish, or nil to fall
+    # back to env/default). Raises ArgumentError for anything else —
+    # config-time failure instead of a silently ignored value.
+    def self.backend=(name)
+      @backend = name.nil? ? nil : normalize_backend(name)
+    end
+
+    def self.normalize_backend(name)
+      value = name.to_s.strip.downcase
+      unless BACKENDS.include?(value)
+        raise ArgumentError, "invalid backend #{name.inspect} — use one of: #{BACKENDS.join(', ')}"
+      end
+
+      value.to_sym
+    end
+    private_class_method :normalize_backend
+
     # The TinyFish API key: ask-auth's chain when that gem is present
     # (env override → ~/.ask/credentials.yml → …), raw ENV otherwise.
     # nil when nothing resolves.
@@ -83,14 +123,12 @@ module Ask
       nil
     end
 
-    # True when TinyFish should be the primary backend: a key resolves
-    # (#tinyfish_api_key) and TINYFISH_SEARCH=0 has not disabled it.
-    # Read fresh on every call so tests and config reloads don't need
-    # memo resets.
+    # True when searches should go to TinyFish — i.e. the backend was
+    # explicitly selected. Read fresh on every call so tests and config
+    # reloads don't need memo resets. Holding a key alone does NOT
+    # opt in: SearXNG stays the default path.
     def self.use_tinyfish?
-      return false if ENV["TINYFISH_SEARCH"] == "0"
-
-      !tinyfish_api_key.to_s.empty?
+      backend == :tinyfish
     end
 
     # True when a SearXNG endpoint was configured explicitly (SEARXNG_URL
@@ -151,14 +189,15 @@ module Ask
     end
 
     # The full response: { results: [...], unresponsive: [[name,
-    # reason], ...] }. Routes to TinyFish when #use_tinyfish?, falling
-    # back to SearXNG (only when explicitly configured) if TinyFish
-    # raises; otherwise straight to SearXNG — byte-for-byte the 0.6.x
-    # behavior for keyless users. Same retry logic either way, but
-    # preserves the engine diagnostics the caller needs to explain an
-    # empty result. time_range / categories are normalized by the
-    # backends that build requests — idempotent, so callers may pass
-    # raw or already-normalized values.
+    # reason], ...] }. Routes to TinyFish when #use_tinyfish? (the
+    # opt-in tinyfish backend — a keyless selection raises its
+    # onboarding error; a transport failure falls back to SearXNG when
+    # explicitly configured), otherwise to SearXNG — the default path
+    # for everyone. Same retry logic either way, but preserves the
+    # engine diagnostics the caller needs to explain an empty result.
+    # time_range / categories are normalized by the backends that build
+    # requests — idempotent, so callers may pass raw or
+    # already-normalized values.
     def self.search_raw(query, time_range: nil, categories: nil)
       return searxng_search_raw(query, time_range: time_range, categories: categories) unless use_tinyfish?
 
@@ -207,6 +246,14 @@ module Ask
     # catches). time_range maps to recency_minutes; the FIRST
     # recognized categories value maps to domain_type.
     def self.tinyfish_search_raw(query, time_range: nil, categories: nil)
+      key = tinyfish_api_key
+      if key.to_s.empty?
+        raise Error, "TinyFish backend selected (SEARCH_BACKEND=tinyfish) but no API key resolves. " \
+                     "Get a free key at https://agent.tinyfish.ai/api-keys, then add " \
+                     "`tinyfish_api_key: <key>` to ~/.ask/credentials.yml or export " \
+                     "TINYFISH_API_KEY — or drop SEARCH_BACKEND to stay on the default SearXNG path."
+      end
+
       params = { query: query }
       normalized_range = normalize_time_range(time_range)
       params[:recency_minutes] = TIME_RANGE_TO_MINUTES[normalized_range] if normalized_range
@@ -224,7 +271,7 @@ module Ask
         http.open_timeout = 5
         http.read_timeout = 10
         req = Net::HTTP::Get.new(uri)
-        req["X-API-Key"] = tinyfish_api_key
+        req["X-API-Key"] = key
         req["User-Agent"] = "ask-web-search/#{Ask::WebSearch::VERSION}"
         res = http.request(req)
         raise Error, "TinyFish returned #{res.code}: #{res.body[0, 200]}" unless res.code.start_with?("2")

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ask-web-search
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.9.0
 platform: ruby
 authors:
 - Kaka Ruto
@@ -93,11 +93,12 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '13.0'
-description: 'Web search returning results as clean numbered markdown. Two backends:
-  TinyFish''s hosted API (primary with TINYFISH_API_KEY — no self-hosting) and a local
-  SearXNG instance (SEARXNG_URL, also the automatic fallback). The capability layer
-  (WebSearch.search); the native Ask::Tools::WebSearch agent tool is an optional integration
-  that registers when ask-tools is present.'
+description: 'Web search returning results as clean numbered markdown. Two selectable
+  backends: a local SearXNG instance (SEARXNG_URL, the default path for everyone)
+  and TinyFish''s hosted API (opt-in: SEARCH_BACKEND=tinyfish plus a TINYFISH_API_KEY
+  or ask-auth credentials key). The capability layer (WebSearch.search); the native
+  Ask::Tools::WebSearch agent tool is an optional integration that registers when
+  ask-tools is present.'
 email:
 - kaka@myrrlabs.com
 executables: []