active_harness 0.1.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 60a596cdaf7c45f9f3865c7ff7e41c3d1f2ba36cfc57eafc66a94a654bf64607
-  data.tar.gz: b8d989e7d6435168761ed94e12d126f0025e9b6a54d7b37464f135519747bfd0
+  metadata.gz: e13cc7f12afbddbea9116cae2b3f5c571386ff21a5d7246107a62ceadc3253be
+  data.tar.gz: 8f4cdcf1333b9f10acdd664e36568e741bf09652f4b8898d028dc3bf601024d9
 SHA512:
-  metadata.gz: b881ea07f0ec55d3116814a5080d9df5bde53773ac23182fc3c5d54cdcadb681d4bf8036570b3e3ef65a90a5e3760c0c775c0440eeacf50b4ebfcc9472849092
-  data.tar.gz: 73f97bc713e3b12f9f7527dfce99afcbe4cce903a104d71b687abc5bf0d73a4edbc8ed6afef3aac2db3dca40e5870a3ba14a31703625e8a93a113319c3b6c357
+  metadata.gz: bf13a6f23ac3053316b31890505d39369bb2e932def11dcc7ecdcb2e948aed9466f91d9b1fe1b356dba35112698f7d2e901f1971e93356f32a3b34743d731e7c
+  data.tar.gz: 43e7202af753ffd6c6761f21ba2543498c6d04c70e52a57fb9c1aa2cb5063922f536036e28e99bc7710f7e079c50a19839ad510b97ba33841a6d6ff7b15d3220

data/lib/active_harness/agent/hooks.rb

@@ -0,0 +1,75 @@
+module ActiveHarness
+  class Agent
+    VALID_HOOKS = %i[
+      setup
+      before_call
+      after_call
+      before_system_prompt
+      after_system_prompt
+      before_parse
+      after_parse
+      parse_error
+      retry
+      failure
+    ].freeze
+
+    class << self
+      # Unified hook DSL.
+      #
+      #   on :setup                do ... end
+      #   on :before_call          do ... end
+      #   on :after_call           do |result| ... end
+      #   on :before_system_prompt do ... end
+      #   on :after_system_prompt  do |prompt| ... end
+      #   on :before_parse         do |raw| ... end
+      #   on :after_parse          do |parsed| ... end
+      #   on :parse_error          do |raw, error| ... end
+      #   on :retry                do |entry, error| ... end
+      #   on :failure              do |attempts| ... end
+      def on(event, &block)
+        unless VALID_HOOKS.include?(event)
+          raise ArgumentError, "Unknown hook :#{event}. Valid hooks: #{VALID_HOOKS.map { |h| ":#{h}" }.join(", ")}"
+        end
+
+        agent_config[:hooks] ||= {}
+        agent_config[:hooks][event] = block
+      end
+
+      # Rails-style aliases for +on+:
+      #
+      #   before :call                    do ... end  # → on :before_call
+      #   before :system_prompt           do ... end  # → on :before_system_prompt
+      #   after  :call                    do |r| end  # → on :after_call
+      #   after  :system_prompt           do |p| end  # → on :after_system_prompt
+      #   after  :parse                   do |p| end  # → on :after_parse
+      #   callback :retry                 do |e,err| end
+      #   callback :failure               do |a| end
+      #   callback :setup                 do end
+      #   callback :parse_error           do |r,e| end
+      def before(event, &block)
+        on(:"before_#{event}", &block)
+      end
+
+      def after(event, &block)
+        on(:"after_#{event}", &block)
+      end
+
+      def callback(event, &block)
+        on(event, &block)
+      end
+    end
+
+    private
+
+    def run_hook(event, *args)
+      hooks = @config[:hooks] || {}
+      return unless hooks[event]
+
+      if args.any?
+        instance_exec(*args, &hooks[event])
+      else
+        instance_eval(&hooks[event])
+      end
+    end
+  end
+end

data/lib/active_harness/agent/models.rb

@@ -0,0 +1,147 @@
+module ActiveHarness
+  class Agent
+    class << self
+      # Array-style model list:
+      #
+      #   models [
+      #     { provider: :openai,     model: "gpt-4.1-mini" },
+      #     { provider: :openrouter, model: "mistralai/mistral-nemo" }
+      #   ]
+      def models(list)
+        agent_config[:models] = Array(list)
+      end
+
+      # Output format for this agent.
+      #
+      #   format :text   # default — output is returned as-is
+      #   format :json   # output is parsed; result.parsed is a Ruby Hash/Array
+      def format(type)
+        unless %i[text json].include?(type)
+          raise ArgumentError, "Unknown format :#{type}. Valid values: :text, :json"
+        end
+
+        agent_config[:format] = type
+      end
+
+      # Block-based model DSL:
+      #
+      #   model do
+      #     use      provider: :openrouter, model: "mistralai/mistral-nemo"
+      #     fallback provider: :openrouter, model: "meta-llama/llama-3.3-70b-instruct:free"
+      #   end
+      def model(&block)
+        config = ModelConfig.new
+        config.instance_eval(&block)
+        agent_config[:model] = config.to_h
+      end
+    end
+
+    # Public instance API — returns a ModelList proxy for this agent instance.
+    #
+    # Allows adding models at runtime before calling the agent:
+    #
+    #   agent.models.prepend([{ provider: :openrouter, model: "..." }])
+    #   agent.models.push([{ provider: :openrouter, model: "..." }])
+    #
+    # Any prepended/pushed models are combined with the class-defined chain:
+    #   [prepended...] + [class chain / constructor override] + [pushed...]
+    def models
+      @model_list_proxy ||= begin
+        base = if @models_override&.any?
+                 @models_override
+               elsif (m = @config[:model])
+                 m[:models] || []
+               else
+                 @config[:models] || []
+               end
+        ModelList.new(base)
+      end
+    end
+
+    private
+
+    def model_list
+      list = models.to_a
+      raise ArgumentError, "#{self.class.name}: no models configured. Use `model do...end` or `models [...]`." if list.empty?
+
+      list
+    end
+  end
+
+  # ---------------------------------------------------------------------------
+  # ModelList — mutable proxy returned by agent.models
+  # ---------------------------------------------------------------------------
+  class ModelList
+    def initialize(base_models)
+      @base      = Array(base_models)
+      @prepended = []
+      @appended  = []
+    end
+
+    # Add models BEFORE the existing chain. Calling multiple times keeps order
+    # (last prepend ends up first).
+    def prepend(models)
+      @prepended = Array(models) + @prepended
+      self
+    end
+
+    # Add models AFTER the existing chain.
+    def push(models)
+      @appended += Array(models)
+      self
+    end
+
+    # Replace the entire chain, discarding prepended/appended too.
+    #
+    #   agent.models.replace([{ provider: :openrouter, model: "..." }])
+    def replace(models)
+      @base      = Array(models)
+      @prepended = []
+      @appended  = []
+      self
+    end
+
+    # Insert a single model entry at an arbitrary position in the final chain.
+    # Position 0 is the same as prepend; -1 appends after the last element.
+    #
+    #   agent.models.insert(0,  { provider: :openrouter, model: "fast-model" })
+    #   agent.models.insert(2,  { provider: :openrouter, model: "mid-model" })
+    #   agent.models.insert(-1, { provider: :openrouter, model: "last-resort" })
+    def insert(position, model)
+      to_a.tap { |list| list.insert(position, model) }.then do |new_list|
+        @prepended = []
+        @base      = new_list
+        @appended  = []
+      end
+      self
+    end
+
+    # Return the fully assembled list: prepended + base + appended.
+    def to_a
+      @prepended + @base + @appended
+    end
+
+    def inspect
+      "#<ModelList prepended=#{@prepended.size} base=#{@base.size} appended=#{@appended.size}>"
+    end
+  end
+
+  # ---------------------------------------------------------------------------
+  # DSL builder — used by Agent.model { ... }
+  # ---------------------------------------------------------------------------
+  class ModelConfig
+    def initialize
+      @models = []
+    end
+
+    def use(provider:, model:, temperature: nil)
+      @models << { provider: provider, model: model, temperature: temperature }.compact
+    end
+
+    alias fallback use
+
+    def to_h
+      { models: @models }
+    end
+  end
+end

data/lib/active_harness/agent/output_parser.rb

@@ -0,0 +1,57 @@
+module ActiveHarness
+  class Agent
+    private
+
+    # Strips markdown code fences that some models add despite being told not to:
+    #   ```json\n{...}\n```  →  {...}
+    def strip_code_fences(raw)
+      raw.to_s.strip
+         .gsub(/\A```(?:json)?\s*/i, "")
+         .gsub(/\s*```\z/, "")
+         .strip
+    end
+
+    # Like run_hook but uses the block's return value to replace the current value.
+    # If no hook is defined, returns the original value unchanged.
+    #
+    #   on :before_parse do |raw|
+    #     raw.gsub("'", '"')   # fixed-up string is used for parsing
+    #   end
+    #
+    #   on :after_parse do |parsed|
+    #     parsed.transform_keys(&:to_sym)  # symbolized hash is stored in result
+    #   end
+    def transform_hook(event, value)
+      hooks = @config[:hooks] || {}
+      return value unless hooks[event]
+
+      instance_exec(value, &hooks[event])
+    end
+
+    def parse_output(raw)
+      return raw unless @config[:format] == :json
+
+      # :before_parse — return value replaces raw before stripping/parsing
+      raw = transform_hook(:before_parse, raw)
+
+      clean = strip_code_fences(raw)
+
+      begin
+        parsed = JSON.parse(clean)
+
+        # :after_parse — return value replaces parsed result stored in Result
+        transform_hook(:after_parse, parsed)
+      rescue JSON::ParserError => e
+        # :parse_error — if hook returns non-nil, it is used as fallback value
+        # and the exception is suppressed. Return nil (or omit return) to re-raise.
+        #
+        #   on :parse_error do |raw, error|
+        #     puts "Parse failed: #{error.message}"
+        #     { "result" => nil, "reason" => "parse error" }   # fallback
+        #   end
+        fallback = run_hook(:parse_error, raw, e)
+        fallback.nil? ? raise : fallback
+      end
+    end
+  end
+end

data/lib/active_harness/agent/prompt.rb

@@ -0,0 +1,58 @@
+module ActiveHarness
+  class Agent
+    class << self
+      # System prompt for this agent.
+      # Accepts:
+      #   - a String  → used as-is
+      #   - a Class   → instantiated and resolved via #call or #text
+      #   - a Proc    → called at request time (no arguments)
+      #
+      #   system_prompt "You are a helpful assistant."
+      #   system_prompt MyPromptClass
+      #   system_prompt -> { "Dynamic prompt built at #{Time.now}" }
+      def system_prompt(text_or_class)
+        agent_config[:system_prompt] = text_or_class
+      end
+      alias prompt system_prompt
+    end
+
+    private
+
+    attr_reader :system_prompt
+    public :system_prompt
+
+    def resolve_system_prompt
+      run_hook(:before_system_prompt)
+
+      sp = @config[:system_prompt]
+
+      prompt = case sp
+      when String   then sp
+      when NilClass then nil
+      when Proc     then instance_exec(&sp)
+      when Class
+        instance = sp.new
+        inject_agent_state(instance)
+        if    instance.respond_to?(:call) then instance.call
+        elsif instance.respond_to?(:text) then instance.text
+        else  instance.to_s
+        end
+      else
+        inject_agent_state(sp)
+        if    sp.respond_to?(:call) then sp.call
+        elsif sp.respond_to?(:text) then sp.text
+        else  sp.to_s
+        end
+      end
+
+      run_hook(:after_system_prompt, prompt)
+      prompt
+    end
+
+    def inject_agent_state(obj)
+      obj.instance_variable_set(:@input,   @input)
+      obj.instance_variable_set(:@context, @context)
+      obj.instance_variable_set(:@config,  @config)
+    end
+  end
+end

data/lib/active_harness/agent/providers.rb

@@ -0,0 +1,54 @@
+module ActiveHarness
+  class Agent
+    # Errors that allow retrying the next model in the chain
+    RETRYABLE_ERRORS = [
+      Errors::TimeoutError,
+      Errors::RateLimitError,
+      Errors::ServerError,
+      Errors::ProviderUnavailableError
+    ].freeze
+
+    # Errors that abort the entire chain immediately
+    STOP_ERRORS = [
+      Errors::InvalidRequestError,
+      Errors::InvalidApiKeyError,
+      Errors::SafetyBlockedError
+    ].freeze
+
+    PROVIDERS = {
+      openai:     -> { Providers::OpenAI.new },
+      openrouter: -> { Providers::OpenRouter.new },
+      groq:       -> { Providers::Groq.new },
+      gemini:     -> { Providers::Gemini.new },
+      anthropic:  -> { Providers::Anthropic.new }
+    }.freeze
+
+    private
+
+    def attempt_model(entry, system_prompt)
+      provider = resolve_provider(entry[:provider])
+      messages = build_messages(system_prompt, @input)
+      opts = { model: entry[:model], messages: messages }
+      opts[:temperature] = entry[:temperature] if entry[:temperature]
+      opts[:stream]      = @stream             if @stream
+      provider.call(**opts)
+    end
+
+    def resolve_provider(name)
+      factory = PROVIDERS[name.to_sym]
+      raise ArgumentError, "Unknown provider: #{name.inspect}. Supported: #{PROVIDERS.keys.join(', ')}" unless factory
+
+      factory.call
+    end
+
+    def build_messages(system_prompt, input)
+      # Memory is NOT auto-injected here.
+      # To use history in LLM context, inject it manually via a hook or prompt class.
+      # See ActiveHarness::Memory for examples.
+      messages = []
+      messages << { role: "system", content: system_prompt } if system_prompt
+      messages << { role: "user",   content: input }
+      messages
+    end
+  end
+end