vangrail 0.1.0

data/lib/vangrail/conversation.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+require_relative 'engine'
+require_relative 'result'
+
+module Vangrail
+  # A dialogue, so rails can see more than the turn in front of them.
+  #
+  # Every rail so far reads one string. That is enough for the attacks that fit
+  # in one string, and it is exactly wrong for the ones built out of turns that
+  # are individually unremarkable: ask something harmless, ask for more detail
+  # about the part of the answer that helps, keep going until the thing you
+  # wanted is on screen. No single message in that sequence looks like an
+  # attack, because none of them is one.
+  #
+  # So this holds the turns and threads them into the rail context as
+  # `:history`, which the rail protocol has always carried and nothing has ever
+  # filled in. A rail that ignores history behaves exactly as before.
+  #
+  #   convo = Vangrail::Conversation.new(engine)
+  #   verdict = convo.ask(question)
+  #   convo.answer(text) if verdict.allowed?
+  #
+  # What it also does is remember the verdicts. A refusal is the most
+  # informative event in a dialogue: the next message is either an ordinary
+  # follow-up or the same request rewritten, and telling those apart is
+  # impossible without knowing a refusal happened.
+  class Conversation
+    Turn = Struct.new(:role, :text, :result, keyword_init: true) do
+      def blocked?
+        result&.blocked? || false
+      end
+
+      def user?
+        role == :user
+      end
+
+      def to_h
+        { 'role' => role.to_s, 'text' => text, 'result' => result&.to_h }.compact
+      end
+    end
+
+    # How many turns of history the rails see. A dialogue that has been running
+    # for an hour is mostly irrelevant to whether this message is a retry, and
+    # an unbounded window makes the cost of a check grow with the session.
+    DEFAULT_WINDOW = 12
+
+    attr_reader :engine, :turns, :window
+
+    def initialize(engine, window: DEFAULT_WINDOW, **context)
+      @engine = engine
+      @window = window
+      @base_context = context
+      @turns = []
+    end
+
+    # Checks a question and records it, whatever the verdict. A blocked turn
+    # stays in the history: it is the part the next check needs most.
+    def ask(text, **context)
+      result = engine.check_input(text, history: history, **@base_context, **context)
+      @turns << Turn.new(role: :user, text: text.to_s, result: result)
+      result
+    end
+
+    def answer(text, **context)
+      result = engine.check_output(text, history: history, **@base_context, **context)
+      @turns << Turn.new(role: :assistant, text: content_of(result, text), result: result)
+      result
+    end
+
+    # Screens retrieved documents with the dialogue in view, so a context rail
+    # can see which question they were fetched for.
+    def screen(documents, **context)
+      engine.screen(documents, history: history, **@base_context, **context)
+    end
+
+    # The window the rails read: role and text, no Result objects, because a
+    # rail should not be reasoning about another rail's verdict text.
+    def history
+      turns.last(window).map { |t| { role: t.role, text: t.text, blocked: t.blocked? } }
+    end
+
+    def blocked_turns
+      turns.select { |t| t.user? && t.blocked? }
+    end
+
+    def blocked?
+      !blocked_turns.empty?
+    end
+
+    def last_user_turn
+      turns.reverse.find(&:user?)
+    end
+
+    def to_h
+      { 'turns' => turns.map(&:to_h), 'blocked' => blocked_turns.size }
+    end
+
+    private
+
+    def content_of(result, fallback)
+      result.respond_to?(:content_or) ? result.content_or(fallback.to_s) : fallback.to_s
+    end
+  end
+end

data/lib/vangrail/engine.rb

@@ -0,0 +1,240 @@
+# frozen_string_literal: true
+
+require_relative 'errors'
+require_relative 'rail'
+require_relative 'result'
+require_relative 'result_cache'
+
+module Vangrail
+  # Runs ordered rails over text and reports one Result.
+  #
+  # The rules are short enough to state in full:
+  #
+  # - Rails run in the order given. The first :blocked ends the pass.
+  # - A :modified result replaces the text for every rail after it, and the
+  #   engine reports :modified unless something later blocks.
+  # - A rail that raises is not a rail that passed. `on_error: :allow` (the
+  #   default) keeps going and marks the pass uncertain; `:block` stops.
+  # - An empty rail list returns :passed with certain false. Nothing ran.
+  #
+  # Threading rewrites through later rails is the part worth being explicit
+  # about: a redaction rail that runs before a policy rail should have the
+  # policy rail judge the redacted text, not the original.
+  class Engine
+    attr_reader :input_rails, :context_rails, :output_rails, :on_error, :cache
+
+    def initialize(input: [], context: [], output: [], on_error: :allow, cache: true)
+      @input_rails = Array(input)
+      @context_rails = Array(context)
+      @output_rails = Array(output)
+      @on_error = on_error.to_sym
+      raise ArgumentError, 'on_error must be :allow or :block' unless %i[allow block].include?(@on_error)
+
+      @cache = cache.is_a?(ResultCache) ? cache : (ResultCache.new if cache)
+    end
+
+    def check_input(text, context = {})
+      run(:input, input_rails, text, context)
+    end
+
+    def check_output(text, user_input: nil, passages: nil, **context)
+      run(:output, output_rails, text, context.merge(user_input: user_input, passages: passages))
+    end
+
+    # One retrieved document, before it goes anywhere near a prompt.
+    def check_context(text, **context)
+      run(:context, context_rails, text, context)
+    end
+
+    # Screens a set of retrieved documents and reports what survived.
+    #
+    # A document that fails is dropped rather than failing the whole turn. One
+    # poisoned wiki page should cost a reader that page, not their answer, and
+    # an application that refuses outright teaches its readers that the
+    # guardrail is the problem.
+    def screen(documents, **context)
+      kept = []
+      rejected = []
+      uncertain = nil
+
+      Array(documents).each_with_index do |document, index|
+        result = check_context(text_of(document), **context, document: document, index: index)
+        uncertain ||= result unless result.certain?
+        if result.blocked?
+          rejected << { document: document, result: result }
+        else
+          kept << (result.modified? ? replace_text(document, result.content) : document)
+        end
+      end
+
+      Screening.new(kept: kept, rejected: rejected, certain: uncertain.nil?, reason: uncertain&.reason)
+    end
+
+    # What screen returns. `certain` means what it means on a Result: false says
+    # a rail did not reach a decision about some document, so "nothing was
+    # rejected" is not evidence that nothing was wrong.
+    Screening = Struct.new(:kept, :rejected, :certain, :reason, keyword_init: true) do
+      def certain?
+        certain
+      end
+
+      def rejected?
+        !rejected.empty?
+      end
+
+      def to_h
+        {
+          'kept' => kept.size,
+          'rejected' => rejected.map { |r| r[:result].to_h },
+          'certain' => certain?,
+          'reason' => reason
+        }.compact
+      end
+    end
+
+    def rails(side)
+      case side.to_sym
+      when :input then input_rails
+      when :context then context_rails
+      else output_rails
+      end
+    end
+
+    def rail_names(side)
+      rails(side).map(&:name)
+    end
+
+    # True when every configured rail decides without a network call, which is
+    # the only case where an unreachable endpoint cannot weaken the check.
+    def offline?
+      all = input_rails + context_rails + output_rails
+      !all.empty? && all.all?(&:offline?)
+    end
+
+    def empty?
+      input_rails.empty? && context_rails.empty? && output_rails.empty?
+    end
+
+    def to_h
+      {
+        'input' => rail_names(:input),
+        'context' => (rail_names(:context) unless context_rails.empty?),
+        'output' => rail_names(:output),
+        'on_error' => on_error.to_s,
+        'offline' => offline?,
+        'cache' => cache&.to_h
+      }.compact
+    end
+
+    def describe
+      return 'no rails' if empty?
+
+      parts = []
+      parts << "input=#{rail_names(:input).join('+')}" unless input_rails.empty?
+      parts << "context=#{rail_names(:context).join('+')}" unless context_rails.empty?
+      parts << "output=#{rail_names(:output).join('+')}" unless output_rails.empty?
+      parts << "on_error=#{on_error}"
+      parts << 'offline' if offline?
+      parts.join(' ')
+    end
+
+    private
+
+    def text_of(document)
+      return document.to_s unless document.is_a?(Hash)
+
+      (document['text'] || document[:text]).to_s
+    end
+
+    # A context rail may rewrite a document rather than reject it, so the
+    # replacement has to go back into the shape the caller passed in.
+    def replace_text(document, content)
+      return content.to_s unless document.is_a?(Hash)
+
+      key = document.key?('text') ? 'text' : :text
+      document.merge(key => content.to_s)
+    end
+
+    def run(side, rails, text, context)
+      return Result.unchecked(rail: side, reason: "no #{side} rails configured") if rails.empty?
+
+      ctx = context.merge(side: side)
+      current = text.to_s
+      modified_by = nil
+      uncertain = nil
+      unbuilt = nil
+
+      rails.each do |rail|
+        next unless rail.applies_to?(side)
+
+        result = invoke(rail, current, ctx)
+        return result.with_rail(rail.name) if result.blocked?
+
+        if result.modified?
+          current = result.content_or(current)
+          modified_by = rail.name
+        end
+        next if result.certain?
+
+        # A rail that ran and could not decide says more than one that was
+        # never built, so its reason is the one the caller sees. Without this,
+        # a placeholder earlier in the list reports "no endpoint was resolved"
+        # over the rail that actually tried and had the connection refused.
+        if rail.placeholder?
+          unbuilt ||= result
+        else
+          uncertain ||= result
+        end
+      end
+
+      finish(side, current, modified_by, uncertain || unbuilt)
+    end
+
+    def finish(side, current, modified_by, uncertain)
+      if modified_by
+        return Result.modified(rail: modified_by, content: current,
+                               certain: uncertain.nil?, reason: uncertain&.reason)
+      end
+      return Result.unchecked(rail: uncertain.rail || side, reason: uncertain.reason) if uncertain
+
+      Result.passed(rail: side)
+    end
+
+    def invoke(rail, text, ctx)
+      memoized(rail, text, ctx) { call_rail(rail, text, ctx) }
+    end
+
+    def call_rail(rail, text, ctx)
+      result = rail.call(text, ctx)
+      return result if result.is_a?(Result)
+
+      raise ProtocolError, "#{rail.name} returned #{result.class}, expected Vangrail::Result"
+    rescue Error => e
+      failed(rail, e)
+    end
+
+    # A rail that raised did not answer. Which way that falls is the operator's
+    # call, and either way the pass carries the reason rather than a silence.
+    def failed(rail, error)
+      reason = "#{rail.name} failed: #{error.class.name.split('::').last}: #{error.message}"
+      if on_error == :block
+        return Result.new(status: :blocked, rail: rail.name, certain: false,
+                          reason: reason)
+      end
+
+      Result.unchecked(rail: rail.name, reason: reason)
+    end
+
+    # Cache keys carry everything the decision depends on. A rail says what that
+    # is through `cache_key`; nil means the rail is not memoizable, which is the
+    # right answer for anything reading passages or history.
+    def memoized(rail, text, ctx, &block)
+      return block.call unless cache
+
+      key = rail.respond_to?(:cache_key) ? rail.cache_key(text, ctx) : nil
+      return block.call if key.nil?
+
+      cache.fetch(ctx[:side], rail.name, key, &block)
+    end
+  end
+end

data/lib/vangrail/errors.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Vangrail
+  # Base for everything this gem raises, so a caller can rescue one class.
+  class Error < StandardError; end
+
+  # The endpoint answered, but not with something this client understands.
+  class ProtocolError < Error; end
+
+  # Transport failed: connect refused, TLS, timeout, DNS.
+  class TransportError < Error
+    attr_reader :cause_class
+
+    def initialize(message, cause_class: nil)
+      super(message)
+      @cause_class = cause_class
+    end
+  end
+
+  # A 4xx or 5xx with the body kept for the operator.
+  class HTTPError < Error
+    attr_reader :status, :body
+
+    def initialize(status, body)
+      @status = status
+      @body = body.to_s
+      super("HTTP #{status}: #{@body[0, 400]}")
+    end
+
+    def retryable?
+      status >= 500 || status == 429
+    end
+  end
+
+  # No credential resolved for an endpoint that needs one.
+  class MissingToken < Error; end
+
+  # A Colang file used something outside the supported subset, or is malformed.
+  # Raised at load, never at run: a rail configuration that half-loads would
+  # report checks it is not performing.
+  class ColangError < Error; end
+
+  # A flow referred to an action or a bot message that nothing defines.
+  class UnknownAction < ColangError; end
+
+  # The configuration folder is missing something the rails it declares need.
+  class ConfigError < Error; end
+end

data/lib/vangrail/http.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'net/http'
+require 'uri'
+
+module Vangrail
+  # JSON over Net::HTTP with stdlib only: a guardrail that pulls in a transport
+  # stack is a guardrail nobody installs. Every call is bounded by open and read
+  # timeouts, because a rail that hangs is worse than a rail that is absent.
+  class HTTP
+    DEFAULT_OPEN_TIMEOUT = 5
+    DEFAULT_READ_TIMEOUT = 30
+
+    attr_reader :base_url, :open_timeout, :read_timeout, :retries
+
+    def initialize(base_url:, api_key: nil, open_timeout: DEFAULT_OPEN_TIMEOUT,
+                   read_timeout: DEFAULT_READ_TIMEOUT, retries: 1, headers: {})
+      @base_url = base_url.to_s.sub(/\/+\z/, '')
+      raise ArgumentError, 'base_url is required' if @base_url.empty?
+
+      @api_key = api_key
+      @open_timeout = open_timeout
+      @read_timeout = read_timeout
+      @retries = retries
+      @headers = headers
+    end
+
+    def get_json(path)
+      request(Net::HTTP::Get, path, nil)
+    end
+
+    def post_json(path, payload)
+      request(Net::HTTP::Post, path, payload)
+    end
+
+    # True when the endpoint answers at all. Used to pick a rail mode without
+    # making the caller handle an exception for the ordinary "not running" case.
+    def reachable?(path)
+      get_json(path)
+      true
+    rescue HTTPError
+      true
+    rescue Error
+      false
+    end
+
+    private
+
+    def request(klass, path, payload)
+      uri = URI.join("#{base_url}/", path.to_s.sub(/\A\/+/, ''))
+      attempt = 0
+      begin
+        attempt += 1
+        perform(klass, uri, payload)
+      rescue TransportError, HTTPError => e
+        raise unless attempt <= retries && retryable?(e)
+
+        sleep(0.25 * attempt)
+        retry
+      end
+    end
+
+    def retryable?(error)
+      error.is_a?(TransportError) || error.retryable?
+    end
+
+    def perform(klass, uri, payload)
+      req = klass.new(uri)
+      req['Accept'] = 'application/json'
+      req['Authorization'] = "Bearer #{@api_key}" if @api_key
+      @headers.each { |k, v| req[k] = v }
+      if payload
+        req['Content-Type'] = 'application/json'
+        req.body = JSON.generate(payload)
+      end
+
+      res = Net::HTTP.start(
+        uri.hostname, uri.port,
+        use_ssl: uri.scheme == 'https',
+        open_timeout: open_timeout,
+        read_timeout: read_timeout
+      ) { |http| http.request(req) }
+
+      code = res.code.to_i
+      raise HTTPError.new(code, res.body) unless code.between?(200, 299)
+
+      parse(res.body)
+    rescue *transport_errors => e
+      raise TransportError.new("#{uri.host}:#{uri.port} #{e.message}", cause_class: e.class.name)
+    end
+
+    def transport_errors
+      [
+        Errno::ECONNREFUSED, Errno::EHOSTUNREACH, Errno::ENETUNREACH, Errno::ECONNRESET,
+        Net::OpenTimeout, Net::ReadTimeout, SocketError, IOError, EOFError
+      ]
+    end
+
+    def parse(body)
+      text = body.to_s
+      return {} if text.strip.empty?
+
+      JSON.parse(text)
+    rescue JSON::ParserError => e
+      raise ProtocolError, "endpoint returned non-JSON: #{e.message}"
+    end
+  end
+end

data/lib/vangrail/parsers.rb

@@ -0,0 +1,181 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module Vangrail
+  # Readers for what guard and judge models actually answer.
+  #
+  # Each returns a hash: {decided:, violated:, categories:, reason:}. `decided`
+  # false means the text was not in a form this code understands, which a rail
+  # turns into an uncertain result rather than a pass. Guessing at an unreadable
+  # answer is how a guardrail comes to report checks it never made.
+  module Parsers
+    module_function
+
+    # Llama Guard 3 hazard codes, the MLCommons taxonomy the model card lists.
+    LLAMA_GUARD_CATEGORIES = {
+      'S1' => 'Violent Crimes',
+      'S2' => 'Non-Violent Crimes',
+      'S3' => 'Sex-Related Crimes',
+      'S4' => 'Child Sexual Exploitation',
+      'S5' => 'Defamation',
+      'S6' => 'Specialized Advice',
+      'S7' => 'Privacy',
+      'S8' => 'Intellectual Property',
+      'S9' => 'Indiscriminate Weapons',
+      'S10' => 'Hate',
+      'S11' => 'Suicide & Self-Harm',
+      'S12' => 'Sexual Content',
+      'S13' => 'Elections',
+      'S14' => 'Code Interpreter Abuse'
+    }.freeze
+
+    # "safe" or "unsafe\nS1,S10".
+    def llama_guard(text)
+      lines = clean_lines(text)
+      head = lines.first.to_s.downcase
+      return undecided(text) unless head.start_with?('safe', 'unsafe')
+      return clean if head.start_with?('safe')
+
+      codes = codes_in(lines[1..]&.join(','), /S\d{1,2}/i)
+      { decided: true, violated: true, categories: codes,
+        reason: describe(codes, LLAMA_GUARD_CATEGORIES, 'unsafe') }
+    end
+
+    # "safe\nnon_adversarial" or "unsafe-O14,O12\nadversarial". Either line can
+    # condemn the turn: a jailbreak attempt with no hazard category is still one.
+    # With reasoning on the same two verdicts arrive as labelled fields after
+    # their assessments, so that form is tried first.
+    def apriel_guard(text)
+      reasoned = apriel_guard_reasoned(text)
+      return reasoned if reasoned
+
+      lines = clean_lines(text)
+      safety = lines.find { |l| l.match?(/\A(safe|unsafe)/i) }
+      adversarial = lines.find { |l| l.match?(/\A(non_adversarial|adversarial)/i) }
+      return undecided(text) if safety.nil? && adversarial.nil?
+
+      unsafe = safety.to_s.match?(/\Aunsafe/i)
+      attack = adversarial.to_s.match?(/\Aadversarial/i)
+      return clean unless unsafe || attack
+
+      codes = codes_in(safety, /O\d{1,2}/i)
+      codes += ['adversarial'] if attack
+      reason = unsafe ? describe(codes - ['adversarial'], {}, 'unsafe') : 'adversarial input'
+      { decided: true, violated: true, categories: codes, reason: reason }
+    end
+
+    # Reasoning mode:
+    #
+    #   safety_risks_assessment_reasoning: ## Step 1 ...
+    #   safety_risks_class: unsafe,
+    #   safety_risks_categories: ['O15'],
+    #   adversarial_attacks_assessment_reasoning: ## Step 1 ...
+    #   adversarial_attacks_class: adversarial
+    #
+    # nil when the text is not in this form, so the caller can try the short one.
+    def apriel_guard_reasoned(text)
+      body = text.to_s
+      return nil unless body.include?('safety_risks_class')
+
+      fields = {}
+      body.each_line do |line|
+        m = line.chomp.match(
+          /\A(safety_risks_class|safety_risks_categories|adversarial_attacks_class)\s*:\s*(.*)\z/
+        )
+        fields[m[1]] = m[2].strip.sub(/,\z/, '') if m
+      end
+      unsafe = fields['safety_risks_class'].to_s.match?(/unsafe/i)
+      attack = fields['adversarial_attacks_class'].to_s.match?(/\Aadversarial/i)
+      return clean unless unsafe || attack
+
+      codes = codes_in(fields['safety_risks_categories'], /O\d{1,2}/i)
+      codes += ['adversarial'] if attack
+      block = unsafe ? 'safety_risks' : 'adversarial_attacks'
+      { decided: true, violated: true, categories: codes, reason: rationale(body, block) }
+    end
+
+    # A JSON verdict first, then a bare 0/1, then Yes/No. All three appear
+    # depending on which answer contract a policy prompt asked for.
+    def policy(text)
+      body = text.to_s
+      from_json = policy_json(body)
+      return from_json if from_json
+
+      stripped = body.strip
+      return (stripped.start_with?('0') ? clean : violation) if stripped.match?(/\A[01]\b/)
+
+      case stripped
+      when /\Ayes\b/i then violation(reason: 'policy judge said yes')
+      when /\Ano\b/i then clean
+      else undecided(body)
+      end
+    end
+
+    def policy_json(body)
+      obj = first_json_object(body)
+      return nil unless obj
+
+      value = obj['violation']
+      return nil unless [0, 1, true, false, '0', '1'].include?(value)
+      return clean unless [1, true, '1'].include?(value)
+
+      cats = [obj['policy_category'], *Array(obj['rule_ids'])].compact.map(&:to_s).reject(&:empty?)
+      violation(categories: cats, reason: (obj['rationale'] || cats.join(',')).to_s[0, 240])
+    end
+
+    # First balanced {...}, so a fenced or prefaced verdict still reads.
+    def first_json_object(text)
+      start = text.index('{')
+      return nil unless start
+
+      depth = 0
+      text[start..].each_char.with_index do |ch, i|
+        depth += 1 if ch == '{'
+        next unless ch == '}'
+
+        depth -= 1
+        return JSON.parse(text[start, i + 1]) if depth.zero?
+      end
+      nil
+    rescue JSON::ParserError
+      nil
+    end
+
+    # Last step of an assessment block, where the model states its conclusion
+    # rather than restating the input.
+    def rationale(body, block)
+      section = body[/#{block}_assessment_reasoning:(.*?)(?=^[a-z_]+:)/m, 1]
+      return nil unless section
+
+      steps = section.split(/^##\s*Step\s*\d+\s*$/m).map(&:strip).reject(&:empty?)
+      (steps.last || section).gsub(/\s+/, ' ').strip[0, 240]
+    end
+
+    def clean
+      { decided: true, violated: false, categories: [], reason: nil }
+    end
+
+    def violation(categories: [], reason: nil)
+      { decided: true, violated: true, categories: categories, reason: reason }
+    end
+
+    def undecided(text)
+      { decided: false, violated: false, categories: [], reason: text.to_s.strip[0, 120] }
+    end
+
+    def clean_lines(text)
+      text.to_s.strip.lines.map(&:strip).reject(&:empty?)
+    end
+
+    def codes_in(text, pattern)
+      text.to_s.scan(pattern).map(&:upcase).uniq
+    end
+
+    def describe(codes, names, fallback)
+      return fallback if codes.empty?
+
+      codes.map { |c| names[c] ? "#{c} #{names[c]}" : c }.join(', ')
+    end
+  end
+end