pikuri-core 0.0.7 → 0.1.0

data/lib/pikuri/tool/search/engines.rb

@@ -2,118 +2,255 @@
 
 module Pikuri
   class Tool
-    # Namespace for the web-search stack used by {Tool::WebSearch}: per-
-    # provider modules ({DuckDuckGo}, {Brave}, {Exa}), the {Result} value
-    # object they all return, the cross-provider {Engines} cascade with
-    # its on-disk cache, and the shared {RateLimiter} a provider can wire
-    # in to back off when a quota header says so.
+    # Namespace for the web-search stack behind {Tool::WebSearch}: per-provider
+    # modules ({DuckDuckGo}, {Brave}, {Exa}), the {Result} they return, the
+    # {Engines} cascade with its on-disk cache, and the shared {RateLimiter}.
     module Search
-      # Search-orchestration object: the cascade across configured
-      # providers, the result cache, and the {Unavailable} protocol marker
-      # the cascade uses to fall back. The LLM-facing tool itself is built
-      # by {Tool::WebSearch.build}, which constructs one of these and wires
-      # its {#search} into a {Tool}. Each {Tool::Search} provider module
-      # ({DuckDuckGo}, {Brave}, {Exa}) raises {Unavailable} when it wants
-      # the cascade to try the next one.
+      # Search-orchestration object: the cascade across selected providers, the
+      # result cache, and the {Unavailable} marker the cascade falls back on.
+      # {Tool::WebSearch.build} constructs one and wires its {#search} into a
+      # {Tool}. Each provider raises {Unavailable} to hand off to the next.
+      #
+      #   Engines.new(engines: [:brave], brave_key: 'BSA...')  # Brave alone
+      #   Engines.new(brave_key: 'BSA...')                     # DuckDuckGo + Brave
+      #   Engines.new                                          # DuckDuckGo alone
+      #
+      # {.resolve} owns which engines that yields and which selections are
+      # refused; {.config_from_h} maps a config file's +search:+ block onto
+      # these keywords.
       #
       # == Provider keys are constructor config, not environment
       #
-      # Brave and Exa are paid and need an API key; DuckDuckGo needs none.
-      # An {Engines} is constructed with the keys it should use
-      # (+brave_key:+ / +exa_key:+, both optional) — pikuri reads no key
-      # from the environment, so the only providers in the cascade are
-      # DuckDuckGo plus whichever keyed providers the host actually
-      # configured. The host sources those keys however it likes (the
-      # bundled +bin/+ examples load a JSON config file by convention); see
-      # CLAUDE.md "Environment is not a secret store".
+      # Brave and Exa are paid and need a key; DuckDuckGo needs none. An
+      # {Engines} is built with the keys it should use (+brave_key:+ /
+      # +exa_key:+, both optional) — pikuri reads no key from the environment,
+      # so a host supplies them. See CLAUDE.md "Environment is not a secret
+      # store".
       class Engines
-        # Subsystem logger; set its level with +PIKURI_LOG_ENGINES+
-        # (e.g. +PIKURI_LOG_ENGINES=debug+) or the global +PIKURI_LOG+.
+        # Subsystem logger; level via +PIKURI_LOG_ENGINES+ or +PIKURI_LOG+.
         #
         # @return [Logger]
         LOGGER = Pikuri.logger_for('Engines')
 
-        # Raised by a provider when it is temporarily unavailable (rate-limited,
-        # bot-blocked, quota-exhausted, or otherwise saying "try again later"
-        # rather than "your request is wrong"). The cascade in {#search}
-        # catches this and tries the next provider; any other exception bubbles
-        # up unchanged so genuine bugs and config errors stay visible.
+        # Every engine name accepted in an +engines:+ selection, in the order
+        # {#providers} reports them. Presentation only — {#search} shuffles.
+        #
+        # @return [Array<Symbol>]
+        ENGINE_NAMES = %i[duckduckgo brave exa].freeze
+
+        # Engine name → the constructor keyword carrying its API key. Naming
+        # one of these without its key is a refusal ({.resolve}); DuckDuckGo is
+        # absent because it needs none.
+        #
+        # @return [Hash{Symbol => Symbol}]
+        KEYED_ENGINES = { brave: :brave_key, exa: :exa_key }.freeze
+
+        # The fields {.config_from_h} accepts from a config file's +search:+
+        # block, matching this class's keywords.
+        #
+        # @return [Array<Symbol>]
+        CONFIG_FIELDS = %i[engines brave_key exa_key].freeze
+
+        # Raised by a provider that is temporarily unavailable (rate-limited,
+        # bot-blocked, quota-exhausted — "try again later", not "your request is
+        # wrong"). The {#search} cascade catches it and tries the next provider;
+        # anything else bubbles up so genuine bugs stay visible.
         class Unavailable < StandardError; end
 
-        # Process-shared on-disk cache backing {#search}'s default. Kept at
-        # class level (not per-instance) so every engine dedupes answered
-        # queries into one directory; the constructor's +cache:+ parameter
-        # injects a different store for tests. Exposed as a method so specs
-        # can swap it for {UrlCache::NULL} without touching the instance.
+        # Process-shared on-disk cache backing {#search}, at class level so every
+        # engine dedupes into one directory; the constructor's +cache:+ injects a
+        # different store for tests.
         #
         # @return [UrlCache, #fetch]
         CACHE = UrlCache.new(ttl: UrlCache::DEFAULT_TTL, dir: "#{UrlCache::ROOT_DIR}/web_search")
-        # Accessor for {CACHE}, used as the constructor's +cache:+ default;
-        # specs override this to swap in {UrlCache::NULL}.
+        # Accessor for {CACHE}, the constructor's +cache:+ default; specs swap in
+        # {UrlCache::NULL}.
         #
         # @return [UrlCache, #fetch]
         def self.cache
           CACHE
         end
 
-        # Builds the provider cascade once: {DuckDuckGo} always (no key
-        # needed), plus {Brave} / {Exa} when their key was supplied
-        # (non-blank). Each keyed provider is constructed with its key, so
-        # from here on every provider is just an object answering +#search+
-        # / +#label+ — the cascade in {#search} treats them uniformly.
-        #
-        # @param brave_key [String, nil] Brave Search subscription token;
-        #   non-blank ⇒ Brave joins the cascade. +nil+/blank ⇒ not configured.
-        # @param exa_key [String, nil] Exa API key; non-blank ⇒ Exa joins the
-        #   cascade. +nil+/blank ⇒ not configured.
-        # @param cache [UrlCache, #fetch] result store memoizing answered
-        #   queries; defaults to the process-shared {.cache}.
+        # Resolve an +engines:+ selection into the engine names to build,
+        # refusing a selection that cannot work:
+        #
+        #   resolve(engines: nil, brave_key: 'B')          # => [:duckduckgo, :brave]
+        #   resolve(engines: nil)                          # => [:duckduckgo]
+        #   resolve(engines: %w[brave], brave_key: 'B')    # => [:brave]
+        #   resolve(engines: [:exa], brave_key: 'B')       # raises — exa has no key
+        #
+        # +nil+ means "whatever the keys say": DuckDuckGo plus every engine
+        # whose key is present, which is what a host that never heard of
+        # +engines:+ gets. An explicit list is a **set** — it is normalized to
+        # {ENGINE_NAMES} order and {#search} shuffles it per call anyway, so
+        # +[brave, duckduckgo]+ expresses no preference for Brave. Names are
+        # matched case-insensitively.
+        #
+        # Supplying a key without listing its engine is fine — parking a key
+        # you are not using today is not a mistake.
+        #
+        # @param engines [Array<String, Symbol>, nil] engine names, or +nil+ to
+        #   derive the set from the keys.
+        # @param brave_key [String, nil] Brave token; blank counts as absent.
+        # @param exa_key [String, nil] Exa key; blank counts as absent.
+        # @return [Array<Symbol>] names drawn from {ENGINE_NAMES}, in that order.
+        # @raise [ArgumentError] if +engines+ is not an Array, is empty, holds
+        #   an unknown or repeated name, or names a {KEYED_ENGINES} engine
+        #   whose key is blank.
+        def self.resolve(engines:, brave_key: nil, exa_key: nil)
+          keys = { brave: brave_key, exa: exa_key }
+          keyless = ->(name) { KEYED_ENGINES.key?(name) && keys[name].to_s.strip.empty? }
+          return ENGINE_NAMES.reject(&keyless) if engines.nil?
+
+          unless engines.is_a?(Array) && !engines.empty?
+            # A list of engine names is safe to echo; anything else might be a
+            # key the writer put in the wrong field, so show only its class.
+            got = engines.is_a?(Array) ? engines.inspect : engines.class
+            raise ArgumentError, 'search engines: expected a non-empty list of engine names ' \
+                                 "(known: #{ENGINE_NAMES.join(', ')}), got #{got}"
+          end
+
+          names = engines.map { |name| name.to_s.strip.downcase.to_sym }
+          refuse_unknown(names)
+          refuse_repeats(names)
+          refuse_keyless(names.select(&keyless))
+          ENGINE_NAMES & names
+        end
+
+        # @param names [Array<Symbol>] the requested engine names.
+        # @return [void]
+        # @raise [ArgumentError] if any name is not in {ENGINE_NAMES}.
+        def self.refuse_unknown(names)
+          unknown = names - ENGINE_NAMES
+          return if unknown.empty?
+
+          raise ArgumentError, "search engines: unknown engine(s) #{unknown.join(', ')} — " \
+                               "known engines are #{ENGINE_NAMES.join(', ')}"
+        end
+
+        # @param names [Array<Symbol>] the requested engine names.
+        # @return [void]
+        # @raise [ArgumentError] if any name appears twice (which would put one
+        #   provider into the cascade twice, weighting the shuffle).
+        def self.refuse_repeats(names)
+          repeated = names.tally.select { |_, count| count > 1 }.keys
+          return if repeated.empty?
+
+          raise ArgumentError, "search engines: #{repeated.join(', ')} listed more than once"
+        end
+
+        # @param keyless [Array<Symbol>] requested engines with no usable key.
+        # @return [void]
+        # @raise [ArgumentError] unless +keyless+ is empty.
+        def self.refuse_keyless(keyless)
+          return if keyless.empty?
+
+          needed = keyless.map { |name| "#{name} needs #{KEYED_ENGINES[name]}" }.join(', ')
+          raise ArgumentError, "search engines: #{needed} — supply the key or drop the engine from the list"
+        end
+
+        # Map a config file's +search:+ block onto this class's keywords, so a
+        # host hands over what it read:
+        #
+        #   # ~/.pikuri-examples-config.yaml
+        #   search:
+        #     brave_key: BSA...
+        #     exa_key: xyz
+        #     engines: [brave, duckduckgo]
+        #
+        #   Tool::WebSearch.from_h(YAML.safe_load_file(path)['search'])
+        #
+        # Nothing here knows what YAML is; a host reading TOML, JSON or its own
+        # settings object uses the same method. Every field is validated rather
+        # than coerced, because the person writing a config file cannot
+        # type-check it — and a mistyped engine name that silently meant "no
+        # Brave" would show up only as worse search results.
+        #
+        # @param config [Hash{String, Symbol => Object}, nil] the +search:+
+        #   block, with String or Symbol keys. +nil+ — what a host reading an
+        #   absent config key gets — yields an empty Hash, so no caller needs a
+        #   +|| {}+.
+        # @return [Hash{Symbol => Object}] +engines:+ / +brave_key:+ /
+        #   +exa_key:+ keywords for {#initialize} or {Tool::WebSearch.build}.
+        # @raise [ArgumentError] on a non-Hash, an unknown field, or a key field
+        #   that is not a String.
+        def self.config_from_h(config)
+          return {} if config.nil?
+
+          unless config.is_a?(Hash)
+            raise ArgumentError, 'search config: expected a Hash of ' \
+                                 "#{CONFIG_FIELDS.join(', ')}, got #{config.class}"
+          end
+
+          fields = config.transform_keys(&:to_sym)
+          unknown = fields.keys - CONFIG_FIELDS
+          unless unknown.empty?
+            raise ArgumentError, "search config: unknown field(s) #{unknown.join(', ')} — " \
+                                 "known fields are #{CONFIG_FIELDS.join(', ')}"
+          end
+          KEYED_ENGINES.each_value do |field|
+            value = fields[field]
+            next if value.nil? || value.is_a?(String)
+
+            # The class, never the value: an error message about a key field is
+            # one paste away from a bug report.
+            raise ArgumentError, "search config: #{field} must be a String, got #{value.class}"
+          end
+          fields
+        end
+
+        # Builds the provider cascade once, from the engines {.resolve} selects.
+        # From here each provider is just an object answering
+        # +#search+/+#label+.
+        #
+        # @param engines [Array<String, Symbol>, nil] engine names; +nil+
+        #   derives the set from the keys. See {.resolve}.
+        # @param brave_key [String, nil] Brave token.
+        # @param exa_key [String, nil] Exa key.
+        # @param cache [UrlCache, #fetch] result store; defaults to {.cache}.
         # @return [Engines]
-        def initialize(brave_key: nil, exa_key: nil, cache: self.class.cache)
-          @providers = [DuckDuckGo.new]
-          @providers << Brave.new(api_key: brave_key) unless brave_key.to_s.strip.empty?
-          @providers << Exa.new(api_key: exa_key) unless exa_key.to_s.strip.empty?
+        # @raise [ArgumentError] as {.resolve}.
+        def initialize(engines: nil, brave_key: nil, exa_key: nil, cache: self.class.cache)
+          @providers = self.class.resolve(engines: engines, brave_key: brave_key, exa_key: exa_key).map do |name|
+            case name
+            when :duckduckgo then DuckDuckGo.new
+            when :brave then Brave.new(api_key: brave_key)
+            when :exa then Exa.new(api_key: exa_key)
+            end
+          end
           @cache = cache
           @last_logged_providers = nil
         end
 
-        # The provider instances this engine cascades across, in
-        # declaration order (the cascade itself shuffles them per call).
-        #
-        # @return [Array<#search, #label>] configured provider instances
+        # @return [Array<#search, #label>] the selected provider instances, in
+        #   {ENGINE_NAMES} order (the cascade shuffles them per call).
         attr_reader :providers
 
-        # Run +query+ through the configured providers in random order, falling
-        # back to the next one each time a provider raises {Unavailable}. The
-        # shuffle spreads load so a single provider isn't always hit first
-        # (and exhausted first); revisit if it stops being the right default.
-        #
-        # The query is whitespace-trimmed and runs of whitespace collapsed
-        # to a single space before the cascade runs. The winning provider's
-        # +Array<Result>+ is rendered into smolagents-style Markdown here
-        # (+"## Search Results"+ header, then +[title](url)\nbody+ entries
-        # joined by blank lines; an empty array becomes +"No results found."+),
-        # and the rendered Markdown is cached on disk via {#initialize}'s
-        # +cache:+, keyed by the cleaned query. A cache hit short-circuits the
-        # cascade entirely (and benefits whichever provider would have
-        # answered next time too — once a query is cached, the cooldown state
-        # of the original answering provider no longer matters). +max_results+
-        # is not part of the cache key, so callers passing a non-default value
-        # may get a result rendered with the previously-cached size.
-        #
-        # If every provider reports temporary unavailability, returns an
-        # +"Error: ..."+ string instead of raising — same convention as
-        # {Tool::Calculator.calculate}, so the agent loop can feed the failure
-        # back to the model as the next observation. Any non-{Unavailable}
-        # exception (network error, parser failure, malformed response, bad
-        # API key) bubbles up to the caller.
+        # Run +query+ through the providers in random order, falling back on each
+        # {Unavailable}. The shuffle spreads load so one provider isn't always
+        # hit (and exhausted) first. The query is whitespace-normalized first;
+        # the winning provider's +Array<Result>+ is rendered to Markdown and
+        # cached on disk keyed by the cleaned query (a hit short-circuits the
+        # cascade). +max_results+ is *not* in the cache key, so a non-default
+        # value may return a previously-cached size.
+        #
+        # If every provider is unavailable, returns an +"Error: ..."+ string
+        # (the tool convention) rather than raising. Any non-{Unavailable}
+        # exception (network, parser, bad key) bubbles up.
         #
         # @param query [String] search query
-        # @param max_results [Integer] maximum number of result entries
-        # @return [String] Markdown-formatted result list, or +"Error: ..."+
-        #   when all providers are exhausted
+        # @param max_results [Integer] maximum result entries
+        # @param cancellable [Pikuri::Agent::Control::Cancellable, nil] handed
+        #   to each provider so its {RateLimiter} pacing wait is interruptible.
+        #   A cache hit never reaches a provider, so it never waits at all.
+        # @return [String] Markdown result list, or +"Error: ..."+ when all
+        #   providers are exhausted
         # @raise [ArgumentError] if the query is empty after normalization
-        def search(query, max_results:)
+        # @raise [Pikuri::Agent::Control::Cancellable::Cancelled] if
+        #   +cancellable+ trips while a provider is pacing. It is *not* caught
+        #   as a provider failure — the cascade stops rather than trying the
+        #   next one, and nothing is cached.
+        def search(query, max_results:, cancellable: Pikuri::Agent::Control::Cancellable::NEVER)
           cleaned = query.to_s.strip.gsub(/\s+/, ' ')
           raise ArgumentError, 'query is empty' if cleaned.empty?
 
@@ -127,16 +264,15 @@ module Pikuri
             results = nil
             chosen = nil
             current_providers.shuffle.each do |provider|
-              results = provider.search(cleaned, max_results: max_results)
+              results = provider.search(cleaned, max_results: max_results, cancellable: cancellable)
               chosen = provider
               break
             rescue Unavailable => e
               failures << "#{provider.label} (#{e.message})"
             end
             # Raise so {UrlCache#fetch} does NOT persist the all-unavailable
-            # message — otherwise that string would block every future search
-            # for this query until the TTL expires. The outer +rescue+ turns
-            # the raise back into the calculator-style "Error: …" string.
+            # message — else it would block every future search for this query
+            # until the TTL expires. The outer rescue turns it into "Error: …".
             chosen or raise Unavailable, "all search providers temporarily unavailable: #{failures.join('; ')}"
 
             LOGGER.info do
@@ -152,26 +288,23 @@ module Pikuri
 
         private
 
-        # Render an +Array<Result>+ into the smolagents-style Markdown the
-        # LLM consumes: +"## Search Results"+ header, then +[title](url)\nbody+
-        # entries joined by blank lines. An empty array becomes the
-        # +"No results found."+ stub so the agent still gets a real
-        # observation to act on.
+        # Render an +Array<Result>+ into the smolagents-style Markdown the LLM
+        # consumes (+"## Search Results"+ header, then +[title](url)\nbody+
+        # joined by blank lines). Empty → the +"No results found."+ stub.
         #
         # @param results [Array<Result>] hits from the winning provider
-        # @return [String] Markdown-formatted result list
+        # @return [String] Markdown result list
         def render(results)
           return "## Search Results\n\nNo results found." if results.empty?
 
           "## Search Results\n\n" + results.map { |r| "[#{r.title}](#{r.url})\n#{r.body}" }.join("\n\n")
         end
 
-        # Emit an INFO log line listing the currently-available providers,
-        # but only when the set differs from the last one this engine
-        # logged. The memo keeps the log to one line per distinct
-        # configuration rather than one per search.
+        # INFO-log the currently-available providers, but only when the set
+        # differs from the last logged — one line per distinct configuration,
+        # not per search.
         #
-        # @param current [Array<#label>] providers returned by {#providers}
+        # @param current [Array<#label>] providers from {#providers}
         # @return [void]
         def log_providers(current)
           return if @last_logged_providers == current

data/lib/pikuri/tool/search/exa.rb

@@ -6,54 +6,40 @@ require 'json'
 module Pikuri
   class Tool
     module Search
-      # Performs an Exa search via the official +/search+ endpoint and
-      # returns the hits as a list of {Result} rows. Split into a thin HTTP
-      # fetch (#search) and a pure parser (.parse) so tests can exercise
-      # the parser against fixture JSON without hitting the network. The
-      # cascade in {Engines#search} owns the final Markdown rendering.
+      # Performs an Exa search via the official +/search+ endpoint, returning
+      # hits as {Result} rows. Split into a thin HTTP fetch (#search) and a pure
+      # parser (.parse) so tests exercise the parser against fixture JSON.
+      # {Engines#search} owns the final Markdown rendering.
       #
-      # A class constructed with the API key it should use
-      # (+Exa.new(api_key:)+); {Engines} builds one only when an Exa key was
-      # configured, so users who haven't registered never spend money on it,
-      # and then drives it through the same +#search+ / +#label+ interface
-      # as every other provider. pikuri reads no key from the environment
-      # (see CLAUDE.md "Environment is not a secret store"). Get a key at
-      # https://exa.ai — the service is paid.
+      # Constructed with its API key (+Exa.new(api_key:)+); {Engines} builds one
+      # only when an Exa key was configured, so users who never registered don't
+      # spend money, then drives it through the same +#search+/+#label+
+      # interface as every provider. pikuri reads no key from the environment
+      # (CLAUDE.md "Environment is not a secret store"). Paid; key at
+      # https://exa.ai.
       #
-      # Calls request +type: "auto"+ (Exa picks neural vs keyword per
-      # query) and +contents: { highlights: true }+ so each result carries
-      # a short neural-ranked snippet — the closest analog to Brave's
-      # +description+ field, populating {Result#body} consistently across
-      # providers.
+      # Requests +type: "auto"+ (Exa picks neural vs keyword) and +contents: {
+      # highlights: true }+ so each result carries a neural-ranked snippet
+      # populating {Result#body} — the analog to Brave's +description+.
       #
       # == Privacy posture
       #
-      # Exa's Privacy Policy states +Query Data is used to improve our
-      # products and technology, including by training and fine-tuning
-      # models that power our Services+, and the Terms of Service §1.2(c)
-      # grant Exa a +perpetual and irrevocable+, +sub-licensable+,
-      # worldwide license over User Input that can be disclosed to third
-      # parties +as needed+. Business customers under a Master Subscription
-      # Agreement / DPA get carve-outs; the default pay-as-you-go API key
-      # (which is what pikuri uses) does not.
-      #
-      # Bottom line: Exa does not sell queries to data brokers, but it
-      # does mine them to train competing models, and the license it
-      # claims is effectively "do what we want with this, forever". If a
-      # query would be embarrassing or sensitive in a training set, simply
-      # don't configure an Exa key — {Engines#providers} leaves Exa out of
-      # the cascade unless its key was supplied to the constructor.
+      # Exa's Privacy Policy uses Query Data to train/fine-tune its models, and
+      # ToS §1.2(c) grants a +perpetual and irrevocable+, sub-licensable license
+      # over User Input. Business customers under an MSA/DPA get carve-outs; the
+      # default pay-as-you-go key pikuri uses does not. Bottom line: Exa mines
+      # queries to train competing models. If a query would be sensitive in a
+      # training set, don't configure an Exa key — {Engines#providers} leaves
+      # Exa out of the cascade unless its key was supplied.
       class Exa
         # @return [String] Search endpoint (POST, JSON body)
         ENDPOINT = 'https://api.exa.ai/search'
         # @return [Integer] default number of results returned, matching
         #   {DuckDuckGo::DEFAULT_MAX_RESULTS}
         DEFAULT_MAX_RESULTS = 10
-        # @return [RateLimiter] Exa is paid and doesn't aggressively
-        #   throttle, so no minimum interval is enforced. The 5-minute
-        #   cooldown still applies on {Engines::Unavailable} so the user's
-        #   budget isn't burned on doomed retries while a 429 / 5xx
-        #   condition persists.
+        # @return [RateLimiter] Exa is paid and doesn't aggressively throttle,
+        #   so no minimum interval; the 5-minute cooldown still applies on
+        #   {Engines::Unavailable} so the budget isn't burned on doomed retries.
         LIMITER = RateLimiter.new(min_interval: 0.0, cooldown: 300.0)
 
         # @param api_key [String] Exa API key. Required and non-blank:
@@ -72,28 +58,23 @@ module Pikuri
           'Exa'
         end
 
-        # Fetch results for +query+ and return them as an +Array<Result>+.
-        # Calls are circuit-broken for 5 minutes on rate-limit / unavailable
-        # responses; see {LIMITER}. The caller (typically {Engines#search})
-        # is expected to have already normalized the query and to wrap this
-        # in a result cache.
+        # Fetch results for +query+ as an +Array<Result>+. Circuit-broken for
+        # 5 minutes on rate-limit/unavailable (see {LIMITER}). The caller
+        # ({Engines#search}) normalizes the query and wraps this in a cache.
         #
         # @param query [String] search query (already normalized)
-        # @param max_results [Integer] maximum number of result entries;
-        #   passed through as Exa's +numResults+
-        # @return [Array<Result>] hits, possibly empty when Exa ran the
-        #   query and matched nothing
-        # @raise [Engines::Unavailable] when Exa returns HTTP 429
-        #   (rate limit / quota exhausted) or 5xx — "try again later"
-        #   responses the cascade in {Engines#search} can fall back from.
-        #   Also raised immediately if {LIMITER} is in cooldown. Other
-        #   non-2xx (e.g. 401/403 from a bad API key) bubble up as
-        #   +RuntimeError+ so config problems stay visible.
-        # @raise [RuntimeError] for non-rate-limit HTTP failures or when the
-        #   response shape contains no results and isn't a recognized
-        #   empty-results payload.
-        def search(query, max_results: DEFAULT_MAX_RESULTS)
-          LIMITER.call do
+        # @param max_results [Integer] max entries; Exa's +numResults+
+        # @param cancellable [Pikuri::Agent::Control::Cancellable] makes
+        #   {LIMITER}'s pacing wait interruptible; see {RateLimiter#call}.
+        # @return [Array<Result>] hits, possibly empty when Exa matched nothing
+        # @raise [Engines::Unavailable] on HTTP 429 or 5xx (the cascade falls
+        #   back from these), or immediately if {LIMITER} is in cooldown. Other
+        #   non-2xx (401/403 bad key) bubble up as +RuntimeError+.
+        # @raise [RuntimeError] for non-rate-limit HTTP failures, or an
+        #   unrecognized empty-results shape.
+        def search(query, max_results: DEFAULT_MAX_RESULTS,
+                   cancellable: Pikuri::Agent::Control::Cancellable::NEVER)
+          LIMITER.call(cancellable: cancellable) do
             response = Faraday.post(ENDPOINT) do |req|
               req.headers['x-api-key'] = @api_key
               req.headers['Content-Type'] = 'application/json'
@@ -117,25 +98,16 @@ module Pikuri
           end
         end
 
-        # Parse an Exa Search JSON response into a list of {Result} rows,
-        # where +body+ is the first non-empty +highlights+ snippet (empty
-        # when Exa returned no highlight for that result — e.g. for
-        # navigational results).
-        #
-        # When the response yields zero result entries, two cases are
-        # distinguished: a genuine "no results" payload (response carries
-        # a +requestId+ and an empty +results+ array — Exa ran the query
-        # but matched nothing) returns an empty array instead of raising,
-        # so {Engines.search} can render its standard no-results stub.
-        # Anything else (unknown shape, structured error) raises with a
-        # diagnostic so the failure surfaces.
+        # Parse an Exa JSON response into {Result} rows, +body+ the first
+        # non-empty +highlights+ snippet. A genuine "no results" payload
+        # (+requestId+ present, empty +results+) returns +[]+ so {Engines.search}
+        # renders its no-results stub; any other zero-result shape raises.
         #
         # @param json [String] response body from {ENDPOINT}
-        # @param max_results [Integer] maximum number of result entries
+        # @param max_results [Integer] max entries
         # @return [Array<Result>] hits, possibly empty on a recognized
         #   empty-results payload
-        # @raise [RuntimeError] when the response yields no result entries and
-        #   is not recognized as a genuine empty-results payload
+        # @raise [RuntimeError] on an unrecognized zero-result response
         def self.parse(json, max_results: DEFAULT_MAX_RESULTS)
           data = JSON.parse(json)
           results = Array(data['results']).take(max_results).filter_map do |r|
@@ -158,12 +130,11 @@ module Pikuri
           results
         end
 
-        # Collapse whitespace and strip; returns +nil+ for nil/empty input
-        # so the caller can fall back (typically to the URL when a result
-        # has no usable title).
+        # Collapse whitespace and strip; +nil+ for nil/empty input so the caller
+        # can fall back (e.g. to the URL when a result has no title).
         #
-        # @param text [String, nil] raw text from an Exa result field
-        # @return [String, nil] cleaned text, or +nil+ if input was blank
+        # @param text [String, nil]
+        # @return [String, nil] cleaned text, or +nil+ if blank
         def self.clean(text)
           return nil if text.nil?
 
@@ -172,10 +143,8 @@ module Pikuri
         end
         private_class_method :clean
 
-        # First non-empty entry from a +highlights+ array, cleaned. Exa
-        # returns highlights as an array sorted by relevance; we surface
-        # only the top one to keep the observation compact and match the
-        # one-line +body+ convention used by Brave / DuckDuckGo.
+        # First non-empty +highlights+ entry, cleaned. Exa sorts highlights by
+        # relevance; the top one populates +body+.
         #
         # @param highlights [Array<String>, nil] +highlights+ field
         # @return [String] cleaned snippet, or empty string if none usable
@@ -190,10 +159,9 @@ module Pikuri
         end
         private_class_method :first_highlight
 
-        # True when a parsed response with zero +results+ entries looks
-        # like Exa's own "search ran, nothing matched" payload rather than
-        # a malformed or error response. The marker is the +requestId+
-        # field, which Exa always sets on a successful request.
+        # True when a zero-+results+ response looks like Exa's own "ran, matched
+        # nothing" payload rather than an error — marked by +requestId+, which
+        # Exa always sets on success.
         #
         # @param data [Hash, Object] parsed response
         # @return [Boolean]
@@ -205,14 +173,12 @@ module Pikuri
         end
         private_class_method :genuine_no_results?
 
-        # Build an error message for a parsed response that yielded zero
-        # results. Quotes Exa's +error+ / +message+ / +detail+ field if
-        # present, otherwise truncates the raw body so the caller can see
-        # the actual payload.
+        # Build an error message for a zero-result response: quote Exa's
+        # +error+/+message+/+detail+ if present, else a truncated raw body.
         #
         # @param data [Hash, Object] parsed response
         # @param raw [String] raw response body
-        # @return [String] human-readable diagnostic to feed to +raise+
+        # @return [String] diagnostic to feed to +raise+
         def self.diagnose_empty(data, raw)
           if data.is_a?(Hash) && (msg = data['error'] || data['message'] || data['detail'])
             return "Exa Search returned an error: #{msg}"