phronomy 0.7.1 → 0.9.0

data/lib/phronomy/agent/context/capability/scope_policy.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    module Context
+      module Capability
+        # Evaluates whether a tool with a given scope may execute.
+        #
+        # A ScopePolicy is a callable that receives +(tool_class, scope, agent)+ and
+        # returns one of:
+        #   +:allow+   — proceed immediately without an approval gate.
+        #   +:reject+  — block execution; the tool returns a denial message.
+        #   +:approve+ — delegate to the agent's approval handler (if registered);
+        #                when no handler is registered the call is rejected.
+        #
+        # The {Default} instance is used automatically when no custom policy is
+        # configured on an agent.
+        #
+        # @example Custom policy that allows everything
+        #   agent.scope_policy = ->(_tool_class, _scope, _agent) { :allow }
+        #
+        # @example Strict policy that rejects all write scopes
+        #   agent.scope_policy = ->(_tc, scope, _agent) {
+        #     scope == :write ? :reject : :allow
+        #   }
+        class ScopePolicy
+          # Scopes that must go through an approval gate before execution.
+          APPROVAL_REQUIRED_SCOPES = %i[write admin external_network filesystem process external_process].freeze
+
+          # Scopes that are always permitted without approval.
+          ALWAYS_ALLOWED_SCOPES = %i[read_only].freeze
+
+          # Returns +:allow+ for always-allowed scopes, +:approve+ for high-risk
+          # scopes, and +:allow+ for anything else (including +nil+).
+          #
+          # @param _tool_class [Class]
+          # @param scope [Symbol, nil]
+          # @param _agent [Object]
+          # @return [:allow, :approve, :reject]
+          # @api private
+          def call(_tool_class, scope, _agent)
+            return :allow if scope.nil? || ALWAYS_ALLOWED_SCOPES.include?(scope)
+            return :approve if APPROVAL_REQUIRED_SCOPES.include?(scope)
+
+            :allow
+          end
+
+          # Shared singleton used when no custom policy is configured.
+          DEFAULT = new.freeze
+        end
+      end
+    end
+  end
+end

data/lib/phronomy/agent/context/instruction/prompt_template.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    module Context
+      module Instruction
+        # A prompt template that substitutes {{variable}} placeholders in a string.
+        #
+        # @example Simple human template
+        #   t = Phronomy::Agent::Context::Instruction::PromptTemplate.new(template: "Translate to {{lang}}: {{text}}")
+        #   t.format(lang: "French", text: "Hello")
+        #   # => "Translate to French: Hello"
+        #
+        # @example With a system template
+        #   t = Phronomy::Agent::Context::Instruction::PromptTemplate.new(
+        #     template: "{{question}}",
+        #     system_template: "You are a {{role}} assistant."
+        #   )
+        #   t.format_system(role: "helpful")
+        #   # => "You are a helpful assistant."
+        #
+        # As a Runnable, #invoke accepts a Hash of variables and returns a Hash
+        # with :prompt (and optionally :system) keys.
+        class PromptTemplate
+          include Phronomy::Runnable
+
+          PLACEHOLDER = /\{\{(\w+)\}\}/
+
+          attr_reader :template, :system_template
+
+          # @param template        [String] human message template with {{var}} placeholders
+          # @param system_template [String, nil] optional system message template
+          # @api public
+          def initialize(template:, system_template: nil)
+            @template = template
+            @system_template = system_template
+          end
+
+          # Substitute all {{var}} placeholders in the human template.
+          #
+          # @param variables [Hash{Symbol => String}]
+          # @return [String]
+          # @api public
+          def format(**variables)
+            substitute(@template, variables)
+          end
+
+          # Substitute all {{var}} placeholders in the system template.
+          # Returns nil when no system template was set.
+          #
+          # @param variables [Hash{Symbol => String}]
+          # @return [String, nil]
+          # @api public
+          def format_system(**variables)
+            @system_template && substitute(@system_template, variables)
+          end
+
+          # Runnable interface: accepts a Hash of variable values.
+          # Returns { prompt: String, system: String|nil }.
+          #
+          # @param input  [Hash{Symbol => String}]
+          # @return [Hash]
+          # @api public
+          def invoke(input, config: {})
+            vars = normalize_input(input)
+            result = {prompt: format(**vars)}
+            sys = format_system(**vars)
+            result[:system] = sys if sys
+            result
+          end
+
+          # Returns the list of placeholder names found in both templates.
+          #
+          # @return [Array<Symbol>]
+          # @api public
+          def variables
+            names = @template.scan(PLACEHOLDER).flatten
+            names += @system_template.scan(PLACEHOLDER).flatten if @system_template
+            names.map(&:to_sym).uniq
+          end
+
+          private
+
+          def substitute(text, variables)
+            text.gsub(PLACEHOLDER) do |match|
+              key = Regexp.last_match(1).to_sym
+              variables.fetch(key) { raise KeyError, "Missing variable: {{#{key}}}" }
+            end
+          end
+
+          def normalize_input(input)
+            case input
+            when Hash then input
+            when String then {input: input}
+            else raise ArgumentError, "PromptTemplate#invoke expects a Hash of variables, got #{input.class}"
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/phronomy/agent/context/knowledge/base.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    module Context
+      module Knowledge
+        # Abstract base class for all KnowledgeSource implementations.
+        #
+        # Subclasses must implement #fetch(query:) and return an Array of chunk Hashes.
+        # Each chunk Hash must contain:
+        #   :content [String]  the text to inject into the context
+        #   :type    [Symbol]  semantic tag (e.g. :static, :rag, :entity)
+        class Base
+          # Retrieve knowledge chunks relevant to the given query.
+          #
+          # @param query              [String, nil]                    the current user input used to select relevant chunks
+          # @param cancellation_token [Phronomy::Concurrency::CancellationToken, nil] optional token; raises CancellationError when cancelled
+          # @return [Array<Hash>] array of { content: String, type: Symbol }
+          # @api public
+          def fetch(query: nil, cancellation_token: nil)
+            cancellation_token&.raise_if_cancelled!
+            raise NotImplementedError, "#{self.class}#fetch is not implemented"
+          end
+
+          # Submits a {#fetch} call to {BlockingAdapterPool} and returns a
+          # {BlockingAdapterPool::PendingOperation}.
+          # Callers can fan out multiple fetches in parallel and await them all.
+          #
+          # @param query              [String, nil]
+          # @param cancellation_token [Phronomy::Concurrency::CancellationToken, nil]
+          # @param timeout            [Numeric, nil] seconds before the operation is abandoned
+          # @return [BlockingAdapterPool::PendingOperation]
+          # @api public
+          def fetch_async(query: nil, cancellation_token: nil, timeout: nil)
+            Phronomy::Runtime.instance.blocking_io.submit(
+              timeout: timeout,
+              cancellation_token: cancellation_token
+            ) do
+              fetch(query: query, cancellation_token: cancellation_token)
+            end
+          end
+
+          # Returns true when this source's content is considered static (i.e. does
+          # not change between agent invocations). Static sources are eligible for
+          # fingerprint-based caching in ContextVersionCache.
+          #
+          # Override in subclasses that return fixed content.
+          #
+          # @return [Boolean]
+          # @api public
+          def static?
+            false
+          end
+        end
+      end
+    end
+  end
+end

data/lib/phronomy/agent/context/knowledge/entity_knowledge.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    module Context
+      module Knowledge
+        # A KnowledgeSource that extracts named-entity facts from conversation history.
+        #
+        # This is the knowledge-injection counterpart of the old EntityMemory.
+        # It scans saved user messages with a regex heuristic (no LLM call) and
+        # returns the discovered facts as a single knowledge chunk tagged :entity.
+        #
+        # EntityKnowledge is stateful: it accumulates extracted facts via #update(messages:)
+        # which should be called each time new messages are saved.
+        #
+        # Supported extraction patterns (case-insensitive):
+        #   "my name is Alice"          → { name: "Alice" }
+        #   "I am Alice"                → { identity: "Alice" }
+        #   "I'm a software engineer"   → { occupation: "software engineer" }
+        #   "I work at / for Acme"      → { workplace: "Acme" }
+        #   "I live in Tokyo"           → { location: "Tokyo" }
+        #   "I'm from Tokyo"            → { location: "Tokyo" }
+        #   "I like / love Ruby"        → { preference: "Ruby" }
+        #
+        # @example
+        #   ks = Phronomy::Agent::Context::Knowledge::EntityKnowledge.new
+        #   ks.update(messages: chat_messages)
+        #   agent = MyAgent.new
+        #   agent.add_knowledge_source(ks)
+        #   agent.invoke("What is my name?")
+        class EntityKnowledge < Base
+          PATTERNS = [
+            [:name, /\bmy name is\s+([A-Za-z][A-Za-z0-9 \-']*)/i],
+            [:identity, /\bI\s+am\s+([A-Z][A-Za-z0-9 \-']+)/],
+            [:occupation, /\bI(?:'m| am) a(?:n)?\s+([A-Za-z][A-Za-z0-9 \-']*)/i],
+            [:workplace, /\bI (?:work|worked) (?:at|for|in)\s+([A-Za-z0-9][A-Za-z0-9 \-'.&,]*)/i],
+            [:location, /\bI live in\s+([A-Za-z][A-Za-z0-9 \-']*)/i],
+            [:location, /\bI(?:'m| am) from\s+([A-Za-z][A-Za-z0-9 \-']*)/i],
+            [:preference, /\bI (?:like|love|enjoy)\s+([A-Za-z][A-Za-z0-9 \-']*)/i]
+          ].freeze
+
+          def initialize
+            @entities = {}
+          end
+
+          # Scan messages and accumulate entity facts.
+          # Call this after saving a new set of messages (e.g. from a ConversationManager save hook).
+          #
+          # @param messages [Array] message objects responding to #role and #content
+          # @api public
+          def update(messages:)
+            messages.each do |msg|
+              next unless msg.role.to_sym == :user
+
+              extract(msg.content.to_s).each { |key, value| @entities[key] = value }
+            end
+          end
+
+          # Returns a single chunk containing all known entity facts in XML context format.
+          # Returns an empty array when no entities have been discovered.
+          #
+          # @param query              [String, nil]                    unused — entity knowledge is always fully injected
+          # @param cancellation_token [Phronomy::Concurrency::CancellationToken, nil] optional; raises CancellationError when cancelled
+          # @return [Array<Hash>]
+          # @api public
+          def fetch(query: nil, cancellation_token: nil)
+            cancellation_token&.raise_if_cancelled!
+            return [] if @entities.empty?
+
+            lines = @entities.map { |key, value| "- #{key}: #{value}" }.join("\n")
+            content = <<~CONTENT.chomp
+              Known facts about the user:
+              #{lines}
+            CONTENT
+            [{content: content, type: :entity}]
+          end
+
+          # Returns the current entity store (primarily for testing).
+          #
+          # @return [Hash]
+          # @api public
+          def entities
+            @entities.dup
+          end
+
+          private
+
+          def extract(text)
+            found = {}
+            PATTERNS.each do |key, pattern|
+              if (match = text.match(pattern))
+                value = match[1].strip.sub(/[.!?]\s+.*$/, "").gsub(/[.,;!?]+$/, "")
+                found[key] = value unless value.empty?
+              end
+            end
+            found
+          end
+        end
+      end
+    end
+  end
+end

data/lib/phronomy/agent/context/knowledge/static_knowledge.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    module Context
+      module Knowledge
+        # A KnowledgeSource backed by fixed text provided at construction time.
+        #
+        # Useful for injecting static documents, policy files, or configuration
+        # knowledge that does not change per request.
+        #
+        # @example
+        #   ks = Phronomy::Agent::Context::Knowledge::StaticKnowledge.new(
+        #     "Our refund policy: ...",
+        #     type: :policy
+        #   )
+        #   agent = MyAgent.new
+        #   agent.add_knowledge_source(ks)
+        #   agent.invoke("What is the refund policy?")
+        class StaticKnowledge < Base
+          # @param text   [String] the static knowledge text to inject
+          # @param type   [Symbol] semantic tag for the chunk (default :static)
+          # @param source [String, nil] label identifying where this knowledge came from
+          #   (e.g. a filename). Included in the context XML tag and exposed to the LLM
+          #   so that agents can produce grounded citations.
+          # @api public
+          def initialize(text, type: :static, source: nil)
+            @text = text.to_s
+            @type = type
+            @source = source
+          end
+
+          # Returns the fixed text as a single chunk, regardless of query.
+          #
+          # @param query              [String, nil]                    ignored for static knowledge
+          # @param cancellation_token [Phronomy::Concurrency::CancellationToken, nil] optional; raises CancellationError when cancelled
+          # @return [Array<Hash>]
+          # @api public
+          def fetch(query: nil, cancellation_token: nil)
+            cancellation_token&.raise_if_cancelled!
+            return [] if @text.empty?
+
+            chunk = {content: @text, type: @type}
+            chunk[:source] = @source if @source
+            [chunk]
+          end
+
+          # Static knowledge content never changes between invocations.
+          # @return [true]
+          # @api public
+          def static?
+            true
+          end
+        end
+      end
+    end
+  end
+end

data/lib/phronomy/agent/fsm.rb

@@ -8,7 +8,7 @@ module Phronomy
     #
     # +AgentFSM+ implements the minimal interface expected by {Phronomy::EventLoop}
     # (+#id+, +#start+, +#handle+) so it can be managed alongside
-    # {Phronomy::FSMSession} instances.  It is *not* a traditional finite-state
+    # {Phronomy::Agent::Lifecycle::FSMSession} instances.  It is *not* a traditional finite-state
     # machine; the name reflects its role in the EventLoop rather than internal
     # state transitions.
     #

data/lib/phronomy/agent/invocation_pipeline.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    # Encapsulates the core per-invocation LLM round-trip for {Agent::Base}.
+    #
+    # {Agent::Base#invoke_once} delegates the body of each LLM turn to this
+    # class, keeping the caller to a thin setup + trace frame (span≈2).
+    # The pipeline executes inside the agent's binding via +instance_exec+
+    # so that private concern methods (guardrails, hooks, cancellation) remain
+    # encapsulated in their original modules while the orchestration logic lives
+    # here.
+    #
+    # @api private
+    class InvocationPipeline
+      # @param agent [Agent::Base] the agent instance driving this invocation
+      # @api private
+      def initialize(agent)
+        @agent = agent
+      end
+
+      # Runs one LLM round-trip inside the agent's execution context.
+      #
+      # Calls private {Agent::Base} concern methods (guardrails, hooks,
+      # cancellation) via +instance_exec+ so that their encapsulation is
+      # preserved, then routes the LLM request through the configured adapter.
+      #
+      # @param input      [String, Hash] the user input for this turn
+      # @param messages   [Array]        prior conversation messages
+      # @param thread_id  [String, nil]  persistence thread identifier
+      # @param config     [Hash]         per-invocation options
+      # @return [Array(Hash, Phronomy::TokenUsage, nil)]
+      #   A two-element array: the result hash and the token usage (or nil on
+      #   suspension).
+      # @api private
+      def run(input, messages:, thread_id:, config:)
+        @agent.instance_exec(input, messages, thread_id, config) do |inp, msgs, tid, cfg|
+          # Run input guardrails before touching the LLM.
+          run_input_guardrails!(inp)
+
+          user_message = extract_message(inp)
+          chat = build_chat
+
+          # Assemble context (system prompt + history). Override #build_context to
+          # inject custom context editing logic at the Agent subclass level.
+          context = build_context(
+            inp,
+            messages: msgs,
+            thread_id: tid,
+            config: cfg,
+            budget: build_token_budget,
+            instruction: build_instructions(inp),
+            tools: self.class.tools + _handoff_tools
+          )
+          apply_instructions(chat, context[:system]) if context[:system]
+          (context[:tool_classes] || []).each { |tc| chat.with_tool(prepare_tool_class(tc)) }
+          context[:messages].each { |msg| chat.messages << msg }
+
+          # Run before_completion hooks (global → class → instance) before the LLM call.
+          run_before_completion_hooks!(chat, cfg)
+
+          # Register suspension hook for approval-required tools (no-op when a
+          # synchronous on_approval_required handler is already registered).
+          _register_suspension_hook!(chat)
+
+          # Check for cancellation immediately before the LLM call.
+          check_cancellation!(cfg, "invocation cancelled before LLM call")
+
+          # Forward the cancellation token to ParallelToolChat explicitly
+          # via the chat instance so that tool dispatch batches can observe
+          # cancellation without needing Thread.current.
+          chat.cancellation_token = cfg[:cancellation_token] if chat.respond_to?(:cancellation_token=)
+
+          begin
+            # Route the LLM call through the configured LLMAdapter so that the
+            # blocking HTTP request runs inside BlockingAdapterPool and the
+            # adapter can be swapped without changing agent code.
+            adapter = Phronomy.configuration.llm_adapter
+            response = adapter.complete_async(chat, user_message, config: cfg).await
+          rescue SuspendSignal => signal
+            checkpoint = Checkpoint.new(
+              thread_id: tid,
+              original_input: inp,
+              messages: chat.messages.dup,
+              pending_tool_name: signal.tool_name,
+              pending_tool_args: signal.args,
+              pending_tool_call_id: signal.tool_call_id
+            )
+            suspended_result = {output: nil, suspended: true, checkpoint: checkpoint, messages: chat.messages}
+            next [suspended_result, nil]
+          ensure
+            # Clear the chat's cancellation token reference after each LLM call.
+            chat.cancellation_token = nil if chat.respond_to?(:cancellation_token=)
+          end
+
+          output = response.content
+          usage = Phronomy::TokenUsage.from_tokens(response.tokens)
+
+          # Run output guardrails before returning to the caller.
+          run_output_guardrails!(output)
+
+          result = {output: output, messages: chat.messages, usage: usage}
+          [result, usage]
+        end
+      end
+    end
+  end
+end