pikuri-core 0.0.7 → 0.1.0

data/lib/pikuri-core.rb

@@ -3,55 +3,34 @@
 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.
+# +Pikuri::VERSION+ lives in its own tiny file so the gemspec can +require_relative+
+# it at build time without loading Zeitwerk and every runtime dep. Requiring it
+# here also defines the constant for ordinary +require 'pikuri-core'+ callers —
+# without this line the Zeitwerk ignore-rule below would leave it undefined.
 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.
+# Boot file: configures the Zeitwerk autoloader for +pikuri-core/lib/pikuri/+
+# and eager-loads it, so after +require 'pikuri-core'+ every constant
+# pikuri-core ships is defined. Sibling gems set up their own loaders into 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).
+# The +Pikuri+ module also owns the logging surface ({.logger_for}, {.log_io=},
+# the +PIKURI_LOG+ / +PIKURI_LOG_<NAME>+ env vars): each subsystem holds a
+# memoized +Logger+ writing through a shared IO that {.log_io=} swaps in one shot.
 #
 # == Why eager-load
 #
-# 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.
+# The stateless bundled tools (+Tool::CALCULATOR+, +Tool::WEB_SCRAPE+,
+# +Tool::FETCH+) are +ALL_CAPS+ value constants, and Zeitwerk only auto-loads
+# constants matching its filename↔CamelCase convention. Eager-loading runs the
+# files defining those values so a bin script can +c.add_tool+ them without
+# per-file +require+. (web_search is host-configured via
+# {Tool::WebSearch.build}, so it's not a value constant.) Cost: a few ms.
 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.
+  # Search path for bundled system prompts. Mutable: each pikuri gem appends its
+  # own +prompts/+ at boot, so +Pikuri.prompt(name)+ from a host requiring
+  # +pikuri-code+ finds +coding-system-prompt.txt+ there. Public so a downstream
+  # user can read pikuri's prompts as a starting point; prefer {.prompt}.
   #
   # @return [Array<String>]
   PROMPT_DIRS = [File.expand_path('../prompts', __dir__)]
@@ -76,19 +55,15 @@ module Pikuri
     # @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.
+    # Swap the shared sink (a +StringIO+ in tests, a file in a daemon),
+    # re-pointing every logger already handed out by {.logger_for}.
     #
-    # 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.
+    # Not +Logger#reopen+: it closes the previous sink before installing the new
+    # one, which makes "swap to a capture StringIO, then swap back" impossible —
+    # the original handle would be dead. Instead we swap each logger's +@logdev+
+    # to a fresh +Logger::LogDevice+ over +io+, leaving the previous device
+    # open. Uses an internal Logger ivar; if a future Ruby renames it the
+    # +Engines+ logging specs fail loudly.
     #
     # @param io [IO] new sink for every Pikuri logger
     # @return [IO]
@@ -100,16 +75,11 @@ module Pikuri
       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.
+    # Memoized {Logger} tagged with +name+ as its +progname+. Level resolves
+    # +PIKURI_LOG_<NAME>+ → +PIKURI_LOG+ → +INFO+. Repeated calls with the same
+    # +name+ return the same instance, so {.log_io=} can rewire them all.
     #
-    # @param name [String] subsystem tag (rendered as +progname+)
+    # @param name [String] subsystem tag (the +progname+)
     # @return [Logger]
     def logger_for(name)
       @log_loggers[name] ||= begin
@@ -120,25 +90,16 @@ module Pikuri
       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: ...)+.
+    # Read a bundled prompt by basename, searching {PROMPT_DIRS} in order
+    # (+.txt+ auto-appended; Symbols accepted). For downstream users
+    # bootstrapping their own +Agent+ wiring from pikuri's defaults.
     #
     # @example
-    #   chat_prompt = Pikuri.prompt(:'pikuri-chat')
-    #   agent = Pikuri::Agent.new(system_prompt: chat_prompt, ...)
+    #   agent = Pikuri::Agent.new(system_prompt: Pikuri.prompt(:'pikuri-chat'), ...)
     #
     # @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}
+    # @raise [ArgumentError] if no matching file exists in any {PROMPT_DIRS}
     def prompt(name)
       basename = name.to_s
       basename += '.txt' unless basename.end_with?('.txt')
@@ -149,30 +110,53 @@ module Pikuri
       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
+
+    # Read several bundled prompts and join them into one system prompt —
+    # the way a binary assembles a base prompt plus shared fragments (e.g.
+    # the tool-loop hygiene in +agent-loop.txt+).
+    #
+    #   system_prompt = Pikuri.prompts(:'pikuri-chat', :'agent-loop')
+    #   system_prompt += "\n\nCurrent date: #{...}"   # dynamic tail, still one blank line
+    #
+    # Each fragment is right-stripped before joining with a single blank
+    # line, and the result carries no trailing newline — so neither the
+    # fragment seams nor a later +"\n\n"+-prefixed append double-blanks,
+    # regardless of the +.txt+ files' own trailing newlines.
+    #
+    # @param names [Array<String, Symbol>] prompt basenames, in order
+    # @return [String] the fragments joined by a blank line
+    # @raise [ArgumentError] if any name has no matching file
+    def prompts(*names)
+      names.map { |name| prompt(name).rstrip }.join("\n\n")
+    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.
+  # Zeitwerk loader for every constant under +pikuri-core/lib/pikuri/+. A
+  # constant (not block-scoped) so a downstream host can add ignore rules
+  # without monkey-patching. Sibling gems set up their own loaders.
   #
   # @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.
+  # +pikuri/version.rb+ defines the ALL_CAPS +Pikuri::VERSION+, not
+  # +Pikuri::Version+ as Zeitwerk expects — so skip it (it's +require_relative+'d
+  # above and by the gemspec, so the constant is already defined).
   Loader.ignore(File.expand_path('pikuri/version.rb', __dir__))
+  # +pikuri/testing.rb+ is opt-in test scaffolding (+require 'pikuri/testing'+
+  # from a spec), kept off the production load path — so don't autoload or
+  # eager-load it. See {Pikuri::Testing}.
+  Loader.ignore(File.expand_path('pikuri/testing.rb', __dir__))
   Loader.inflector.inflect(
     'html'       => 'HTML',
     'duckduckgo' => 'DuckDuckGo'
   )
   Loader.setup
   Loader.eager_load
+
+  # Reap +~/.cache/pikuri/temp-*+ scratch left by processes killed before their
+  # {Pikuri::Finalizers} reap could fire. Best-effort, once per process at the
+  # earliest load point (every gem requires pikuri-core). See {Paths.new_temp}.
+  Paths.sweep_stale_temps!
 end

data/prompts/agent-loop.txt

@@ -0,0 +1,5 @@
+Working with tools:
+- If several next steps are independent (e.g. two unrelated lookups), emit them as parallel tool calls in one turn rather than one at a time.
+- Don't repeat a tool call with identical arguments — re-read the previous observation instead.
+- Treat a tool error (an observation starting with `Error:`) as feedback, not a dead-end: it often tells you how to proceed — retry with corrected or narrowed arguments. Only when the error genuinely leaves no way forward, use what you already have, or tell the user plainly what failed and why (a timeout, an unreachable resource, a rate limit, a missing tool). Don't retry the identical call.
+- When you're done, reply in plain text with no tool call — that is how you end the turn.

data/prompts/pikuri-chat.txt

@@ -1,15 +1,6 @@
 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".
+How to work:
+- When 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 — or for anything time-sensitive or obscure, search the web rather than answering from memory. Your training will *feel* certain on these and is often wrong; check rather than guess. One well-chosen search beats three exploratory ones.
+- For any arithmetic beyond simple mental math, compute it with a tool rather than in your head — and 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.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pikuri-core
 version: !ruby/object:Gem::Version
-  version: 0.0.7
+  version: 0.1.0
 platform: ruby
 authors:
 - Martin Vysny
@@ -85,14 +85,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.15'
+        version: '1.16'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.15'
+        version: '1.16'
 - !ruby/object:Gem::Dependency
   name: zeitwerk
   requirement: !ruby/object:Gem::Requirement
@@ -136,6 +136,7 @@ files:
 - lib/pikuri/agent/event.rb
 - lib/pikuri/agent/extension.rb
 - lib/pikuri/agent/extension_context.rb
+- lib/pikuri/agent/history.rb
 - lib/pikuri/agent/listener.rb
 - lib/pikuri/agent/listener/in_memory_event_list.rb
 - lib/pikuri/agent/listener/rate_limited.rb
@@ -143,16 +144,20 @@ files:
 - lib/pikuri/agent/listener/token_log.rb
 - lib/pikuri/agent/listener_list.rb
 - lib/pikuri/agent/synthesizer.rb
+- lib/pikuri/bundler_env.rb
 - lib/pikuri/extractor.rb
 - lib/pikuri/extractor/html.rb
 - lib/pikuri/extractor/passthrough.rb
 - lib/pikuri/file_type.rb
 - lib/pikuri/finalizers.rb
 - lib/pikuri/paths.rb
+- lib/pikuri/ruby_llm_patches.rb
 - lib/pikuri/sanitizer.rb
 - lib/pikuri/subprocess.rb
+- lib/pikuri/testing.rb
 - lib/pikuri/tool.rb
 - lib/pikuri/tool/calculator.rb
+- lib/pikuri/tool/execute_context.rb
 - lib/pikuri/tool/fetch.rb
 - lib/pikuri/tool/parameters.rb
 - lib/pikuri/tool/scraper.rb
@@ -162,10 +167,16 @@ files:
 - lib/pikuri/tool/search/exa.rb
 - lib/pikuri/tool/search/rate_limiter.rb
 - lib/pikuri/tool/search/result.rb
+- lib/pikuri/tool/trifecta_legs.rb
 - lib/pikuri/tool/web_scrape.rb
 - lib/pikuri/tool/web_search.rb
+- lib/pikuri/trifecta.rb
+- lib/pikuri/trifecta/contribution.rb
+- lib/pikuri/trifecta/node.rb
+- lib/pikuri/trifecta/report.rb
 - lib/pikuri/url_cache.rb
 - lib/pikuri/version.rb
+- prompts/agent-loop.txt
 - prompts/pikuri-chat.txt
 homepage: https://codeberg.org/mvysny/pikuri
 licenses: