vangrail 0.1.0 → 0.2.0

data/lib/vangrail.rb

@@ -4,15 +4,26 @@ require_relative 'vangrail/version'
 require_relative 'vangrail/errors'
 require_relative 'vangrail/http'
 require_relative 'vangrail/chat'
+require_relative 'vangrail/completion'
+require_relative 'vangrail/embeddings'
 require_relative 'vangrail/parsers'
 require_relative 'vangrail/prompt'
 require_relative 'vangrail/policies'
 require_relative 'vangrail/result'
 require_relative 'vangrail/result_cache'
+require_relative 'vangrail/beta'
+require_relative 'vangrail/evidence'
+require_relative 'vangrail/evidence_data'
+require_relative 'vangrail/judgement'
+require_relative 'vangrail/origin'
 require_relative 'vangrail/rail'
 require_relative 'vangrail/engine'
 require_relative 'vangrail/stream_guard'
 require_relative 'vangrail/conversation'
+require_relative 'vangrail/session'
+require_relative 'vangrail/profile'
+require_relative 'vangrail/tools'
+require_relative 'vangrail/dojo'
 require_relative 'vangrail/actions'
 require_relative 'vangrail/provider'
 require_relative 'vangrail/providers'
@@ -20,8 +31,20 @@ require_relative 'vangrail/colang/parser'
 require_relative 'vangrail/colang/interpreter'
 require_relative 'vangrail/colang/library'
 require_relative 'vangrail/confusables'
+require_relative 'vangrail/nlp'
+require_relative 'vangrail/known_attacks'
+require_relative 'vangrail/linear_model'
+require_relative 'vangrail/bayes_data'
 require_relative 'vangrail/spotlight'
 require_relative 'vangrail/rails/injected_instructions'
+require_relative 'vangrail/rails/paraphrase'
+require_relative 'vangrail/rails/alignment'
+require_relative 'vangrail/rails/language'
+require_relative 'vangrail/rails/similarity'
+require_relative 'vangrail/rails/bayes'
+require_relative 'vangrail/rails/linear'
+require_relative 'vangrail/rails/semantic'
+require_relative 'vangrail/rails/perplexity'
 require_relative 'vangrail/rails/missing'
 require_relative 'vangrail/rails/jailbreak'
 require_relative 'vangrail/rails/pattern'
@@ -30,6 +53,7 @@ require_relative 'vangrail/rails/hidden'
 require_relative 'vangrail/rails/escalation'
 require_relative 'vangrail/rails/many_shot'
 require_relative 'vangrail/rails/canary'
+require_relative 'vangrail/rails/prompt_leak'
 require_relative 'vangrail/rails/personal_data'
 require_relative 'vangrail/rails/markup'
 require_relative 'vangrail/rails/budget'
@@ -44,6 +68,7 @@ require_relative 'vangrail/rails/colang_flow'
 require_relative 'vangrail/rails/remote'
 require_relative 'vangrail/client'
 require_relative 'vangrail/config'
+require_relative 'vangrail/builder'
 
 # Guardrails for Ruby applications: input and output rails that run in the
 # calling process, with no Python service anywhere in the path.
@@ -71,6 +96,12 @@ module Vangrail
   #   GUARDRAILS_JUDGE_MODEL=<m>  instruct model for policy and grounding rails
   #   GUARDRAILS_RAILS=input,context,output,grounding,secrets,patterns,links,multiturn
   #   GUARDRAILS_CANARY=<token>   a marker in your prompt that must not come back
+  #   GUARDRAILS_PROMPT_FILE=<path>  the prompt text that must not come back out
+  #   GUARDRAILS_EMBED_MODEL=<model> an embedding model, for GUARDRAILS_RAILS=...,semantic
+  #   GUARDRAILS_SEMANTIC_THRESHOLD=<0..1>  calibrate it with script/embedding_probe.rb
+  #   GUARDRAILS_RAILS=...,perplexity  block optimised gibberish, where the
+  #                               endpoint will score a prompt it echoes
+  #   GUARDRAILS_PERPLEXITY_THRESHOLD=<nats>  calibrate it with script/perplexity_probe.rb
   #   GUARDRAILS_RAILS=...,privacy  redact a reader's own details before sending
   #   GUARDRAILS_RAILS=...,markup   strip active markup from the answer
   #   GUARDRAILS_RAILS=...,budget   refuse text too large to be a question
@@ -83,272 +114,22 @@ module Vangrail
   # With no endpoint reachable the engine keeps its offline rails and every
   # model-backed check reports passed with certain false. Nothing is quietly
   # assumed to be running.
-  def from_env(env = ENV)
-    Builder.new(env).engine
-  end
+  def from_env(env = ENV) = Builder.new(env).engine
+
+  # Same engine, carrying a posterior across turns. The prior is still
+  # required: a session that guessed the base rate would hide the same
+  # error `assess` exists to expose.
+  def session_from_env(prior:, env: ENV, **kwargs) = Builder.new(env).session(prior: prior, **kwargs)
 
   def provider(env = ENV)
     Provider.resolve(env)
   end
 
-  def engine(**kwargs)
-    Engine.new(**kwargs)
-  end
+  def engine(**kwargs) = Engine.new(**kwargs)
 
-  def config(dir)
-    Config.load(dir)
-  end
+  def config(dir) = Config.load(dir)
 
   def client(base_url:, **kwargs)
     Client.new(base_url: base_url, **kwargs)
   end
-
-  # Reads the environment into an engine. A class rather than a method so each
-  # decision is separable and testable on its own.
-  class Builder
-    DEFAULT_RAILS = %i[input context output].freeze
-    ALL_RAILS = %i[input context output grounding secrets patterns links multiturn privacy
-                   markup budget].freeze
-
-    # Deterministic input patterns, kept small on purpose. Each is a phrase
-    # whose presence is itself the violation; anything needing judgement belongs
-    # in a policy rail, where a false positive is a model's opinion rather than
-    # a hard rule.
-    INJECTION_PATTERNS = {
-      'instruction_override' => /\bignore\s+(?:all\s+|any\s+)?(?:previous|prior|above|earlier)\s+instructions?\b/i,
-      'prompt_disclosure' => /\b(?:reveal|print|repeat|show|output)\s+(?:me\s+)?(?:your|the|its)?\s*
-                              (?:system\s+prompt|initial\s+instructions|developer\s+message)\b/xi,
-      'role_reset' => /\byou\s+are\s+now\s+(?:a|an|in)\b.{0,40}\b(?:mode|persona|dan|jailbreak)\b/i
-    }.freeze
-
-    attr_reader :env
-
-    def initialize(env = ENV)
-      @env = env
-    end
-
-    def engine
-      return Engine.new(on_error: on_error, cache: cache?) if off?
-      return config_engine if config_dir
-
-      Engine.new(input: input_rails, context: context_rails, output: output_rails,
-                 on_error: on_error, cache: cache?)
-    end
-
-    def enabled
-      text = env['GUARDRAILS_RAILS'].to_s.strip
-      return DEFAULT_RAILS if text.empty?
-      return [] if off_value?(text) || text.casecmp('none').zero?
-      return ALL_RAILS.dup if text.casecmp('all').zero?
-
-      text.split(/[,\s]+/).map { |s| s.strip.downcase.to_sym } & ALL_RAILS
-    end
-
-    def on?(rail)
-      enabled.include?(rail)
-    end
-
-    def off?
-      off_value?(env['GUARDRAILS'])
-    end
-
-    def on_error
-      env['GUARDRAILS_ON_ERROR'].to_s.strip.casecmp('block').zero? ? :block : :allow
-    end
-
-    def cache?
-      !off_value?(env['GUARDRAILS_CACHE'])
-    end
-
-    def config_dir
-      present(env['GUARDRAILS_CONFIG'])
-    end
-
-    def server_url
-      present(env['GUARDRAILS_SERVER'])
-    end
-
-    # The endpoint the model-backed rails call, or nil when none is reachable.
-    def provider
-      return @provider if defined?(@provider)
-
-      @provider = Provider.resolve(env)
-    end
-
-    private
-
-    def config_engine
-      Config.load(config_dir).engine(provider: provider, on_error: on_error, cache: cache?)
-    end
-
-    # The pattern rail runs whenever any input rail does. It costs microseconds
-    # and it is the only part of the input side that still works when the
-    # endpoint is down.
-    def input_rails
-      return [] unless on?(:input) || on?(:patterns)
-
-      deterministic = [Rails::Pattern.new(patterns: INJECTION_PATTERNS, name: 'injection_patterns',
-                                          sides: [:input]),
-                       Rails::Jailbreak.new(sides: [:input]),
-                       Rails::ManyShot.new(sides: [:input])]
-      rails = deterministic + [Rails::Obfuscation.new(rails: deterministic, sides: [:input])]
-      # A question carrying the canary is too late to prevent and worth
-      # knowing: the prompt is already out.
-      rails << canary(:input) if canary_token
-      # Opt-in: it rewrites the question before the model sees it, which is a
-      # deployment's call rather than a default. Where the endpoint is a third
-      # party it is close to obligatory, and where it is a local proxy it buys
-      # little.
-      rails << Rails::PersonalData.new if on?(:privacy)
-      rails << Rails::Budget.new(sides: [:input]) if on?(:budget)
-      # Off unless asked for: they read history, and a caller that threads none
-      # would have every input check come back uncertain, which is true and
-      # useless. Conversation is what makes them worth having.
-      #
-      # The deterministic one goes first so a refused question asked again
-      # never reaches the judge: it is free, and the round trip is not.
-      rails.concat(multiturn_rails) if on?(:multiturn)
-      rails << judged(:input) if on?(:input)
-      rails.compact
-    end
-
-    # Deterministic, offline, and free, so it is on by default. The document a
-    # retrieval step just fetched is the side an attacker can usually reach
-    # without touching the application, and nothing else in this engine reads it.
-    #
-    # The decoding pass matters more here than anywhere else: a page an
-    # attacker edits is a page they can base64.
-    def context_rails
-      return [] unless on?(:context)
-
-      deterministic = [Rails::InjectedInstructions.new, Rails::Jailbreak.new(sides: [:context]),
-                       Rails::ManyShot.new(sides: [:context])]
-      # Two passes over the same definitions, for the two ways a page hides
-      # one: encoded so the patterns cannot read it, or in markup a reader
-      # never sees.
-      rails = deterministic + [Rails::Obfuscation.new(rails: deterministic, sides: [:context]),
-                               Rails::Hidden.new(rails: deterministic)]
-      rails << Rails::Budget.new(sides: [:context]) if on?(:budget)
-      rails
-    end
-
-    def output_rails
-      rails = []
-      rails << Rails::Secrets.new if on?(:secrets) || on?(:output)
-      rails << canary(:output) if canary_token
-      # Off by default: a desk whose client renders answers as plain text does
-      # not need it, and stripping markup nobody would have executed is noise
-      # in the result.
-      rails << Rails::Markup.new if on?(:markup)
-      rails << exfiltration if link_hosts || on?(:links)
-      rails << judged(:output) if on?(:output)
-      rails << grounding if on?(:grounding)
-      rails.compact
-    end
-
-    # The hosts an answer may link to. Not defaulted to anything, because the
-    # empty allowlist means "no links at all", which is right for an
-    # application that said so and wrong to impose on one that never mentioned
-    # links. Naming the variable is the opt-in.
-    def link_hosts
-      present(env['GUARDRAILS_LINK_HOSTS'])
-    end
-
-    # The pair, because they cover different halves. Escalation sees a retry
-    # after a refusal and nothing before one; the judge reads a sequence that
-    # has never been refused, which is what the published multi-turn methods
-    # are built to produce.
-    def multiturn_rails
-      rails = [Rails::Escalation.new]
-      rails << if provider&.available?
-                 Rails::Trajectory.new(provider: provider, every: judge_every)
-               else
-                 missing('trajectory', :input)
-               end
-      rails
-    end
-
-    # One round trip per turn is the honest cost, and a desk may not want to
-    # pay it every turn. A staged escalation takes several turns by
-    # construction and cannot finish inside a gap of two.
-    def judge_every
-      value = env['GUARDRAILS_TRAJECTORY_EVERY'].to_i
-      value.positive? ? value : 1
-    end
-
-    # The rail class follows what the endpoint can actually serve. A provider
-    # hosting a classifier gets one; a provider serving only instruct models
-    # gets a written policy in front of one, which is the same job done
-    # differently rather than the same job skipped.
-    def judged(side)
-      return remote(side) if server_url
-      return missing("#{side}_model", side) unless provider&.available?
-      return guard_model(side) if provider.guard?
-
-      Rails::SelfCheck.new(provider: provider, sides: [side], name: "policy_#{side}")
-    end
-
-    # Asked for and unbuildable. Kept in the list rather than dropped, so the
-    # engine's pass stays uncertain instead of resting on the offline rails.
-    #
-    # `name` is what the rail would have been; `side` is where it would have
-    # run. They are not the same thing, and conflating them is how a grounding
-    # placeholder ends up claiming a side that does not exist.
-    def missing(name, side)
-      reason =
-        if provider
-          "#{provider.name} is not available at #{provider.base_url}"
-        else
-          'no endpoint resolved: set GUARDRAILS_API_BASE, or start a local one'
-        end
-      Rails::Missing.new(reason: reason, name: name.to_s, sides: [side])
-    end
-
-    def remote(side)
-      Rails::Remote.new(base_url: server_url, config_id: present(env['GUARDRAILS_CONFIG_ID']),
-                        api_key: present(env['GUARDRAILS_SERVER_API_KEY']), sides: [side])
-    end
-
-    def guard_model(side)
-      Rails::GuardModel.new(provider: provider, reasoning: truthy?(env['GUARDRAILS_REASONING']),
-                            sides: [side])
-    end
-
-    # The application generates the token, puts it in its prompt, and names it
-    # here. Nothing can be checked without one, so its absence is the off
-    # switch.
-    def canary_token
-      present(env['GUARDRAILS_CANARY'])
-    end
-
-    def canary(side)
-      Rails::Canary.new(tokens: canary_token.split(/[,\s]+/), sides: [side])
-    end
-
-    def exfiltration
-      hosts = link_hosts.to_s.split(/[,\s]+/).reject(&:empty?)
-      images = present(env['GUARDRAILS_IMAGE_HOSTS'])
-      Rails::Exfiltration.new(allow_hosts: hosts,
-                              allow_images: images&.split(/[,\s]+/)&.reject(&:empty?))
-    end
-
-    def grounding
-      return missing('grounding', :output) unless provider&.available?
-
-      Rails::Grounding.new(provider: provider)
-    end
-
-    def off_value?(value)
-      %w[0 off false no].include?(value.to_s.strip.downcase)
-    end
-
-    def truthy?(value)
-      %w[1 on true yes].include?(value.to_s.strip.downcase)
-    end
-
-    def present(value)
-      s = value.to_s.strip
-      s.empty? ? nil : s
-    end
-  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: vangrail
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Rohit Goswami
@@ -28,9 +28,10 @@ description: |
   or blocked, and reporting whether a rail actually reached the decision.
   Deterministic rails need no network at all; model-backed ones call any
   OpenAI-compatible endpoint through a provider abstraction that prefers a
-  local proxy. Reads and writes NeMo Guardrails configuration folders and
-  executes their Colang flows in process, with an optional client for teams
-  who already run the Python server. Standard library only.
+  local proxy. Reads folders in the NeMo layout and executes a documented
+  Colang 1.0 rail-flow subset in process. A NeMo folder is not drop-in.
+  Optional client for teams who already run the Python server. Standard
+  library only.
 email:
 - rohit.goswami@surf.nl
 executables: []
@@ -41,28 +42,46 @@ files:
 - README.md
 - lib/vangrail.rb
 - lib/vangrail/actions.rb
+- lib/vangrail/assessor.rb
+- lib/vangrail/bayes_data.rb
+- lib/vangrail/beta.rb
+- lib/vangrail/builder.rb
 - lib/vangrail/chat.rb
 - lib/vangrail/client.rb
-- lib/vangrail/client/completion.rb
+- lib/vangrail/client/turn.rb
 - lib/vangrail/colang/ast.rb
 - lib/vangrail/colang/interpreter.rb
 - lib/vangrail/colang/library.rb
 - lib/vangrail/colang/parser.rb
+- lib/vangrail/colang/value_parser.rb
+- lib/vangrail/completion.rb
 - lib/vangrail/config.rb
 - lib/vangrail/confusables.rb
 - lib/vangrail/confusables_data.rb
 - lib/vangrail/conversation.rb
+- lib/vangrail/dojo.rb
+- lib/vangrail/embeddings.rb
 - lib/vangrail/engine.rb
 - lib/vangrail/errors.rb
+- lib/vangrail/evidence.rb
+- lib/vangrail/evidence_data.rb
 - lib/vangrail/http.rb
+- lib/vangrail/judgement.rb
+- lib/vangrail/known_attacks.rb
+- lib/vangrail/linear_model.rb
+- lib/vangrail/nlp.rb
+- lib/vangrail/origin.rb
 - lib/vangrail/parsers.rb
 - lib/vangrail/policies.rb
+- lib/vangrail/profile.rb
 - lib/vangrail/prompt.rb
 - lib/vangrail/provider.rb
 - lib/vangrail/providers.rb
 - lib/vangrail/providers/gateway.rb
 - lib/vangrail/providers/llmlite.rb
 - lib/vangrail/rail.rb
+- lib/vangrail/rails/alignment.rb
+- lib/vangrail/rails/bayes.rb
 - lib/vangrail/rails/budget.rb
 - lib/vangrail/rails/canary.rb
 - lib/vangrail/rails/colang_flow.rb
@@ -74,20 +93,30 @@ files:
 - lib/vangrail/rails/injected_instructions.rb
 - lib/vangrail/rails/jailbreak.rb
 - lib/vangrail/rails/known_answer.rb
+- lib/vangrail/rails/language.rb
+- lib/vangrail/rails/linear.rb
 - lib/vangrail/rails/many_shot.rb
 - lib/vangrail/rails/markup.rb
 - lib/vangrail/rails/missing.rb
 - lib/vangrail/rails/obfuscation.rb
+- lib/vangrail/rails/paraphrase.rb
 - lib/vangrail/rails/pattern.rb
+- lib/vangrail/rails/perplexity.rb
 - lib/vangrail/rails/personal_data.rb
+- lib/vangrail/rails/prompt_leak.rb
 - lib/vangrail/rails/remote.rb
 - lib/vangrail/rails/secrets.rb
 - lib/vangrail/rails/self_check.rb
+- lib/vangrail/rails/semantic.rb
+- lib/vangrail/rails/similarity.rb
 - lib/vangrail/rails/trajectory.rb
 - lib/vangrail/result.rb
 - lib/vangrail/result_cache.rb
+- lib/vangrail/screening.rb
+- lib/vangrail/session.rb
 - lib/vangrail/spotlight.rb
 - lib/vangrail/stream_guard.rb
+- lib/vangrail/tools.rb
 - lib/vangrail/version.rb
 homepage: https://github.com/HaoZeke/vangrail
 licenses: