vangrail 0.1.0 → 0.2.0

data/lib/vangrail/rails/semantic.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+require_relative '../embeddings'
+require_relative '../known_attacks'
+require_relative '../nlp'
+require_relative '../rail'
+
+module Vangrail
+  module Rails
+    # Compares meaning rather than words, through whatever endpoint is already
+    # configured.
+    #
+    # Rails::Paraphrase reaches exactly as far as the words in NLP::CONCEPTS,
+    # and Rails::Similarity exactly as far as the wordings in KnownAttacks. Both
+    # limits are the same limit written twice: a synonym nobody listed is a
+    # miss. An embedding is the cheap way past it. "Countermand the guidance
+    # issued to you" shares no listed word with "ignore all previous
+    # instructions" and sits next to it in a vector space.
+    #
+    # This is the one rail here that is genuinely semantic, and it costs a round
+    # trip, so it is opt-in and it runs beside the deterministic rails rather
+    # than instead of them. When it cannot run it says so: an endpoint that
+    # serves no embedding model, or refuses the call, produces passed with
+    # certain? false, never a clean pass.
+    #
+    # On a loopback proxy it costs no money, keeps the retrieved text on the
+    # machine, and adds one local call per document. On a third-party endpoint
+    # it is a data-flow decision: every document screened is a document sent.
+    # That is why nothing here picks an endpoint on its own.
+    #
+    # The threshold is the part that cannot ship measured. Cosine scores are a
+    # property of the embedding model, not of this gem, so 0.75 is a starting
+    # point rather than a finding: run script/embedding_probe.rb against the
+    # endpoint you actually use, read the gap between its benign and attack
+    # distributions, and set the number from that. A threshold nobody measured
+    # on the model in use is a number, not a defence.
+    class Semantic < Rail
+      THRESHOLD = 0.75
+
+      # Clauses shorter than this are not compared. A four-word fragment
+      # embeds to something close to everything, and the score it produces is
+      # noise that only ever costs a false positive.
+      FLOOR = 24
+
+      # An upper bound on the work one document can ask for. A long page has
+      # hundreds of clauses, and embedding all of them turns one round trip into
+      # a payload nobody budgeted for. The longest clauses are kept, because an
+      # injected instruction is a sentence rather than a fragment.
+      #
+      # A page that exceeds it is not fully checked, and the result says so with
+      # certain? false rather than with a footnote on a clean pass. That is the
+      # same rule the rest of this gem follows: a partial check is not a check.
+      MAX_CLAUSES = 64
+
+      attr_reader :embeddings, :seeds, :threshold
+
+      def initialize(embeddings:, seeds: KnownAttacks::ALL, threshold: THRESHOLD, floor: FLOOR,
+                     max_clauses: MAX_CLAUSES, name: 'semantic', sides: %i[input context])
+        super(name: name, sides: sides)
+        @embeddings = embeddings
+        @seeds = Array(seeds)
+        @threshold = threshold
+        @floor = floor
+        @max_clauses = max_clauses
+      end
+
+      def offline?
+        false
+      end
+
+      # Not memoizable across models or thresholds, and the text alone is not
+      # the question being asked.
+      def cache_key(text, _context)
+        "#{embeddings.model}\n#{threshold}\n#{text}"
+      end
+
+      def decide(text, _context)
+        clauses, dropped = candidates(text)
+        return pass if clauses.empty?
+
+        score, seed, clause = nearest(clauses)
+        if score < threshold
+          return dropped.zero? ? pass : unchecked(cut_reason(dropped))
+        end
+
+        block(categories: ['semantic_match'],
+              reason: format('reads as a known attack (%<score>.2f against "%<seed>s"): %<clause>s',
+                             score: score, seed: seed, clause: clause[0, 80]))
+      rescue Error => e
+        unchecked("semantic check did not run: #{e.message}")
+      end
+
+      # The closest seed, its score, and the clause that matched, for a caller
+      # that wants the number rather than the verdict. Raises what the transport
+      # raises: a probe script wants the error, a rail wants a Result.
+      def nearest(clauses)
+        vectors = embeddings.embed(clauses)
+        best = [-1.0, nil, nil]
+        vectors.each_with_index do |vector, i|
+          seed_vectors.each_with_index do |seed_vector, j|
+            score = Embeddings.cosine(vector, seed_vector)
+            best = [score, seeds[j], clauses[i]] if score > best.first
+          end
+        end
+        best
+      end
+
+      # Embedded once per rail, on first use rather than at construction: a rail
+      # that is never reached should never have called the endpoint, and an
+      # engine built with no network available must still build.
+      def seed_vectors
+        @seed_vectors ||= embeddings.embed(seeds)
+      end
+
+      private
+
+      def candidates(text)
+        clauses = NLP.clauses(text).select { |clause| clause.length >= @floor }
+        return [clauses, 0] if clauses.size <= @max_clauses
+
+        kept = clauses.sort_by { |clause| -clause.length }.first(@max_clauses)
+        [kept, clauses.size - kept.size]
+      end
+
+      # A rail that looked at part of a page has to say which part it skipped,
+      # or the pass it returns claims more than it checked.
+      def cut_reason(dropped)
+        "checked the #{@max_clauses} longest clauses; #{dropped} shorter ones were not embedded"
+      end
+    end
+  end
+end

data/lib/vangrail/rails/similarity.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require_relative '../known_attacks'
+require_relative '../nlp'
+require_relative '../rail'
+
+module Vangrail
+  module Rails
+    # Catches the known attack that was edited rather than reworded.
+    #
+    # A published jailbreak spreads by being pasted, and what arrives is a near
+    # copy: a typo, two words inserted, different capitals, a word inflected
+    # differently, an exclamation mark added. A regexp misses all of those
+    # unless somebody widens it for each one, and every widening is spent from
+    # the same false-positive budget. Near-duplicate detection is the standard
+    # answer, and the standard measure is containment over character n-grams:
+    # how much of the known sentence is present in the text, rather than how
+    # similar the two are overall.
+    #
+    # Containment rather than Jaccard, because the case is a sentence inside a
+    # page. A wiki page with one pasted jailbreak in it is 99% ordinary prose,
+    # so overlap over union is near zero however exact the copy, and the
+    # measure that answers "is this in there" is the one that divides by the
+    # seed.
+    #
+    # Clause by clause rather than page by page, and that is not a detail. A
+    # long page accidentally contains most of the four-character n-grams of any
+    # short English sentence: measured against the benign corpus in this repo,
+    # a page of ordinary documentation scores 0.94 against a seed it does not
+    # contain, and the same corpus split into clauses scores 0.67. Containment
+    # saturates with length, so the comparison has to be against a span the
+    # size of the thing being looked for.
+    #
+    # What this does not do is judge. A clause either reproduces a sentence
+    # somebody published or it does not; there is no scoring of intent, and a
+    # novel attack in nobody's corpus scores zero here by construction.
+    class Similarity < Rail
+      # Measured on the corpora in this repo: ordinary documentation tops out
+      # at 0.67 against the nearest seed, and edited copies of the seeds bottom
+      # out at 0.83. The gap is where the threshold goes, and 0.75 is the
+      # middle of it rather than a round number picked first.
+      THRESHOLD = 0.75
+
+      # Four characters: long enough that a shingle is a fragment of a word
+      # rather than a letter pair, short enough that a typo costs four shingles
+      # instead of a whole token.
+      SHINGLE = 4
+
+      attr_reader :threshold, :seeds
+
+      def initialize(seeds: KnownAttacks::ALL, threshold: THRESHOLD, shingle: SHINGLE,
+                     name: 'similarity', sides: %i[input context])
+        super(name: name, sides: sides)
+        @threshold = threshold
+        @shingle = shingle
+        @seeds = seeds.map { |seed| [seed, NLP.shingles(seed, size: shingle)] }.freeze
+        # Every n-gram any seed contains, and the smallest number of them a
+        # clause needs before any seed can possibly clear the threshold. One
+        # intersection against this decides whether the clause is worth
+        # comparing seed by seed, and on ordinary prose it decides no. The
+        # bound is exact rather than heuristic: a clause sharing fewer grams
+        # with the union than the shortest seed needs cannot contain any seed.
+        @union = @seeds.flat_map { |(_, shingles)| shingles.to_a }.to_set.freeze
+        @floor = (threshold * @seeds.map { |(_, shingles)| shingles.size }.min).ceil
+      end
+
+      def cache_key(text, _context)
+        "#{threshold}\n#{text}"
+      end
+
+      def decide(text, _context)
+        score, seed = nearest(text)
+        return pass if score < threshold
+
+        block(categories: ['known_attack'],
+              reason: format('near copy of a known attack (%<score>.2f): %<seed>s', score: score, seed: seed))
+      end
+
+      # The closest seed and how much of it is present, for a caller that wants
+      # the number rather than the verdict.
+      def nearest(text)
+        best = [0.0, nil]
+        NLP.clauses(text).each do |clause|
+          present = NLP.shingles(clause, size: @shingle)
+          next if (present & @union).size < @floor
+
+          seeds.each do |(seed, shingles)|
+            score = NLP.containment(shingles, present)
+            best = [score, seed] if score > best.first
+          end
+        end
+        best
+      end
+    end
+  end
+end

data/lib/vangrail/rails/trajectory.rb

@@ -55,13 +55,19 @@ module Vangrail
         end
       end
 
+      def offline?
+        false
+      end
+
       # Never memoizable: the same message means different things depending on
       # what it follows.
       def cache_key(_text, _context)
         nil
       end
 
-      def call(text, context)
+      def decide(text, context)
+        return unchecked('no history was provided, so the sequence was not judged') unless context.key?(:history)
+
         turns = Array(context[:history]).last(window)
         return pass if turns.size < min_turns
 
@@ -82,13 +88,12 @@ module Vangrail
       def judge(text, turns)
         answer = chat.ask([
                             { 'role' => 'system', 'content' => policy },
-                            { 'role' => 'user', 'content' => Policies.trajectory_prompt(turns, text) }
+                            { 'role' => 'user', 'content' => Policies.trajectory_prompt(turns, text) },
                           ])
         parsed = Parsers.policy(answer.text)
         unless parsed[:decided]
-          return Result.new(status: :passed, rail: name, certain: false, model: model,
-                            latency_ms: answer.latency_ms, raw: answer.raw,
-                            reason: "unparsed judge response: #{parsed[:reason]}")
+          return unchecked("unparsed judge response: #{parsed[:reason]}",
+                           model: model, latency_ms: answer.latency_ms, raw: answer.raw)
         end
 
         return pass(model: model, latency_ms: answer.latency_ms, raw: answer.raw) unless parsed[:violated]

data/lib/vangrail/result.rb

@@ -52,8 +52,8 @@ module Vangrail
     end
 
     # No rail ran. Allowed, and explicitly not vouched for.
-    def self.unchecked(rail:, reason:)
-      new(status: :passed, rail: rail, certain: false, reason: reason)
+    def self.unchecked(rail:, reason:, **kwargs)
+      new(status: :passed, rail: rail, certain: false, reason: reason, **kwargs)
     end
 
     def passed?
@@ -99,7 +99,7 @@ module Vangrail
         'reason' => reason,
         'categories' => (categories unless categories.empty?),
         'model' => model,
-        'latency_ms' => latency_ms
+        'latency_ms' => latency_ms,
       }.compact
     end
 

data/lib/vangrail/screening.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require_relative 'origin'
+
+module Vangrail
+  # What Engine#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 cells
+      kept.map { |document| Cell.data(Cell.text_of(document)) }
+    end
+
+    def to_h
+      {
+        'kept' => kept.size,
+        'rejected' => rejected.map { |r| r[:result].to_h },
+        'certain' => certain?,
+        'reason' => reason,
+      }.compact
+    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 self.run(engine, documents, **context)
+      kept = []
+      rejected = []
+      uncertain = nil
+
+      Array(documents).each_with_index do |document, index|
+        result = engine.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
+
+      new(kept: kept, rejected: rejected, certain: uncertain.nil?, reason: uncertain&.reason)
+    end
+
+    def self.text_of(document)
+      Cell.text_of(document)
+    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 self.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
+  end
+end