pikuri-core 0.0.5 → 0.0.7

data/lib/pikuri/tool/scraper.rb

@@ -0,0 +1,186 @@
+# frozen_string_literal: true
+
+require 'faraday'
+require 'stringio'
+require 'uri'
+
+module Pikuri
+  class Tool
+    # HTTP side of the web tools ({Tool::WEB_SCRAPE} and {Tool::FETCH}):
+    # GET the URL with a real-browser User-Agent, follow redirects, and
+    # hand the response body to {Pikuri::Extractor.extract} with the
+    # response's +Content-Type+ as the hint. HTML/XHTML render via
+    # {Extractor::HTML}, any other +text/*+ type passes through
+    # verbatim, and plug-in extractors extend the set (with pikuri-pdf
+    # registered, +application/pdf+ extracts — by header or by +%PDF-+
+    # magic, so a PDF served under a lying header still works); the
+    # remaining types raise {FetchError} so the LLM observes the
+    # failure instead of receiving an empty rendering.
+    #
+    # Split into a thin HTTP fetch ({.fetch}) and the extraction
+    # wrapper ({.visit}) so tests can drive each piece in isolation and
+    # {Tool::Fetch} can reuse the HTTP half without the extraction
+    # pass. Nothing here knows about the LLM; the tools that wrap this
+    # module own caching and truncation and turn rendered Markdown (or
+    # {FetchError}) into the next observation.
+    module Scraper
+      # Raised when a URL cannot be rendered into Markdown text — HTTP
+      # non-2xx, network failure, redirect-loop, missing +Location+,
+      # unsupported content-type, or a parse failure that reads as "try
+      # a different URL" to the LLM. Catching this in
+      # {Tool::WEB_SCRAPE} / {Tool::FETCH} turns the failure into an
+      # +"Error: ..."+ observation; anything else bubbles up so genuine
+      # bugs stay visible.
+      class FetchError < StandardError; end
+
+      # @return [String] User-Agent sent with each request; many sites
+      #   reject requests with no UA or an obvious bot UA
+      USER_AGENT = 'Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 ' \
+                   '(KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36'
+      # @return [String] +Accept+ header sent with each request, so
+      #   servers that content-negotiate hand back something we can use:
+      #   rendered HTML first, +application/pdf+ for hosts with a PDF
+      #   extractor registered, then any +text/*+ for the verbatim
+      #   pass-through arm.
+      ACCEPT = 'text/html,application/xhtml+xml,application/pdf,text/*;q=0.8'
+      # @return [Integer] maximum number of HTTP redirects to follow
+      #   before giving up
+      MAX_REDIRECTS = 5
+      # @return [Integer] connect timeout in seconds for the underlying
+      #   Faraday request
+      OPEN_TIMEOUT = 10
+      # @return [Integer] read timeout in seconds for the underlying
+      #   Faraday request
+      READ_TIMEOUT = 20
+
+      # @return [Integer] maximum number of characters of an error
+      #   response body to include in a {FetchError} message. The body is
+      #   often a multi-kilobyte HTML challenge page (Cloudflare, WAF
+      #   interstitial, etc.); a short excerpt tells the LLM what kind of
+      #   page came back without flooding the next observation.
+      ERROR_BODY_EXCERPT = 200
+
+      # Result of a successful {Scraper.fetch}: the response body, the
+      # normalized content-type (lower-cased, with any +; charset=...+
+      # parameters stripped), and the final URL after redirects.
+      Fetched = Data.define(:body, :content_type, :url)
+
+      # Fetch +url+ and render its main content as Markdown.
+      #
+      # No caching here — every call hits the network. Callers that want
+      # to memoize results should wrap this method themselves (see
+      # {Tool::WebScrape.visit}, which does exactly that).
+      #
+      # The extracted output is +String#strip+'d so the LLM never sees
+      # a body that opens or closes with blank lines — common with
+      # extracted PDFs' page-feed whitespace and with text bodies that
+      # carry a trailing newline. Interior whitespace is preserved
+      # because Markdown paragraph breaks and source-code indentation
+      # are load-bearing.
+      #
+      # @param url [String] absolute HTTP(S) URL of the page to download
+      # @return [String] full Markdown representation of the page with
+      #   leading/trailing whitespace trimmed, uncapped otherwise —
+      #   caller is responsible for any size limiting before feeding
+      #   the result back to the LLM
+      # @raise [FetchError] on HTTP non-2xx, network failure, redirect
+      #   loop, a 3xx without a +Location+ header, a response no
+      #   extractor recognizes, or an extraction failure (malformed
+      #   PDF, ...)
+      def self.visit(url)
+        extract(fetch(url)).strip
+      end
+
+      # Render a {Fetched} response as Markdown via
+      # {Pikuri::Extractor.extract}, re-raising both extraction failure
+      # modes as {FetchError} — the single exception type the web tools
+      # rescue. The content-type is passed verbatim (including the +""+
+      # of a missing header, which matches no text arm — a body without
+      # transport metadata is refused, not sniffed; only a strong magic
+      # sniff like pikuri-pdf's +%PDF-+ overrides a wrong or missing
+      # header, because such a sniff never misfires on text).
+      #
+      # @param fetched [Fetched]
+      # @return [String] Markdown representation produced by the
+      #   matched extractor
+      # @raise [FetchError] when no extractor matches the response's
+      #   content-type, or when extraction fails
+      def self.extract(fetched)
+        Pikuri::Extractor.extract(StringIO.new(fetched.body), content_type: fetched.content_type)
+      rescue Pikuri::Extractor::Unsupported
+        raise FetchError, "unsupported content-type #{fetched.content_type.inspect} for #{fetched.url}"
+      rescue Pikuri::Extractor::Error => e
+        raise FetchError, e.message
+      end
+
+      # Download the body of +url+, manually following up to
+      # {MAX_REDIRECTS} redirects. Faraday is configured with no
+      # middleware so behavior here mirrors the rest of the codebase
+      # (see +Tool::Search::DuckDuckGo.search+).
+      #
+      # All recoverable failures — HTTP 4xx/5xx, +Faraday::Error+ network
+      # blips, exhausted redirect budget, 3xx without a +Location+ —
+      # surface as {FetchError} so the caller has a single exception type
+      # to rescue. Error bodies are trimmed to {ERROR_BODY_EXCERPT}
+      # characters with whitespace collapsed, so a Cloudflare-challenge
+      # response doesn't dump kilobytes of inline HTML into the next LLM
+      # observation.
+      #
+      # @param url [String] absolute HTTP(S) URL to fetch
+      # @param limit [Integer] redirects remaining; recurses with
+      #   +limit - 1+ on each 3xx
+      # @return [Fetched] body, normalized content-type, and final URL
+      #   after redirects
+      # @raise [FetchError] on non-2xx/3xx responses, network errors,
+      #   redirect-loop exhaustion, or 3xx without a +Location+ header
+      def self.fetch(url, limit: MAX_REDIRECTS)
+        raise FetchError, "too many redirects fetching #{url}" if limit.zero?
+
+        response = begin
+          Faraday.new(request: { open_timeout: OPEN_TIMEOUT, timeout: READ_TIMEOUT }).get(url) do |req|
+            req.headers['User-Agent'] = USER_AGENT
+            req.headers['Accept']     = ACCEPT
+          end
+        rescue Faraday::Error => e
+          raise FetchError, "#{e.class.name.split('::').last} fetching #{url}: #{e.message}"
+        end
+
+        case response.status
+        when 200..299
+          Fetched.new(body: response.body, content_type: normalize_content_type(response.headers['content-type']), url: url)
+        when 300..399
+          location = response.headers['location']
+          raise FetchError, "HTTP #{response.status} from #{url} with no Location header" if location.nil? || location.empty?
+
+          fetch(URI.join(url, location).to_s, limit: limit - 1)
+        else
+          raise FetchError, "HTTP #{response.status} fetching #{url}: #{excerpt(response.body)}"
+        end
+      end
+
+      # Lower-case +raw+ and strip any +; charset=...+ parameters so the
+      # extractors can match on a canonical token.
+      #
+      # @param raw [String, nil] raw +Content-Type+ header value
+      # @return [String] normalized content-type, or +""+ when the
+      #   header was missing
+      def self.normalize_content_type(raw)
+        raw.to_s.split(';').first.to_s.strip.downcase
+      end
+      private_class_method :normalize_content_type
+
+      # Whitespace-collapse +body+ and clip to {ERROR_BODY_EXCERPT}
+      # characters, so the {FetchError} message stays a single readable
+      # line even when the server returned a multi-KB HTML challenge
+      # page.
+      #
+      # @param body [String, nil]
+      # @return [String]
+      def self.excerpt(body)
+        text = body.to_s.gsub(/\s+/, ' ').strip
+        text.length > ERROR_BODY_EXCERPT ? "#{text[0, ERROR_BODY_EXCERPT]}..." : text
+      end
+      private_class_method :excerpt
+    end
+  end
+end

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

@@ -9,13 +9,17 @@ module Pikuri
     module Search
       # Performs a Brave Search via the official Web Search API 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
+      # (#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.
+      # cascade in {Engines#search} owns the final Markdown rendering.
       #
-      # Requires a Brave Search API key. Get one at
-      # https://api-dashboard.search.brave.com — the free "Data for Search"
-      # tier allows 1 query/sec and ~2k queries/month.
+      # A class constructed with the API key it should use
+      # (+Brave.new(api_key:)+); {Engines} builds one only when a Brave key
+      # was configured 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://api-dashboard.search.brave.com — the
+      # free "Data for Search" tier allows 1 query/sec and ~2k queries/month.
       #
       # == Privacy posture
       #
@@ -32,49 +36,59 @@ module Pikuri
       # 90-day retention by default, real ZDR if you pay for it. Still a
       # logged 90-day window on the cheap tier, so not a substitute for
       # ZDR for genuinely sensitive queries.
-      module Brave
+      class Brave
         # @return [String] Web Search endpoint
         ENDPOINT = 'https://api.search.brave.com/res/v1/web/search'
         # @return [Integer] default number of results returned, matching
         #   {DuckDuckGo::DEFAULT_MAX_RESULTS}
         DEFAULT_MAX_RESULTS = 10
-        # @return [String] env var holding the API key; +X-Subscription-Token+
-        ENV_KEY = 'BRAVE_SEARCH_API_KEY'
         # @return [RateLimiter] free-tier Brave caps at 1 req/sec; the
         #   5-minute cooldown protects the limited monthly quota from
         #   being burned on doomed retries when a 429 hits.
         LIMITER = RateLimiter.new(min_interval: 1.0, cooldown: 300.0)
 
+        # @param api_key [String] Brave Search subscription token. Required
+        #   and non-blank: pikuri reads no key from the environment — the
+        #   host supplies it ({Engines} only constructs a Brave when a key
+        #   was configured).
+        # @raise [ArgumentError] if +api_key+ is blank
+        def initialize(api_key:)
+          raise ArgumentError, 'Brave Search API key is blank' if api_key.to_s.strip.empty?
+
+          @api_key = api_key
+        end
+
+        # @return [String] short provider label for {Engines} logging /
+        #   fallback messages.
+        def label
+          'Brave'
+        end
+
         # Fetch results for +query+ and return them as an +Array<Result>+.
         # Calls are throttled to one per second and circuit-broken for 5
         # minutes on rate-limit / quota-exhausted responses; see {LIMITER}.
-        # The caller (typically {Engines.search}) is expected to have
+        # The caller (typically {Engines#search}) is expected to have
         # already normalized the query and to wrap this in a result cache.
         #
         # @param query [String] search query (already normalized)
         # @param max_results [Integer] maximum number of result entries;
         #   passed through as Brave's +count+ (1..20)
-        # @param api_key [String] Brave Search subscription token; defaults to
-        #   the {ENV_KEY} environment variable
         # @return [Array<Result>] hits, possibly empty when Brave ran the
         #   query and matched nothing
-        # @raise [ArgumentError] if no API key is available
         # @raise [Engines::Unavailable] when Brave returns HTTP 429
         #   (rate limit / quota exhausted) or 5xx — "try again later"
-        #   responses the cascade in {Engines.search} can fall back
+        #   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.
-        def self.search(query, max_results: DEFAULT_MAX_RESULTS, api_key: ENV.fetch(ENV_KEY, nil))
-          raise ArgumentError, "Brave Search API key not set (#{ENV_KEY})" if api_key.to_s.strip.empty?
-
+        def search(query, max_results: DEFAULT_MAX_RESULTS)
           LIMITER.call do
             response = Faraday.get(
               ENDPOINT,
               { q: query, count: max_results },
-              { 'X-Subscription-Token' => api_key, 'Accept' => 'application/json' }
+              { 'X-Subscription-Token' => @api_key, 'Accept' => 'application/json' }
             )
             unless response.success?
               if response.status == 429 || response.status >= 500
@@ -84,7 +98,7 @@ module Pikuri
               raise "Brave Search request failed: #{response.status} #{response.body}"
             end
 
-            parse(response.body, max_results: max_results)
+            self.class.parse(response.body, max_results: max_results)
           end
         end
 

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

@@ -9,9 +9,14 @@ module Pikuri
     module Search
       # Performs a DuckDuckGo search by scraping +html.duckduckgo.com+ 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
+      # fetch (#search) and a pure parser (.parse) so tests can exercise
       # the parser against fixture HTML without hitting the network. The
-      # cascade in {Engines.search} owns the final Markdown rendering.
+      # cascade in {Engines#search} owns the final Markdown rendering.
+      #
+      # A class (constructed with no arguments) so it shares the uniform
+      # provider shape with the keyed {Brave} / {Exa}: {Engines} holds a
+      # list of provider *instances* and calls +#search+ / +#label+ on each
+      # without caring which is which.
       #
       # == Privacy posture
       #
@@ -30,7 +35,7 @@ module Pikuri
       # Microsoft, who has no comparable no-training pledge. Better than
       # Exa for sensitive queries, worse than Brave; for anything
       # genuinely embarrassing, don't search the web at all.
-      module DuckDuckGo
+      class DuckDuckGo
         # @return [String] HTML search endpoint
         ENDPOINT = 'https://html.duckduckgo.com/html/'
         # @return [String] User-Agent sent with each request; DDG often rejects
@@ -44,10 +49,16 @@ module Pikuri
         #   soft-block response doesn't get retried for the next 5 minutes
         LIMITER = RateLimiter.new(min_interval: 2.0, cooldown: 300.0)
 
+        # @return [String] short provider label for {Engines} logging /
+        #   fallback messages. Uniform across providers (see {Brave#label}).
+        def label
+          'DuckDuckGo'
+        end
+
         # Fetch results for +query+ and return them as an +Array<Result>+.
         # Calls are throttled to one every 2s and circuit-broken for 5 minutes
         # after a soft-block; see {LIMITER}. The caller (typically
-        # {Engines.search}) is expected to have already normalized the
+        # {Engines#search}) is expected to have already normalized the
         # query and to wrap this in a result cache.
         #
         # @param query [String] search query (already normalized)
@@ -56,12 +67,12 @@ module Pikuri
         #   query and matched nothing
         # @raise [Engines::Unavailable] when DDG soft-blocks the IP
         #   (anomaly/CAPTCHA page) or returns HTTP 429/5xx — i.e. "try again
-        #   later" responses the cascade in {Engines.search} can fall
+        #   later" responses the cascade in {Engines#search} can fall
         #   back from. Also raised immediately if {LIMITER} is in cooldown.
         # @raise [RuntimeError] if the HTTP call fails for other reasons or
         #   the empty-results page is in an unrecognized layout. A genuine
         #   empty-results page is *not* an error; see {.parse}.
-        def self.search(query, max_results: DEFAULT_MAX_RESULTS)
+        def search(query, max_results: DEFAULT_MAX_RESULTS)
           LIMITER.call do
             response = Faraday.get(ENDPOINT, { q: query }, { 'User-Agent' => USER_AGENT })
             unless response.success?
@@ -72,7 +83,7 @@ module Pikuri
               raise "DuckDuckGo request failed: #{response.status} #{response.body}"
             end
 
-            parse(response.body, max_results: max_results)
+            self.class.parse(response.body, max_results: max_results)
           end
         end
 

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

@@ -2,20 +2,31 @@
 
 module Pikuri
   class Tool
-    # Namespace for the web-search stack used by {Tool::WEB_SEARCH}: per-
+    # 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.
     module Search
-      # Search-orchestration entry point: the cascade across configured
+      # 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
-      # ({Tool::WEB_SEARCH}) lives in +lib/tool/web_search.rb+ and calls
-      # into {.search} below. Each {Tool::Search} provider module
+      # 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.
-      module Engines
+      #
+      # == 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".
+      class Engines
         # Subsystem logger; set its level with +PIKURI_LOG_ENGINES+
         # (e.g. +PIKURI_LOG_ENGINES=debug+) or the global +PIKURI_LOG+.
         #
@@ -24,40 +35,54 @@ module Pikuri
 
         # 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 {Engines.search}
+        # 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.
         class Unavailable < StandardError; end
 
-        # All providers that are currently configured. {DuckDuckGo} is always
-        # available (no API key needed); {Brave} and {Exa} each join the
-        # list when their API token is present in the environment. Recomputed
-        # on every call so a process picks up a newly-set token without a
-        # restart.
-        #
-        # @return [Array<Module>] +Tool::Search::*+ provider modules, each
-        #   exposing +.search(query, max_results:)+ → +Array<Result>+
-        def self.providers
-          list = [DuckDuckGo]
-          list << Brave unless ENV[Brave::ENV_KEY].to_s.strip.empty?
-          list << Exa unless ENV[Exa::ENV_KEY].to_s.strip.empty?
-          list
-        end
-
-        # On-disk cache used by {.search} to memoize answered queries.
-        # Defined as a method so specs can swap it for an isolated cache
-        # or {UrlCache::NULL} without touching the shared instance.
+        # 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.
         #
         # @return [UrlCache, #fetch]
         CACHE = UrlCache.new(ttl: UrlCache::DEFAULT_TTL, dir: "#{UrlCache::ROOT_DIR}/web_search")
-        # Accessor for {CACHE}; specs override this to swap in
-        # {UrlCache::NULL} or an isolated cache.
+        # Accessor for {CACHE}, used as the constructor's +cache:+ default;
+        # specs override this to 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}.
+        # @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?
+          @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
+        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
@@ -68,13 +93,13 @@ module Pikuri
         # +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 {.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.
+        # 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
@@ -88,7 +113,7 @@ module Pikuri
         # @return [String] Markdown-formatted result list, or +"Error: ..."+
         #   when all providers are exhausted
         # @raise [ArgumentError] if the query is empty after normalization
-        def self.search(query, max_results:)
+        def search(query, max_results:)
           cleaned = query.to_s.strip.gsub(/\s+/, ' ')
           raise ArgumentError, 'query is empty' if cleaned.empty?
 
@@ -96,7 +121,7 @@ module Pikuri
           log_providers(current_providers)
 
           hit = true
-          result = cache.fetch(cleaned) do
+          result = @cache.fetch(cleaned) do
             hit = false
             failures = []
             results = nil
@@ -106,7 +131,7 @@ module Pikuri
               chosen = provider
               break
             rescue Unavailable => e
-              failures << "#{provider.name.split('::').last} (#{e.message})"
+              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
@@ -115,7 +140,7 @@ module Pikuri
             chosen or raise Unavailable, "all search providers temporarily unavailable: #{failures.join('; ')}"
 
             LOGGER.info do
-              "engine=#{chosen.name.split('::').last} query=#{cleaned.inspect} results=#{results.size}"
+              "engine=#{chosen.label} query=#{cleaned.inspect} results=#{results.size}"
             end
             render(results)
           end
@@ -125,6 +150,8 @@ module Pikuri
           "Error: #{e.message}"
         end
 
+        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
@@ -133,30 +160,26 @@ module Pikuri
         #
         # @param results [Array<Result>] hits from the winning provider
         # @return [String] Markdown-formatted result list
-        def self.render(results)
+        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
-        private_class_method :render
 
         # Emit an INFO log line listing the currently-available providers,
-        # but only when the set differs from the last one we logged.
-        # {.providers} is recomputed on every {.search} call so a process
-        # picks up newly-set API keys without a restart; the memo here
-        # keeps the log to one line per distinct configuration rather
-        # than one per search.
+        # 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.
         #
-        # @param current [Array<Module>] providers returned by {.providers}
+        # @param current [Array<#label>] providers returned by {#providers}
         # @return [void]
-        def self.log_providers(current)
+        def log_providers(current)
           return if @last_logged_providers == current
 
           @last_logged_providers = current
-          names = current.map { |p| p.name.split('::').last }.join(', ')
+          names = current.map(&:label).join(', ')
           LOGGER.info("engines available: #{names}")
         end
-        private_class_method :log_providers
       end
     end
   end