active_harness 0.1.0 → 0.2.1

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

@@ -0,0 +1,141 @@
+require "json"
+require "fileutils"
+
+module ActiveHarness
+  class Memory
+    module Adapter
+      # Persists memory as JSON files on disk.
+      #
+      # Each session is stored in one file:
+      #   <path>/<session_id>.json                   (no namespace)
+      #   <path>/<session_id>/<namespace>.json       (with namespace)
+      #
+      # Options:
+      #   path             — base directory                  (default: "storage/ai/memory")
+      #   filename         — String or Proc(session_id)      (default: "<session_id>.json")
+      #   pretty           — format JSON with indentation    (default: false)
+      #   compact          — store only q/a keys             (default: false)
+      #   encoding         — file encoding                   (default: "UTF-8")
+      #   storage_size     — max turns kept in file          (default: 1000)
+      #   eviction_percent — % of oldest turns to drop       (default: 10)
+      #   on_trim          — Proc called with trimmed turns  (default: nil)
+      class File < Base
+        DEFAULT_PATH             = "storage/ai/memory"
+        DEFAULT_STORAGE_SIZE     = 1000
+        DEFAULT_TRIM_PERCENT = 10
+
+        def initialize(opts = {})
+          @path             = opts.fetch(:path, DEFAULT_PATH)
+          @filename_opt     = opts[:filename]
+          @pretty           = opts.fetch(:pretty, false)
+          @compact          = opts.fetch(:compact, false)
+          @encoding         = opts.fetch(:encoding, "UTF-8")
+          @storage_size     = opts.fetch(:storage_size, DEFAULT_STORAGE_SIZE)
+          @trim_percent = opts.fetch(:eviction_percent, DEFAULT_TRIM_PERCENT)
+          @on_trim          = opts[:on_trim]
+          @namespace        = opts[:namespace]
+
+          @session_id = nil
+          @turns      = []
+        end
+
+        def open(session_id)
+          @session_id = session_id
+          @turns      = load_from_disk
+        end
+
+        def read
+          @turns.dup
+        end
+
+        def write(turn)
+          @turns << turn
+          trim_if_needed!
+          flush!
+        end
+
+        def close
+          # File adapter writes immediately on each write, nothing to flush.
+        end
+
+        def delete
+          path = file_path
+          ::FileUtils.rm_f(path)
+          # remove parent dir only if it's a namespace dir and now empty
+          dir = ::File.dirname(path)
+          if @namespace && Dir.exist?(dir) && Dir.empty?(dir)
+            Dir.rmdir(dir)
+          end
+          @turns = []
+        end
+
+        # -----------------------------------------------------------------------
+        private
+        # -----------------------------------------------------------------------
+
+        def file_path
+          name = resolve_filename
+          if @namespace
+            ::File.join(@path, @session_id.to_s, "#{@namespace}.json")
+          elsif @filename_opt
+            ::File.join(@path, name)
+          else
+            ::File.join(@path, name)
+          end
+        end
+
+        def resolve_filename
+          case @filename_opt
+          when Proc   then @filename_opt.call(@session_id)
+          when String then @filename_opt
+          else             "#{@session_id}.json"
+          end
+        end
+
+        def load_from_disk
+          path = file_path
+          return [] unless ::File.exist?(path)
+
+          raw  = ::File.read(path, encoding: @encoding)
+          data = JSON.parse(raw, symbolize_names: true)
+          turns = Array(data[:turns])
+
+          # Normalise compact format (q/a) to full format (request/response)
+          turns.map do |t|
+            if t.key?(:q)
+              { request: t[:q], response: t[:a] }
+            else
+              t
+            end
+          end
+        rescue JSON::ParserError
+          []
+        end
+
+        def flush!
+          path = file_path
+          ::FileUtils.mkdir_p(::File.dirname(path))
+
+          turns_to_write = if @compact
+            @turns.map { |t| { q: t[:request], a: t[:response] } }
+          else
+            @turns
+          end
+
+          data = { session_id: @session_id, turns: turns_to_write }
+          json = @pretty ? JSON.pretty_generate(data) : JSON.generate(data)
+          ::File.write(path, json, encoding: @encoding)
+        end
+
+        def trim_if_needed!
+          return unless @storage_size
+          return if @turns.size <= @storage_size
+
+          count   = [@turns.size * @trim_percent / 100, 1].max
+          trimmed = @turns.shift(count)
+          @on_trim&.call(trimmed)
+        end
+      end
+    end
+  end
+end

data/lib/active_harness/memory.rb

@@ -0,0 +1,212 @@
+require_relative "memory/adapter/base"
+require_relative "memory/adapter/file"
+
+module ActiveHarness
+  # Conversational memory for agents.
+  #
+  # Memory only records the history of request/response turns.
+  # It does NOT automatically inject history into LLM messages.
+  # Injection is always manual — you control when and how context is used.
+  #
+  # --- Recording (automatic) ---
+  #
+  # When a Memory object is passed to an agent, the agent automatically
+  # saves each successful turn (request + response) after the call.
+  #
+  #   memory = ActiveHarness::Memory.new(session_id: "u42", depth: 8)
+  #   SupportAgent.call(input: "Hello", memory: memory)
+  #   # => turn is saved to storage/ai/memory/u42.json
+  #
+  # --- Manual injection patterns ---
+  #
+  # Option A: prepend history to input in a before_call hook
+  #
+  #   on :before_call do
+  #     history = @memory&.to_messages
+  #     if history&.any?
+  #       lines = history.map { |m| "#{m[:role]}: #{m[:content]}" }.join("\n")
+  #       @input = "Previous conversation:\n#{lines}\n\nUser: #{@input}"
+  #     end
+  #   end
+  #
+  # Option B: inject history into the system prompt
+  #
+  #   on :after_system_prompt do |prompt|
+  #     history = @memory&.to_messages
+  #     if history&.any?
+  #       lines = history.map { |m| "#{m[:role]}: #{m[:content]}" }.join("\n")
+  #       @system_prompt = "#{prompt}\n\nConversation so far:\n#{lines}"
+  #     end
+  #   end
+  #
+  # Option C: use a prompt class that reads @memory directly
+  #
+  #   class SupportPrompt
+  #     def call
+  #       base = "You are a helpful assistant."
+  #       return base unless @memory&.size&.positive?
+  #       history = @memory.to_messages
+  #                        .map { |m| "#{m[:role]}: #{m[:content]}" }
+  #                        .join("\n")
+  #       "#{base}\n\nConversation so far:\n#{history}"
+  #     end
+  #   end
+  #
+  class Memory
+    ADAPTERS = {
+      file: ->(**opts) { Adapter::File.new(**opts) }
+    }.freeze
+
+    attr_reader :session_id
+
+    # -------------------------------------------------------------------------
+    # Constructor
+    # -------------------------------------------------------------------------
+    #   session_id       — required; uniquely identifies this conversation
+    #   depth            — how many past turns to inject into messages (nil = all)
+    #   adapter          — :file (default), or an adapter instance
+    #   enabled          — false disables all reads and writes (no-op mode)
+    #   read_only        — true: load history but never write new turns
+    #   namespace        — isolates history per-agent within a session
+    #   on_trim          — Proc called with trimmed turns on storage trim
+    #   async            — write to adapter in a background thread
+    #   **adapter_opts   — forwarded to the adapter (path, storage_size, etc.)
+    def initialize(
+      session_id:,
+      depth:       nil,
+      adapter:     :file,
+      enabled:     true,
+      read_only:   false,
+      namespace:   nil,
+      on_trim:     nil,
+      async:       false,
+      **adapter_opts
+    )
+      @session_id  = session_id
+      @depth       = depth
+      @enabled     = enabled
+      @read_only   = read_only
+      @namespace   = namespace
+      @async       = async
+      @turns       = []
+      @loaded      = false
+
+      adapter_opts[:namespace] = namespace if namespace
+      adapter_opts[:on_trim]   = on_trim   if on_trim
+
+      @adapter = resolve_adapter(adapter, adapter_opts)
+    end
+
+    # -------------------------------------------------------------------------
+    # Public API
+    # -------------------------------------------------------------------------
+
+    # Load history from storage into RAM.
+    # Called automatically by the agent at the start of #call.
+    # After loading, history is available via #turns and #to_messages
+    # for manual injection in hooks or prompt classes.
+    def load
+      return unless @enabled
+      return if @loaded
+
+      @adapter.open(@session_id)
+      @turns  = @adapter.read
+      @loaded = true
+    end
+
+    # Record a turn after a successful agent call.
+    def record(request:, response:, **meta)
+      return unless @enabled
+      return if @read_only
+
+      turn = { request: request.to_s, response: response.to_s }
+      turn.merge!(meta) unless meta.empty?
+      turn[:at] ||= Time.now.utc.strftime("%Y-%m-%dT%H:%M:%SZ")
+
+      @turns << turn
+
+      if @async
+        Thread.new { safe_write(turn) }
+      else
+        safe_write(turn)
+        # keep RAM in sync with what adapter stored (adapter may have trimmed)
+        @turns = @adapter.read
+      end
+    end
+
+    # Returns messages array for LLM consumption, respecting depth.
+    # Optional filters:
+    #   filter: ->(turn) { turn[:agent] == "SupportAgent" }
+    #   since:  Time.now - 3600
+    def to_messages(filter: nil, since: nil)
+      turns = @turns.dup
+      turns.select! { |t| filter.call(t) }   if filter
+      turns.select! { |t| after?(t, since) } if since
+      turns = turns.last(@depth)              if @depth
+
+      turns.flat_map do |t|
+        [
+          { role: "user",      content: t[:request]  },
+          { role: "assistant", content: t[:response] }
+        ]
+      end
+    end
+
+    # All stored turns without depth/filter trimming.
+    def turns
+      @turns.dup
+    end
+
+    # Number of turns currently in memory.
+    def size
+      @turns.size
+    end
+
+    # Clear in-RAM turns (does not touch the storage file/key).
+    def clear
+      @turns  = []
+      @loaded = false
+    end
+
+    # Delete the session from storage backend entirely.
+    def delete
+      return unless @enabled
+
+      @adapter.open(@session_id) unless @loaded
+      @adapter.delete
+      clear
+    end
+
+    # Flush and close the adapter.
+    def close
+      @adapter.close
+    end
+
+    # -------------------------------------------------------------------------
+    private
+    # -------------------------------------------------------------------------
+
+    def resolve_adapter(adapter, opts)
+      case adapter
+      when Symbol
+        factory = ADAPTERS[adapter]
+        raise ArgumentError, "Unknown adapter: #{adapter.inspect}. Available: #{ADAPTERS.keys.join(', ')}" unless factory
+        factory.call(**opts)
+      else
+        # assume an adapter instance
+        adapter
+      end
+    end
+
+    def safe_write(turn)
+      @adapter.open(@session_id) unless @loaded
+      @adapter.write(turn)
+    end
+
+    def after?(turn, time)
+      return true unless turn[:at]
+      turn_time = Time.parse(turn[:at].to_s) rescue nil
+      turn_time ? turn_time >= time : true
+    end
+  end
+end

data/lib/active_harness/pipeline/step.rb

@@ -0,0 +1,36 @@
+module ActiveHarness
+  class Pipeline
+    class Step
+      attr_reader :name, :agent_class
+
+      def initialize(name, agent_class = nil, &block)
+        @name        = name
+        @agent_class = agent_class
+        @stop_if     = nil
+        instance_eval(&block) if block_given?
+      end
+
+      # DSL: use TranslationAgent
+      def use(klass)
+        @agent_class = klass
+      end
+
+      # DSL (inside block): stop_if ->(result) { ... }
+      # Getter (external):   step.stop_if  → lambda or nil
+      def stop_if(lam = nil)
+        lam ? @stop_if = lam : @stop_if
+      end
+
+      # True if agent_class is a Tribunal subclass — tribunal steps do not update payload.
+      def tribunal?
+        @agent_class.is_a?(Class) && @agent_class <= ActiveHarness::Tribunal
+      end
+
+      # Transform steps update payload to result.output after execution.
+      # Guard steps (stop_if present) and tribunal steps leave payload unchanged.
+      def transform?
+        !tribunal? && @stop_if.nil?
+      end
+    end
+  end
+end

data/lib/active_harness/pipeline.rb

@@ -0,0 +1,207 @@
+module ActiveHarness
+  # Sequential pipeline that chains agents and tribunals.
+  # Each step receives the current payload and can transform it or stop the pipeline.
+  #
+  # Usage (subclass with DSL):
+  #
+  #   class SupportPipeline < ActiveHarness::Pipeline
+  #     step :injection_guard do
+  #       use InjectionGuardAgent
+  #       stop_if ->(result) { result.parsed["detected"] == true }
+  #     end
+  #
+  #     step :translate, TranslationAgent   # shorthand — no stop_if
+  #
+  #     step :safety_tribunal do
+  #       use SafetyTribunal
+  #       stop_if ->(result) { result.verdict == false }
+  #     end
+  #
+  #     on :before_step do |step_name, payload| ... end
+  #     on :after_step  do |step_name, result|  ... end
+  #     on :before_step, :translate do |payload| ... end
+  #     on :after_step,  :translate do |result|  ... end
+  #     on :stopped  do |step_name, result| ... end
+  #     on :complete do |last_result|       ... end
+  #   end
+  #
+  #   pipeline = SupportPipeline.new(input: "...", context: { user_id: 1 })
+  #   pipeline.call
+  #   pipeline.output       # => final payload string (nil if stopped)
+  #   pipeline.stopped?     # => false
+  #   pipeline.step_results # => { translate: <Result>, ... }
+  #
+  class Pipeline
+    VALID_HOOKS      = %i[before_step after_step stopped complete].freeze
+    VALID_STEP_HOOKS = %i[before_step after_step].freeze
+
+    # -------------------------------------------------------------------------
+    # Class-level DSL
+    # -------------------------------------------------------------------------
+    class << self
+      # Define a step in the pipeline.
+      #
+      # Shorthand (agent only, no stop_if):
+      #   step :translate, TranslationAgent
+      #
+      # Full block form:
+      #   step :injection_guard do
+      #     use InjectionGuardAgent
+      #     stop_if ->(result) { result.parsed["detected"] == true }
+      #   end
+      def step(name, agent_class = nil, &block)
+        pipeline_config[:steps] << Pipeline::Step.new(name, agent_class, &block)
+      end
+
+      # Register a global or per-step hook.
+      #
+      # Global hooks fire on every step:
+      #   on :before_step do |step_name, payload| ... end
+      #   on :after_step  do |step_name, result|  ... end
+      #   on :stopped     do |step_name, result|  ... end
+      #   on :complete    do |last_result|         ... end
+      #
+      # Per-step hooks fire only for the named step (no step_name passed):
+      #   on :before_step, :translate do |payload| ... end
+      #   on :after_step,  :translate do |result|  ... end
+      def on(event, step_name = nil, &block)
+        if step_name
+          unless VALID_STEP_HOOKS.include?(event)
+            raise ArgumentError,
+              "Per-step hooks support: #{VALID_STEP_HOOKS.join(", ")}. Got :#{event}"
+          end
+          pipeline_config[:step_hooks][step_name] ||= {}
+          pipeline_config[:step_hooks][step_name][event] = block
+        else
+          unless VALID_HOOKS.include?(event)
+            raise ArgumentError,
+              "Unknown Pipeline hook :#{event}. Valid: #{VALID_HOOKS.join(", ")}"
+          end
+          pipeline_config[:hooks][event] = block
+        end
+      end
+
+      # Rails-style aliases for +on+:
+      #
+      # Global:
+      #   before :step                          do |name, payload| end  # → on :before_step
+      #   after  :step                          do |name, result|  end  # → on :after_step
+      #   callback :stopped                     do |name, result|  end  # → on :stopped
+      #   callback :complete                    do |result|        end  # → on :complete
+      #
+      # Per-step:
+      #   after  :step, :translate              do |result| end
+      #   before :step, :translate              do |payload| end
+      def before(event, step_name = nil, &block)
+        on(:"before_#{event}", step_name, &block)
+      end
+
+      def after(event, step_name = nil, &block)
+        on(:"after_#{event}", step_name, &block)
+      end
+
+      def callback(event, &block)
+        on(event, &block)
+      end
+
+      def pipeline_config
+        @pipeline_config ||= { steps: [], hooks: {}, step_hooks: {} }
+      end
+
+      # Each subclass gets its own isolated config.
+      def inherited(subclass)
+        subclass.instance_variable_set(
+          :@pipeline_config,
+          { steps: [], hooks: {}, step_hooks: {} }
+        )
+      end
+    end
+
+    # -------------------------------------------------------------------------
+    # Instance API
+    # -------------------------------------------------------------------------
+    attr_reader :original_input, :output, :stopped_at, :stop_reason,
+                :execution_time, :step_results, :context
+
+    def initialize(input:, context: {}, memory: nil)
+      @original_input = input
+      @payload        = input
+      @context        = context.dup
+      @memory         = memory
+      @step_results   = {}
+      @stopped        = false
+      @stopped_at     = nil
+      @stop_reason    = nil
+      @execution_time = nil
+      @output         = nil
+    end
+
+    def stopped?
+      @stopped
+    end
+
+    # Execute all steps sequentially. Returns self for chaining.
+    def call
+      config = self.class.pipeline_config
+      t0     = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+      @memory&.load
+
+      config[:steps].each do |step|
+        fire_global(:before_step, step.name, @payload, config)
+        fire_step(:before_step, step.name, @payload, config)
+
+        result = execute_step(step)
+
+        @step_results[step.name] = result
+        @context[step.name]      = result
+        @payload                 = result.output if step.transform?
+
+        fire_global(:after_step, step.name, result, config)
+        fire_step(:after_step, step.name, result, config)
+
+        if step.stop_if && step.stop_if.call(result)
+          @stopped     = true
+          @stopped_at  = step.name
+          @stop_reason = result
+          config[:hooks][:stopped]&.call(step.name, result)
+          break
+        end
+      end
+
+      @execution_time = (Process.clock_gettime(Process::CLOCK_MONOTONIC) - t0).round(3)
+      @output         = @payload unless @stopped
+
+      unless @stopped
+        @memory&.record(
+          request:  @original_input,
+          response: @output,
+          pipeline: self.class.name
+        )
+
+        last_result = @step_results[@step_results.keys.last]
+        config[:hooks][:complete]&.call(last_result)
+      end
+
+      self
+    end
+
+    private
+
+    def execute_step(step)
+      step.agent_class.new(input: @payload, context: @context.dup).call
+    end
+
+    # Global hook: receives (step_name, data)
+    def fire_global(event, step_name, data, config)
+      config[:hooks][event]&.call(step_name, data)
+    end
+
+    # Per-step hook: receives (data) only
+    def fire_step(event, step_name, data, config)
+      config[:step_hooks][step_name]&.dig(event)&.call(data)
+    end
+  end
+end
+
+require_relative "pipeline/step"

data/lib/active_harness/providers/PROVIDER_CONTRACT.md

@@ -0,0 +1,54 @@
+# Provider Contract
+
+Each provider class must inherit from `Providers::Base` and implement a single public method:
+
+```ruby
+def call(model:, messages:, temperature: 0.7) → Hash
+```
+
+## Return value
+
+A plain Hash with exactly these keys:
+
+| Key         | Type   | Description                                        |
+| ----------- | ------ | -------------------------------------------------- |
+| `:content`  | String | The model's text reply (stripped)                  |
+| `:provider` | Symbol | Provider identifier, e.g. `:openai`, `:openrouter` |
+| `:model`    | String | Actual model name returned by the API              |
+
+```ruby
+{
+  content:  "Washington, D.C.",
+  provider: :openrouter,
+  model:    "mistralai/mistral-nemo"
+}
+```
+
+## Errors
+
+All exceptions must be subclasses of `ActiveHarness::Errors::ProviderError` and carry:
+
+| Attribute    | Type          | Description                                                             |
+| ------------ | ------------- | ----------------------------------------------------------------------- |
+| `message`    | String        | Human-readable error text from the API                                  |
+| `error_code` | String or nil | Raw code from the API response (`"429"`, `"invalid_api_key"`, etc.)     |
+| `metadata`   | Hash or nil   | Extra data returned by the API (rate-limit timing, provider name, etc.) |
+
+```ruby
+raise Errors::RateLimitError.new(msg, error_code: code, metadata: metadata)
+```
+
+### Error classes and retry behaviour
+
+| Class                      | Retryable | Typical trigger                  |
+| -------------------------- | --------- | -------------------------------- |
+| `TimeoutError`             | yes       | Network open/read timeout        |
+| `RateLimitError`           | yes       | HTTP 429 / `rate_limit_exceeded` |
+| `ServerError`              | yes       | API `server_error` type          |
+| `ProviderUnavailableError` | yes       | HTTP 5xx, host unreachable       |
+| `InvalidRequestError`      | no        | Bad request, unknown model, etc. |
+| `InvalidApiKeyError`       | no        | Missing or invalid API key       |
+| `SafetyBlockedError`       | no        | Content policy violation         |
+
+Retryable errors cause the agent to move to the next model in the chain.
+Non-retryable errors abort the chain immediately and are re-raised.