active_harness 0.1.0 → 0.2.1

data/lib/active_harness/agent.rb

@@ -1,257 +1,136 @@
+require "json"
+
 module ActiveHarness
-  # DSL base class for agents and guard agents — one class, two roles.
-  #
-  # Main agent (class-method style — one-liner):
-  #   SupportAgent.call(input: "hi", context: {})
-  #
-  # Main agent (instance style — store params, call later):
-  #   agent  = SupportAgent.new(input: "hi", language: :ru, context: {})
-  #   result = agent.call
-  #   result = agent.call(constraints: { max_input_length: 200 })  # merge extra params
-  #
-  # Guard agent (same class, called positionally by the engine guard chain):
-  #   class InjectionGuard < ActiveHarness::Agent
-  #     model { use provider: :openai, model: "gpt-4.1-mini" }
-  #     system_prompt MyGuardPrompt
-  #     system_language :en
-  #   end
   class Agent
+    # -------------------------------------------------------------------------
+    # Class-level DSL — core
+    # -------------------------------------------------------------------------
     class << self
-      # Entry point.
-      #
-      # Main mode:  MyAgent.call(input: "...", context: {}, language: :en, translate: fn)
-      # Guard mode: MyGuard.call(payload)            — called by the engine guard chain
-      #             MyGuard.call("raw string")        — manual / test use
-      #             MyGuard.call(prev_input_result)   — manual / test use
-      def call(*args, input: nil, context: {}, constraints: {}, language: nil, translate: nil, options: {})
-        if args.any?
-          first   = args.first
-          payload = first.is_a?(Payload) ? first : Payload.new(
-            input:     first.is_a?(InputResult) ? first.processed : first.to_s,
-            context:   context,
-            language:  language,
-            translate: translate,
-            options:   options
-          )
-          call_as_guard(payload)
-        else
-          Engine.new(agent_config).call(
-            input: input, context: context, constraints: constraints,
-            language: language, translate: translate
-          )
-        end
-      end
-
-      # DSL -------------------------------------------------------------------
-
-      def system_language(lang)
-        agent_config[:system_language] = lang
-      end
-
-      # Registers a guard class for the safety chain (main agent only).
-      # Optional per-registration options are forwarded to the guard at call time.
-      # If name: is not given, defaults to the class name as a symbol (e.g., :InjectionGuard).
+      # Class-level entry point.
       #
-      # Examples:
-      #   guard InjectionGuard
-      #   guard InjectionGuard, name: :injection_guard
-      #   guard TopicGuard, name: :topic, allowed_topics: [:ruby, :programming]
-      def guard(klass, name: nil, **options)
-        guard_name = (name || klass.name).to_sym
-        agent_config[:guards] ||= []
-        agent_config[:guards] << { klass: klass, options: options, name: guard_name }
-      end
-
-      def model(&block)
-        config = ModelConfig.new
-        config.instance_eval(&block)
-        agent_config[:model] = config.to_h
+      #   SupportAgent.call(input: "Hi")
+      #   SupportAgent.call(input: "Hi", context: { user_id: 42 })
+      #   SupportAgent.call(input: "Hi", memory: memory)
+      def call(input: nil, context: {}, models: nil, memory: nil, stream: nil)
+        new(input: input, context: context, models: models, memory: memory, stream: stream).call
       end
 
-      def param(name, required: false)
-        agent_config[:params]          ||= []
-        agent_config[:required_params] ||= []
-        agent_config[:params] << { name: name, required: required }
-        agent_config[:required_params] << name if required
-      end
-
-      def system_prompt(text)
-        agent_config[:system_prompt] = text
-      end
-      alias prompt system_prompt
-
-      def output(type, schema: nil)
-        agent_config[:output_type]   = type
-        agent_config[:output_schema] = schema
-      end
-
-      def risk_tolerance(level)
-        agent_config[:risk_tolerance] = level
-      end
-
-      # Declares a default constraint for this agent.
-      # Call-time constraints (passed to .call) override agent-level defaults.
-      #
-      # Supported constraints:
-      #   constraint :max_input_length, 500   # reject inputs longer than 500 chars
-      def constraint(name, value)
-        agent_config[:constraints]       ||= {}
-        agent_config[:constraints][name]   = value
-      end
-
-      # How many times to retry when a guard returns invalid/unparseable JSON.
-      # Overrides ActiveHarness.config.guard_retries for this specific guard.
-      def guard_retries(n)
-        agent_config[:guard_retries] = n
-      end
-
-      # Accepts a String or a callable (proc/lambda).
-      # When a callable is given, it is called with the Payload at block time:
-      #   default_error_answer ->(payload) { payload.translate&.call("my.key") || "Fallback text" }
-      def default_error_answer(text_or_callable)
-        agent_config[:default_error_answer] = text_or_callable
-      end
-
-      # Initializer hook — runs once before the pipeline starts.
-      # Receives the Payload and must return it (optionally modified).
-      #
-      # Example:
-      #   setup do |payload|
-      #     payload.meta[:started_at] = Time.now
-      #     payload.context[:locale]  = determine_locale(payload.language)
-      #     payload
-      #   end
-      def setup(&block)
-        agent_config[:setup] = block
-      end
-
-      # Callbacks ------------------------------------------------------------
-      # All callbacks receive TWO arguments — (payload, current_value) — and
-      # must return the new current_value.  The payload is read-only context;
-      # current_value is what gets threaded through the pipeline stage.
-      #
-      # Main-agent pipeline hooks:
-      #   before(:guards)  { |payload, input|    input.strip   }  # String  → String
-      #   after(:guards)   { |payload, result|   result        }  # InputResult → InputResult
-      #   before(:guard, :injection_guard) { |payload, input| input.downcase }
-      #   after(:guard,  :injection_guard) { |payload, result| result }
-      #   before(:request) { |payload, prompt|   prompt        }  # Hash → Hash
-      #   after(:request)  { |payload, response| response      }  # ModelResponse → ModelResponse
-      #
-      # Guard-mode hooks (when *this* class acts as a guard):
-      #   before { |payload, input|  input.strip  }  # String → String
-      #   after  { |payload, result| result        }  # InputResult → InputResult
-      def before(hook = nil, guard_name = nil, &block)
-        if hook
-          key = (hook == :guard && guard_name) ? :"before_guard_#{guard_name}" : :"before_#{hook}"
-          agent_config[:callbacks] ||= {}
-          agent_config[:callbacks][key] ||= []
-          agent_config[:callbacks][key] << block
-        else
-          agent_config[:guard_before_callbacks] ||= []
-          agent_config[:guard_before_callbacks] << block
-        end
-      end
-
-      def after(hook = nil, guard_name = nil, &block)
-        if hook
-          key = (hook == :guard && guard_name) ? :"after_guard_#{guard_name}" : :"after_#{hook}"
-          agent_config[:callbacks] ||= {}
-          agent_config[:callbacks][key] ||= []
-          agent_config[:callbacks][key] << block
-        else
-          agent_config[:guard_after_callbacks] ||= []
-          agent_config[:guard_after_callbacks] << block
-        end
-      end
-
-      # Debug info from the most recent guard-mode .call (class-level).
-      attr_reader :last_run_prompt, :last_run_response
-
       # Each subclass gets its own isolated config hash.
       def agent_config
         @agent_config ||= {}
       end
 
-      private
-
-      def call_as_guard(payload)
-        # Run the guard's own setup hook (if defined)
-        setup_block = agent_config[:setup]
-        payload     = setup_block.call(payload) if setup_block
-
-        raw = payload.input
-
-        # Guard-mode before callbacks: (payload, String) → String
-        processed = run_guard_callbacks(agent_config[:guard_before_callbacks], payload, raw)
-
-        runner             = GuardRunner.new(self, payload: payload)
-        result             = runner.run(raw: raw, processed: processed)
-        @last_run_prompt   = runner.last_guard_prompt
-        @last_run_response = runner.last_guard_response
-
-        # Guard-mode after callbacks: (payload, InputResult) → InputResult
-        run_guard_callbacks(agent_config[:guard_after_callbacks], payload, result)
-      end
-
-      # Threads +current+ through each callback as (payload, current) → new_current.
-      def run_guard_callbacks(callbacks, payload, current)
-        Array(callbacks).reduce(current) { |val, cb| cb.call(payload, val) }
+      def inherited(subclass)
+        subclass.instance_variable_set(:@agent_config, {})
       end
     end
 
     # -------------------------------------------------------------------------
     # Instance API
     # -------------------------------------------------------------------------
-
-    # Build an agent instance with preset call parameters.
-    # Any keyword accepted by .call is valid here.
-    #
-    #   agent  = SupportAgent.new(input: "hello", language: :ru)
-    #   result = agent.call                              # use stored params
-    #   result = agent.call(constraints: { max_input_length: 200 })  # merge overrides
-    def initialize(input: nil, context: {}, constraints: {}, language: nil,
-                   translate: nil, options: {})
-      @stored_params = {
-        input:       input,
-        context:     context,
-        constraints: constraints,
-        language:    language,
-        translate:   translate,
-        options:     options
-      }
+    attr_accessor :input
+    attr_reader :context
+
+    def initialize(input: nil, context: {}, models: nil, memory: nil, stream: nil)
+      @input           = input
+      @context         = context
+      @config          = self.class.agent_config
+      @models_override = Array(models) if models
+      @stream          = stream
+      # memory: can be passed directly or via context[:memory]
+      @memory = memory || @context[:memory]
+      run_hook(:setup)
     end
 
-    # Execute the agent.  +overrides+ is merged into the stored params —
-    # any key present in overrides wins.
-    def call(**overrides)
-      params = @stored_params.merge(overrides) do |_key, stored, override|
-        # For Hash values (context, constraints) do a shallow merge so callers
-        # can add keys without replacing the whole hash.
-        (stored.is_a?(Hash) && override.is_a?(Hash)) ? stored.merge(override) : override
-      end
-      self.class.call(**params)
+    # Attempts each model in order, returns the first successful Result.
+    # Raises Errors::AllModelsFailed if every model in the chain fails.
+    #
+    # Optionally accepts input and stream callback inline:
+    #   agent.call("What is the capital of Japan?")
+    #   agent.call("...", stream: ->(token) { print token })
+    def call(input = nil, stream: nil)
+      @input  = input  if input
+      @stream = stream if stream
+      @memory&.load
+      @system_prompt = resolve_system_prompt
+      run_hook(:before_call)
+      attempts = []
+
+      model_list.each do |entry|
+        t0       = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        response = attempt_model(entry, @system_prompt)
+        elapsed  = (Process.clock_gettime(Process::CLOCK_MONOTONIC) - t0).round(3)
+        result   = build_result(response, entry, attempts, elapsed)
+        save_to_memory(result)
+        run_hook(:after_call, result)
+        return result
+      rescue *RETRYABLE_ERRORS => e
+        elapsed = (Process.clock_gettime(Process::CLOCK_MONOTONIC) - t0).round(3)
+        attempts << attempt_entry(entry, e, elapsed)
+        run_hook(:retry, entry, e)
+        next
+      rescue *STOP_ERRORS => e
+        elapsed = (Process.clock_gettime(Process::CLOCK_MONOTONIC) - t0).round(3)
+        attempts << attempt_entry(entry, e, elapsed)
+        run_hook(:retry, entry, e)
+        raise
+      end
+
+      run_hook(:failure, attempts)
+      raise Errors::AllModelsFailed, "All models failed. Attempts: #{attempts.inspect}"
     end
-  end
 
-  # ---------------------------------------------------------------------------
-  # Internal helper — collects the `use` + `fallback` entries inside a `model` block.
-  # ---------------------------------------------------------------------------
-  class ModelConfig
-    def initialize
-      @config = { fallbacks: [] }
-    end
+    private
 
-    def use(provider:, model:)
-      @config[:use] = { provider: provider, model: model }
+    def attempt_entry(entry, error, elapsed)
+      {
+        provider:       entry[:provider],
+        model:          entry[:model],
+        error:          error.message,
+        error_code:     error.respond_to?(:error_code) ? error.error_code : nil,
+        execution_time: elapsed
+      }
     end
 
-    def fallback(provider:, model:)
-      @config[:fallbacks] << { provider: provider, model: model }
+    def build_result(response, entry, attempts, elapsed)
+      raw    = response[:content]
+      parsed = parse_output(raw)
+
+      Result.new(
+        input:          @input,
+        output:         raw,
+        parsed:         parsed,
+        system_prompt:  @system_prompt,
+        provider:       entry[:provider],
+        model:          entry[:model],
+        temperature:    entry[:temperature],
+        model_list:     model_list,
+        attempts:       attempts,
+        execution_time: elapsed,
+        usage:          response[:usage]
+      )
     end
 
-    def to_h
-      @config
+    # Auto-save to memory if no manual record was done in after_call hook.
+    # Hooks fire after this method — if a hook calls memory.record manually,
+    # the automatic save here is still the first save (hook overrides are additive).
+    # To suppress auto-save, set @memory_auto_saved in the hook.
+    def save_to_memory(result)
+      return unless @memory
+
+      @memory.record(
+        request:  @input,
+        response: result.output,
+        agent:    self.class.name,
+        model:    result.model
+      )
     end
   end
 end
+
+require_relative "agent/prompt"
+require_relative "agent/hooks"
+require_relative "agent/models"
+require_relative "agent/providers"
+require_relative "agent/output_parser"
+

data/lib/active_harness/core/errors.rb

@@ -1,38 +1,32 @@
 module ActiveHarness
   module Errors
-    # Base
-    class Error < StandardError; end
+    Error = Class.new(StandardError)
 
-    # Configuration
-    class ConfigurationError < Error; end
-    class ContextValidationError < Error; end
+    # Raised when all models in the chain fail
+    AllModelsFailed = Class.new(Error)
 
-    # Provider — retryable (fallback chain continues)
-    class ProviderError < Error; end
-    class TimeoutError              < ProviderError; end
-    class RateLimitError            < ProviderError; end
-    class ProviderUnavailableError  < ProviderError; end
-    class ServerError               < ProviderError; end
+    # Raised by Tribunal when every agent fails or times out
+    AllAgentsFailed = Class.new(Error)
 
-    # Provider — terminal (fallback chain stops)
-    class InvalidRequestError       < ProviderError; end
-    class InvalidApiKeyError        < ProviderError; end
-    class SafetyBlockedError        < ProviderError; end
+    # Base for all provider-level failures — carries an optional error_code and metadata
+    class ProviderError < Error
+      attr_reader :error_code, :metadata
 
-    # Output
-    class SchemaValidationError < Error; end
-    class OutputParsingError    < Error; end
+      def initialize(message = nil, error_code: nil, metadata: nil)
+        super(message)
+        @error_code = error_code
+        @metadata   = metadata
+      end
+    end
 
-    # Guard — raised when the guard model returns unparseable or schema-invalid JSON.
-    # Triggers the retry loop inside GuardRunner.
-    class GuardResponseError < Error; end
+    TimeoutError             = Class.new(ProviderError)
+    RateLimitError           = Class.new(ProviderError)
+    ServerError              = Class.new(ProviderError)
+    ProviderUnavailableError = Class.new(ProviderError)
 
-    # Input constraints (max_input_length, etc.)
-    class ConstraintViolationError < Error; end
-
-    # Throttling (application-level, not provider-level)
-    class ThrottleError          < Error; end
-    class RequestThrottledError  < ThrottleError; end  # sliding-window rate limit
-    class UserHoldbackError      < ThrottleError; end  # progressive risk hold-back
+    # Non-retryable failures
+    InvalidRequestError = Class.new(ProviderError)
+    InvalidApiKeyError  = Class.new(ProviderError)
+    SafetyBlockedError  = Class.new(ProviderError)
   end
 end

data/lib/active_harness/http/client.rb

@@ -1,38 +1,27 @@
 require "net/http"
-require "json"
 
 module ActiveHarness
   module Http
-    # Thin HTTP POST adapter backed by Net::HTTP.
-    #
-    # To swap in Faraday (or any other client), assign a compatible object to
-    # ActiveHarness.config.http_client:
-    #
-    #   class FaradayClient
-    #     def post(url, headers:, body:, timeout:) = ...
-    #   end
-    #
-    #   ActiveHarness.configure { |c| c.http_client = FaradayClient.new }
-    #
+    # Thin Net::HTTP wrapper — no external dependencies.
     class Client
       # @param url     [URI]
       # @param headers [Hash{String => String}]
-      # @param body    [String]   serialized request body
-      # @param timeout [Integer]  seconds for both open and read timeout
+      # @param body    [String]   JSON-serialized body
+      # @param timeout [Integer]  seconds (open + read)
       # @return        [String]   raw response body
-      def post(url, headers:, body:, timeout:)
+      def post(url, headers:, body:, timeout: 30)
         http              = Net::HTTP.new(url.host, url.port)
         http.use_ssl      = true
-        http.read_timeout = timeout
         http.open_timeout = timeout
+        http.read_timeout = timeout
 
-        req      = Net::HTTP::Post.new(url)
+        req = Net::HTTP::Post.new(url)
         headers.each { |k, v| req[k] = v }
         req.body = body
 
         http.request(req).body
-      rescue Net::ReadTimeout, Net::OpenTimeout
-        raise Errors::TimeoutError, "Request timed out (#{url.host})"
+      rescue Net::OpenTimeout, Net::ReadTimeout
+        raise Errors::TimeoutError, "Request to #{url.host} timed out"
       rescue => e
         raise Errors::ProviderUnavailableError, "#{url.host} unreachable: #{e.message}"
       end

data/lib/active_harness/http/streaming_client.rb

@@ -0,0 +1,60 @@
+require "net/http"
+require "json"
+
+module ActiveHarness
+  module Http
+    # Streaming variant of Client.
+    # Calls +on_token+ for each content token as it arrives via SSE.
+    # Accumulates and returns the full content string when the stream ends.
+    class StreamingClient
+      # @param url      [URI]
+      # @param headers  [Hash{String => String}]
+      # @param body     [String]  JSON-serialized body
+      # @param timeout  [Integer] seconds (open + read)
+      # @param on_token [Proc]    called with each partial token string
+      # @return         [String]  full accumulated content
+      def post(url, headers:, body:, timeout: 60, on_token:)
+        http              = Net::HTTP.new(url.host, url.port)
+        http.use_ssl      = true
+        http.open_timeout = timeout
+        http.read_timeout = timeout
+
+        req = Net::HTTP::Post.new(url)
+        headers.each { |k, v| req[k] = v }
+        req.body = body
+
+        buffer  = ""
+        content = ""
+
+        http.request(req) do |response|
+          response.read_body do |chunk|
+            buffer += chunk
+            while (line_end = buffer.index("\n"))
+              line = buffer.slice!(0, line_end + 1).strip
+              next unless line.start_with?("data: ")
+
+              data = line.delete_prefix("data: ")
+              next if data == "[DONE]"
+
+              parsed = JSON.parse(data)
+              token  = parsed.dig("choices", 0, "delta", "content")
+              if token && !token.empty?
+                on_token.call(token)
+                content += token
+              end
+            end
+          end
+        end
+
+        content
+      rescue Net::OpenTimeout, Net::ReadTimeout
+        raise Errors::TimeoutError, "Request to #{url.host} timed out"
+      rescue JSON::ParserError
+        # ignore malformed SSE chunks
+        content
+      rescue => e
+        raise Errors::ProviderUnavailableError, "#{url.host} unreachable: #{e.message}"
+      end
+    end
+  end
+end

data/lib/active_harness/memory/adapter/base.rb

@@ -0,0 +1,36 @@
+module ActiveHarness
+  class Memory
+    module Adapter
+      # Contract that every adapter must implement.
+      # Subclasses override these four methods.
+      class Base
+        # Load turns for the given session from the storage backend.
+        # Must be called before read/write.
+        def open(session_id)
+          raise NotImplementedError, "#{self.class}#open not implemented"
+        end
+
+        # Return a plain Array of turn hashes.
+        # Each turn has at minimum: { request:, response: }
+        def read
+          raise NotImplementedError, "#{self.class}#read not implemented"
+        end
+
+        # Persist a single turn hash.
+        def write(turn)
+          raise NotImplementedError, "#{self.class}#write not implemented"
+        end
+
+        # Flush buffers and release resources.
+        def close
+          raise NotImplementedError, "#{self.class}#close not implemented"
+        end
+
+        # Remove all data for the current session from the backend.
+        def delete
+          raise NotImplementedError, "#{self.class}#delete not implemented"
+        end
+      end
+    end
+  end
+end