vangrail 0.1.0

data/lib/vangrail/colang/parser.rb

@@ -0,0 +1,222 @@
+# frozen_string_literal: true
+
+require_relative '../errors'
+require_relative 'ast'
+
+module Vangrail
+  module Colang
+    # Reads the Colang 1.0 subset that rail flows are written in.
+    #
+    #   define flow self check input
+    #     $allowed = execute self_check_input
+    #     if not $allowed
+    #       bot refuse to respond
+    #       stop
+    #
+    #   define bot refuse to respond
+    #     "I'm sorry, I can't respond to that."
+    #
+    # That subset covers the input and output rails that ship with the toolkit
+    # and the ones people write. Dialog flows with user-intent matching are not
+    # supported, and a file using them raises rather than loading with the
+    # matching quietly missing: a guardrail that half-loads is a guardrail that
+    # reports checks it is not running.
+    #
+    # Indentation defines blocks. Tabs are refused, because a file mixing tabs
+    # and spaces would otherwise parse into a different program than it looks.
+    class Parser
+      Line = Struct.new(:indent, :text, :number, keyword_init: true)
+
+      def self.parse(source, filename: nil)
+        new(source, filename: filename).parse
+      end
+
+      def initialize(source, filename: nil)
+        @source = source.to_s
+        @filename = filename
+        @flows = {}
+        @bot_messages = {}
+        @user_messages = {}
+      end
+
+      def parse
+        lines = significant_lines
+        index = 0
+        index = definition(lines, index) while index < lines.length
+        Program.new(flows: @flows, bot_messages: @bot_messages, user_messages: @user_messages)
+      end
+
+      private
+
+      def significant_lines
+        @source.lines.each_with_index.filter_map do |raw, i|
+          number = i + 1
+          raise error('tabs are not allowed in Colang indentation', number) if raw.start_with?("\t")
+
+          text = raw.rstrip
+          stripped = text.strip
+          next if stripped.empty? || stripped.start_with?('#')
+
+          Line.new(indent: text[/\A */].length, text: stripped, number: number)
+        end
+      end
+
+      # One `define ...` header plus everything indented under it.
+      def definition(lines, index)
+        header = lines[index]
+        raise error("expected a `define` block, got #{header.text.inspect}", header.number) unless
+          header.text.start_with?('define ')
+
+        body, next_index = block(lines, index + 1, header.indent)
+        case header.text
+        when /\Adefine (flow|subflow)\s+(.+)\z/
+          name = Regexp.last_match(2).strip
+          @flows[name] =
+            Flow.new(name: name, body: statements(body), subflow: Regexp.last_match(1) == 'subflow')
+        when /\Adefine bot\s+(.+)\z/
+          @bot_messages[Regexp.last_match(1).strip] = strings(body)
+        when /\Adefine user\s+(.+)\z/
+          @user_messages[Regexp.last_match(1).strip] = strings(body)
+        else
+          raise error("unsupported definition #{header.text.inspect}", header.number)
+        end
+        next_index
+      end
+
+      # Every line indented deeper than `indent`, and where to resume.
+      def block(lines, index, indent)
+        body = []
+        while index < lines.length && lines[index].indent > indent
+          body << lines[index]
+          index += 1
+        end
+        [body, index]
+      end
+
+      def statements(lines)
+        result = []
+        index = 0
+        while index < lines.length
+          statement, index = statement(lines, index)
+          result << statement
+        end
+        result
+      end
+
+      def statement(lines, index)
+        line = lines[index]
+        case line.text
+        when /\A\$(\w+)\s*=\s*(.+)\z/
+          [Assign.new(variable: Regexp.last_match(1), expression: expression(Regexp.last_match(2), line)),
+           index + 1]
+        when /\Aexecute\s+(.+)\z/
+          [action_call(Regexp.last_match(1), line), index + 1]
+        when /\Abot\s+(.+)\z/
+          [Bot.new(message: Regexp.last_match(1).strip), index + 1]
+        when /\Astop\z/
+          [Stop.new(reason: nil), index + 1]
+        when /\Aif\s+(.+)\z/
+          # $~ is frame-local, so the captured condition is passed rather than
+          # read again inside the callee.
+          conditional(lines, index, line, Regexp.last_match(1))
+        when /\Aelse\z/
+          raise error('`else` without a matching `if`', line.number)
+        else
+          raise error("unsupported statement #{line.text.inspect}", line.number)
+        end
+      end
+
+      def conditional(lines, index, line, condition_text)
+        condition = condition(condition_text, line)
+        then_lines, index = block(lines, index + 1, line.indent)
+        else_lines = []
+        if index < lines.length && lines[index].text == 'else' && lines[index].indent == line.indent
+          else_lines, index = block(lines, index + 1, lines[index].indent)
+        end
+        [If.new(condition: condition, then_body: statements(then_lines), else_body: statements(else_lines)),
+         index]
+      end
+
+      def expression(text, line)
+        return action_call(Regexp.last_match(1), line) if text =~ /\Aexecute\s+(.+)\z/
+        return Literal.new(value: unquote(text)) if quoted?(text)
+        return Var.new(name: Regexp.last_match(1)) if text =~ /\A\$(\w+)\z/
+
+        raise error("unsupported expression #{text.inspect}", line.number)
+      end
+
+      def action_call(text, line)
+        name, args = text.match(/\A([\w.]+)\s*(?:\((.*)\))?\s*\z/)&.captures
+        raise error("unsupported action call #{text.inspect}", line.number) unless name
+
+        Execute.new(action: name, arguments: arguments(args, line))
+      end
+
+      # key="value", key=$var, key=42. Positional arguments are refused: an
+      # action here is a Ruby method taking a keyword hash.
+      def arguments(text, line)
+        return {} if text.nil? || text.strip.empty?
+
+        text.split(/,(?=(?:[^"]*"[^"]*")*[^"]*\z)/).to_h do |pair|
+          key, value = pair.split('=', 2).map { |s| s.to_s.strip }
+          raise error("argument #{pair.inspect} needs a name", line.number) if value.nil? || key.empty?
+
+          [key, argument_value(value, line)]
+        end
+      end
+
+      def argument_value(value, line)
+        return unquote(value) if quoted?(value)
+        return Var.new(name: Regexp.last_match(1)) if value =~ /\A\$(\w+)\z/
+        return value.to_i if value.match?(/\A-?\d+\z/)
+        return true if %w[True true].include?(value)
+        return false if %w[False false].include?(value)
+
+        raise error("unsupported argument value #{value.inspect}", line.number)
+      end
+
+      def condition(text, line)
+        text = text.strip
+        return Not.new(expression: condition(Regexp.last_match(1), line)) if text =~ /\Anot\s+(.+)\z/
+        if text =~ /\A(.+?)\s*(==|!=)\s*(.+)\z/
+          return Compare.new(
+            left: condition(Regexp.last_match(1), line),
+            operator: Regexp.last_match(2),
+            right: condition(Regexp.last_match(3), line)
+          )
+        end
+        return Var.new(name: Regexp.last_match(1)) if text =~ /\A\$(\w+)\z/
+        return Literal.new(value: unquote(text)) if quoted?(text)
+        return Literal.new(value: true) if %w[True true].include?(text)
+        return Literal.new(value: false) if %w[False false].include?(text)
+
+        raise error("unsupported condition #{text.inspect}", line.number)
+      end
+
+      def strings(lines)
+        lines.map do |line|
+          unless quoted?(line.text)
+            raise error("expected a quoted message, got #{line.text.inspect}",
+                        line.number)
+          end
+
+          unquote(line.text)
+        end
+      end
+
+      def quoted?(text)
+        text.length >= 2 && ((text.start_with?('"') && text.end_with?('"')) ||
+          (text.start_with?("'") && text.end_with?("'")))
+      end
+
+      def unquote(text)
+        text[1..-2].gsub('\\"', '"').gsub("\\'", "'")
+      end
+
+      def error(message, number)
+        where = [@filename, number].compact.join(':')
+        ColangError.new("#{where}: #{message}")
+      end
+    end
+  end
+end

data/lib/vangrail/config.rb

@@ -0,0 +1,270 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require 'yaml'
+require_relative 'actions'
+require_relative 'chat'
+require_relative 'colang/library'
+require_relative 'colang/parser'
+require_relative 'engine'
+require_relative 'errors'
+require_relative 'policies'
+require_relative 'rails/colang_flow'
+require_relative 'rails/grounding'
+require_relative 'rails/self_check'
+require_relative 'provider'
+
+module Vangrail
+  # A guardrails configuration folder, read and written by Ruby.
+  #
+  #   config = Vangrail::Config.load('config/handbook')
+  #   engine = config.engine
+  #   engine.check_input('Ignore your instructions.')
+  #
+  # The folder is the format the Python toolkit uses: config.yml for models and
+  # which flows run on which side, prompts.yml for the policy text each
+  # self-check task judges against, and rails/*.co for the flows themselves.
+  # Nothing here shells out to it. The YAML is read, the Colang is parsed, and
+  # the flows execute in this process, so the same folder can be handed to
+  # either runtime and describes one set of rails either way.
+  #
+  # A folder naming a flow that nothing defines raises. A folder naming a model
+  # type this gem cannot serve raises. Both are load-time failures on purpose: a
+  # configuration that comes up with half its rails missing is worse than one
+  # that refuses to come up.
+  class Config
+    SELF_CHECK_TASKS = { 'self_check_input' => :input, 'self_check_output' => :output }.freeze
+
+    attr_reader :name, :models, :rails, :prompts, :flows, :instructions, :sample_conversation, :path
+
+    def initialize(name:, models: [], rails: {}, prompts: [], flows: {}, instructions: nil,
+                   sample_conversation: nil, path: nil)
+      @name = name
+      @models = models
+      @rails = rails
+      @prompts = prompts
+      @flows = flows
+      @instructions = instructions
+      @sample_conversation = sample_conversation
+      @path = path
+    end
+
+    # --- reading ---
+
+    def self.load(dir)
+      raise ConfigError, "no configuration folder at #{dir}" unless File.directory?(dir)
+
+      yaml = load_yaml(File.join(dir, 'config.yml')) || load_yaml(File.join(dir, 'config.yaml')) || {}
+      prompts = Array((load_yaml(File.join(dir, 'prompts.yml')) || {})['prompts'])
+      flows = Dir[File.join(dir, '**', '*.co')].to_h do |file|
+        [File.basename(file, '.co'), File.read(file)]
+      end
+
+      new(
+        name: File.basename(dir),
+        models: Array(yaml['models']),
+        rails: yaml['rails'] || {},
+        prompts: prompts,
+        flows: flows,
+        instructions: yaml['instructions'],
+        sample_conversation: yaml['sample_conversation'],
+        path: dir
+      )
+    end
+
+    def self.load_yaml(file)
+      return nil unless File.file?(file)
+
+      YAML.safe_load_file(file, aliases: true)
+    end
+
+    # --- running ---
+
+    # Every flow this configuration can execute: the ones it ships plus the
+    # built-ins it is allowed to name without defining.
+    def program
+      @program ||= flows.reduce(Colang::Library.program) do |acc, (file, source)|
+        acc.merge(Colang::Parser.parse(source, filename: "#{file}.co"))
+      end
+    end
+
+    def flow_names(side)
+      keys = [side.to_s]
+      # NeMo names the retrieved-document side `retrieval`. That is :context.
+      keys << 'retrieval' if side.to_sym == :context
+      keys.flat_map { |key| Array(rails.dig(key, 'flows')) }.map(&:to_s).uniq
+    end
+
+    def prompt_for(task)
+      entry = prompts.find { |p| p['task'].to_s == task.to_s }
+      entry && entry['content'].to_s
+    end
+
+    def model_for(type)
+      models.find { |m| m['type'].to_s == type.to_s }
+    end
+
+    # Builds the engine this configuration describes.
+    #
+    # `chat:` overrides where model-backed actions call, which is what tests and
+    # a caller with its own client pass. `actions:` adds or replaces actions by
+    # name, so a team's own check joins the built-ins without touching the gem.
+    def engine(provider: nil, chat: nil, actions: {}, on_error: :allow, cache: true)
+      registry = self_check_actions(provider, chat).merge(actions)
+      Engine.new(
+        input: rails_for(:input, registry),
+        context: rails_for(:context, registry),
+        output: rails_for(:output, registry),
+        on_error: on_error,
+        cache: cache
+      )
+    end
+
+    def rails_for(side, registry)
+      flow_names(side).map do |flow_name|
+        unless program.flow(flow_name)
+          raise ConfigError,
+                "#{name}: rails.#{side}.flows names #{flow_name.inspect}, which no .co file defines " \
+                "and which is not built in (#{Colang::Library.flow_names.join(', ')})"
+        end
+
+        Rails::ColangFlow.new(flow_name: flow_name, program: program, actions: registry, sides: [side])
+      end
+    end
+
+    private
+
+    # The three tasks a stock configuration expects, each backed by a rail this
+    # gem implements. A configuration that names none of them gets none of them.
+    def self_check_actions(provider, chat)
+      input = self_check_rail('self_check_input', :input, provider, chat)
+      output = self_check_rail('self_check_output', :output, provider, chat)
+      facts = grounding_rail(provider, chat)
+      Actions.from_rails(input: input, output: output, facts: facts)
+    end
+
+    def self_check_rail(task, side, provider, chat)
+      entry = model_for(task) || model_for('main')
+      return nil unless entry
+
+      Rails::SelfCheck.new(
+        name: task,
+        sides: [side],
+        policy: prompt_for(task),
+        model: entry['model'],
+        chat: chat,
+        provider: provider_for(entry, provider)
+      )
+    end
+
+    def grounding_rail(provider, chat)
+      entry = model_for('self_check_facts') || model_for('main')
+      return nil unless entry
+
+      Rails::Grounding.new(model: entry['model'], chat: chat, provider: provider_for(entry, provider))
+    end
+
+    # A model entry names its own endpoint through `parameters.base_url`, which
+    # is how the configuration format points at an OpenAI-compatible gateway.
+    # That wins over the caller's provider, because the folder is the thing
+    # under version control and the provider is ambient.
+    def provider_for(entry, provider)
+      base = entry.dig('parameters', 'base_url')
+      return provider if base.nil? || base.to_s.strip.empty?
+      return provider if provider && provider.base_url == base.to_s.sub(/\/+\z/, '')
+
+      key = provider&.api_key
+      Provider.new(name: entry['type'].to_s, base_url: base, models: { judge: entry['model'] },
+                   key_resolver: key ? -> { key } : nil)
+    end
+
+    public
+
+    # --- writing ---
+
+    # A starting configuration for a provider. `engine: openai` with a base_url
+    # parameter is how the format names an OpenAI-compatible gateway, and this
+    # gem reads that field the same way, so one folder serves both runtimes.
+    def self.for_provider(provider, name: 'handbook', main_model: nil, judge_model: nil,
+                          subject: 'a public documentation handbook')
+      base_url = provider.base_url
+      main_model ||= provider.model(:judge)
+      judge_model ||= provider.model(:judge)
+      new(
+        name: name,
+        models: [
+          model_entry('main', main_model, base_url),
+          model_entry('self_check_input', judge_model, base_url),
+          model_entry('self_check_output', judge_model, base_url)
+        ],
+        rails: {
+          'input' => { 'flows' => ['self check input'] },
+          'output' => { 'flows' => ['self check output'] }
+        },
+        prompts: [
+          { 'task' => 'self_check_input', 'content' => self_check_prompt(:input, subject) },
+          { 'task' => 'self_check_output', 'content' => self_check_prompt(:output, subject) }
+        ],
+        instructions: [
+          {
+            'type' => 'general',
+            'content' => "You answer questions about #{subject}. Every factual clause " \
+                         'comes from a supplied passage. Where the passages do not cover ' \
+                         'the question, say so.'
+          }
+        ]
+      )
+    end
+
+    def self.model_entry(type, model, base_url)
+      { 'type' => type, 'engine' => 'openai', 'model' => model, 'parameters' => { 'base_url' => base_url } }
+    end
+
+    # The self-check tasks read a Yes/No answer, so the policy is rendered as a
+    # question rather than with the JSON contract a policy judge uses.
+    def self.self_check_prompt(rail, subject)
+      policy = rail == :input ? Policies.input_policy(subject: subject) : Policies.output_policy(subject: subject)
+      body = policy.sub(Policies::ANSWER_CONTRACT, '').rstrip
+      slot = rail == :input ? '{{ user_input }}' : '{{ bot_response }}'
+      label = rail == :input ? 'User message' : 'Bot message'
+      <<~TXT
+        #{body}
+
+        #{label}: "#{slot}"
+
+        Question: Should the message be blocked (Yes or No)?
+        Answer:
+      TXT
+    end
+
+    def to_h
+      h = {}
+      h['models'] = models unless models.empty?
+      h['instructions'] = instructions if instructions
+      h['rails'] = rails unless rails.empty?
+      h['sample_conversation'] = sample_conversation if sample_conversation
+      h
+    end
+
+    def config_yaml
+      YAML.dump(to_h)
+    end
+
+    def prompts_yaml
+      YAML.dump('prompts' => prompts)
+    end
+
+    # Writes <root>/<name>/. Returns the directory it wrote.
+    def write!(root)
+      dir = File.join(root, name)
+      FileUtils.mkdir_p(dir)
+      File.write(File.join(dir, 'config.yml'), config_yaml)
+      File.write(File.join(dir, 'prompts.yml'), prompts_yaml) unless prompts.empty?
+      unless flows.empty?
+        FileUtils.mkdir_p(File.join(dir, 'rails'))
+        flows.each { |file, colang| File.write(File.join(dir, 'rails', "#{file}.co"), colang.to_s) }
+      end
+      dir
+    end
+  end
+end

data/lib/vangrail/confusables.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require_relative 'confusables_data'
+
+module Vangrail
+  # Folds characters that imitate ASCII back to the ASCII they imitate.
+  #
+  # The data is generated from the Unicode confusables file (UTS #39) and lives
+  # in confusables_data.rb. This is the policy that uses it, kept apart so
+  # regenerating the table cannot overwrite a decision.
+  #
+  # The decision worth writing down is which words to fold. Folding everything
+  # turns a page of Russian into ASCII noise: "Кластер" becomes "Kлacтep",
+  # which is not Russian, not English, and not what anybody wrote. It happens
+  # to be harmless here, because a folded variant is only ever shown to a
+  # pattern and never to a reader, but it is the wrong thing to be doing and it
+  # widens the surface for an accidental match.
+  #
+  # What an imitation attack actually looks like is a *mixed* word: Latin
+  # letters with one or two lookalikes dropped in, so that "system" reads as
+  # "system" and is not. A word written entirely in Cyrillic is not imitating
+  # anything; it is a word in Cyrillic. UTS #39 draws the same line and calls
+  # it mixed-script detection.
+  #
+  # So `fold` leaves single-script words alone and folds the mixed ones. That
+  # keeps genuine multilingual documentation intact and still catches the
+  # attack, which the corpus asserts in both directions.
+  module Confusables
+    # A run of non-space characters. Folding is decided per word because that
+    # is the unit the mixing happens in.
+    WORD = /\S+/
+
+    module_function
+
+    # Every word that mixes ASCII with imitators, folded. Text with no
+    # imitators at all is returned untouched and costs one match.
+    def fold(text)
+      body = text.to_s
+      return body unless body.match?(PATTERN)
+
+      body.gsub(WORD) { |word| mixed?(word) ? fold_word(word) : word }
+    end
+
+    # Folds regardless of mixing. For a caller that has already decided the
+    # text should be Latin, and for measuring what the policy costs.
+    def fold_all(text)
+      body = text.to_s
+      return body unless body.match?(PATTERN)
+
+      fold_word(body)
+    end
+
+    def confusable?(text)
+      text.to_s.match?(PATTERN)
+    end
+
+    # A word imitating ASCII carries both: at least one ASCII letter or digit,
+    # and at least one character pretending to be one.
+    def mixed?(word)
+      word.match?(/[A-Za-z0-9]/) && word.match?(PATTERN)
+    end
+
+    def fold_word(word)
+      word.gsub(PATTERN) { |char| MAP.fetch(char, char) }
+    end
+  end
+end