active_harness 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 60a596cdaf7c45f9f3865c7ff7e41c3d1f2ba36cfc57eafc66a94a654bf64607
+  data.tar.gz: b8d989e7d6435168761ed94e12d126f0025e9b6a54d7b37464f135519747bfd0
+SHA512:
+  metadata.gz: b881ea07f0ec55d3116814a5080d9df5bde53773ac23182fc3c5d54cdcadb681d4bf8036570b3e3ef65a90a5e3760c0c775c0440eeacf50b4ebfcc9472849092
+  data.tar.gz: 73f97bc713e3b12f9f7527dfce99afcbe4cce903a104d71b687abc5bf0d73a4edbc8ed6afef3aac2db3dca40e5870a3ba14a31703625e8a93a113319c3b6c357

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 the-teacher
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,113 @@
+# ActiveHarness
+
+ActiveHarness is a lightweight framework for building production-ready AI agents in Ruby and Rails.
+
+Instead of relying on complex orchestration frameworks, ActiveHarness provides a simple and transparent DSL to define agents as plain Ruby classes.
+
+## Features
+
+- Agent-based architecture (Rails-style DSL)
+- Built-in guard layer (prompt injection, toxicity, relevance checks)
+- Multi-provider support: OpenAI, Anthropic, Google, OpenRouter
+- Automatic fallback between models and providers
+- Per-call language and translation support
+- Structured outputs (text / JSON with schema validation)
+- Input constraints (e.g. `max_input_length`)
+- Debug mode with full prompt visibility
+- Minimal dependencies, no magic
+
+## Installation
+
+```ruby
+# Gemfile
+gem "active_harness"
+```
+
+```bash
+bundle install
+```
+
+Or install directly:
+
+```bash
+gem install active_harness
+```
+
+## Quick Start
+
+### 1. Configure
+
+```ruby
+ActiveHarness.configure do |config|
+  config.openai_api_key      = ENV["OPENAI_API_KEY"]
+  config.openrouter_api_key  = ENV["OPENROUTER_API_KEY"]
+  config.default_temperature = 0.2
+  config.default_timeout     = 30
+end
+```
+
+### 2. Define an agent
+
+```ruby
+class SupportAgent < ActiveHarness::Agent
+  guard InjectionGuard
+
+  model do
+    use      provider: :openai,     model: "gpt-4.1-mini"
+    fallback provider: :openrouter, model: "meta-llama/llama-3.3-70b-instruct:free"
+  end
+
+  system_prompt "You are a helpful support assistant."
+  output :text
+end
+```
+
+### 3. Call it
+
+```ruby
+# One-liner
+result = SupportAgent.call(input: "How do I get started?")
+
+# Instance style
+agent  = SupportAgent.new(input: "How do I get started?", language: :ru)
+result = agent.call
+
+puts result.output  if result.success?
+puts result.output  if result.blocked?   # default_error_answer
+```
+
+## Guards
+
+Guards run before the main request and can block it:
+
+```ruby
+class InjectionGuard < ActiveHarness::Agent
+  model { use provider: :openai, model: "gpt-4.1-mini" }
+  system_language :en
+  risk_tolerance  :low
+end
+
+# Register on the main agent:
+guard InjectionGuard, name: :injection_guard
+guard ToxicityGuard,  name: :toxicity_guard
+```
+
+## Result API
+
+```ruby
+result.success?   # true / false
+result.blocked?   # true / false  (guard rejected)
+result.failed?    # true / false  (error / timeout)
+result.output     # String
+result.model      # "gpt-4.1-mini"
+result.provider   # :openai
+```
+
+## Requirements
+
+- Ruby >= 2.6
+- API key for at least one supported provider (OpenAI, Anthropic, Google, OpenRouter)
+
+## License
+
+MIT — see [LICENSE](LICENSE).

data/lib/active_harness/agent.rb

@@ -0,0 +1,257 @@
+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 << 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).
+      #
+      # 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
+      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) }
+      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
+      }
+    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)
+    end
+  end
+
+  # ---------------------------------------------------------------------------
+  # Internal helper — collects the `use` + `fallback` entries inside a `model` block.
+  # ---------------------------------------------------------------------------
+  class ModelConfig
+    def initialize
+      @config = { fallbacks: [] }
+    end
+
+    def use(provider:, model:)
+      @config[:use] = { provider: provider, model: model }
+    end
+
+    def fallback(provider:, model:)
+      @config[:fallbacks] << { provider: provider, model: model }
+    end
+
+    def to_h
+      @config
+    end
+  end
+end

data/lib/active_harness/core/configuration.rb

@@ -0,0 +1,55 @@
+module ActiveHarness
+  class Configuration
+    attr_accessor :openai_api_key,
+                  :openrouter_api_key,
+                  :anthropic_api_key,
+                  :google_api_key,
+                  :default_timeout,
+                  :default_temperature,
+                  :default_language,
+                  :guard_retries,
+                  :log_requests,
+                  :log_responses,
+                  :debug,
+                  :on_model_attempt,
+                  :on_model_failure
+
+    def initialize
+      @openai_api_key      = ENV["OPENAI_API_KEY"]
+      @openrouter_api_key  = ENV["OPENROUTER_API_KEY"]
+      @anthropic_api_key   = ENV["ANTHROPIC_API_KEY"]
+      @google_api_key      = ENV["GOOGLE_API_KEY"]
+
+      @default_timeout     = 20
+      @default_temperature = 0.2
+      @default_language    = :en
+      @guard_retries       = 2   # up to 3 total attempts (1 initial + 2 retries)
+
+      @log_requests  = true
+      @log_responses = false
+      @debug         = false
+    end
+
+    # HTTP transport. Swap for a Faraday-backed client if needed:
+    #   config.http_client = MyFaradayClient.new
+    # Set to nil to let providers manage their own transport.
+    def http_client
+      @http_client ||= Http::Client.new
+    end
+    attr_writer :http_client
+
+    # Sliding-window rate limiter (10 req/min per user_id by default).
+    # Set to nil to disable.
+    def request_limiter
+      @request_limiter ||= RateLimit::RequestLimiter.new
+    end
+    attr_writer :request_limiter
+
+    # Progressive hold-back after repeated risky requests.
+    # Set to nil to disable.
+    def risk_holdback
+      @risk_holdback ||= RateLimit::RiskHoldback.new
+    end
+    attr_writer :risk_holdback
+  end
+end

data/lib/active_harness/core/errors.rb

@@ -0,0 +1,38 @@
+module ActiveHarness
+  module Errors
+    # Base
+    class Error < StandardError; end
+
+    # Configuration
+    class ConfigurationError < Error; end
+    class ContextValidationError < Error; end
+
+    # 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
+
+    # Provider — terminal (fallback chain stops)
+    class InvalidRequestError       < ProviderError; end
+    class InvalidApiKeyError        < ProviderError; end
+    class SafetyBlockedError        < ProviderError; end
+
+    # Output
+    class SchemaValidationError < Error; end
+    class OutputParsingError    < Error; end
+
+    # Guard — raised when the guard model returns unparseable or schema-invalid JSON.
+    # Triggers the retry loop inside GuardRunner.
+    class GuardResponseError < Error; end
+
+    # 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
+  end
+end

data/lib/active_harness/core/version.rb

@@ -0,0 +1,3 @@
+module ActiveHarness
+  VERSION = "0.1.0"
+end

data/lib/active_harness/http/client.rb

@@ -0,0 +1,41 @@
+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 }
+    #
+    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
+      # @return        [String]   raw response body
+      def post(url, headers:, body:, timeout:)
+        http              = Net::HTTP.new(url.host, url.port)
+        http.use_ssl      = true
+        http.read_timeout = timeout
+        http.open_timeout = timeout
+
+        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 => e
+        raise Errors::ProviderUnavailableError, "#{url.host} unreachable: #{e.message}"
+      end
+    end
+  end
+end

data/lib/active_harness/http/retry_policy.rb

@@ -0,0 +1,47 @@
+module ActiveHarness
+  module Http
+    # Wraps a block with automatic retry on transient errors.
+    # Uses exponential backoff: delay doubles after each failed attempt.
+    #
+    # Example:
+    #   RetryPolicy.new(max_attempts: 3, base_delay: 0.5).run do
+    #     http_client.post(...)
+    #   end
+    #
+    # Custom errors:
+    #   RetryPolicy.new(errors: [MyTransientError]).run { ... }
+    #
+    class RetryPolicy
+      DEFAULT_ERRORS = [
+        Errors::TimeoutError,
+        Errors::RateLimitError,
+        Errors::ProviderUnavailableError,
+        Errors::ServerError
+      ].freeze
+
+      # @param max_attempts [Integer]  total number of attempts (first + retries)
+      # @param base_delay   [Float]    delay before 1st retry in seconds; doubles each round
+      # @param errors       [Array]    error classes that trigger a retry
+      def initialize(max_attempts: 3, base_delay: 1.0, errors: DEFAULT_ERRORS)
+        @max_attempts = max_attempts
+        @base_delay   = base_delay
+        @errors       = errors
+      end
+
+      # @yieldreturn [Object] result of the block on success
+      # @raise last error after all attempts are exhausted
+      def run
+        attempt = 0
+        begin
+          attempt += 1
+          yield
+        rescue *@errors
+          raise if attempt >= @max_attempts
+
+          sleep(@base_delay * (2**(attempt - 1)))
+          retry
+        end
+      end
+    end
+  end
+end

data/lib/active_harness/models/model_request.rb

@@ -0,0 +1,14 @@
+module ActiveHarness
+  class ModelRequest
+    attr_reader :provider, :model, :messages, :temperature, :timeout, :response_format
+
+    def initialize(provider:, model:, messages:, temperature: nil, timeout: nil, response_format: nil)
+      @provider        = provider
+      @model           = model
+      @messages        = messages
+      @temperature     = temperature || ActiveHarness.config.default_temperature
+      @timeout         = timeout     || ActiveHarness.config.default_timeout
+      @response_format = response_format
+    end
+  end
+end

data/lib/active_harness/models/model_response.rb

@@ -0,0 +1,13 @@
+module ActiveHarness
+  class ModelResponse
+    attr_reader :content, :provider, :model, :usage, :raw
+
+    def initialize(content:, provider:, model:, usage: {}, raw: nil)
+      @content  = content
+      @provider = provider
+      @model    = model
+      @usage    = usage
+      @raw      = raw
+    end
+  end
+end

data/lib/active_harness/payload.rb

@@ -0,0 +1,47 @@
+module ActiveHarness
+  # Unified request context — the single object available in every hook.
+  #
+  # Passed as the first argument to ALL before/after callbacks and to +setup+:
+  #
+  #   setup do |payload|
+  #     payload.meta[:started_at] = Time.now
+  #     payload                               # must return payload
+  #   end
+  #
+  #   before :guards do |payload, input|      # input = String
+  #     input.strip                           # return new String
+  #   end
+  #
+  #   after  :guards do |payload, result|     # result = InputResult
+  #     result                                # return InputResult
+  #   end
+  #
+  #   before :request do |payload, prompt|    # prompt = { system:, user: }
+  #     prompt                                # return Hash
+  #   end
+  #
+  #   after  :request do |payload, response|  # response = ModelResponse
+  #     response                              # return ModelResponse
+  #   end
+  #
+  # Fields:
+  #   input     — raw input text; can be modified in +setup+
+  #   context   — runtime context Hash (e.g. user_id, session data)
+  #   language  — language hint for guards / responses (e.g. :ru, :en)
+  #   translate — callable: translate.(key) → localized string; key format: "scope.agent.message"
+  #               typically built by an I18n module: Playground::I18n.translator(locale: language)
+  #   options   — per-guard static options set at registration time
+  #   meta      — free-form Hash for user-defined data (timestamps, flags, …)
+  class Payload
+    attr_accessor :input, :context, :language, :translate, :options, :meta
+
+    def initialize(input:, context: {}, language: nil, translate: nil, options: {}, meta: {})
+      @input     = input
+      @context   = context
+      @language  = language
+      @translate = translate
+      @options   = options
+      @meta      = meta
+    end
+  end
+end