active_harness 0.1.0

data/lib/active_harness/providers/openai.rb

@@ -0,0 +1,76 @@
+require "json"
+
+module ActiveHarness
+  module Providers
+    class OpenAI < Base
+      API_URL = URI("https://api.openai.com/v1/chat/completions")
+
+      def call(request)
+        body     = build_body(request)
+        raw      = post(body, request.timeout)
+        data     = JSON.parse(raw)
+
+        handle_error!(data)
+
+        content = data.dig("choices", 0, "message", "content").to_s.strip
+        usage   = data["usage"] || {}
+
+        build_response(
+          content:  content,
+          provider: :openai,
+          model:    data["model"] || request.model,
+          usage:    { prompt: usage["prompt_tokens"], completion: usage["completion_tokens"] },
+          raw:      raw
+        )
+      end
+
+      private
+
+      def build_body(request)
+        body = {
+          model:       request.model,
+          messages:    request.messages,
+          temperature: request.temperature
+        }
+        body[:response_format] = { type: "json_object" } if request.response_format == :json
+        body.to_json
+      end
+
+      def post(body, timeout)
+        ActiveHarness.config.http_client.post(
+          API_URL,
+          headers: {
+            "Content-Type"  => "application/json",
+            "Authorization" => "Bearer #{api_key}"
+          },
+          body:    body,
+          timeout: timeout
+        )
+      end
+
+      def handle_error!(data)
+        return unless data["error"]
+
+        message = data.dig("error", "message").to_s
+        code    = data.dig("error", "code").to_s
+
+        case code
+        when "invalid_api_key", "unauthorized"
+          raise Errors::InvalidApiKeyError, message
+        when "rate_limit_exceeded"
+          raise Errors::RateLimitError, message
+        when "content_filter"
+          raise Errors::SafetyBlockedError, message
+        else
+          raise Errors::InvalidRequestError, message
+        end
+      end
+
+      def api_key
+        key = ActiveHarness.config.openai_api_key
+        raise Errors::InvalidApiKeyError, "OPENAI_API_KEY not configured" if key.nil? || key.empty?
+        key
+      end
+    end
+  end
+end

data/lib/active_harness/providers/openrouter.rb

@@ -0,0 +1,80 @@
+require "json"
+
+module ActiveHarness
+  module Providers
+    # OpenRouter proxies many models (OpenAI, Anthropic, etc.) through a single API.
+    # API is OpenAI-compatible with an extra "HTTP-Referer" header.
+    class OpenRouter < Base
+      API_URL = URI("https://openrouter.ai/api/v1/chat/completions")
+
+      def call(request)
+        body = build_body(request)
+        raw  = post(body, request.timeout)
+        data = JSON.parse(raw)
+
+        handle_error!(data)
+
+        content = data.dig("choices", 0, "message", "content").to_s.strip
+        usage   = data["usage"] || {}
+
+        build_response(
+          content:  content,
+          provider: :openrouter,
+          model:    data["model"] || request.model,
+          usage:    { prompt: usage["prompt_tokens"], completion: usage["completion_tokens"] },
+          raw:      raw
+        )
+      end
+
+      private
+
+      def build_body(request)
+        body = {
+          model:       request.model,
+          messages:    request.messages,
+          temperature: request.temperature
+        }
+        body[:response_format] = { type: "json_object" } if request.response_format == :json
+        body.to_json
+      end
+
+      def post(body, timeout)
+        ActiveHarness.config.http_client.post(
+          API_URL,
+          headers: {
+            "Content-Type"  => "application/json",
+            "Authorization" => "Bearer #{api_key}",
+            "HTTP-Referer"  => "https://github.com/the-teacher/ActiveHarness"
+          },
+          body:    body,
+          timeout: timeout
+        )
+      end
+
+      def handle_error!(data)
+        return unless data["error"]
+
+        error   = data["error"]
+        message = error["message"].to_s
+        code    = error["code"].to_s
+        meta    = error.reject { |k, _| k == "message" }
+        full    = meta.empty? ? message : "#{message} | #{meta.inspect}"
+
+        case code
+        when "401"
+          raise Errors::InvalidApiKeyError, full
+        when "429"
+          raise Errors::RateLimitError, full
+        else
+          raise Errors::InvalidRequestError, full
+        end
+      end
+
+      def api_key
+        key = ActiveHarness.config.openrouter_api_key
+        raise Errors::InvalidApiKeyError, "OPENROUTER_API_KEY not configured" if key.nil? || key.empty?
+        key
+      end
+    end
+  end
+end

data/lib/active_harness/rate_limit/request_limiter.rb

@@ -0,0 +1,50 @@
+module ActiveHarness
+  module RateLimit
+    # Sliding-window rate limiter. Tracks request timestamps per user_id
+    # and raises if the limit is exceeded within the rolling time window.
+    #
+    # Storage is in-memory (per-process). For multi-process environments,
+    # replace with a shared backend (Redis, Memcached, etc.) by subclassing
+    # and overriding #timestamps_for / #record_timestamp.
+    #
+    # Usage:
+    #   limiter = RequestLimiter.new(max_requests: 10, window_seconds: 60)
+    #   limiter.check!(user_id)   # call before each request; raises if over limit
+    #
+    class RequestLimiter
+      DEFAULT_MAX    = 10
+      DEFAULT_WINDOW = 60  # seconds
+
+      # @param max_requests   [Integer]  maximum allowed requests per window
+      # @param window_seconds [Integer]  length of the sliding window in seconds
+      def initialize(max_requests: DEFAULT_MAX, window_seconds: DEFAULT_WINDOW)
+        @max_requests   = max_requests
+        @window_seconds = window_seconds
+        @log            = Hash.new { |h, k| h[k] = [] }
+        @mutex          = Mutex.new
+      end
+
+      # Records this request and raises if the limit has been reached.
+      # @param user_id [String, Integer, nil]  nil disables the check
+      # @raise [Errors::RequestThrottledError]
+      def check!(user_id)
+        return if user_id.nil?
+
+        key    = user_id.to_s
+        now    = Time.now.to_f
+        cutoff = now - @window_seconds
+
+        @mutex.synchronize do
+          @log[key].reject! { |t| t < cutoff }
+
+          if @log[key].size >= @max_requests
+            raise Errors::RequestThrottledError,
+              "Rate limit exceeded: #{@max_requests} requests/#{@window_seconds}s (user: #{key})"
+          end
+
+          @log[key] << now
+        end
+      end
+    end
+  end
+end

data/lib/active_harness/rate_limit/risk_holdback.rb

@@ -0,0 +1,69 @@
+module ActiveHarness
+  module RateLimit
+    # Progressive hold-back for users who repeatedly submit risky requests.
+    #
+    # Every RISKY_THRESHOLD blocked requests trigger a hold. The hold duration
+    # escalates with each offense:
+    #
+    #   Offense 1 (3rd  risky request) →  5 minutes
+    #   Offense 2 (6th  risky request) → 30 minutes
+    #   Offense 3+ (9th+ risky request) →  2 hours
+    #
+    # Storage is in-memory (per-process). Thread-safe via Mutex.
+    #
+    # Usage:
+    #   holdback = RiskHoldback.new
+    #   holdback.check!(user_id)           # before each request; raises if held
+    #   holdback.record_risky!(user_id)    # after guard blocks a request
+    #
+    class RiskHoldback
+      RISKY_THRESHOLD = 3
+      HOLD_SCHEDULE   = [5 * 60, 30 * 60, 2 * 60 * 60].freeze  # 5 min / 30 min / 2 h
+
+      # @param risky_threshold [Integer]  number of risky requests before a hold is applied
+      def initialize(risky_threshold: RISKY_THRESHOLD)
+        @risky_threshold = risky_threshold
+        @state           = {}
+        @mutex           = Mutex.new
+      end
+
+      # Records a risky (guard-blocked) request for the user.
+      # Applies a hold when the count reaches the next threshold multiple.
+      # @param user_id [String, Integer, nil]  nil is a no-op
+      def record_risky!(user_id)
+        return if user_id.nil?
+
+        key = user_id.to_s
+        @mutex.synchronize do
+          s = @state[key] ||= { risky_count: 0, offense_count: 0, held_until: nil }
+          s[:risky_count] += 1
+
+          if (s[:risky_count] % @risky_threshold).zero?
+            offense_idx      = [s[:offense_count], HOLD_SCHEDULE.size - 1].min
+            s[:held_until]   = Time.now.to_f + HOLD_SCHEDULE[offense_idx]
+            s[:offense_count] += 1
+          end
+        end
+      end
+
+      # Raises if the user is currently held back due to risky behaviour.
+      # @param user_id [String, Integer, nil]  nil disables the check
+      # @raise [Errors::UserHoldbackError]
+      def check!(user_id)
+        return if user_id.nil?
+
+        key = user_id.to_s
+        @mutex.synchronize do
+          s = @state[key]
+          return unless s&.dig(:held_until)
+          return if Time.now.to_f >= s[:held_until]
+
+          remaining = (s[:held_until] - Time.now.to_f).ceil
+          raise Errors::UserHoldbackError,
+            "Requests paused due to repeated safety violations. " \
+            "Retry in #{remaining}s (user: #{key})"
+        end
+      end
+    end
+  end
+end

data/lib/active_harness/results/debug_result.rb

@@ -0,0 +1,19 @@
+module ActiveHarness
+  # Available only when ActiveHarness.config.debug == true
+  class DebugResult
+    attr_reader :system_prompt,
+                :guard_runs,
+                :callback_log
+
+    def initialize(system_prompt: nil,
+                   guard_runs: [], callback_log: [])
+      @system_prompt = system_prompt
+      @guard_runs    = guard_runs
+      @callback_log  = callback_log
+    end
+
+    def full_prompt
+      @system_prompt.to_s
+    end
+  end
+end

data/lib/active_harness/results/input_result.rb

@@ -0,0 +1,27 @@
+module ActiveHarness
+  # Holds the result of the guard (input safety) layer.
+  class InputResult
+    attr_reader :raw, :processed, :errors, :risk_level, :intent, :reason
+
+    def initialize(raw:, processed:, safe:, valid:,
+                   risk_level: :low, errors: [],
+                   intent: nil, reason: nil)
+      @raw        = raw
+      @processed  = processed
+      @safe       = safe
+      @valid      = valid
+      @risk_level = risk_level
+      @errors     = errors
+      @intent     = intent
+      @reason     = reason
+    end
+
+    def safe?
+      @safe
+    end
+
+    def valid?
+      @valid
+    end
+  end
+end

data/lib/active_harness/results/result.rb

@@ -0,0 +1,55 @@
+module ActiveHarness
+  class Result
+    SUCCESS = :success
+    FAILED  = :failed
+    BLOCKED = :blocked
+
+    attr_reader :input, :output, :raw_response,
+                :provider, :model, :usage, :attempts,
+                :debug, :error
+
+    def initialize(status:, input: nil, output: nil, raw_response: nil,
+                   provider: nil, model: nil, usage: {}, attempts: [],
+                   debug: nil, error: nil)
+      @status       = status
+      @input        = input
+      @output       = output
+      @raw_response = raw_response
+      @provider     = provider
+      @model        = model
+      @usage        = usage
+      @attempts     = attempts
+      @debug        = debug
+      @error        = error
+    end
+
+    def success?
+      @status == SUCCESS
+    end
+
+    def failed?
+      @status == FAILED
+    end
+
+    def blocked?
+      @status == BLOCKED
+    end
+
+    # Factory helpers
+
+    def self.success(input:, output:, raw_response:, provider:, model:,
+                     usage:, attempts:, debug: nil)
+      new(status: SUCCESS, input: input, output: output,
+          raw_response: raw_response, provider: provider,
+          model: model, usage: usage, attempts: attempts, debug: debug)
+    end
+
+    def self.blocked(input:, output: nil, debug: nil)
+      new(status: BLOCKED, input: input, output: output, debug: debug)
+    end
+
+    def self.failed(error: nil, input: nil, debug: nil)
+      new(status: FAILED, error: error, input: input, debug: debug)
+    end
+  end
+end

data/lib/active_harness.rb

@@ -0,0 +1,49 @@
+require "active_harness/core/version"
+require "active_harness/core/errors"
+require "active_harness/core/configuration"
+require "active_harness/payload"
+
+require "active_harness/http/client"
+require "active_harness/http/retry_policy"
+
+require "active_harness/rate_limit/request_limiter"
+require "active_harness/rate_limit/risk_holdback"
+
+require "active_harness/models/model_request"
+require "active_harness/models/model_response"
+require "active_harness/results/input_result"
+require "active_harness/results/debug_result"
+require "active_harness/results/result"
+
+require "active_harness/providers/base"
+require "active_harness/providers/openai"
+require "active_harness/providers/openrouter"
+require "active_harness/providers/anthropic"
+require "active_harness/providers/google"
+
+require "active_harness/prompts/guard_system_prompt"
+
+require "active_harness/pipeline/provider_registry"
+require "active_harness/pipeline/prompt_builder"
+require "active_harness/pipeline/output_parser"
+require "active_harness/pipeline/fallback_runner"
+require "active_harness/pipeline/guard_runner"
+require "active_harness/pipeline/engine"
+require "active_harness/agent"
+
+module ActiveHarness
+  class << self
+    def configure
+      yield configuration
+    end
+
+    def configuration
+      @configuration ||= Configuration.new
+    end
+    alias config configuration
+
+    def reset!
+      @configuration = nil
+    end
+  end
+end

metadata

@@ -0,0 +1,131 @@
+--- !ruby/object:Gem::Specification
+name: active_harness
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- the-teacher
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2026-05-06 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: minitest-reporters
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: mocha
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+description: |
+  ActiveHarness provides a DSL for describing AI agents and an engine for
+  their execution, with built-in prompt-injection protection (guard layer),
+  provider fallback chains, and a structured result API.
+email:
+- the-teacher@github.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/active_harness.rb
+- lib/active_harness/agent.rb
+- lib/active_harness/core/configuration.rb
+- lib/active_harness/core/errors.rb
+- lib/active_harness/core/version.rb
+- lib/active_harness/http/client.rb
+- lib/active_harness/http/retry_policy.rb
+- lib/active_harness/models/model_request.rb
+- lib/active_harness/models/model_response.rb
+- lib/active_harness/payload.rb
+- lib/active_harness/pipeline/engine.rb
+- lib/active_harness/pipeline/fallback_runner.rb
+- lib/active_harness/pipeline/guard_runner.rb
+- lib/active_harness/pipeline/output_parser.rb
+- lib/active_harness/pipeline/prompt_builder.rb
+- lib/active_harness/pipeline/provider_registry.rb
+- lib/active_harness/prompts/guard_system_prompt.rb
+- lib/active_harness/providers/anthropic.rb
+- lib/active_harness/providers/base.rb
+- lib/active_harness/providers/google.rb
+- lib/active_harness/providers/openai.rb
+- lib/active_harness/providers/openrouter.rb
+- lib/active_harness/rate_limit/request_limiter.rb
+- lib/active_harness/rate_limit/risk_holdback.rb
+- lib/active_harness/results/debug_result.rb
+- lib/active_harness/results/input_result.rb
+- lib/active_harness/results/result.rb
+homepage: https://github.com/the-teacher/active_harness
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.6'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.3.1
+signing_key: 
+specification_version: 4
+summary: DSL for describing and running AI agents with safety layers
+test_files: []