pikuri-core 0.0.6 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ac822a7bd46228f2eea2994c2e1428e3aa90c269e6ebafd603474fb630ba34ee
-  data.tar.gz: 00c69d139bc38c1a881bf87980970672517db51f59469aef266009a803a874db
+  metadata.gz: f2703004f3ce0c935f4ee932493db6231109f4ecde7bcfe0ec1481dfecc21001
+  data.tar.gz: adf19fd1af6df3aad4ef58d10d5845ce38932566ba5c9d33a7f45791c34287a3
 SHA512:
-  metadata.gz: d148d78b2027d747ef10f4dd7a19252f66bb1b5f99e8eef763149bf3e93ae608a3f7cf739b02ed4d92ab3ab39d8fe6888615a5acaf90dcb44ca783058a95a716
-  data.tar.gz: 32ef75bbd6d825970e5a1e6b5e27cf0fc812980e87e5ddd59b14f2c10772c91cf93003c2ebe2c9501f5e9682e726f77c4c387c7c83b467b9aa57dc91a9a178f0
+  metadata.gz: e7475e59d9dc941226a77c875a7236c6649f678e933938bc7d9bbe18a76cbb1b8b492c3d471d94db1e68dc242f2030e25a48c236b3690cb8191a77d403467bae
+  data.tar.gz: 28345b25378c2ae0dabe37d58b8cc592d2f45c4a634d57f134ecd0c15bad7b157c912aa09f9f93dab46a8e78e035400faf69f0e6a2e4222874ffe88e1c73503f

data/README.md

@@ -12,8 +12,10 @@ AI-assistant toolkit:
   token accounting, and structured capture.
 - Controls (`StepLimit`, `Cancellable`, `Interloper`) for budget
   enforcement + cancellation.
-- Four stateless bundled tools: `CALCULATOR`, `WEB_SEARCH`,
-  `WEB_SCRAPE`, `FETCH`.
+- Three stateless bundled tools (`CALCULATOR`, `WEB_SCRAPE`,
+  `FETCH`) plus a host-configured web-search tool built via
+  `Pikuri::Tool::WebSearch.build` (provider keys passed in, never
+  read from the environment).
 - A demo binary, `bin/pikuri-chat`.
 
 Extensions (skills, MCP, workspace, coding stack, named-agent
@@ -57,7 +59,7 @@ agent = Pikuri::Agent.new(
   step_limit: Pikuri::Agent::Control::StepLimit.new(max: 20)
 ) do |c|
   c.add_tool Pikuri::Tool::CALCULATOR
-  c.add_tool Pikuri::Tool::WEB_SEARCH
+  c.add_tool Pikuri::Tool::WebSearch.build
   c.add_listener Pikuri::Agent::Listener::Terminal.new
 end
 agent.run_loop(user_message: 'What is 17 * 23?')
@@ -68,7 +70,7 @@ handling, and cancellation.
 
 ## Further reading
 
-- **Narrative walkthrough:** [chapter 1 of the pikuri guide](../docs/guide/01-chat.md)
+- **Narrative walkthrough:** [the first-conversation chapter of the pikuri guide](../book/chat.md)
   — install llama.cpp, start the server, run `pikuri-chat`, the
   agentic loop, the four bundled tools, and search-provider
   privacy postures.

data/lib/pikuri/agent/chat_transport.rb

@@ -2,41 +2,145 @@
 
 module Pikuri
   class Agent
-    # The trio of arguments that has to travel together to +RubyLLM.chat+
-    # for model resolution to come out the same on every construction:
-    # the model id, the provider hint, and the registry-bypass flag.
+    # Everything that must travel together for a chat to resolve to the same
+    # model *on the same server* on every construction: model id, provider
+    # hint, registry-bypass flag, and — when the model lives off the
+    # process-global +RubyLLM.config+ default — that server's base URL and API
+    # key. One value object so a forwarding site (the synthesizer, a sub-agent
+    # spawn, a mid-conversation switch) can't silently drop a field and route
+    # the chat to the wrong server or raise +RubyLLM::ModelNotFoundError+.
     #
-    # Bundling them is structural protection against a recurring bug
-    # class — every forwarding site (the synthesizer rescue in
-    # {Agent#run_loop}, the +agent+ tool from +pikuri-subagents+
-    # spawning a sub-agent) used to pass the three individually, and
-    # dropping one routed the spawned chat to a different server or
-    # raised +RubyLLM::ModelNotFoundError+ on the unknown model id.
-    # With a single value object the call site can't silently miss a
-    # field.
+    # == Why +api_base+ / +api_key+ live here
     #
-    # Pure data carrier: no +RubyLLM+ references here, so the seam stays
-    # in {Agent}, +bin/pikuri-chat+, and {Tool}.
+    # +RubyLLM::Chat#with_model+ swaps only model/provider against the chat's
+    # *existing* connection, so switching to a model on a different server
+    # needs the connection to travel with the model — else the new id is sent
+    # to the old server's URL with the old key. {Agent} maps these two generic
+    # fields onto the provider's config slots (+#{provider}_api_base+ /
+    # +#{provider}_api_key+) via a per-chat +RubyLLM::Context+; both +nil+ for a
+    # transport riding the global config.
+    #
+    # Pure data carrier — no +RubyLLM+ references here, so the seam stays in
+    # {Agent}, +bin/pikuri-chat+, and {Tool}.
     #
     # @!attribute [r] model
-    #   @return [String, nil] LLM identifier; +nil+ defers to
-    #     +RubyLLM.config.default_model+ at {Agent} construction time
+    #   @return [String, nil] LLM id; +nil+ defers to
+    #     +RubyLLM.config.default_model+ at {Agent} construction.
     # @!attribute [r] provider
-    #   @return [Symbol, nil] forwarded to +RubyLLM.chat+. Required
-    #     together with +assume_model_exists+ when pointing at a local
-    #     OpenAI-compatible server (llama.cpp, gpustack, ...) whose model
-    #     ids are not in ruby_llm's bundled registry.
+    #   @return [Symbol, nil] forwarded to +RubyLLM.chat+. Required with
+    #     +assume_model_exists+ for a local OpenAI-compatible server whose ids
+    #     aren't in ruby_llm's registry, and whenever +api_base+/+api_key+ is
+    #     set (it names the config slots).
     # @!attribute [r] assume_model_exists
-    #   @return [Boolean] forwarded to +RubyLLM.chat+; +true+ skips
-    #     ruby_llm's registry lookup and trusts the supplied model id.
-    #     Requires +provider+.
-    class ChatTransport < Data.define(:model, :provider, :assume_model_exists)
+    #   @return [Boolean] forwarded to +RubyLLM.chat+; +true+ skips the registry
+    #     lookup and trusts the model id. Requires +provider+.
+    # @!attribute [r] api_base
+    #   @return [String, nil] this server's base URL (e.g.
+    #     +http://localhost:8080/v1+); +nil+ rides the global config. Mapped to
+    #     +#{provider}_api_base+ by {Agent}.
+    # @!attribute [r] api_key
+    #   @return [String, nil] API key for this server; +nil+ rides the global
+    #     config. Mapped to +#{provider}_api_key+ by {Agent}. Redacted in
+    #     {#inspect}.
+    # @!attribute [r] context_window
+    #   @return [Integer, nil] explicit context-window cap for this
+    #     model-on-server, or +nil+ to defer to {ContextWindowDetector}. Travels
+    #     with the model because the cap *is* per-model-per-server. Never sent to
+    #     ruby_llm — pure pikuri metadata read by
+    #     {Agent#detect_and_emit_context_cap!}, and the cap-inheritance channel:
+    #     a spawned agent gets +parent.transport.with(context_window:
+    #     parent.context_window_cap)+ so the resolved cap rides along without a
+    #     re-probe.
+    # @!attribute [r] faraday_adapter
+    #   @return [Class, Symbol, nil] a custom Faraday adapter to install on this
+    #     agent's per-chat +RubyLLM::Context+ (via +config.faraday_adapter=+),
+    #     or +nil+ for ruby_llm's default (+:net_http+). A generic HTTP seam —
+    #     inject a VCR / logging / *scripted-fake* adapter without touching the
+    #     global +RubyLLM.config+. Its worked use is
+    #     {Pikuri::Testing.fake_transport}, which bakes an anonymous scripted
+    #     adapter here so the real ruby_llm loop runs against canned HTTP. Only
+    #     honoured on the connection-override path ({#connection_overrides?}),
+    #     which any adapter-carrying transport is on (it also sets +api_base+).
+    class ChatTransport < Data.define(:model, :provider, :assume_model_exists, :api_base, :api_key,
+                                      :context_window, :faraday_adapter)
+      # Build an +:openai+-provider transport for an OpenAI-compatible server
+      # (local llama.cpp, cloud endpoint, ...), carrying its connection so the
+      # agent rides a per-chat +RubyLLM::Context+ instead of the global config.
+      # The +bin/pikuri-*+ host-boot factory in place of +RubyLLM.configure+ —
+      # one isolated connection per agent.
+      #
+      # A trailing +/v1+ on +server+ is stripped and re-appended exactly once,
+      # so +https://api.x.ai+, +.../v1+, and +.../v1/+ all normalize to the same
+      # +.../v1+ base — without which a +/v1+-terminated value would double to
+      # +/v1/v1+ and 404.
+      #
+      # @param server [String] server origin, with or without a trailing +/v1+
+      # @param model [String] model id served there, trusted verbatim
+      # @param api_key [String] API key; the +"not-needed"+ placeholder for a
+      #   keyless local server
+      # @param context_window [Integer, nil] explicit cap, or +nil+ to defer to
+      #   {ContextWindowDetector}'s +/props+ probe (right for local llama.cpp;
+      #   an override for a cloud server the probe can't reach)
+      # @return [ChatTransport]
+      def self.from_openai_server(server:, model:, api_key: 'not-needed', context_window: nil)
+        base = server.to_s.strip.chomp('/').delete_suffix('/v1')
+        new(
+          model: model,
+          provider: :openai,
+          assume_model_exists: true,
+          api_base: "#{base}/v1",
+          api_key: api_key,
+          context_window: context_window
+        )
+      end
+
       # @param model [String, nil]
       # @param provider [Symbol, nil]
       # @param assume_model_exists [Boolean]
-      def initialize(model:, provider: nil, assume_model_exists: false)
+      # @param api_base [String, nil]
+      # @param api_key [String, nil]
+      # @param context_window [Integer, nil]
+      # @param faraday_adapter [Class, Symbol, nil]
+      # @raise [ArgumentError] if +api_base+ or +api_key+ is set without
+      #   a +provider+ (the provider names the config slots the
+      #   connection overrides map onto)
+      def initialize(model:, provider: nil, assume_model_exists: false,
+                     api_base: nil, api_key: nil, context_window: nil, faraday_adapter: nil)
+        if (api_base || api_key) && provider.nil?
+          raise ArgumentError, "api_base/api_key require a provider, got #{provider.inspect}"
+        end
+
         super
       end
+
+      # Model-resolution kwargs to spread into +RubyLLM.chat+ /
+      # +RubyLLM::Context#chat+. Excludes the connection fields (those configure
+      # the +Context+, not the +chat+ call).
+      #
+      # @return [Hash{Symbol => String, Symbol, Boolean, nil}]
+      def chat_kwargs
+        { model: model, provider: provider, assume_model_exists: assume_model_exists }
+      end
+
+      # Whether this transport overrides the process-global connection
+      # (and so needs a dedicated +RubyLLM::Context+).
+      #
+      # @return [Boolean]
+      def connection_overrides?
+        !api_base.nil? || !api_key.nil?
+      end
+
+      # Default +Data#inspect+ would print +api_key+ verbatim into any log line
+      # or backtrace. Redact it.
+      #
+      # @return [String]
+      def inspect
+        "#<#{self.class} model=#{model.inspect} provider=#{provider.inspect} " \
+          "assume_model_exists=#{assume_model_exists} api_base=#{api_base.inspect} " \
+          "api_key=#{api_key.nil? ? 'nil' : '[REDACTED]'} context_window=#{context_window.inspect} " \
+          "faraday_adapter=#{faraday_adapter.inspect}>"
+      end
+      alias to_s inspect
     end
   end
 end

data/lib/pikuri/agent/configurator.rb

@@ -2,64 +2,40 @@
 
 module Pikuri
   class Agent
-    # Build-time collector yielded into the +Pikuri::Agent.new+ block.
-    # Hosts and {Extension} implementations call its methods to declare
-    # additional tools, listeners, system-prompt snippets, +on_close+
-    # handlers, extension instances, and persona-flavored sub-agents;
-    # {Agent#initialize} drains the collected state into the agent's
-    # final wiring before returning.
-    #
-    # == Why this exists
-    #
-    # Splits "configure the agent" from "the agent's runtime state".
-    # Hosts can write a block that reads cleanly:
+    # Build-time collector yielded into the +Pikuri::Agent.new+ block. Hosts
+    # and {Extension}s call its methods to declare tools, listeners,
+    # +on_close+ handlers, and extension instances; {Agent#initialize} drains
+    # the collected state into the agent's wiring before returning, then
+    # discards the Configurator (it carries no runtime state). System-prompt
+    # contributions are *not* collected here — the Agent pulls them from each
+    # extension's {Extension#system_prompt_snippets} at assembly time.
     #
     #   Pikuri::Agent.new(transport: ..., system_prompt: ...) do |c|
     #     c.add_listener Pikuri::Agent::Listener::Terminal.new
-    #     c.add_tool     Pikuri::Tool::WEB_SEARCH
-    #     c.add_tool     Pikuri::Tool::WEB_SCRAPE
-    #     c.add_tool     Pikuri::Tool::FETCH
-    #     c.add_extension Pikuri::Skill::Extension.new(catalog: catalog)
+    #     c.add_tool     Pikuri::Tool::WebSearch.build
+    #     c.add_extension Pikuri::Skill::Extension.new(catalog: catalog, root: project_root)
     #   end
     #
-    # == Two tool pools: regular vs. sub-agent-only
-    #
-    # {#add_tool} registers a tool the parent agent can call: it lands
-    # in {#tools} and gets handed to ruby_llm via +chat.with_tool+.
-    # {#add_sub_agent_tool} registers a tool the parent *cannot* call
-    # — it lands in {#sub_agent_tools} and is never sent to ruby_llm
-    # for the parent, but is visible to {Pikuri::SubAgent::Extension}'s
-    # persona-tool-name resolution. The use case is the lethal-trifecta
-    # defense in {Pikuri::Code::Bash::Sandbox} terms: keep network tools
-    # (+web_search+ / +web_scrape+ / +fetch+) off the parent so a prompt-
-    # injected file read cannot egress through the parent's own tools,
-    # while still letting the +researcher+ persona reach them via the
-    # +agent+ delegation tool. See SECURITY.md §"Defense: capability
-    # boundaries via sub-agents".
+    # Extensions implement +configure(c)+ against this same type, so
+    # block-users and extensions share one API.
     #
-    # Extensions implement their +configure(c)+ hook against the same
-    # type, so the call sites for "block users add stuff" and
-    # "extensions add stuff" share one API.
-    #
-    # == Lifecycle
+    # == Two tool pools: regular vs. sub-agent-only
     #
-    # One +Configurator+ per +Agent.new+ invocation. The Configurator
-    # is constructed inside {Agent#initialize}, yielded to the block
-    # (if any), then its collected state is drained by the Agent body.
-    # The Configurator instance is discarded once +Agent.new+ returns
-    # — it carries no runtime state.
+    # {#add_tool} registers a tool the parent agent can call (lands in {#tools},
+    # handed to ruby_llm). {#add_sub_agent_tool} registers one the parent
+    # *cannot* call (lands in {#sub_agent_tools}, never sent to ruby_llm for the
+    # parent) but which {Pikuri::SubAgent::Extension}'s persona-tool-name
+    # resolution can reach. The use case is the lethal-trifecta defense: keep
+    # network tools (+web_search+ / +web_scrape+ / +fetch+) off the parent so a
+    # prompt-injected file read can't egress through it, while the +researcher+
+    # persona still reaches them via the +agent+ tool. See SECURITY.md.
     class Configurator
-      # @return [Agent::ChatTransport] same transport the Agent will
-      #   use. Extensions read this to wire helpers consistently
-      #   (e.g. an MCP description-synthesizer that calls the same
-      #   model the agent itself uses).
+      # @return [Agent::ChatTransport] same transport the Agent will use, so an
+      #   extension can wire helpers against the same model.
       attr_reader :transport
 
-      # @return [String] the +system_prompt:+ kwarg passed to
-      #   {Agent#initialize}, untouched. Extensions append to the
-      #   prompt via {#append_system_prompt} rather than mutating
-      #   this; the attribute exists so a peek at the base is
-      #   available for diagnostics.
+      # @return [String] the +system_prompt:+ kwarg, untouched — the base the
+      #   Agent prepends to the pulled {Extension#system_prompt_snippets}.
       attr_reader :system_prompt_base
 
       # @return [String] this agent's unique identifier; empty for the
@@ -74,28 +50,22 @@ module Pikuri
       #   to the Agent ctor, or +nil+.
       attr_reader :step_limit
 
-      # @return [Control::Cancellable, nil] cancellation control
-      #   passed to the Agent ctor, or +nil+. Extensions that run
-      #   sub-LLM calls during +configure+ (e.g. an MCP description
-      #   synthesizer) share this so a user cancel during boot
-      #   propagates correctly.
+      # @return [Control::Cancellable, nil] cancellation control, or +nil+.
+      #   Extensions running sub-LLM calls in +configure+ share it so a user
+      #   cancel during boot propagates.
       attr_reader :cancellable
 
       # @return [Control::Interloper, nil] mid-loop user-input queue
       #   passed to the Agent ctor, or +nil+.
       attr_reader :interloper
 
-      # @return [Array<Tool>] tools added via {#add_tool}, in
-      #   declaration order. Drained by {Agent#initialize} and
-      #   registered with ruby_llm so the parent LLM can call them.
+      # @return [Array<Tool>] tools added via {#add_tool}, in declaration order;
+      #   drained by {Agent#initialize} and registered with ruby_llm.
       attr_reader :tools
 
-      # @return [Array<Tool>] tools added via {#add_sub_agent_tool},
-      #   in declaration order. Drained by {Agent#initialize} but
-      #   *not* registered with ruby_llm — invisible to the parent
-      #   LLM, available only to sub-agents through
-      #   {Pikuri::SubAgent::Extension}'s persona-tool-name
-      #   resolution. See the class header.
+      # @return [Array<Tool>] tools added via {#add_sub_agent_tool}, in
+      #   declaration order; drained but *not* registered with ruby_llm —
+      #   available only to sub-agents (see the class header).
       attr_reader :sub_agent_tools
 
       # @return [Array<Listener::Base>] listeners added via
@@ -103,21 +73,14 @@ module Pikuri
       #   {Agent#initialize}.
       attr_reader :listeners
 
-      # @return [Array<String>] system-prompt snippets added via
-      #   {#append_system_prompt}, in declaration order. Joined with
-      #   double-newline separators between the base prompt and each
-      #   snippet by {Agent#initialize}.
-      attr_reader :system_prompt_additions
-
       # @return [Array<Proc>] +on_close+ handlers added via
       #   {#on_close}, in declaration order. Fired by {Agent#close}
       #   in LIFO order with per-handler rescue.
       attr_reader :on_close_handlers
 
       # @return [Array<#configure>] extension instances added via
-      #   {#add_extension}, in declaration order. The Agent ctor
-      #   walks this list and calls +bind(self)+ on each after
-      #   wiring is complete.
+      #   {#add_extension}, in declaration order. The Agent calls +bind+ on
+      #   each after wiring is complete.
       attr_reader :extensions
 
       # @param transport [Agent::ChatTransport]
@@ -127,15 +90,14 @@ module Pikuri
       # @param step_limit [Control::StepLimit, nil]
       # @param cancellable [Control::Cancellable, nil]
       # @param interloper [Control::Interloper, nil]
-      # @param on_close_sink [Array<Proc>, nil] array that {#on_close}
-      #   appends to. {Agent#initialize} passes its own live
-      #   +@on_close_handlers+ so a handler an extension arms via
-      #   +c.on_close+ is reachable the instant it's registered — which
-      #   is what lets the constructor close a half-built agent if a
-      #   later extension's +configure+ raises. Defaults to a fresh
-      #   array for standalone use (e.g. specs).
+      # @param on_close_sink [Array<Proc>, nil] array {#on_close} appends to.
+      #   {Agent#initialize} passes its live +@on_close_handlers+ so a handler
+      #   armed via +c.on_close+ is reachable instantly — what lets the
+      #   constructor close a half-built agent if a later +configure+ raises.
+      #   Defaults to a fresh array (standalone/spec use).
       def initialize(transport:, system_prompt_base:, id:, streaming:,
-                     step_limit:, cancellable:, interloper:, on_close_sink: nil)
+                     step_limit:, cancellable:, interloper:,
+                     on_close_sink: nil)
         @transport = transport
         @system_prompt_base = system_prompt_base
         @id = id
@@ -147,7 +109,6 @@ module Pikuri
         @tools = []
         @sub_agent_tools = []
         @listeners = []
-        @system_prompt_additions = []
         @on_close_handlers = on_close_sink || []
         @extensions = []
       end
@@ -202,30 +163,10 @@ module Pikuri
         nil
       end
 
-      # Append a snippet to the system prompt. Snippets are joined
-      # to the base prompt with double-newline separators.
-      #
-      # Used by extensions to register +<available_skills>+,
-      # +<available_mcps>+, and similar advertisement blocks. Block
-      # users typically pass the full system prompt via the ctor's
-      # +system_prompt:+ kwarg instead.
-      #
-      # @param snippet [String]
-      # @return [void]
-      def append_system_prompt(snippet)
-        @system_prompt_additions << snippet
-        nil
-      end
-
-      # Register an extension. The extension's +configure(self)+ is
-      # called immediately so source-order matches execution-order.
-      # The instance is also retained for the +bind(agent)+ sweep
-      # that runs at the end of {Agent#initialize}.
-      #
-      # Extensions must implement both +configure+ and +bind+. The
-      # easy way is to +include Pikuri::Agent::Extension+ — that
-      # mixes in empty defaults for both, so an extension overrides
-      # only what it cares about and leaves the other as a no-op.
+      # Register an extension: its +configure(self)+ runs immediately (so
+      # source order matches execution order), and the instance is retained for
+      # the +bind(ctx)+ sweep at the end of {Agent#initialize}. Both hooks are
+      # required — +include Pikuri::Agent::Extension+ for no-op defaults.
       #
       # @param extension [Extension, #configure, #bind] extension instance
       # @return [void]
@@ -235,9 +176,8 @@ module Pikuri
         nil
       end
 
-      # Register a handler called by {Agent#close}. Handlers fire in
-      # LIFO order, each inside its own +rescue+ — same semantics as
-      # +ensure+-block cleanup discipline.
+      # Register a handler called by {Agent#close} (LIFO, each inside its own
+      # +rescue+).
       #
       # @yield called with no arguments at close time
       # @return [void]