pikuri-core 0.0.6 → 0.0.7

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

@@ -8,14 +8,17 @@ module Pikuri
     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
+      # 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.
+      # 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.
+      # 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.
       #
       # Calls request +type: "auto"+ (Exa picks neural vs keyword per
       # query) and +contents: { highlights: true }+ so each result carries
@@ -37,17 +40,15 @@ module Pikuri
       # 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
+      # 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.
+      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 [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
@@ -55,35 +56,46 @@ module Pikuri
         #   condition persists.
         LIMITER = RateLimiter.new(min_interval: 0.0, cooldown: 300.0)
 
+        # @param api_key [String] Exa API key. Required and non-blank:
+        #   pikuri reads no key from the environment — the host supplies it
+        #   ({Engines} only constructs an Exa when a key was configured).
+        # @raise [ArgumentError] if +api_key+ is blank
+        def initialize(api_key:)
+          raise ArgumentError, 'Exa 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
+          '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})
+        # 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.
+        #   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?
-
+        def search(query, max_results: DEFAULT_MAX_RESULTS)
           LIMITER.call do
             response = Faraday.post(ENDPOINT) do |req|
-              req.headers['x-api-key'] = api_key
+              req.headers['x-api-key'] = @api_key
               req.headers['Content-Type'] = 'application/json'
               req.headers['Accept'] = 'application/json'
               req.body = JSON.dump(
@@ -101,7 +113,7 @@ module Pikuri
               raise "Exa 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/web_search.rb

@@ -2,37 +2,56 @@
 
 module Pikuri
   class Tool
-    # Namespace marker matching the file path. The actual search
-    # orchestration lives in {Tool::Search::Engines}; this file owns only
-    # the LLM-facing {Tool::WEB_SEARCH} constant below.
-    module WebSearch; end
-
-    # Web-search tool exposed to the agent loop in OpenAI tool-call shape.
-    # Calls {Tool::Search::Engines.search}, which cascades through whichever
-    # providers are configured (DuckDuckGo always, Brave when its API key is
-    # present) in random order, falling back on temporary-unavailability
-    # errors. Providers return structured {Tool::Search::Result} rows;
-    # +Engines.search+ renders the winning provider's rows into the
-    # smolagents-style Markdown shape the LLM sees, so the format stays
-    # stable regardless of which provider ran.
+    # Builder for the LLM-facing web-search tool. The search orchestration
+    # lives in {Tool::Search::Engines}; this module owns only the {.build}
+    # factory that wires a configured {Search::Engines} into a {Tool}.
     #
-    # @return [Tool]
-    WEB_SEARCH = new(
-      name: 'web_search',
-      description: <<~DESC,
+    # Unlike the stateless bundled tools (+CALCULATOR+ / +WEB_SCRAPE+ /
+    # +FETCH+, shared value constants), web_search is *host-configured*:
+    # the paid providers (Brave / Exa) join the cascade only when the host
+    # passes their API key, so the tool is built per-wiring — like
+    # {Code::Bash} — rather than handed out as a single shared constant.
+    # pikuri reads no key from the environment; the host supplies them (the
+    # bundled +bin/+ examples load a JSON config file by convention). See
+    # CLAUDE.md "Environment is not a secret store".
+    module WebSearch
+      # Description shown to the LLM, opencode-shape (summary + +Usage:+).
+      #
+      # @return [String]
+      DESCRIPTION = <<~DESC
         Searches the web for a query and returns the top results as a Markdown list of titles, URLs, and short snippets.
 
         Usage:
         - Use this to find candidate URLs, then call web_scrape on the most promising one(s) for full content. Snippets alone rarely answer a question.
       DESC
-      parameters: Parameters.build { |p|
-        p.required_string :query,
-                          'The search query, e.g. "BigDecimal precision Ruby".'
-        p.optional_integer :max_results,
-                           'Maximum number of result entries to return. ' \
-                           'Defaults to 10; most providers cap this at 20.'
-      },
-      execute: ->(query:, max_results: 10) { Search::Engines.search(query, max_results: max_results) }
-    )
+
+      # Build the +web_search+ tool. It calls {Search::Engines#search},
+      # which cascades through DuckDuckGo (always) plus whichever keyed
+      # providers were configured, in random order, falling back on
+      # temporary-unavailability errors and rendering the winning
+      # provider's rows into a stable Markdown shape.
+      #
+      # @param brave_key [String, nil] Brave Search API key; when present
+      #   (non-blank) Brave joins the cascade. Get one at
+      #   https://api-dashboard.search.brave.com.
+      # @param exa_key [String, nil] Exa API key; when present (non-blank)
+      #   Exa joins the cascade. Get one at https://exa.ai.
+      # @return [Tool] the +web_search+ tool in OpenAI tool-call shape
+      def self.build(brave_key: nil, exa_key: nil)
+        engines = Search::Engines.new(brave_key: brave_key, exa_key: exa_key)
+        Tool.new(
+          name: 'web_search',
+          description: DESCRIPTION,
+          parameters: Parameters.build { |p|
+            p.required_string :query,
+                              'The search query, e.g. "BigDecimal precision Ruby".'
+            p.optional_integer :max_results,
+                               'Maximum number of result entries to return. ' \
+                               'Defaults to 10; most providers cap this at 20.'
+          },
+          execute: ->(query:, max_results: 10) { engines.search(query, max_results: max_results) }
+        )
+      end
+    end
   end
 end

data/lib/pikuri/version.rb

@@ -6,5 +6,5 @@ module Pikuri
   # additions to the public surface (+Pikuri::Tool+ / +Pikuri::Agent+ /
   # listeners / bundled tools), major for breaking changes to that
   # surface or to the +bin/pikuri-*+ CLIs.
-  VERSION = '0.0.6'
+  VERSION = '0.0.7'
 end

data/lib/pikuri-core.rb

@@ -28,15 +28,17 @@ require_relative 'pikuri/version'
 #
 # == Why eager-load
 #
-# Tool implementations (+Pikuri::Tool::CALCULATOR+,
-# +Pikuri::Tool::WEB_SEARCH+, +Pikuri::Tool::WEB_SCRAPE+,
-# +Pikuri::Tool::FETCH+) are +ALL_CAPS+ value constants rather than
-# classes/modules, and Zeitwerk only auto-loads constants that match
-# its filename-↔-CamelCase convention. Eager-loading at boot guarantees
-# the files defining those values run, so the bin script can drop them
-# straight into the +Agent.new+ block via +c.add_tool+ without per-file
-# +require+ ceremony. The cost is a few milliseconds of startup —
-# negligible compared to a single LLM round-trip.
+# The stateless bundled tools (+Pikuri::Tool::CALCULATOR+,
+# +Pikuri::Tool::WEB_SCRAPE+, +Pikuri::Tool::FETCH+) are +ALL_CAPS+ value
+# constants rather than classes/modules, and Zeitwerk only auto-loads
+# constants that match its filename-↔-CamelCase convention. Eager-loading
+# at boot guarantees the files defining those values run, so the bin
+# script can drop them straight into the +Agent.new+ block via
+# +c.add_tool+ without per-file +require+ ceremony. (web_search is instead
+# host-configured — built per-wiring via {Pikuri::Tool::WebSearch.build}
+# with the host's provider keys — so it is not a value constant.) The cost
+# is a few milliseconds of startup — negligible compared to a single LLM
+# round-trip.
 module Pikuri
   # Search path for bundled system prompts. Mutable list: each pikuri
   # gem appends its own +prompts/+ directory when it boots, so a

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: pikuri-core
 version: !ruby/object:Gem::Version
-  version: 0.0.6
+  version: 0.0.7
 platform: ruby
 authors:
 - Martin Vysny
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-06-04 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -136,6 +135,7 @@ files:
 - lib/pikuri/agent/control/step_limit.rb
 - lib/pikuri/agent/event.rb
 - lib/pikuri/agent/extension.rb
+- lib/pikuri/agent/extension_context.rb
 - lib/pikuri/agent/listener.rb
 - lib/pikuri/agent/listener/in_memory_event_list.rb
 - lib/pikuri/agent/listener/rate_limited.rb
@@ -149,6 +149,7 @@ files:
 - lib/pikuri/file_type.rb
 - lib/pikuri/finalizers.rb
 - lib/pikuri/paths.rb
+- lib/pikuri/sanitizer.rb
 - lib/pikuri/subprocess.rb
 - lib/pikuri/tool.rb
 - lib/pikuri/tool/calculator.rb
@@ -174,7 +175,6 @@ metadata:
   changelog_uri: https://codeberg.org/mvysny/pikuri/src/branch/master/CHANGELOG.md
   bug_tracker_uri: https://codeberg.org/mvysny/pikuri/issues
   rubygems_mfa_required: 'true'
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -189,8 +189,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.22
-signing_key:
+rubygems_version: 3.6.7
 specification_version: 4
 summary: The minimal core of the pikuri AI-assistant toolkit (Agent, Tool framework,
   web tools, bin/pikuri-chat).