pikuri-core 0.0.3

data/lib/pikuri/tool/web_scrape.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+module Pikuri
+  class Tool
+    # Truncation policy and Tool spec for the +web_scrape+ tool. The actual
+    # scraping lives in {Tool::Scraper::Simple}; this module is a thin
+    # wrapper that picks the scraper, applies a character cap so the LLM
+    # doesn't drown in long-form content, and exposes the result to the
+    # agent loop in OpenAI tool-call shape.
+    module WebScrape
+      # @return [Integer] default character cap on the Markdown returned
+      #   by {.visit}. Sized to cover most post-readability article bodies
+      #   in full on the first call, so the LLM doesn't have to re-request
+      #   with a larger cap and pollute its context with the same prefix
+      #   twice. ~5K tokens at the typical char/token ratio — light even
+      #   for small local models. The genuinely long pages (long Wikipedia
+      #   entries, multi-section docs) still get cut, and the truncation
+      #   marker invites a deliberate larger {.visit} call when needed.
+      DEFAULT_MAX_CHARS = 20_000
+
+      # @return [Integer] hard ceiling on the +max_chars+ argument to
+      #   {.visit}. Requests above this are clamped silently so the LLM
+      #   cannot dump an arbitrarily large page into the conversation.
+      MAX_MAX_CHARS = 100_000
+
+      # On-disk cache used by {.visit} to memoize fetched pages. 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_scrape")
+      # Accessor for {CACHE}; specs override this to swap in
+      # {UrlCache::NULL} or an isolated cache.
+      #
+      # @return [UrlCache, #fetch]
+      def self.cache
+        CACHE
+      end
+
+      # Fetch +url+ via {Tool::Scraper::Simple} and truncate the rendered
+      # Markdown to +max_chars+ characters.
+      #
+      # The full extracted Markdown is cached on disk via {.cache}, keyed
+      # by URL, so repeat visits within the cache TTL skip the network
+      # and the extraction pass entirely. +max_chars+ is not part of the
+      # cache key — different values for the same URL share one entry,
+      # and truncation runs after the cache lookup.
+      #
+      # {Tool::Scraper::FetchError} (HTTP non-2xx, network failure,
+      # redirect-loop, missing +Location+ header) is caught and returned
+      # as +"Error: ..."+ in the calculator-style convention so the agent
+      # loop feeds the failure back to the model as the next observation
+      # instead of crashing — the LLM can then try a different URL or
+      # search again. The rescue lives outside {.cache}'s +fetch+ block,
+      # so failure strings are never persisted: a retry on the next call
+      # hits the network again. Other exceptions (parser bugs in our own
+      # code) bubble up unchanged.
+      #
+      # @param url [String] absolute HTTP(S) URL of the page to download
+      # @param max_chars [Integer] character cap on the returned Markdown.
+      #   Clamped to +[1, {MAX_MAX_CHARS}]+; defaults to
+      #   {DEFAULT_MAX_CHARS}. When the full page exceeds the cap, output
+      #   is cut and a marker noting the original length is appended.
+      # @return [String] Markdown representation of the page, possibly
+      #   truncated, or +"Error: ..."+ on a recoverable fetch failure
+      def self.visit(url, max_chars: DEFAULT_MAX_CHARS)
+        max_chars = max_chars.clamp(1, MAX_MAX_CHARS)
+        markdown = cache.fetch(url) { Scraper::Simple.visit(url) }
+        truncate(markdown, max_chars)
+      rescue Scraper::FetchError => e
+        "Error: #{e.message}"
+      end
+
+      # Cut +markdown+ to at most +max_chars+ characters, appending a
+      # marker describing the original length when truncation actually
+      # happens. Returns +markdown+ unchanged if it already fits.
+      #
+      # @param markdown [String] full Markdown text
+      # @param max_chars [Integer] character cap; assumed already clamped
+      # @return [String]
+      def self.truncate(markdown, max_chars)
+        return markdown if markdown.length <= max_chars
+
+        "#{markdown[0, max_chars]}\n\n" \
+          "... [truncated at #{max_chars} of #{markdown.length} chars; " \
+          'call again with a larger `max_chars` to see more]'
+      end
+    end
+
+    # Webpage download + Markdown conversion tool. Thin wrapper over
+    # {Tool::WebScrape.visit} that exposes it to the agent loop in OpenAI
+    # tool-call shape.
+    #
+    # @return [Tool]
+    WEB_SCRAPE = new(
+      name: 'web_scrape',
+      description: <<~DESC,
+        Scrapes the rendered webpage, PDF, or text file at the given URL and returns its main content as Markdown.
+
+        Usage:
+        - Use for HTML pages or PDFs where you want readable content — readability extraction strips nav, sidebars, and boilerplate.
+        - For raw textual payloads (JSON, CSV, robots.txt, source files), use fetch instead — it returns bytes verbatim, while web_scrape would corrupt them with a Markdown pass.
+        - A Single Page App may return very little or no content. Do NOT retry with a larger max_chars; try a different URL instead.
+      DESC
+      parameters: Parameters.build { |p|
+        p.required_string :url,
+                          'Absolute URL of the webpage to scrape, including ' \
+                          'the scheme, e.g. "https://example.com/article".'
+        p.optional_integer :max_chars,
+                           'Maximum number of characters of Markdown to ' \
+                           'return. Defaults to 20000; hard-capped at ' \
+                           '100000. When the page is longer than this, ' \
+                           'output is cut and a marker reports the full ' \
+                           'length.'
+      },
+      execute: ->(url:, max_chars: WebScrape::DEFAULT_MAX_CHARS) {
+        WebScrape.visit(url, max_chars: max_chars)
+      }
+    )
+  end
+end

data/lib/pikuri/tool/web_search.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+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.
+    #
+    # @return [Tool]
+    WEB_SEARCH = new(
+      name: 'web_search',
+      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) }
+    )
+  end
+end

data/lib/pikuri/tool.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+require 'ruby_llm'
+
+module Pikuri
+  # A tool the LLM can request via OpenAI-style tool calling.
+  #
+  # {Tool} is a plain value object: +name+, +description+, +parameters+,
+  # and an +execute+ Proc that produces the observation. Pikuri's own
+  # code talks to this surface (the bundled tools, the sub-agent factory,
+  # the +Agent+ constructor); the conversion to ruby_llm's runtime shape
+  # happens at exactly one named seam — {#to_ruby_llm_tool} — which the
+  # +Agent+ calls when wiring tools into the underlying +RubyLLM::Chat+.
+  #
+  # Bundled tool implementations live under +lib/tool/+ and are required
+  # explicitly by the scripts that use them; +lib/tool.rb+ itself only
+  # introduces the {Tool} class and {Tool::Parameters} machinery.
+  #
+  # == Validation ordering
+  #
+  # Pikuri's {Parameters#validate} — DidYouMean suggestions, type coercion,
+  # all-errors-collected — is what the LLM must see when it emits bad
+  # arguments, not ruby_llm's keyword-presence checker. The synthetic
+  # class produced by {#to_ruby_llm_tool} defines +execute(**args)+: the
+  # keyrest signature makes +RubyLLM::Tool#validate_keyword_arguments+
+  # no-op (it bails out at the +accepts_extra_keywords+ check), so
+  # pikuri's validator runs inside {#run} before any user code does.
+  #
+  # == Error handling convention
+  #
+  # Tools split failures into two buckets:
+  #
+  # * *Recoverable* failures — anything the LLM can react to by retrying with
+  #   different inputs (bad arguments, HTTP 4xx/5xx, network blips, search
+  #   provider rate-limits, division by zero in the calculator, ...). These
+  #   come back as a +"Error: <message>"+ String and become the next
+  #   observation; the model sees them and self-corrects on the following
+  #   turn instead of crashing the agent loop.
+  # * *Bugs* in pikuri's own code (parser regressions, schema misuse,
+  #   misconfigured clients, ...). These keep raising. The LLM cannot fix
+  #   them; a human needs to.
+  #
+  # Argument-validation failures from {Parameters#validate} are caught by
+  # {#run} and turned into +"Error: ..."+ observations. The +execute+ Proc
+  # owns the rest — it should follow the same convention internally for
+  # tool-specific recoverable failures, and let bugs raise.
+  class Tool
+    # @return [String] function name advertised to the LLM
+    attr_reader :name
+
+    # @return [String] human-readable description used by the LLM to decide
+    #   when to call the tool
+    attr_reader :description
+
+    # @return [Tool::Parameters] declared schema; validates incoming
+    #   arguments and serializes to the JSON Schema shape advertised to the
+    #   LLM
+    attr_reader :parameters
+
+    # @return [Proc] callable invoked once arguments have been validated;
+    #   receives validated keyword arguments and returns a +String+
+    #   observation
+    attr_reader :execute
+
+    # @param name [String] function name advertised to the LLM
+    # @param description [String] human-readable description used by the LLM
+    #   to decide when to call the tool
+    # @param parameters [Tool::Parameters] declared schema
+    # @param execute [Proc] callable invoked with validated keyword arguments
+    #   that returns a +String+ observation. Recoverable failures should be
+    #   returned as +"Error: <message>"+ Strings rather than raised — see
+    #   "Error handling convention" above.
+    # @return [Tool]
+    def initialize(name:, description:, parameters:, execute:)
+      @name = name
+      @description = description
+      @parameters = parameters
+      @execute = execute
+    end
+
+    # Validate +args+ against {#parameters} and forward them as keyword
+    # arguments to {#execute}. Validation failures are caught and rendered
+    # as +"Error: <message>"+ Strings so the agent loop can feed them back
+    # to the LLM as the next observation; everything else bubbles up.
+    #
+    # @param args [Hash] raw arguments supplied by the LLM
+    # @return [String] tool observation, or +"Error: ..."+ on validation
+    #   failure
+    def run(args)
+      validated = @parameters.validate(args)
+      @execute.call(**validated)
+    rescue Tool::Parameters::ValidationError => e
+      "Error: #{e.message}"
+    end
+
+    # Build a synthetic +RubyLLM::Tool+ subclass that wraps this Tool. The
+    # subclass is what +RubyLLM::Chat#with_tool+ accepts: ruby_llm
+    # instantiates it (+tool.new+) and routes tool calls through
+    # +instance.call(args)+, which lands in +#execute(**args)+ and
+    # delegates back to {#run} on this instance.
+    #
+    # @return [Class] anonymous +RubyLLM::Tool+ subclass
+    def to_ruby_llm_tool
+      pikuri_tool = self
+      schema      = @parameters.to_h
+      tool_name   = @name
+      tool_desc   = @description
+
+      Class.new(RubyLLM::Tool) do
+        description(tool_desc)
+        params(schema)
+
+        define_singleton_method(:name) { tool_name }
+        define_method(:execute) { |**args| pikuri_tool.run(args) }
+      end
+    end
+  end
+end

data/lib/pikuri/url_cache.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+require 'digest'
+require 'fileutils'
+
+module Pikuri
+  # On-disk cache for string-keyed text payloads. Used by the bundled tools
+  # to avoid re-fetching the same page or re-issuing the same web-search
+  # query within a TTL window: {Tool::WebScrape.visit} caches the rendered
+  # Markdown for a URL, and {Tool::Search::Engines.search} caches the
+  # rendered result list for a query (the query string itself acts as the
+  # key — keys are SHA-256 hashed, so any opaque string works).
+  #
+  # Each tool wires its own {UrlCache} instance against a dedicated
+  # subdirectory under {ROOT_DIR}, so a +web_search+ query string and a
+  # +web_scrape+ URL string can never collide on the same cache file. There
+  # is no global default singleton — pass a fresh instance to whichever
+  # code needs caching, or use {NULL} to disable caching entirely.
+  #
+  # One file per entry, named +<sha256>.txt+ under {#initialize}'s +dir+.
+  # Freshness is tracked via the file's mtime; there is no sidecar metadata.
+  # Stale entries are simply overwritten the next time {#fetch} is called
+  # with the same key. To clear the cache, +rm -rf+ the directory.
+  #
+  # Not thread-safe: if two callers race on the same cold key, both compute
+  # and both write the same file. That is the intended tradeoff to keep this
+  # under a few dozen lines — the worst-case cost is a duplicate fetch.
+  class UrlCache
+    # Root directory under which per-tool cache subdirectories live.
+    # Follows the XDG Base Directory spec: +$XDG_CACHE_HOME/pikuri/url_cache+
+    # if the env var is set to a non-empty value, else
+    # +~/.cache/pikuri/url_cache+. Each tool picks its own subdir
+    # (e.g. +"#{ROOT_DIR}/web_scrape"+) so keys from different tools cannot
+    # collide. The directory is created lazily on first cache write; pikuri
+    # does not pre-create it.
+    # @return [String]
+    ROOT_DIR = begin
+      xdg = ENV['XDG_CACHE_HOME']
+      cache_home = xdg && !xdg.empty? ? xdg : File.join(Dir.home, '.cache')
+      File.join(cache_home, 'pikuri', 'url_cache')
+    end.freeze
+
+    # Default freshness window: 2 hours, in seconds.
+    #
+    # Long enough to cover a single interactive session — revisiting
+    # a scraped page or re-running a similar search within the same
+    # working window hits the cache. Short enough that resuming the
+    # next day doesn't serve stale news, docs, or search results.
+    # Reference points: opencode keeps no cache, the +pi-web-fetch+
+    # community extension uses 15 minutes, +pi-web-search+ uses 5;
+    # 2 hours sits comfortably above the "single follow-up" window
+    # those numbers are aimed at without holding content across days.
+    # @return [Integer]
+    DEFAULT_TTL = 2 * 60 * 60
+
+    # @param ttl [Integer] freshness window in seconds; entries with an
+    #   mtime older than this are treated as misses
+    # @param dir [String] directory under which cache files live; created
+    #   lazily on first write
+    def initialize(ttl:, dir:)
+      @ttl = ttl
+      @dir = dir
+    end
+
+    # Return the cached payload for +url+ if a fresh entry exists, otherwise
+    # yield to compute it, persist the result, and return it.
+    #
+    # The block is only invoked on a miss. If the block raises, no file is
+    # written — errors are not cached.
+    #
+    # @param url [String] cache key; a URL or any opaque string identifier
+    # @yieldreturn [String] payload to store and return on a miss
+    # @return [String] cached or freshly-computed payload
+    def fetch(url)
+      path = path_for(url)
+      return File.read(path) if fresh?(path)
+
+      content = yield
+      FileUtils.mkdir_p(@dir)
+      File.write(path, content)
+      content
+    end
+
+    # @param path [String]
+    # @return [Boolean] true when +path+ exists and was written within the
+    #   TTL window
+    def fresh?(path)
+      File.exist?(path) && Time.now - File.mtime(path) < @ttl
+    end
+
+    # @param url [String]
+    # @return [String] absolute path of the cache file for +url+
+    def path_for(url)
+      File.join(@dir, "#{Digest::SHA256.hexdigest(url)}.txt")
+    end
+
+    # Null cache: a drop-in replacement that always misses and never
+    # persists. Use this in tests (or anywhere else you want caching off)
+    # without giving up the {UrlCache#fetch} contract.
+    NULL = Object.new
+    # Singleton +fetch+ on {NULL} that mirrors {UrlCache#fetch}'s shape:
+    # ignores +_key+, always yields, never persists.
+    #
+    # @param _key [String] cache key; ignored
+    # @yieldreturn [String] freshly-computed payload
+    # @return [String] whatever the block returned
+    def NULL.fetch(_key)
+      yield
+    end
+    NULL.freeze
+  end
+end

data/lib/pikuri/version.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Pikuri
+  # Gem version, advertised in +pikuri.gemspec+. Bump on every release
+  # following semver: patch for bug fixes, minor for backward-compatible
+  # 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.3'
+end

data/lib/pikuri-core.rb

@@ -0,0 +1,177 @@
+# frozen_string_literal: true
+
+require 'logger'
+require 'zeitwerk'
+
+# +Pikuri::VERSION+ lives in its own tiny file so the gemspec can read
+# the version constant via +require_relative+ at build time without
+# loading Zeitwerk and every runtime dep. Requiring it here makes the
+# constant available to ordinary +require 'pikuri-core'+ callers too —
+# without this line, Zeitwerk's ignore-rule below would leave
+# +Pikuri::VERSION+ undefined for anyone using the installed gem.
+require_relative 'pikuri/version'
+
+# Boot file: configures the Zeitwerk autoloader for every file under
+# +pikuri-core/lib/pikuri/+ and eager-loads them all. After
+# +require 'pikuri-core'+, every constant pikuri-core ships
+# (+Pikuri::Agent+, +Pikuri::Tool+, +Pikuri::Tool::Calculator+, ...)
+# is defined and resolvable. Sibling gems (+pikuri-skills+,
+# +pikuri-mcp+, ...) set up their own Zeitwerk loaders rooted at
+# their own +lib/+ and contribute to the same +Pikuri::+ namespace.
+#
+# Beyond loading, the +Pikuri+ module owns the logging surface — see
+# {.logger_for}, {.log_io=}, and the +PIKURI_LOG+ /
+# +PIKURI_LOG_<NAME>+ env vars. Each subsystem holds its own
+# memoized +Logger+, all writing through a shared IO that
+# {.log_io=} can swap in one shot (handy in tests, daemons, or
+# anywhere stderr isn't the right sink).
+#
+# == 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.
+module Pikuri
+  # Search path for bundled system prompts. Mutable list: each pikuri
+  # gem appends its own +prompts/+ directory when it boots, so a
+  # +Pikuri.prompt(name)+ call from a host that requires +pikuri-code+
+  # (for example) finds +coding-system-prompt.txt+ in
+  # +pikuri-code/prompts/+. The core gem registers its own
+  # +pikuri-core/prompts/+ below; sibling gems do the equivalent in
+  # their own entry files.
+  #
+  # Exposed publicly so a downstream library user can read pikuri's
+  # prompts as a starting point for their own system prompt (or
+  # use them verbatim). Prefer {.prompt} for the common case of
+  # loading one by name.
+  #
+  # @return [Array<String>]
+  PROMPT_DIRS = [File.expand_path('../prompts', __dir__)]
+
+  # Mapping from +PIKURI_LOG+ env-var values (lowercased) to
+  # {Logger} level constants. Anything else falls back to +INFO+.
+  #
+  # @return [Hash{String=>Integer}]
+  LOG_LEVELS = {
+    'debug' => Logger::DEBUG,
+    'info'  => Logger::INFO,
+    'warn'  => Logger::WARN,
+    'error' => Logger::ERROR,
+    'fatal' => Logger::FATAL
+  }.freeze
+
+  @log_io      = $stderr
+  @log_loggers = {} # name → Logger; lets {.log_io=} rewire all of them
+  @log_default = LOG_LEVELS.fetch(ENV['PIKURI_LOG'].to_s.downcase, Logger::INFO)
+
+  class << self
+    # @return [IO] shared sink every {.logger_for} writes through
+    attr_reader :log_io
+
+    # Swap the shared sink (e.g. a +StringIO+ in tests, a file in a
+    # daemon). Re-points every logger already handed out by
+    # {.logger_for} so callers don't have to re-fetch them.
+    #
+    # Why we don't use +Logger#reopen+: that method closes the previous
+    # sink before installing the new one, which makes "swap to a
+    # capture +StringIO+, then swap back to the original" impossible —
+    # the original handle would be dead the second time around. Instead
+    # we swap each logger's +@logdev+ to a fresh +Logger::LogDevice+
+    # over the new +io+, leaving the previous device untouched so the
+    # caller can hand the same +IO+ back in later. This uses a documented
+    # but internal Logger ivar; if a future Ruby renames it the
+    # +Engines+ logging specs will fail loudly.
+    #
+    # @param io [IO] new sink for every Pikuri logger
+    # @return [IO]
+    def log_io=(io)
+      @log_io = io
+      @log_loggers.each_value do |lg|
+        lg.instance_variable_set(:@logdev, Logger::LogDevice.new(io))
+      end
+      io
+    end
+
+    # Memoized {Logger} tagged with +name+ in its +progname+, so each
+    # subsystem's lines stand out in the shared sink. Level resolves
+    # in this order: +PIKURI_LOG_<NAME>+ (e.g. +PIKURI_LOG_ENGINES=debug+),
+    # then +PIKURI_LOG+, then +INFO+.
+    #
+    # Repeated calls with the same +name+ return the same instance so
+    # there is one logger per subsystem and {.log_io=} can rewire them
+    # all in one shot.
+    #
+    # @param name [String] subsystem tag (rendered as +progname+)
+    # @return [Logger]
+    def logger_for(name)
+      @log_loggers[name] ||= begin
+        lg = Logger.new(@log_io, progname: name)
+        override = ENV["PIKURI_LOG_#{name.upcase}"].to_s.downcase
+        lg.level = LOG_LEVELS.fetch(override, @log_default)
+        lg
+      end
+    end
+
+    # Read a bundled prompt by basename. Searches every directory in
+    # {PROMPT_DIRS} in order, returning the first match. +.txt+ is
+    # auto-appended if absent. Symbols are accepted as a convenience
+    # (+:pikuri-chat+ / +'pikuri-chat'+ / +'pikuri-chat.txt'+ all
+    # resolve to the same file).
+    #
+    # Intended for downstream library users who want to bootstrap their
+    # own +Pikuri::Agent+ wiring from pikuri's defaults — read the
+    # prompt, customize the bits they care about, hand the result to
+    # +Agent.new(system_prompt: ...)+.
+    #
+    # @example
+    #   chat_prompt = Pikuri.prompt(:'pikuri-chat')
+    #   agent = Pikuri::Agent.new(system_prompt: chat_prompt, ...)
+    #
+    # @param name [String, Symbol] basename of the prompt file
+    # @return [String] file contents
+    # @raise [ArgumentError] if no matching file exists in any
+    #   directory in {PROMPT_DIRS}
+    def prompt(name)
+      basename = name.to_s
+      basename += '.txt' unless basename.end_with?('.txt')
+      PROMPT_DIRS.each do |dir|
+        path = File.join(dir, basename)
+        return File.read(path) if File.exist?(path)
+      end
+      available = PROMPT_DIRS.flat_map { |dir| Dir.exist?(dir) ? Dir.children(dir) : [] }.sort.uniq
+      raise ArgumentError, "Unknown pikuri prompt #{name.inspect}; available: #{available.join(', ')}"
+    end
+  end
+
+  # Zeitwerk loader managing every constant under
+  # +pikuri-core/lib/pikuri/+. Exposed as a constant (rather than scoped
+  # to the boot block) so a downstream host that wants to add ignore
+  # rules can reach it without monkey-patching. Sibling gems
+  # (+pikuri-skills+, +pikuri-mcp+, ...) set up their own loaders
+  # rooted at their own +lib/+ dirs — see each gem's entry file.
+  #
+  # @return [Zeitwerk::Loader]
+  Loader = Zeitwerk::Loader.new
+  Loader.tag = 'pikuri-core'
+  Loader.push_dir(File.expand_path('.', __dir__))
+  Loader.ignore(__FILE__)
+  # +pikuri/version.rb+ defines +Pikuri::VERSION+ (an ALL_CAPS value
+  # constant), not +Pikuri::Version+ as Zeitwerk would expect from the
+  # filename — so tell the loader to skip it. The file is +require_relative+'d
+  # at the top of this file (and also by the gemspec at build time), so
+  # the constant is defined before Zeitwerk runs.
+  Loader.ignore(File.expand_path('pikuri/version.rb', __dir__))
+  Loader.inflector.inflect(
+    'html'       => 'HTML',
+    'pdf'        => 'PDF',
+    'duckduckgo' => 'DuckDuckGo'
+  )
+  Loader.setup
+  Loader.eager_load
+end

data/prompts/pikuri-chat.txt

@@ -0,0 +1,15 @@
+You are an expert assistant who solves tasks by calling tools when needed.
+
+You have access to tools described in the API's tool list. To call one, use the standard tool-call mechanism — do not write tool calls as text.
+
+If several next steps are independent (e.g. two unrelated lookups), emit them as parallel tool calls in a single turn rather than one at a time.
+
+Choosing a tool:
+- Default to `web_search` whenever a question asks for a specific fact about a named entity — company HQs and headcounts, product versions and release dates, prices, people's bios and roles, anything tying a proper noun to a specific attribute — and for anything time-sensitive or obscure. Your training will *feel* certain on these and is often wrong; check rather than guess. One well-chosen search beats three exploratory ones.
+- Use `calculator` for any arithmetic beyond simple mental math. Don't search the web for "what is X * Y".
+- Reply directly, without any tool, for language and translation, definitions of common terms, and widely-known general history.
+
+Other guidelines:
+- Don't repeat a tool call with identical arguments — re-read the previous observation instead.
+- On a tool error (observation starting with `Error:`): use the data you already have to answer if you can. If you can't, reply to the user that you weren't able to find the answer and briefly say why (e.g. "web search hit a rate limit", "the page wasn't reachable"). Do not retry the same call hoping for a different result, and do not loop on rephrased variants of the same failing call.
+- When you have the answer, reply in plain text with no tool call. That is how you finish.