vangrail 0.1.0 → 0.2.0

data/lib/vangrail/colang/interpreter.rb

@@ -10,62 +10,55 @@ module Vangrail
     # The mapping onto rail statuses is the whole design:
     #
     #   `bot <message>` then `stop`     -> blocked, with the message as content
-    #   assignment to $user_message or
-    #   $bot_message                    -> modified, with the new value
+    #   a change to a content binding   -> modified, with the new value
     #   falls off the end               -> passed
     #
+    # `$user_input` is a rewrite alias of `$user_message`; `$bot_response` is
+    # a rewrite alias of `$bot_message`. Input and context seed the user pair
+    # from the turn text; output seeds the bot pair. The other pair is left
+    # unset so an output flow that reads `$user_message` is not reading the
+    # answer unless the caller put it there.
+    #
     # A `stop` without a preceding `bot` still blocks; it just has no refusal
     # text to show. Actions are plain Ruby callables, so the flow decides the
     # control shape and Ruby does the work.
     class Interpreter
-      # Variables a flow assigns to when it rewrites the turn rather than
-      # refusing it, matching the names the toolkit's own flows use.
+      # The four names a flow assigns to when it rewrites the turn. Order is
+      # the last-write winner when more than one of them changed.
       CONTENT_VARS = %w[user_message bot_message user_input bot_response].freeze
 
       Outcome = Struct.new(:status, :content, :reason, :variables, keyword_init: true)
 
-      # Raised through the interpreter to unwind a flow on `stop`.
-      class Stopped < StandardError
-        attr_reader :message_text
-
-        def initialize(message_text)
-          @message_text = message_text
-          super('flow stopped')
-        end
-      end
-
       attr_reader :program, :actions
 
       def initialize(program:, actions:)
-        @program = program
+        @program = program.check!
         @actions = actions
       end
 
       def run(flow_name, context = {})
         flow = program.flow(flow_name)
-        raise UnknownAction, "no flow named #{flow_name.inspect}" unless flow
-
-        state = { 'context' => context }
-        last_bot = nil
-        begin
-          last_bot = execute(flow.body, state, context)
-        rescue Stopped => e
-          return Outcome.new(status: :blocked, content: e.message_text, reason: flow_name, variables: state)
-        end
+        raise ColangError, "no flow named #{flow_name.inspect}" unless flow
+
+        seeds = seed_bindings(context)
+        state = { 'context' => context }.merge(seeds)
+        result = execute(flow.body, state, context)
+        return stop_outcome(result.last, flow_name, state) if stop_tag?(result)
 
-        rewrite = CONTENT_VARS.filter_map { |v| state[v] if state.key?(v) }.last
+        rewrite = rewritten_content(state, seeds)
         if rewrite
           return Outcome.new(status: :modified, content: rewrite.to_s, reason: flow_name,
                              variables: state)
         end
 
-        Outcome.new(status: :passed, content: last_bot, reason: nil, variables: state)
+        Outcome.new(status: :passed, content: result, reason: nil, variables: state)
       end
 
       private
 
       # Returns the text of the last `bot` statement reached, so a flow that
-      # says something without stopping still hands that text back.
+      # says something without stopping still hands that text back. `stop`
+      # returns `[:stop, said]` rather than raising.
       def execute(body, state, context)
         said = nil
         body.each do |node|
@@ -73,14 +66,45 @@ module Vangrail
           when Assign then state[node.variable] = evaluate(node.expression, state, context)
           when Execute then evaluate(node, state, context)
           when Bot then said = bot_text(node.message)
-          when Stop then raise Stopped, said
-          when If then said = branch(node, state, context) || said
+          when Stop then return [:stop, said]
+          when If
+            result = branch(node, state, context)
+            return result if stop_tag?(result)
+
+            said = result || said
           else raise ColangError, "cannot execute #{node.class}"
           end
         end
         said
       end
 
+      def stop_tag?(result)
+        result.is_a?(Array) && result.first == :stop
+      end
+
+      def stop_outcome(content, flow_name, state)
+        Outcome.new(status: :blocked, content: content, reason: flow_name, variables: state)
+      end
+
+      def seed_bindings(context)
+        text = context[:text]
+        if context[:side] == :output
+          { 'bot_message' => text, 'bot_response' => text }
+        else
+          { 'user_message' => text, 'user_input' => text }
+        end
+      end
+
+      def rewritten_content(state, seeds)
+        rewritten = CONTENT_VARS.filter_map do |name|
+          next unless state.key?(name)
+          next if seeds.key?(name) && state[name] == seeds[name]
+
+          state[name]
+        end
+        rewritten.last
+      end
+
       def branch(node, state, context)
         taken = truthy?(evaluate(node.condition, state, context)) ? node.then_body : node.else_body
         execute(Array(taken), state, context)
@@ -107,13 +131,13 @@ module Vangrail
         action = actions[node.action]
         raise UnknownAction, "no action registered for #{node.action.inspect}" unless action
 
-        args = node.arguments.transform_values { |v| v.is_a?(Var) ? state[v.name] : v }
+        args = node.arguments.transform_values { |v| evaluate(v, state, context) }
         action.call(args, context)
       end
 
       def bot_text(message)
         alternatives = program.bot_message(message)
-        raise UnknownAction, "no `define bot #{message}` for this flow" unless alternatives
+        raise ColangError, "no `define bot #{message}` for this flow" unless alternatives
 
         # Deterministic: a guardrail refusal that varies between runs makes an
         # incident report harder to read for no benefit.

data/lib/vangrail/colang/parser.rb

@@ -2,6 +2,7 @@
 
 require_relative '../errors'
 require_relative 'ast'
+require_relative 'value_parser'
 
 module Vangrail
   module Colang
@@ -22,8 +23,13 @@ module Vangrail
     # 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.
+    # Indentation defines blocks. A tab anywhere in the indent run is refused,
+    # because a file mixing tabs and spaces would otherwise parse into a
+    # different program than it looks.
+    #
+    # Assignments, `if` conditions, and action arguments share one value
+    # grammar: string, int, and bool literals, `$vars`, `execute`, `not`, and
+    # `==` / `!=`.
     class Parser
       Line = Struct.new(:indent, :text, :number, keyword_init: true)
 
@@ -51,7 +57,8 @@ module Vangrail
       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")
+          indent_run = raw[/\A[ \t]*/]
+          raise error('tabs are not allowed in Colang indentation', number) if indent_run.include?("\t")
 
           text = raw.rstrip
           stripped = text.strip
@@ -107,10 +114,13 @@ module Vangrail
         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)),
+          [Assign.new(variable: Regexp.last_match(1), expression: value(Regexp.last_match(2), line)),
            index + 1]
-        when /\Aexecute\s+(.+)\z/
-          [action_call(Regexp.last_match(1), line), index + 1]
+        when /\Aexecute\s+/
+          node = value(line.text, line)
+          raise error("unsupported statement #{line.text.inspect}", line.number) unless node.is_a?(Execute)
+
+          [node, index + 1]
         when /\Abot\s+(.+)\z/
           [Bot.new(message: Regexp.last_match(1).strip), index + 1]
         when /\Astop\z/
@@ -127,7 +137,7 @@ module Vangrail
       end
 
       def conditional(lines, index, line, condition_text)
-        condition = condition(condition_text, line)
+        condition = value(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
@@ -137,60 +147,8 @@ module Vangrail
          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)
+      def value(text, line)
+        ValueParser.parse(text, line, method(:error))
       end
 
       def strings(lines)

data/lib/vangrail/colang/value_parser.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+require_relative 'ast'
+
+module Vangrail
+  module Colang
+    # One grammar for assign RHS, `if` conditions, and action arguments.
+    #
+    # Strings are tokenized before `==` / `!=` is considered, so
+    # `"a == b" == $x` is a compare of a literal against a variable.
+    class ValueParser
+      def self.parse(text, line, error)
+        new(text, line, error).parse
+      end
+
+      def initialize(text, line, error)
+        @text = text
+        @line = line
+        @error = error
+      end
+
+      def parse
+        tokens = tokenize
+        node, index = parse_value(tokens, 0)
+        raise fail_value(@text) unless tokens[index][0] == :eof
+
+        node
+      end
+
+      private
+
+      def tokenize
+        tokens = []
+        index = 0
+        while index < @text.length
+          if @text[index] == ' '
+            index += 1
+          else
+            token, index = next_token(index)
+            tokens << token
+          end
+        end
+        tokens << [:eof]
+        tokens
+      end
+
+      def next_token(index)
+        char = @text[index]
+        if char == '"' || char == "'"
+          read_string(index)
+        elsif char == '$' && (name = @text[(index + 1)..][/\A\w+/])
+          [[:var, name], index + 1 + name.length]
+        elsif @text[index, 2] == '=='
+          [[:eqeq, '=='], index + 2]
+        elsif @text[index, 2] == '!='
+          [[:neq, '!='], index + 2]
+        elsif char == '='
+          [[:eq, '='], index + 1]
+        elsif char == '('
+          [[:lparen], index + 1]
+        elsif char == ')'
+          [[:rparen], index + 1]
+        elsif char == ','
+          [[:comma], index + 1]
+        elsif (num = @text[index..][/\A-?\d+/])
+          [[:int, num.to_i], index + num.length]
+        elsif (word = @text[index..][/\A[\w.]+/])
+          [[:ident, word], index + word.length]
+        else
+          raise fail_value(@text)
+        end
+      end
+
+      def read_string(start)
+        quote = @text[start]
+        index = start + 1
+        while index < @text.length
+          return [[:string, unquote(@text[start..index])], index + 1] if @text[index] == quote
+
+          index += @text[index] == '\\' && index + 1 < @text.length ? 2 : 1
+        end
+        raise @error.call("unterminated string in #{@text.inspect}", @line.number)
+      end
+
+      def parse_value(tokens, index)
+        tok = tokens[index]
+        if tok[0] == :ident && tok[1] == 'not'
+          expr, index = parse_value(tokens, index + 1)
+          return [Not.new(expression: expr), index]
+        end
+
+        left, index = parse_atom(tokens, index)
+        op = tokens[index]
+        return [left, index] unless %i[eqeq neq].include?(op[0])
+
+        right, index = parse_value(tokens, index + 1)
+        [Compare.new(left: left, operator: op[1], right: right), index]
+      end
+
+      def parse_atom(tokens, index)
+        tok = tokens[index]
+        case tok[0]
+        when :string then [Literal.new(value: tok[1]), index + 1]
+        when :int then [Literal.new(value: tok[1]), index + 1]
+        when :var then [Var.new(name: tok[1]), index + 1]
+        when :ident
+          word = tok[1]
+          return parse_execute(tokens, index + 1) if word == 'execute'
+          return [Literal.new(value: true), index + 1] if %w[True true].include?(word)
+          return [Literal.new(value: false), index + 1] if %w[False false].include?(word)
+
+          raise fail_value(word)
+        else
+          raise fail_value(tok)
+        end
+      end
+
+      # execute name / execute name(key=value, ...). Positional arguments
+      # are refused: an action here is a Ruby method taking a keyword hash.
+      def parse_execute(tokens, index)
+        name_tok = tokens[index]
+        raise fail_value(name_tok) unless name_tok[0] == :ident
+
+        name = name_tok[1]
+        index += 1
+        return [Execute.new(action: name, arguments: {}), index] unless tokens[index][0] == :lparen
+
+        args, index = parse_arguments(tokens, index + 1)
+        [Execute.new(action: name, arguments: args), index]
+      end
+
+      def parse_arguments(tokens, index)
+        return [{}, index + 1] if tokens[index][0] == :rparen
+
+        args = {}
+        loop do
+          key = tokens[index]
+          unless key[0] == :ident && tokens[index + 1][0] == :eq
+            raise @error.call("argument #{key[1].inspect} needs a name", @line.number)
+          end
+
+          val, index = parse_value(tokens, index + 2)
+          args[key[1]] = val
+          case tokens[index][0]
+          when :comma then index += 1
+          when :rparen then return [args, index + 1]
+          else raise fail_value(@text)
+          end
+        end
+      end
+
+      def unquote(text)
+        text[1..-2].gsub('\\"', '"').gsub("\\'", "'")
+      end
+
+      def fail_value(what)
+        @error.call("unsupported value #{what.inspect}", @line.number)
+      end
+    end
+  end
+end

data/lib/vangrail/completion.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require_relative 'errors'
+require_relative 'http'
+
+module Vangrail
+  # The other OpenAI-compatible endpoint: /completions, asked to score text
+  # rather than to write any.
+  #
+  # It exists for one job. A chat endpoint returns what a model would say next
+  # and never says how surprising the text it was given was, and that number is
+  # what the published perplexity detectors are built on. The legacy completions
+  # endpoint answers it directly: echo the prompt, generate nothing, and return
+  # the log probability the model assigned each token of it.
+  #
+  # Support is genuinely uneven. Local servers built on llama.cpp and vLLM
+  # answer it; several hosted APIs removed the endpoint, and a proxy in front of
+  # a chat-only model cannot synthesise it. So `supported?` is a question worth
+  # asking rather than an assumption, and everything here raises ProtocolError
+  # rather than inventing a score when the fields are missing. A rail reading
+  # this turns that into an uncertain result, which is the truth: the check did
+  # not run.
+  class Completion
+    PATH = '/completions'
+
+    attr_reader :model, :http
+
+    def initialize(model:, http: nil, base_url: nil, api_key: nil,
+                   open_timeout: HTTP::DEFAULT_OPEN_TIMEOUT,
+                   read_timeout: HTTP::DEFAULT_READ_TIMEOUT)
+      @model = model
+      @http = HTTP.build(http: http, base_url: base_url, api_key: api_key,
+                         open_timeout: open_timeout, read_timeout: read_timeout,
+                         missing: 'a Completion needs a base_url or an http client')
+    end
+
+    # The log probability of each token of `text`, under this model.
+    #
+    # The first token has none, by construction: nothing preceded it. It is
+    # dropped rather than counted as zero, because zero is a log probability of
+    # one and would report the opening word as perfectly predicted.
+    def token_logprobs(text)
+      body = http.post_json(PATH, {
+                              'model' => model,
+                              'prompt' => text.to_s,
+                              'max_tokens' => 0,
+                              'echo' => true,
+                              'logprobs' => 0,
+                              'temperature' => 0,
+                            })
+      values = logprobs_in(body)
+      raise ProtocolError, 'completions endpoint returned no token logprobs' if values.empty?
+
+      values.compact
+    end
+
+    # Whether this endpoint can score at all. ProtocolError and HTTP 404 mean
+    # it cannot; TransportError means it is down, which is a different
+    # question. Asked once and kept, so a rail does not spend a scoring
+    # request on a boolean every check.
+    def supported?
+      return @supported unless @supported.nil?
+
+      @supported = token_logprobs('the quick brown fox').size > 1
+    rescue ProtocolError
+      @supported = false
+    rescue HTTPError => e
+      raise unless e.status == 404
+
+      @supported = false
+    end
+
+    private
+
+    def logprobs_in(body)
+      choices = body.is_a?(Hash) ? body['choices'] : nil
+      logprobs = choices.is_a?(Array) ? choices.dig(0, 'logprobs') : nil
+      raise ProtocolError, 'completions endpoint returned no logprobs field' unless logprobs.is_a?(Hash)
+
+      values = logprobs['token_logprobs']
+      raise ProtocolError, 'completions endpoint returned no token_logprobs array' unless values.is_a?(Array)
+
+      values.map { |value| value&.to_f }
+    end
+  end
+end

data/lib/vangrail/config.rb

@@ -4,6 +4,7 @@ require 'fileutils'
 require 'yaml'
 require_relative 'actions'
 require_relative 'chat'
+require_relative 'conversation'
 require_relative 'colang/library'
 require_relative 'colang/parser'
 require_relative 'engine'
@@ -68,7 +69,7 @@ module Vangrail
         flows: flows,
         instructions: yaml['instructions'],
         sample_conversation: yaml['sample_conversation'],
-        path: dir
+        path: dir,
       )
     end
 
@@ -85,7 +86,7 @@ module Vangrail
     def program
       @program ||= flows.reduce(Colang::Library.program) do |acc, (file, source)|
         acc.merge(Colang::Parser.parse(source, filename: "#{file}.co"))
-      end
+      end.tap(&:check!)
     end
 
     def flow_names(side)
@@ -96,12 +97,12 @@ module Vangrail
     end
 
     def prompt_for(task)
-      entry = prompts.find { |p| p['task'].to_s == task.to_s }
+      entry = prompts.detect { |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 }
+      models.detect { |m| m['type'].to_s == type.to_s }
     end
 
     # Builds the engine this configuration describes.
@@ -109,17 +110,30 @@ module Vangrail
     # `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)
+    #
+    # `stdlib:` prepends the deterministic input and context rails this gem
+    # ships (patterns, paraphrase, language posture). Off by default so a
+    # folder still describes one set of rails on either runtime; on so a
+    # folder whose judge is down still refuses a reworded injection and
+    # still refuses to call an unread language a clean pass.
+    def engine(provider: nil, chat: nil, actions: {}, on_error: :allow, cache: true, stdlib: false)
       registry = self_check_actions(provider, chat).merge(actions)
       Engine.new(
-        input: rails_for(:input, registry),
-        context: rails_for(:context, registry),
+        input: compose(:input, rails_for(:input, registry), stdlib),
+        context: compose(:context, rails_for(:context, registry), stdlib),
         output: rails_for(:output, registry),
         on_error: on_error,
-        cache: cache
+        cache: cache,
       )
     end
 
+    # Same engine, already carrying a session and an admission gate, so a
+    # retrieved page enters as data rather than as a raw string a caller
+    # might paste into the question.
+    def conversation(prior:, stdlib: true, **kwargs)
+      Conversation.new(engine(stdlib: stdlib), prior: prior, **kwargs)
+    end
+
     def rails_for(side, registry)
       flow_names(side).map do |flow_name|
         unless program.flow(flow_name)
@@ -134,6 +148,12 @@ module Vangrail
 
     private
 
+    def compose(side, flows, stdlib)
+      return flows unless stdlib
+
+      Builder.deterministic(side) + flows
+    end
+
     # 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)
@@ -153,7 +173,7 @@ module Vangrail
         policy: prompt_for(task),
         model: entry['model'],
         chat: chat,
-        provider: provider_for(entry, provider)
+        provider: provider_for(entry, provider),
       )
     end
 
@@ -195,24 +215,24 @@ module Vangrail
         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)
+          model_entry('self_check_output', judge_model, base_url),
         ],
         rails: {
           'input' => { 'flows' => ['self check input'] },
-          'output' => { 'flows' => ['self check output'] }
+          '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) }
+          { '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.'
-          }
-        ]
+                         'the question, say so.',
+          },
+        ],
       )
     end