olyx-guardrails 1.0.0

data/examples/rails_opt_in.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+# Copy the relevant sections into a Rails application. Nothing is scanned
+# globally: each helper is called at an application-owned AI boundary.
+
+require 'olyx/guardrails/rails'
+
+# config/initializers/olyx_guardrails.rb
+Olyx::Guardrails::Rails.configure do |config|
+  config.enabled = true
+  config.policy_path = Rails.root.join('config/olyx_guardrails.yml')
+  config.ai_analyzer = nil
+  config.notifier_handlers = {
+    audit: ->(event) { Rails.logger.warn(event.inspect) }
+  }
+  config.filter_parameters = %i[prompt system_prompt ai_input llm_input]
+end
+
+# Controller input, redaction, and completed-output enforcement.
+class AiRequestsController < ApplicationController
+  include Olyx::Guardrails::Rails::Controller
+
+  rescue_from Olyx::Guardrails::Blocked do |error|
+    render json: { error: 'input_rejected', decision: error.decision },
+           status: :unprocessable_entity
+  end
+
+  def create
+    prompt = params.require(:prompt)
+    guardrails_check!(prompt, metadata: { account_id: current_account.id })
+    safe_prompt = guardrails_redact(prompt)[:text]
+    completion = LlmClient.complete(safe_prompt)
+    Olyx::Guardrails::Rails::Enforcer.check_output!(completion)
+    render json: { completion: completion }, status: :created
+  end
+end
+
+# GraphQL resolver or mutation.
+class CompletionResolver
+  include Olyx::Guardrails::Rails::GraphQL
+
+  def resolve(prompt:)
+    guardrails_check_graphql!(prompt)
+    completion = LlmClient.complete(prompt)
+    guardrails_check_graphql_output!(completion)
+    { completion: completion }
+  end
+end
+
+# Action Cable channel.
+class PromptChannel < ApplicationCable::Channel
+  include Olyx::Guardrails::Rails::ActionCable
+
+  def receive(data)
+    guardrails_check_cable!(data.fetch('prompt'))
+    transmit(status: 'accepted')
+  end
+end
+
+# Active Job arguments are checked immediately before perform.
+class CompletionJob < ApplicationJob
+  include Olyx::Guardrails::Rails::Job
+
+  guardrails_input_arguments 0, :system_prompt
+
+  def perform(prompt, system_prompt:)
+    LlmClient.complete(prompt, system_prompt: system_prompt)
+  end
+end
+
+# Active Model validation for an explicitly declared AI-bound attribute.
+class PromptDraft
+  include ActiveModel::Model
+
+  attr_accessor :prompt
+
+  validates :prompt, olyx_guardrails: true
+end
+
+# Caller-owned upload parsing. The extractor must return a String.
+class UploadedPromptChecker
+  def self.call(upload)
+    Olyx::Guardrails::Rails::Upload.check!(
+      upload,
+      extractor: ->(file) { DocumentTextExtractor.call(file.tempfile) }
+    )
+  end
+end
+
+# Service objects, callbacks, and custom transports use the reusable enforcer.
+class ConversationService
+  def self.call(messages)
+    Olyx::Guardrails::Rails::Enforcer.check_messages!(
+      messages,
+      metadata: { boundary: 'conversation_service' }
+    )
+    LlmClient.chat(messages)
+  end
+end

data/examples/ruby_only.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+# Run with:
+#   ruby -Ilib examples/ruby_only.rb "Summarize these release notes"
+#
+# This path has no Rails dependency and keeps policy, enforcement, model calls,
+# and notification delivery under the application's control.
+
+require 'olyx/guardrails'
+
+policy = Olyx::Guardrails::Policy.new(
+  name: 'ruby-application',
+  max_input_length: 4_000,
+  block_pii: true,
+  block_injections: true,
+  block_secrets: true,
+  ai_failure_mode: :block,
+  secret_patterns: ['company-token-[a-z0-9]{24}'],
+  rules: [
+    {
+      name: :confidential_project,
+      terms: ['Project Falcon'],
+      match: :whole_word,
+      replacement: '[CONFIDENTIAL_PROJECT]'
+    }
+  ]
+)
+
+notifier = Olyx::Guardrails::Notifier.new(
+  policy: policy,
+  handlers: { stderr: ->(event) { warn("guardrail event: #{event.inspect}") } }
+)
+
+prompt = ARGV.fetch(0, 'Summarize these public release notes')
+decision = Olyx::Guardrails.check(prompt, policy: policy)
+notifier.notify(decision, input: prompt, metadata: { boundary: 'model_input' })
+unless decision[:allowed]
+  rejected = decision[:checks].reject { |check| check[:allowed] }
+  rejected_types = rejected.map { |check| check[:type] }
+  abort "Input rejected: #{rejected_types.join(', ')}"
+end
+
+safe_prompt = Olyx::Guardrails.redact(prompt, policy: policy)[:text]
+
+# Replace this lambda with the application's model client.
+model = ->(input) { "Completed response for: #{input}" }
+completion = model.call(safe_prompt)
+
+output_decision = Olyx::Guardrails.check_output(completion, policy: policy)
+notifier.notify(output_decision, input: completion, metadata: { boundary: 'model_output' })
+abort 'Output rejected' unless output_decision[:allowed]
+
+puts Olyx::Guardrails.redact_output(completion, policy: policy)[:text]

data/lib/generators/olyx_guardrails/install_generator.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require 'rails/generators/base'
+
+module OlyxGuardrails
+  module Generators
+    # Installs explicit, environment-specific Rails policy configuration.
+    class InstallGenerator < ::Rails::Generators::Base
+      source_root File.expand_path('templates', __dir__)
+
+      desc 'Install Olyx Guardrails Rails configuration and policies'
+
+      def copy_initializer
+        template 'initializer.rb.tt', 'config/initializers/olyx_guardrails.rb'
+      end
+
+      def copy_policy
+        template 'policy.yml.tt', 'config/olyx_guardrails.yml'
+      end
+    end
+  end
+end

data/lib/generators/olyx_guardrails/templates/initializer.rb.tt

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+Olyx::Guardrails::Rails.configure do |config|
+  config.enabled = true
+  config.policy_path = Rails.root.join("config/olyx_guardrails.yml")
+
+  # Optional semantic analyzer. Keep deterministic findings authoritative.
+  config.ai_analyzer = nil
+
+  # Handlers receive sanitized, immutable events. Keep this empty when
+  # ActiveSupport::Notifications is sufficient for your application.
+  config.notifier_handlers = {}
+
+  # Prevent common AI input parameter names from appearing in Rails logs.
+  config.filter_parameters = %i[prompt system_prompt ai_input llm_input]
+end

data/lib/generators/olyx_guardrails/templates/policy.yml.tt

@@ -0,0 +1,41 @@
+development:
+  name: development
+  max_input_length: 10000
+  block_pii: false
+  block_injections: true
+  block_secrets: false
+  ai_failure_mode: allow
+  secret_patterns: []
+  rules: []
+
+test:
+  name: test
+  max_input_length: 10000
+  block_pii: true
+  block_injections: true
+  block_secrets: true
+  ai_failure_mode: block
+  secret_patterns: []
+  rules: []
+
+production:
+  name: production
+  max_input_length: 10000
+  block_pii: true
+  block_injections: true
+  block_secrets: true
+  ai_failure_mode: block
+  secret_patterns: []
+    # String values are case-insensitive regular-expression source.
+    # - 'company-token-[a-z0-9]{24}'
+  rules: []
+    # Add organization restrictions explicitly. Example:
+    # - name: confidential_projects
+    #   description: Internal project names must not enter AI requests
+    #   terms:
+    #     - 'Project Falcon'
+    #   match: whole_word
+    #   patterns:
+    #     - '\bPF-[0-9]{4}\b'
+    #   block: true
+    #   replacement: '[CONFIDENTIAL_PROJECT]'

data/lib/olyx/guardrails/ai/analysis_normalizer.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Olyx
+  module Guardrails
+    module Ai
+      # Converts supported schema-model results into Hash values.
+      module AnalysisNormalizer
+        module_function
+
+        def call(value)
+          return value if value.is_a?(Hash)
+
+          converted = convert(value)
+          converted if converted.is_a?(Hash)
+        end
+
+        def convert(value)
+          return value.deep_to_h if value.respond_to?(:deep_to_h)
+
+          value.to_h if value.respond_to?(:to_h)
+        end
+        private_class_method :convert
+      end
+    end
+  end
+end

data/lib/olyx/guardrails/ai/analysis_pipeline.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Olyx
+  module Guardrails
+    module Ai
+      # Applies normalization, selection, Boolean validation, and reason bounds.
+      module AnalysisPipeline
+        INVALID_SHAPE_ERROR = 'ai_analyzer must return a Hash or a schema model with deep_to_h/to_h'
+
+        module_function
+
+        def call(value)
+          result = AnalysisNormalizer.call(value)
+          return { error: INVALID_SHAPE_ERROR } unless result
+
+          sanitized = ResultSanitizer.call(result)
+          invalid_key = BooleanValidator.invalid_key(sanitized)
+          return { error: "ai_analyzer #{invalid_key} must be true or false" } if invalid_key
+
+          sanitized[:reason] = sanitized[:reason].to_s[0...500] if sanitized.key?(:reason)
+          sanitized
+        end
+      end
+    end
+  end
+end

data/lib/olyx/guardrails/ai/boolean_validator.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Olyx
+  module Guardrails
+    module Ai
+      # Finds the first analyzer flag whose value is not Boolean.
+      module BooleanValidator
+        KEYS = %i[injection_attempt pii_detected secret_leaked].freeze
+
+        module_function
+
+        def invalid_key(analysis)
+          KEYS.find { |key| analysis.key?(key) && ![true, false].include?(analysis[key]) }
+        end
+      end
+    end
+  end
+end

data/lib/olyx/guardrails/ai/flag_finding_merger.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Olyx
+  module Guardrails
+    module Ai
+      # Merges one semantic Boolean finding into its deterministic check.
+      module FlagFindingMerger
+        module_function
+
+        def call(check, flagged, changes)
+          flagged ? check.merge(**changes, ai_flagged: true) : check
+        end
+      end
+    end
+  end
+end

data/lib/olyx/guardrails/ai/result_sanitizer.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Olyx
+  module Guardrails
+    module Ai
+      # Selects the bounded analyzer contract from an untrusted result Hash.
+      module ResultSanitizer
+        KEYS = %i[injection_attempt pii_detected secret_leaked risk_score reason].freeze
+
+        module_function
+
+        def call(result)
+          KEYS.each_with_object({}) do |key, output|
+            value, present = value_for(result, key)
+            output[key] = value if present
+          end
+        end
+
+        def value_for(result, key)
+          return [result[key], true] if result.key?(key)
+
+          string_key = key.to_s
+          [result[string_key], result.key?(string_key)]
+        end
+        private_class_method :value_for
+      end
+    end
+  end
+end

data/lib/olyx/guardrails/ai/secret_finding_merger.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Olyx
+  module Guardrails
+    module Ai
+      # Merges the semantic secret flag into a deterministic secret check.
+      module SecretFindingMerger
+        module_function
+
+        def call(check, analysis, policy)
+          return check unless analysis[:secret_leaked]
+
+          count = [check[:count].to_i, 1].max
+          check.merge(leaked: true, allowed: !policy.block_secrets?, count: count, ai_flagged: true)
+        end
+      end
+    end
+  end
+end

data/lib/olyx/guardrails/ai/standard_finding_merger.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Olyx
+  module Guardrails
+    module Ai
+      # Merges semantic PII and injection flags using declarative mappings.
+      module StandardFindingMerger
+        SETTINGS = {
+          pii: %i[pii_detected detected block_pii?],
+          injection: %i[injection_attempt injection_attempt block_injections?]
+        }.freeze
+
+        module_function
+
+        def call(checks, analysis, policy)
+          SETTINGS.to_h do |check_name, (finding_name, result_name, blocking_query)|
+            changes = { result_name => true, allowed: !policy.public_send(blocking_query) }
+            [check_name, FlagFindingMerger.call(checks[check_name], analysis[finding_name], changes)]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/olyx/guardrails/ai_analysis.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative 'ai/analysis_normalizer'
+require_relative 'ai/analysis_pipeline'
+require_relative 'ai/boolean_validator'
+require_relative 'ai/result_sanitizer'
+
+module Olyx
+  module Guardrails
+    # Normalizes and bounds responses from an untrusted optional AI analyzer.
+    class AiAnalysis
+      def self.call(analyzer, text, context)
+        new(analyzer, text, context).call
+      end
+
+      def initialize(analyzer, text, context)
+        @analyzer = analyzer
+        @text = text
+        @context = context
+      end
+
+      def call
+        Ai::AnalysisPipeline.call(@analyzer.call(@text, @context))
+      rescue StandardError => error
+        { error: error.message.to_s[0..200] }
+      end
+    end
+  end
+end

data/lib/olyx/guardrails/ai_context_builder.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Olyx
+  module Guardrails
+    # Builds the bounded deterministic context passed to semantic analyzers.
+    module AiContextBuilder
+      module_function
+
+      def call(checks)
+        detection(checks).merge(policy(checks[:policy]))
+      end
+
+      def detection(checks)
+        injection = checks[:injection]
+        {
+          pii_detected: checks[:pii][:detected],
+          injection_attempt: injection[:injection_attempt],
+          injection_patterns: injection[:patterns],
+          secret_leaked: checks[:secret][:leaked]
+        }
+      end
+
+      def policy(check)
+        {
+          policy_violated: check[:violated],
+          policy_rules: check[:findings].map { |finding| finding[:rule] }
+        }
+      end
+      private_class_method :detection, :policy
+    end
+  end
+end

data/lib/olyx/guardrails/ai_failure_handler.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Olyx
+  module Guardrails
+    # Applies the policy-selected behavior for an analyzer failure.
+    module AiFailureHandler
+      module_function
+
+      def call(checks, analysis, mode)
+        return checks if mode == :allow
+        raise AiAnalyzerError, analysis[:error] if mode == :raise
+
+        checks.merge(ai: { type: 'ai', allowed: false, error: true })
+      end
+    end
+  end
+end

data/lib/olyx/guardrails/ai_finding_merger.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require_relative 'ai/secret_finding_merger'
+require_relative 'ai/flag_finding_merger'
+require_relative 'ai/standard_finding_merger'
+
+module Olyx
+  module Guardrails
+    # Unions semantic findings into deterministic checks without clearing any.
+    class AiFindingMerger
+      def self.call(checks, analysis, policy)
+        new(checks, analysis, policy).call
+      end
+
+      def initialize(checks, analysis, policy)
+        @checks = checks
+        @analysis = analysis
+        @policy = policy
+      end
+
+      def call
+        @checks.merge(
+          Ai::StandardFindingMerger.call(@checks, @analysis, @policy).merge(
+            secret: Ai::SecretFindingMerger.call(@checks[:secret], @analysis, @policy)
+          )
+        )
+      end
+    end
+  end
+end

data/lib/olyx/guardrails/check_analyzer.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require_relative 'ai_failure_handler'
+
+module Olyx
+  module Guardrails
+    # Runs optional semantic analysis and merges valid findings.
+    module CheckAnalyzer
+      module_function
+
+      def call(checks, analyzer:, source:, policy:)
+        return [checks, nil] unless analyzer && checks[:length][:allowed]
+
+        analysis = AiAnalysis.call(analyzer, source, AiContextBuilder.call(checks))
+        [merge(checks, analysis, policy), analysis]
+      end
+
+      def merge(checks, analysis, policy)
+        return AiFailureHandler.call(checks, analysis, policy.ai_failure_mode) if analysis[:error]
+
+        AiFindingMerger.call(checks, analysis, policy)
+      end
+      private_class_method :merge
+    end
+  end
+end

data/lib/olyx/guardrails/check_base_result.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Olyx
+  module Guardrails
+    # Builds the stable deterministic portion of a check decision.
+    module CheckBaseResult
+      module_function
+
+      def call(checks, ordered, policy)
+        detection(checks, ordered).merge(policy(checks[:policy], policy))
+      end
+
+      def detection(checks, ordered)
+        {
+          allowed: ordered.all? { |check| check[:allowed] },
+          pii_detected: checks[:pii][:detected],
+          injection_attempt: checks[:injection][:injection_attempt],
+          secret_leaked: checks[:secret][:leaked]
+        }
+      end
+
+      def policy(check, configuration)
+        {
+          policy_name: configuration.name,
+          policy_violated: check[:violated],
+          policy_findings: check[:findings]
+        }
+      end
+      private_class_method :detection, :policy
+    end
+  end
+end

data/lib/olyx/guardrails/check_pipeline.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Olyx
+  module Guardrails
+    # Applies optional analysis and builds the public decision contract.
+    module CheckPipeline
+      module_function
+
+      def call(source, checks, policy:, ai_analyzer:)
+        merged, analysis = CheckAnalyzer.call(
+          checks, analyzer: ai_analyzer, source: source, policy: policy
+        )
+        CheckResultBuilder.call(merged, analysis, policy)
+      end
+    end
+  end
+end

data/lib/olyx/guardrails/check_result_builder.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require_relative 'risk_scorer'
+require_relative 'check_base_result'
+
+module Olyx
+  module Guardrails
+    # Presents merged checks as the stable public decision contract.
+    module CheckResultBuilder
+      CHECK_ORDER = %i[pii injection secret policy length ai].freeze
+
+      module_function
+
+      def call(checks, analysis, policy)
+        ordered = CHECK_ORDER.filter_map { |type| checks[type] }
+        result = CheckBaseResult.call(checks, ordered, policy)
+        result[:risk_score] = RiskScorer.call(checks, ordered, analysis)
+        result[:checks] = ordered
+        result[:ai_analysis] = analysis if analysis
+        result
+      end
+    end
+  end
+end

data/lib/olyx/guardrails/check_runner.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require_relative 'ai_analysis'
+require_relative 'ai_context_builder'
+require_relative 'ai_finding_merger'
+require_relative 'check_result_builder'
+require_relative 'check_analyzer'
+require_relative 'check_set'
+require_relative 'check_pipeline'
+require_relative 'policy'
+require_relative 'validation'
+
+module Olyx
+  module Guardrails
+    # Orchestrates deterministic checks and optional semantic enrichment.
+    class CheckRunner
+      def self.call(input, **)
+        new(input, **).call
+      end
+
+      def initialize(input, policy:, ai_analyzer:)
+        @source = input.to_s
+        @policy = policy
+        @ai_analyzer = ai_analyzer
+        validate_options!
+      end
+
+      def call
+        checks = CheckSet.call(@source, policy: @policy)
+        CheckPipeline.call(@source, checks, policy: @policy, ai_analyzer: @ai_analyzer)
+      end
+
+      private
+
+      def validate_options!
+        raise ArgumentError, 'policy must be an Olyx::Guardrails::Policy' unless @policy.is_a?(Policy)
+
+        Validation.callable_or_nil!(@ai_analyzer, name: 'ai_analyzer')
+      end
+    end
+  end
+end