pikuri 0.0.1

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

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+module Pikuri
+  class Tool
+    module Search
+      # Search-orchestration entry point: 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
+      # ({DuckDuckGo}, {Brave}, {Exa}) raises {Unavailable} when it wants
+      # the cascade to try the next one.
+      module Engines
+        # Subsystem logger; set its level with +PIKURI_LOG_ENGINES+
+        # (e.g. +PIKURI_LOG_ENGINES=debug+) or the global +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 {Engines.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.
+        #
+        # @return [UrlCache, #fetch]
+        CACHE = UrlCache.new(ttl: UrlCache::DEFAULT_TTL, dir: "#{UrlCache::ROOT_DIR}/web_search")
+        def self.cache
+          CACHE
+        end
+
+        # 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 {.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.
+        #
+        # @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
+        # @raise [ArgumentError] if the query is empty after normalization
+        def self.search(query, max_results:)
+          cleaned = query.to_s.strip.gsub(/\s+/, ' ')
+          raise ArgumentError, 'query is empty' if cleaned.empty?
+
+          current_providers = providers
+          log_providers(current_providers)
+
+          hit = true
+          result = cache.fetch(cleaned) do
+            hit = false
+            failures = []
+            results = nil
+            chosen = nil
+            current_providers.shuffle.each do |provider|
+              results = provider.search(cleaned, max_results: max_results)
+              chosen = provider
+              break
+            rescue Unavailable => e
+              failures << "#{provider.name.split('::').last} (#{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.
+            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}"
+            end
+            render(results)
+          end
+          LOGGER.info { "cache=hit query=#{cleaned.inspect} bytes=#{result.bytesize}" } if hit
+          result
+        rescue Unavailable => e
+          "Error: #{e.message}"
+        end
+
+        # 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.
+        #
+        # @param results [Array<Result>] hits from the winning provider
+        # @return [String] Markdown-formatted result list
+        def self.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.
+        #
+        # @param current [Array<Module>] providers returned by {.providers}
+        # @return [void]
+        def self.log_providers(current)
+          return if @last_logged_providers == current
+
+          @last_logged_providers = current
+          names = current.map { |p| p.name.split('::').last }.join(', ')
+          LOGGER.info("engines available: #{names}")
+        end
+        private_class_method :log_providers
+      end
+    end
+  end
+end

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

@@ -0,0 +1,217 @@
+# frozen_string_literal: true
+
+require 'faraday'
+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.
+      #
+      # Requires an Exa API key. Get one at https://exa.ai — the service is
+      # paid, so the cascade in {Engines.providers} only includes Exa when
+      # {ENV_KEY} is set in the environment; users who haven't registered
+      # never spend money on it.
+      #
+      # 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.
+      #
+      # == 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, drop
+      # Exa out of the cascade by unsetting {ENV_KEY} — {Engines.providers}
+      # is recomputed every call.
+      module 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 [String] env var holding the API key; sent as +x-api-key+
+        ENV_KEY = 'EXA_API_KEY'
+        # @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.
+        LIMITER = RateLimiter.new(min_interval: 0.0, cooldown: 300.0)
+
+        # 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.
+        #
+        # @param query [String] search query (already normalized)
+        # @param max_results [Integer] maximum number of result entries;
+        #   passed through as Exa's +numResults+
+        # @param api_key [String] Exa API key; defaults to the {ENV_KEY}
+        #   environment variable
+        # @return [Array<Result>] hits, possibly empty when Exa ran the
+        #   query and matched nothing
+        # @raise [ArgumentError] if no API key is available
+        # @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 self.search(query, max_results: DEFAULT_MAX_RESULTS, api_key: ENV.fetch(ENV_KEY, nil))
+          raise ArgumentError, "Exa Search API key not set (#{ENV_KEY})" if api_key.to_s.strip.empty?
+
+          LIMITER.call do
+            response = Faraday.post(ENDPOINT) do |req|
+              req.headers['x-api-key'] = api_key
+              req.headers['Content-Type'] = 'application/json'
+              req.headers['Accept'] = 'application/json'
+              req.body = JSON.dump(
+                query: query,
+                type: 'auto',
+                numResults: max_results,
+                contents: { highlights: true }
+              )
+            end
+            unless response.success?
+              if response.status == 429 || response.status >= 500
+                raise Engines::Unavailable, "HTTP #{response.status}"
+              end
+
+              raise "Exa Search request failed: #{response.status} #{response.body}"
+            end
+
+            parse(response.body, max_results: max_results)
+          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.
+        #
+        # @param json [String] response body from {ENDPOINT}
+        # @param max_results [Integer] maximum number of result 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
+        def self.parse(json, max_results: DEFAULT_MAX_RESULTS)
+          data = JSON.parse(json)
+          results = Array(data['results']).take(max_results).filter_map do |r|
+            href = r['url'].to_s
+            next nil if href.empty?
+
+            Result.new(
+              url: href,
+              title: clean(r['title']) || href,
+              body: first_highlight(r['highlights'])
+            )
+          end
+
+          if results.empty?
+            return [] if genuine_no_results?(data)
+
+            raise diagnose_empty(data, json)
+          end
+
+          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).
+        #
+        # @param text [String, nil] raw text from an Exa result field
+        # @return [String, nil] cleaned text, or +nil+ if input was blank
+        def self.clean(text)
+          return nil if text.nil?
+
+          cleaned = text.to_s.gsub(/\s+/, ' ').strip
+          cleaned.empty? ? nil : cleaned
+        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.
+        #
+        # @param highlights [Array<String>, nil] +highlights+ field
+        # @return [String] cleaned snippet, or empty string if none usable
+        def self.first_highlight(highlights)
+          return '' unless highlights.is_a?(Array)
+
+          highlights.each do |h|
+            cleaned = clean(h)
+            return cleaned if cleaned
+          end
+          ''
+        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.
+        #
+        # @param data [Hash, Object] parsed response
+        # @return [Boolean]
+        def self.genuine_no_results?(data)
+          return false unless data.is_a?(Hash)
+          return false unless data.key?('requestId')
+
+          Array(data['results']).empty?
+        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.
+        #
+        # @param data [Hash, Object] parsed response
+        # @param raw [String] raw response body
+        # @return [String] human-readable 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}"
+          end
+
+          snippet = raw.to_s[0, 800]
+          snippet += '…' if raw.to_s.length > 800
+          "Exa Search returned no results. Body: #{snippet}"
+        end
+        private_class_method :diagnose_empty
+      end
+    end
+  end
+end

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

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module Pikuri
+  # Loaded after {Tool} itself is defined; the +class Tool+ reopening below
+  # assumes that order.
+  class Tool
+    module Search
+      # Thread-safe pacing + circuit-breaker wrapper for a search provider.
+      #
+      # +#call { ... }+ enforces a minimum interval between consecutive
+      # invocations of the block (sleeping if the previous one was too
+      # recent), and watches for {Engines::Unavailable} raised by the
+      # block: when that happens, a cooldown deadline is recorded and
+      # further calls within the window raise {Engines::Unavailable}
+      # immediately without invoking the block. This stops a provider
+      # that has been rate-limited or bot-blocked from being hammered
+      # with retries.
+      #
+      # The mutex is held across the block, so concurrent callers
+      # serialize — matching the behavior {DuckDuckGo} has always
+      # required to keep its IP-spacing throttle correct under
+      # concurrent agents.
+      #
+      # Uses wall-clock {Time.now} rather than the monotonic clock; the
+      # intervals here are 1s–5min, well above any realistic NTP step,
+      # and {Time.now} keeps tests trivially fakeable with Timecop.
+      class RateLimiter
+        # @param min_interval [Float] minimum seconds between consecutive
+        #   block invocations. {#call} sleeps if a previous call was more
+        #   recent.
+        # @param cooldown [Float] seconds to refuse calls after the block
+        #   raises {Engines::Unavailable}. Calls within this window raise
+        #   {Engines::Unavailable} immediately without invoking the block.
+        def initialize(min_interval:, cooldown:)
+          @min_interval = min_interval
+          @cooldown = cooldown
+          @mutex = Mutex.new
+          @last_call_at = nil
+          @cooldown_until = nil
+        end
+
+        # Run the given block subject to throttle and cooldown rules.
+        #
+        # The block is invoked with the mutex held, so concurrent calls
+        # serialize: only one block runs at a time per limiter instance.
+        # If the block raises {Engines::Unavailable}, the cooldown is
+        # armed and the exception is re-raised. Any other exception
+        # bubbles up without arming cooldown — only "try again later"
+        # signals from the provider are treated as backoff triggers.
+        #
+        # @yieldreturn [Object] block's return value is passed through
+        # @return [Object] whatever the block returned
+        # @raise [Engines::Unavailable] either re-raised from the block,
+        #   or raised directly when the limiter is currently in cooldown
+        def call
+          @mutex.synchronize do
+            now = Time.now
+            if @cooldown_until && now < @cooldown_until
+              remaining = (@cooldown_until - now).ceil
+              raise Engines::Unavailable, "rate-limiter cooldown active for another #{remaining}s"
+            end
+
+            if @last_call_at
+              elapsed = now - @last_call_at
+              sleep_for(@min_interval - elapsed) if elapsed < @min_interval
+            end
+            @last_call_at = Time.now
+
+            begin
+              yield
+            rescue Engines::Unavailable
+              @cooldown_until = Time.now + @cooldown
+              raise
+            end
+          end
+        end
+
+        # Sleep for +seconds+. Isolated as a private method so tests can
+        # override it on a single instance (typically to advance a frozen
+        # Timecop clock by the same amount) without monkey-patching the
+        # global +sleep+.
+        #
+        # @param seconds [Float] non-negative duration to sleep
+        # @return [void]
+        def sleep_for(seconds)
+          sleep(seconds)
+        end
+        private :sleep_for
+      end
+    end
+  end
+end

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

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Pikuri
+  class Tool
+    module Search
+      # A single search hit produced by a {Tool::Search} provider
+      # ({DuckDuckGo}, {Brave}, {Exa}). Providers return +Array<Result>+
+      # from +.parse+ / +.search+; {Engines.search} concatenates the
+      # rows into the smolagents-style Markdown the LLM sees.
+      #
+      # Splitting structure from rendering keeps the three providers
+      # interchangeable — they only have to agree on these three fields
+      # (provider-specific extras like relevance scores or published
+      # dates are discarded today, which is fine because no caller uses
+      # them).
+      #
+      # @!attribute [r] url
+      #   @return [String] absolute URL of the hit
+      # @!attribute [r] title
+      #   @return [String] plain-text title, with provider-specific
+      #     highlight markup ({Brave}'s +<strong>+, {DuckDuckGo}'s
+      #     +<b>+) already stripped
+      # @!attribute [r] body
+      #   @return [String] plain-text snippet, possibly empty (e.g. an
+      #     {Exa} navigational result with no highlights)
+      Result = Data.define(:url, :title, :body)
+    end
+  end
+end

data/lib/pikuri/tool/skill.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Pikuri
+  class Tool
+    # The +skill+ tool: instantiating +Tool::Skill.new(catalog:)+ produces
+    # a tool whose +execute+ closure looks the requested name up in the
+    # bound {SkillCatalog} and returns the skill's body wrapped in a
+    # +<skill>+ block with the absolute base directory, so the LLM can
+    # resolve relative sidecar paths against it via the regular +read+
+    # tool.
+    #
+    # The catalog of available skills is *not* duplicated into this tool's
+    # description. It lives in the system prompt — see
+    # {SkillCatalog#format_for_prompt} — because skills describe what the
+    # agent is, not just what one of its tools returns. Putting the
+    # catalog in the system prompt keeps it next to the agent's persona
+    # and matches what PI and Claude Code do (opencode is the outlier
+    # here). The tool description below is therefore *static* — it
+    # explains the load mechanism, not the inventory.
+    #
+    # This tool is not registered manually. {Agent#initialize} auto-
+    # registers it whenever +skill_catalog+ is non-empty, and skips it
+    # otherwise; sub-agents inherit it through the parent's tool snapshot.
+    # The bound catalog rides along in the +execute+ closure, so any
+    # sub-agent invoking +skill+ resolves names against the same catalog
+    # the parent saw.
+    class Skill < Tool
+      # Description shown to the LLM. Follows the opencode-shape (summary
+      # + +Usage:+ bullets) prescribed by the project's tool-description
+      # convention. The list of which skills exist is not here — see
+      # the class header.
+      #
+      # @return [String]
+      DESCRIPTION = <<~DESC
+        Load a specialized skill that provides domain-specific instructions and resources for a particular task.
+
+        Usage:
+        - The catalog of available skills is listed in your system prompt under `<available_skills>`.
+        - Invoke this tool with a skill's `name` to inject its full instructions into the conversation.
+        - The loaded skill may reference helper scripts and files in its base directory — use the `read` tool to load those when the skill's instructions tell you to.
+        - On `Error: skill '...' not found`, do NOT retry with a guessed name. Pick a name that actually appears in `<available_skills>`, or report to the user that no matching skill is installed.
+      DESC
+
+      # @param catalog [SkillCatalog] the catalog to resolve names
+      #   against. Captured by closure so the tool retains access to
+      #   the same instance even when copied into a sub-agent's tool
+      #   snapshot.
+      # @return [Skill]
+      def initialize(catalog:)
+        super(
+          name: 'skill',
+          description: DESCRIPTION,
+          parameters: Parameters.build { |p|
+            p.required_string :name,
+                              'Name of the skill to load, e.g. "pdf-extraction". ' \
+                              'Must match a name listed under `<available_skills>` ' \
+                              'in the system prompt.'
+          },
+          execute: lambda { |name:|
+            loaded = catalog.get(name)
+            if loaded.nil?
+              available = catalog.list.map(&:name).sort
+              list = available.empty? ? 'none' : available.join(', ')
+              next "Error: skill '#{name}' not found. Available skills: #{list}."
+            end
+
+            base_dir = File.dirname(loaded.location)
+            <<~OUT
+              <skill name="#{loaded.name}" location="#{loaded.location}">
+              Sidecar paths in this skill (e.g. scripts/, references/) are relative to #{base_dir}.
+
+              #{loaded.body}
+              </skill>
+            OUT
+          }
+        )
+      end
+    end
+  end
+end