olyx-guardrails 1.0.0

data/lib/olyx/guardrails/check_set.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require_relative 'checks/injection_check'
+require_relative 'checks/length_check'
+require_relative 'checks/pii_check'
+require_relative 'checks/policy_check'
+require_relative 'checks/secret_check'
+require_relative 'checks/skipped_checks'
+
+module Olyx
+  module Guardrails
+    # Coordinates independent deterministic checks for one normalized input.
+    class CheckSet
+      CHECKS = {
+        pii: Checks::PiiCheck,
+        injection: Checks::InjectionCheck,
+        secret: Checks::SecretCheck,
+        policy: Checks::PolicyCheck
+      }.freeze
+
+      def self.call(source, policy:)
+        length = Checks::LengthCheck.call(source, policy)
+        content = length[:allowed] ? scan(source, policy) : Checks::SkippedChecks.call
+        content.merge(length: length)
+      end
+
+      def self.scan(source, policy)
+        CHECKS.to_h { |name, check| [name, check.call(source, policy)] }
+      end
+      private_class_method :scan
+    end
+  end
+end

data/lib/olyx/guardrails/checks/injection_check.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require_relative '../injection_detector'
+require_relative 'injection_result'
+
+module Olyx
+  module Guardrails
+    module Checks
+      # Decides whether deterministic injection findings are allowed.
+      module InjectionCheck
+        module_function
+
+        def call(source, policy)
+          scan = InjectionDetector.scan([{ 'role' => 'user', 'content' => source }])
+          InjectionResult.call(scan, policy)
+        end
+      end
+    end
+  end
+end

data/lib/olyx/guardrails/checks/injection_result.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Olyx
+  module Guardrails
+    module Checks
+      # Builds the shared injection check decision from detector output.
+      module InjectionResult
+        module_function
+
+        def call(scan, policy)
+          attempt = scan[:injection_attempt]
+          {
+            type: 'injection',
+            allowed: !attempt || !policy.block_injections?,
+            injection_attempt: attempt,
+            patterns: scan[:patterns]
+          }
+        end
+      end
+    end
+  end
+end

data/lib/olyx/guardrails/checks/length_check.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Olyx
+  module Guardrails
+    module Checks
+      # Enforces the bounded-input invariant before content scanners run.
+      module LengthCheck
+        module_function
+
+        def call(source, policy)
+          length = source.length
+          maximum = policy.max_input_length
+          { type: 'length', allowed: length <= maximum, length: length, max_length: maximum }
+        end
+      end
+    end
+  end
+end

data/lib/olyx/guardrails/checks/message_injection_check.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require_relative '../injection_detector'
+require_relative 'injection_result'
+
+module Olyx
+  module Guardrails
+    module Checks
+      # Decides whether structured-message injection findings are allowed.
+      module MessageInjectionCheck
+        module_function
+
+        def call(messages, policy)
+          InjectionResult.call(InjectionDetector.scan(messages), policy)
+        end
+      end
+    end
+  end
+end

data/lib/olyx/guardrails/checks/pii_check.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require_relative '../pii_scrubber'
+
+module Olyx
+  module Guardrails
+    module Checks
+      # Decides whether deterministic PII findings are allowed by policy.
+      module PiiCheck
+        module_function
+
+        def call(source, policy)
+          detected = PiiScrubber.scrub(source) != source
+          { type: 'pii', allowed: !detected || !policy.block_pii?, detected: detected }
+        end
+      end
+    end
+  end
+end

data/lib/olyx/guardrails/checks/policy_check.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require_relative '../policy_scanner'
+
+module Olyx
+  module Guardrails
+    module Checks
+      # Presents named restricted-content matches as one policy check.
+      module PolicyCheck
+        module_function
+
+        def call(source, policy)
+          scan = PolicyScanner.scan(source, policy: policy)
+          findings = scan[:findings]
+          {
+            type: 'policy',
+            allowed: !scan[:blocked],
+            violated: scan[:violated],
+            count: findings.size,
+            findings: findings
+          }
+        end
+      end
+    end
+  end
+end

data/lib/olyx/guardrails/checks/secret_check.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require_relative '../secret_scanner'
+
+module Olyx
+  module Guardrails
+    module Checks
+      # Decides whether secret findings are allowed by policy.
+      module SecretCheck
+        module_function
+
+        def call(source, policy)
+          scan = SecretScanner.scan(source, custom_patterns: policy.secret_patterns)
+          result(scan, policy)
+        end
+
+        def result(scan, policy)
+          leaked = scan[:leaked]
+          {
+            type: 'secret',
+            allowed: !leaked || !policy.block_secrets?,
+            leaked: leaked,
+            count: scan[:findings].size
+          }
+        end
+        private_class_method :result
+      end
+    end
+  end
+end

data/lib/olyx/guardrails/checks/skipped_checks.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Olyx
+  module Guardrails
+    module Checks
+      # Produces stable check contracts when the length guard short-circuits.
+      module SkippedChecks
+        module_function
+
+        def call
+          {
+            pii: skipped('pii', detected: false),
+            injection: skipped('injection', injection_attempt: false, patterns: []),
+            secret: skipped('secret', leaked: false, count: 0),
+            policy: skipped('policy', violated: false, count: 0, findings: [])
+          }
+        end
+
+        def skipped(type, **fields)
+          { type: type, allowed: true, skipped: true, **fields }
+        end
+        private_class_method :skipped
+      end
+    end
+  end
+end

data/lib/olyx/guardrails/enum_value.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Olyx
+  module Guardrails
+    # Callable validator for a closed public option set.
+    class EnumValue
+      def initialize(allowed:, error:)
+        @allowed = allowed.freeze
+        @error = error
+      end
+
+      def call(value)
+        normalized = value.to_sym if value.respond_to?(:to_sym)
+        return normalized if @allowed.include?(normalized)
+
+        raise ArgumentError, @error
+      end
+    end
+  end
+end

data/lib/olyx/guardrails/errors.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Olyx
+  module Guardrails
+    # Raised when framework integration cannot establish a valid, safe policy.
+    class ConfigurationError < StandardError; end
+
+    # Raised when policy requires analyzer failures to interrupt evaluation.
+    class AiAnalyzerError < StandardError; end
+
+    # Raised by explicit enforcement entry points when a policy rejects input.
+    class Blocked < StandardError
+      attr_reader :decision
+
+      # @param decision [Hash] immutable, sanitized decision summary.
+      def initialize(decision)
+        @decision = decision
+        super('input blocked by guardrail policy')
+      end
+    end
+  end
+end

data/lib/olyx/guardrails/injection_detector.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require_relative 'multi_turn_injection_detector'
+require_relative 'single_message_injection_detector'
+require_relative 'validation'
+
+module Olyx
+  module Guardrails
+    # Coordinates phrase, structure, and adjacent-turn injection detectors.
+    class InjectionDetector
+      def self.scan(messages)
+        Validation.array_of!(messages, Hash, name: 'messages')
+        findings = messages.flat_map { |message| SingleMessageInjectionDetector.call(message) }
+        findings.concat(MultiTurnInjectionDetector.call(messages))
+        { injection_attempt: findings.any?, patterns: findings.uniq { |finding| finding[:match] } }
+      end
+
+      def self.check(messages)
+        scan(messages)
+      end
+
+      def self.injection?(text)
+        scan([{ 'role' => 'user', 'content' => text.to_s }])[:injection_attempt]
+      end
+    end
+  end
+end

data/lib/olyx/guardrails/injection_patterns.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Olyx
+  module Guardrails
+    # Declarative prompt-injection pattern catalog.
+    module InjectionPatterns
+      STRUCTURAL = [
+        /\[\s*(?:SYSTEM|INST|INSTRUCTION|OVERRIDE)\s*\]/i,
+        /<<\s*(?:sys|system|instructions?)\s*>>/i,
+        /#{Regexp.escape('<|system|>')}/i,
+        /---+\s*(?:new\s+)?instructions?\s*---+/i,
+        /={3,}\s*(?:instructions?|override)\s*={3,}/i,
+        /###\s*(?:override|instructions?)/i
+      ].freeze
+
+      PHRASES = [
+        /ignore\s+(?:all\s+)?(?:previous|prior)\s+instructions?/i,
+        /disregard\s+(?:all\s+)?(?:previous|prior|your)\s+(?:instructions?|rules?|training)/i,
+        /forget\s+(?:all\s+)?(?:your|previous)\s+instructions?/i,
+        /your\s+(?:new\s+)?(?:instructions?\s+are|rules?\s+are)/i,
+        /(?:override|bypass|ignore)\s+your\s+(?:instructions?|safety|restrictions?|filters?|rules?|training)/i,
+        /(?:pretend|act)\s+(?:you\s+are|as\s+if\s+you|as\s+a(?:n?\s+AI)?)/i,
+        /you\s+are\s+now\s+(?:a|an|free|DAN|unrestricted)/i,
+        /(?:jailbreak|dan\s+mode|developer\s+mode|god\s+mode|unrestricted\s+mode)/i,
+        /do\s+anything\s+now/i,
+        /you\s+have\s+no\s+(?:restrictions?|limits?|rules?|filters?)/i,
+        /without\s+(?:any\s+)?(?:restrictions?|filters?|limits?|rules?|safety)/i,
+        /new\s+(?:system\s+)?persona/i,
+        /system\s*(?:prompt|message|instruction)\s*:/i,
+        /reveal\s+(?:your\s+)?(?:system\s+)?(?:prompt|instructions?)/i,
+        /repeat\s+(?:your\s+)?(?:system\s+)?(?:prompt|instructions?)/i
+      ].freeze
+
+      SINGLE_MESSAGE = (STRUCTURAL + PHRASES).freeze
+
+      MULTI_TURN = [
+        [/hypothetically/i, /no\s+restrictions?/i],
+        [/for\s+a\s+story/i, /ignore\s+(?:your\s+)?(?:guidelines?|rules?)/i],
+        [/pretend\s+you('re|\s+are)/i, /as\s+(an?\s+)?(?:AI|assistant)\s+without/i],
+        [/let'?s?\s+play\s+a\s+game/i, /you\s+(?:must|have\s+to)\s+answer/i]
+      ].freeze
+    end
+  end
+end

data/lib/olyx/guardrails/integrations/openai/analyzer_setup.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Olyx
+  module Guardrails
+    module Integrations
+      module OpenAIComponents
+        # Resolves analyzer dependencies and constructs its request builder.
+        module AnalyzerSetup
+          module_function
+
+          def call(config, analyzer_class)
+            client = config.client || analyzer_class.openai_client
+            schema = config.schema || analyzer_class.analysis_schema
+            resolved = ConfigurationResolver.call(config, client: client, schema: schema)
+            [client, RequestBuilder.new(resolved)]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/olyx/guardrails/integrations/openai/configuration_resolver.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require_relative '../openai_analyzer_configuration'
+
+module Olyx
+  module Guardrails
+    module Integrations
+      module OpenAIComponents
+        # Resolves optional client and schema dependencies after validation.
+        module ConfigurationResolver
+          module_function
+
+          def call(config, client:, schema:)
+            OpenAIAnalyzerConfiguration.new(
+              model: config.model,
+              client: client,
+              schema: config.schema || schema,
+              instructions: config.instructions,
+              store: config.store,
+              request_options: config.request_options,
+              response_options: config.response_options
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/olyx/guardrails/integrations/openai/dependency_contracts.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Olyx
+  module Guardrails
+    module Integrations
+      module OpenAIComponents
+        # Validates injected SDK collaborators at the integration boundary.
+        module DependencyContracts
+          module_function
+
+          def client(value)
+            raise ArgumentError, 'client must expose responses' unless value.nil? || value.respond_to?(:responses)
+
+            value
+          end
+
+          def schema(value)
+            unless value.nil? || value.respond_to?(:to_json_schema)
+              raise ArgumentError, 'schema must be an OpenAI schema model class'
+            end
+
+            value
+          end
+        end
+      end
+    end
+  end
+end

data/lib/olyx/guardrails/integrations/openai/input_builder.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require 'json'
+require_relative 'signal_summary'
+
+module Olyx
+  module Guardrails
+    module Integrations
+      module OpenAIComponents
+        # Encodes untrusted input separately from trusted classifier context.
+        class InputBuilder
+          def self.call(text, context, instructions:)
+            new(text, context, instructions).call
+          end
+
+          def initialize(text, context, instructions)
+            @text = text
+            @signals = context.is_a?(Hash) ? context : {}
+            @instructions = instructions
+          end
+
+          def call
+            [
+              { role: :system, content: system_content },
+              { role: :user, content: @text.to_s }
+            ]
+          end
+
+          private
+
+          def system_content
+            summary = SignalSummary.call(@signals)
+            "#{@instructions}\nLocal scanner signals: #{JSON.generate(summary)}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/olyx/guardrails/integrations/openai/member_reader.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Olyx
+  module Guardrails
+    module Integrations
+      module OpenAIComponents
+        # Reads SDK object and Hash members through one compatibility boundary.
+        module MemberReader
+          module_function
+
+          def call(object, key)
+            return object.public_send(key) if object.respond_to?(key)
+            return unless object.is_a?(Hash)
+
+            object.key?(key) ? object[key] : object[key.to_s]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/olyx/guardrails/integrations/openai/model_identifier.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Olyx
+  module Guardrails
+    module Integrations
+      module OpenAIComponents
+        # Validates model identifiers without imposing a stale model allowlist.
+        module ModelIdentifier
+          module_function
+
+          def call(model)
+            raise ArgumentError, 'model must be a non-empty String or Symbol' unless valid?(model)
+
+            model
+          end
+
+          def valid?(model)
+            string?(model) || symbol?(model)
+          end
+
+          def string?(model) = model.is_a?(String) && !model.strip.empty?
+          def symbol?(model) = model.is_a?(Symbol) && !model.to_s.empty?
+          private_class_method :string?, :symbol?, :valid?
+        end
+      end
+    end
+  end
+end

data/lib/olyx/guardrails/integrations/openai/refusal_guard.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require_relative 'member_reader'
+
+module Olyx
+  module Guardrails
+    module Integrations
+      module OpenAIComponents
+        # Converts OpenAI refusal content into the connector error contract.
+        module RefusalGuard
+          module_function
+
+          def call(content, error_class)
+            return unless MemberReader.call(content, :type).to_s == 'refusal'
+
+            raise error_class, message(content)
+          end
+
+          def message(content)
+            refusal = MemberReader.call(content, :refusal).to_s
+            "OpenAI refused the analysis: #{refusal}".gsub(/[\r\n\t]+/, ' ')[0...201]
+          end
+          private_class_method :message
+        end
+      end
+    end
+  end
+end

data/lib/olyx/guardrails/integrations/openai/request_builder.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require_relative 'input_builder'
+
+module Olyx
+  module Guardrails
+    module Integrations
+      module OpenAIComponents
+        # Builds the owned and caller-supplied Responses API parameters.
+        class RequestBuilder
+          def initialize(configuration)
+            @configuration = configuration
+          end
+
+          def call(text, context)
+            params = @configuration.response_options.merge(owned_params(text, context))
+            request_options = @configuration.request_options
+            params[:request_options] = request_options if request_options
+            params
+          end
+
+          private
+
+          def owned_params(text, context)
+            {
+              model: @configuration.model,
+              input: InputBuilder.call(text, context, instructions: @configuration.instructions),
+              text: @configuration.schema,
+              store: @configuration.store
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/olyx/guardrails/integrations/openai/request_configuration.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require_relative 'response_options'
+require_relative 'request_values'
+
+module Olyx
+  module Guardrails
+    module Integrations
+      module OpenAIComponents
+        # Validates options that control a Responses API request.
+        class RequestConfiguration
+          attr_reader :instructions, :store, :request_options, :response_options
+
+          def initialize(instructions:, store:, request_options:, response_options:)
+            @instructions = RequestValues.instructions(instructions)
+            @store = RequestValues.store(store)
+            @request_options = RequestValues.request_options(request_options)
+            @response_options = ResponseOptions.call(response_options)
+            freeze
+          end
+        end
+      end
+    end
+  end
+end

data/lib/olyx/guardrails/integrations/openai/request_values.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Olyx
+  module Guardrails
+    module Integrations
+      module OpenAIComponents
+        # Validates scalar Responses API request settings.
+        module RequestValues
+          module_function
+
+          def instructions(value)
+            valid = value.is_a?(String) && !value.strip.empty?
+            raise ArgumentError, 'instructions must be a non-empty String' unless valid
+
+            value
+          end
+
+          def store(value)
+            raise ArgumentError, 'store must be true or false' unless [true, false].include?(value)
+
+            value
+          end
+
+          def request_options(value)
+            raise ArgumentError, 'request_options must be a Hash or nil' unless value.nil? || value.is_a?(Hash)
+
+            value
+          end
+        end
+      end
+    end
+  end
+end

data/lib/olyx/guardrails/integrations/openai/response_contents.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require_relative 'member_reader'
+
+module Olyx
+  module Guardrails
+    module Integrations
+      module OpenAIComponents
+        # Flattens Responses API output content across SDK and Hash shapes.
+        module ResponseContents
+          module_function
+
+          def call(response)
+            Array(MemberReader.call(response, :output)).flat_map do |output|
+              Array(MemberReader.call(output, :content))
+            end
+          end
+        end
+      end
+    end
+  end
+end