vangrail 0.1.0

data/lib/vangrail/client/completion.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+module Vangrail
+  class Client
+    # A guardrailed chat completion, read out of either server response shape.
+    #
+    # The OpenAI-compatible shape puts the answer in choices[0].message.content
+    # and rail bookkeeping under a top-level `guardrails` object. The older shape
+    # answers with a bare {role, content} message (or a list of them) and puts
+    # bookkeeping at the top level. Both appear in the wild depending on the
+    # server version, so this reads whichever is present.
+    class Completion
+      # Server-side names for the variables holding the rail that stopped a turn.
+      INPUT_RAIL_VAR = 'triggered_input_rail'
+      OUTPUT_RAIL_VAR = 'triggered_output_rail'
+
+      attr_reader :raw
+
+      def initialize(raw)
+        @raw = raw.is_a?(Hash) ? raw : {}
+      end
+
+      def content
+        choice = choices.first
+        if choice.is_a?(Hash)
+          msg = choice['message'] || choice['delta'] || {}
+          return msg['content'].to_s if msg.is_a?(Hash) && msg.key?('content')
+        end
+        return raw['content'].to_s if raw.key?('content')
+
+        messages = raw['messages']
+        if messages.is_a?(Array)
+          last = messages.reverse.find { |m| m.is_a?(Hash) && m['role'].to_s == 'assistant' }
+          return last['content'].to_s if last
+        end
+        ''
+      end
+
+      def config_id
+        guardrails['config_id']
+      end
+
+      # The rail that stopped this turn, or nil. Reported only when the request
+      # asked for the output variables that carry it.
+      def triggered_input_rail
+        output_data[INPUT_RAIL_VAR]
+      end
+
+      def triggered_output_rail
+        output_data[OUTPUT_RAIL_VAR]
+      end
+
+      def triggered_rail
+        triggered_input_rail || triggered_output_rail
+      end
+
+      # Rails that ran, from options.log.activated_rails. Empty unless logging
+      # was requested; an empty list is not evidence that no rail ran.
+      def activated_rails
+        entries = log['activated_rails']
+        entries.is_a?(Array) ? entries : []
+      end
+
+      def stopped_rails
+        activated_rails.select { |r| r.is_a?(Hash) && r['stop'] == true }
+      end
+
+      # True when a rail is known to have stopped the turn. Absent explicit
+      # signals this stays false, so a refusal the model wrote itself is never
+      # reported as a rail decision.
+      def blocked?
+        return true unless triggered_rail.nil?
+
+        !stopped_rails.empty?
+      end
+
+      def allowed?
+        !blocked?
+      end
+
+      def model
+        raw['model']
+      end
+
+      def guardrails
+        g = raw['guardrails']
+        g.is_a?(Hash) ? g : {}
+      end
+
+      def output_data
+        d = guardrails['output_data'] || raw['output_data']
+        d.is_a?(Hash) ? d : {}
+      end
+
+      def log
+        l = guardrails['log'] || raw['log']
+        l.is_a?(Hash) ? l : {}
+      end
+
+      def llm_calls
+        calls = log['llm_calls']
+        calls.is_a?(Array) ? calls : []
+      end
+
+      # Total tokens the rails plus the answer spent, when the server reports it.
+      def total_tokens
+        usage = raw['usage']
+        return usage['total_tokens'] if usage.is_a?(Hash) && usage['total_tokens']
+
+        sums = llm_calls.filter_map { |c| c['total_tokens'] if c.is_a?(Hash) }
+        sums.empty? ? nil : sums.sum
+      end
+
+      private
+
+      def choices
+        c = raw['choices']
+        c.is_a?(Array) ? c : []
+      end
+    end
+  end
+end

data/lib/vangrail/client.rb

@@ -0,0 +1,219 @@
+# frozen_string_literal: true
+
+require_relative 'client/completion'
+require_relative 'errors'
+require_relative 'http'
+require_relative 'result'
+
+module Vangrail
+  # Interop with a NeMo Guardrails server that already exists.
+  #
+  # Nothing in this gem needs one. It is here for the case where a team already
+  # runs the Python service, wants its configs to stay the source of truth, and
+  # wants Ruby to call rather than reimplement. Reach for Config#engine first:
+  # it runs the same folder in this process with nothing to deploy.
+  #
+  # `/v1/checks` is the endpoint that matches what a rail actually wants, and it
+  # answers in the same three states this gem models: passed, modified, blocked.
+  # Older servers do not have it, so `check` falls back to a chat completion with
+  # generation switched off and reads the rail-tracking variables out of that.
+  class Client
+    CONFIGS_PATH = '/v1/rails/configs'
+    CHECKS_PATH = '/v1/checks'
+    COMPLETIONS_PATH = '/v1/chat/completions'
+    PROTOCOLS = %i[auto nested flat].freeze
+
+    RAIL_VARS = [Completion::INPUT_RAIL_VAR, Completion::OUTPUT_RAIL_VAR].freeze
+
+    attr_reader :config_id, :model, :protocol, :http
+
+    # True once /v1/checks has answered, false once it has 404ed, nil until one
+    # of those happens, so a caller can report "not yet known" honestly.
+    attr_reader :checks_supported
+
+    def initialize(base_url:, config_id: nil, model: nil, api_key: nil, protocol: :auto,
+                   open_timeout: HTTP::DEFAULT_OPEN_TIMEOUT, read_timeout: HTTP::DEFAULT_READ_TIMEOUT,
+                   http: nil)
+      unless PROTOCOLS.include?(protocol)
+        raise ArgumentError,
+              "protocol must be one of #{PROTOCOLS.join(', ')}"
+      end
+
+      @config_id = config_id
+      @model = model
+      @protocol = protocol
+      @checks_supported = nil
+      @http = http || HTTP.new(
+        base_url: base_url, api_key: api_key,
+        open_timeout: open_timeout, read_timeout: read_timeout
+      )
+    end
+
+    def base_url
+      http.base_url
+    end
+
+    def configs
+      body = http.get_json(CONFIGS_PATH)
+      list = body.is_a?(Array) ? body : Array(body['configs'])
+      list.filter_map { |entry| entry.is_a?(Hash) ? entry['id'] : entry.to_s }
+    end
+
+    def available?
+      http.reachable?(CONFIGS_PATH)
+    end
+
+    def check_input(text, config_id: nil)
+      check([{ 'role' => 'user', 'content' => text.to_s }], rail: :input, config_id: config_id)
+    end
+
+    def check_output(text, user_input: nil, config_id: nil)
+      messages = []
+      messages << { 'role' => 'user', 'content' => user_input.to_s } unless user_input.to_s.strip.empty?
+      messages << { 'role' => 'assistant', 'content' => text.to_s }
+      check(messages, rail: :output, config_id: config_id)
+    end
+
+    # Runs rails without generation and returns a Result.
+    def check(messages, rail:, config_id: nil)
+      chosen = config_id || @config_id
+      if @checks_supported != false
+        begin
+          return from_checks(http.post_json(CHECKS_PATH, checks_payload(messages, rail, chosen)), rail)
+        rescue HTTPError => e
+          raise unless e.status == 404
+
+          @checks_supported = false
+        end
+      end
+      from_completion(chat(messages: messages, config_id: chosen, options: check_options(rail)), rail)
+    end
+
+    # A full guardrailed completion, for the case where the server generates the
+    # answer as well as checking it.
+    def chat(messages:, config_id: nil, config_ids: nil, options: nil, context: nil,
+             thread_id: nil, model: nil, **extra)
+      opts = merge_options(options)
+      body = extra.merge(messages: normalize(messages))
+      chosen = { config_id: config_id || @config_id, config_ids: config_ids }
+      Completion.new(send_payload(body, chosen, opts, context, thread_id, model))
+    end
+
+    private
+
+    def checks_payload(messages, rail, config_id)
+      payload = { 'messages' => normalize(messages), 'rail_types' => [rail.to_s] }
+      payload['config_id'] = config_id if config_id
+      payload
+    end
+
+    # {"status": "passed"|"modified"|"blocked", "content": "...", "rail": "..."}
+    def from_checks(body, rail)
+      @checks_supported = true
+      status = body['status'].to_s
+      unless Result::STATUSES.map(&:to_s).include?(status)
+        raise ProtocolError, "/v1/checks answered status #{status.inspect}"
+      end
+
+      Result.new(status: status.to_sym, rail: body['rail'] || rail.to_s,
+                 content: body['content'], raw: body)
+    end
+
+    def from_completion(completion, rail)
+      return Result.passed(rail: rail.to_s, raw: completion.raw) if completion.allowed?
+
+      reason = completion.triggered_rail || completion.stopped_rails.first&.dig('name')
+      Result.blocked(rail: reason || rail.to_s, content: completion.content, reason: reason,
+                     raw: completion.raw)
+    end
+
+    def check_options(rail)
+      { 'rails' => { 'input' => rail == :input, 'output' => rail == :output, 'dialog' => false } }
+    end
+
+    def merge_options(options)
+      base = { 'output_vars' => RAIL_VARS.dup, 'log' => { 'activated_rails' => true } }
+      return base unless options.is_a?(Hash)
+
+      stringified = deep_stringify(options)
+      merged = base.merge(stringified)
+      merged['output_vars'] = (RAIL_VARS + Array(stringified['output_vars'])).uniq
+      merged['log'] = base['log'].merge(stringified['log']) if stringified['log'].is_a?(Hash)
+      merged
+    end
+
+    def send_payload(body, chosen, opts, context, thread_id, model)
+      case protocol
+      when :flat
+        http.post_json(COMPLETIONS_PATH, flat_payload(body, chosen, opts, context, thread_id, model))
+      when :nested
+        http.post_json(COMPLETIONS_PATH, nested_payload(body, chosen, opts, context, thread_id, model))
+      else
+        try_nested_then_flat(body, chosen, opts, context, thread_id, model)
+      end
+    end
+
+    def try_nested_then_flat(body, chosen, opts, context, thread_id, model)
+      answer = http.post_json(COMPLETIONS_PATH, nested_payload(body, chosen, opts, context, thread_id, model))
+      @protocol = :nested
+      answer
+    rescue HTTPError => e
+      raise unless schema_rejection?(e)
+
+      answer = http.post_json(COMPLETIONS_PATH, flat_payload(body, chosen, opts, context, thread_id, model))
+      @protocol = :flat
+      answer
+    end
+
+    # A 400/422 naming a field is the server saying it speaks the other shape.
+    # Any other status is a real failure and stays raised.
+    def schema_rejection?(error)
+      return false unless [400, 422].include?(error.status)
+
+      error.body.match?(/extra fields not permitted|unexpected keyword|field required|guardrails|config_id/i)
+    end
+
+    def nested_payload(body, chosen, opts, context, thread_id, model)
+      guardrails = {}
+      guardrails['config_id'] = chosen[:config_id] if chosen[:config_id]
+      guardrails['config_ids'] = Array(chosen[:config_ids]) if chosen[:config_ids]
+      guardrails['options'] = opts if opts
+      guardrails['context'] = deep_stringify(context) if context
+      guardrails['thread_id'] = thread_id if thread_id
+
+      payload = body.transform_keys(&:to_s)
+      payload['model'] = model || @model if model || @model
+      payload['guardrails'] = guardrails unless guardrails.empty?
+      payload
+    end
+
+    def flat_payload(body, chosen, opts, context, thread_id, model)
+      payload = body.transform_keys(&:to_s)
+      payload['config_id'] = chosen[:config_id] if chosen[:config_id]
+      payload['config_ids'] = Array(chosen[:config_ids]) if chosen[:config_ids]
+      payload['options'] = opts if opts
+      payload['context'] = deep_stringify(context) if context
+      payload['thread_id'] = thread_id if thread_id
+      payload['model'] = model || @model if model || @model
+      payload
+    end
+
+    def normalize(messages)
+      Array(messages).map do |m|
+        if m.is_a?(Hash)
+          { 'role' => (m['role'] || m[:role]).to_s, 'content' => (m['content'] || m[:content]).to_s }
+        else
+          { 'role' => 'user', 'content' => m.to_s }
+        end
+      end
+    end
+
+    def deep_stringify(value)
+      case value
+      when Hash then value.to_h { |k, v| [k.to_s, deep_stringify(v)] }
+      when Array then value.map { |v| deep_stringify(v) }
+      else value
+      end
+    end
+  end
+end

data/lib/vangrail/colang/ast.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Vangrail
+  module Colang
+    # The whole grammar this gem executes, as data. Everything the parser can
+    # produce is one of these, which is also the honest statement of what a
+    # Colang file may contain here: anything else is refused at parse time
+    # rather than skipped at run time.
+    Program = Struct.new(:flows, :bot_messages, :user_messages, keyword_init: true) do
+      def flow(name)
+        flows[name.to_s]
+      end
+
+      def flow_names
+        flows.keys
+      end
+
+      def bot_message(name)
+        bot_messages[name.to_s]
+      end
+
+      def merge(other)
+        Program.new(
+          flows: flows.merge(other.flows),
+          bot_messages: bot_messages.merge(other.bot_messages),
+          user_messages: user_messages.merge(other.user_messages)
+        )
+      end
+    end
+
+    Flow = Struct.new(:name, :body, :subflow, keyword_init: true)
+
+    # $var = execute action(key="value")
+    Assign = Struct.new(:variable, :expression, keyword_init: true)
+
+    # execute action(key="value")
+    Execute = Struct.new(:action, :arguments, keyword_init: true)
+
+    # bot <message name>
+    Bot = Struct.new(:message, keyword_init: true)
+
+    # stop
+    Stop = Struct.new(:reason, keyword_init: true)
+
+    If = Struct.new(:condition, :then_body, :else_body, keyword_init: true)
+
+    # Conditions
+    Var = Struct.new(:name, keyword_init: true)
+    Not = Struct.new(:expression, keyword_init: true)
+    Compare = Struct.new(:left, :operator, :right, keyword_init: true)
+    Literal = Struct.new(:value, keyword_init: true)
+  end
+end

data/lib/vangrail/colang/interpreter.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+require_relative '../errors'
+require_relative 'ast'
+
+module Vangrail
+  module Colang
+    # Runs one flow and reports what it decided.
+    #
+    # 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
+    #   falls off the end               -> passed
+    #
+    # 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.
+      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
+        @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
+
+        rewrite = CONTENT_VARS.filter_map { |v| state[v] if state.key?(v) }.last
+        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)
+      end
+
+      private
+
+      # Returns the text of the last `bot` statement reached, so a flow that
+      # says something without stopping still hands that text back.
+      def execute(body, state, context)
+        said = nil
+        body.each do |node|
+          case node
+          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
+          else raise ColangError, "cannot execute #{node.class}"
+          end
+        end
+        said
+      end
+
+      def branch(node, state, context)
+        taken = truthy?(evaluate(node.condition, state, context)) ? node.then_body : node.else_body
+        execute(Array(taken), state, context)
+      end
+
+      def evaluate(node, state, context)
+        case node
+        when Execute then call_action(node, state, context)
+        when Var then state[node.name]
+        when Literal then node.value
+        when Not then !truthy?(evaluate(node.expression, state, context))
+        when Compare then compare(node, state, context)
+        else node
+        end
+      end
+
+      def compare(node, state, context)
+        left = evaluate(node.left, state, context)
+        right = evaluate(node.right, state, context)
+        node.operator == '==' ? left == right : left != right
+      end
+
+      def call_action(node, state, context)
+        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 }
+        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
+
+        # Deterministic: a guardrail refusal that varies between runs makes an
+        # incident report harder to read for no benefit.
+        alternatives.first
+      end
+
+      def truthy?(value)
+        return false if value.nil? || value == false
+        return false if value.respond_to?(:empty?) && value.empty?
+
+        true
+      end
+    end
+  end
+end

data/lib/vangrail/colang/library.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require_relative 'parser'
+
+module Vangrail
+  module Colang
+    # The flows a configuration can name without defining.
+    #
+    # A config folder that lists `self check input` under `rails.input.flows`
+    # and ships no `.co` file is the ordinary case: those flows are built into
+    # the toolkit. They are written out here as Colang rather than hand-built
+    # AST, so the parser this gem ships is the same one that reads them, and a
+    # bug in it fails loudly on the built-ins instead of hiding until someone
+    # writes their own flow.
+    module Library
+      SOURCE = <<~COLANG
+        define flow self check input
+          $allowed = execute self_check_input
+          if not $allowed
+            bot refuse to respond
+            stop
+
+        define flow self check output
+          $allowed = execute self_check_output
+          if not $allowed
+            bot refuse to respond
+            stop
+
+        define flow self check facts
+          $accurate = execute self_check_facts
+          if not $accurate
+            bot inform answer unknown
+            stop
+
+        define bot refuse to respond
+          "I'm sorry, I can't respond to that."
+
+        define bot inform answer unknown
+          "I don't know the answer to that."
+      COLANG
+
+      module_function
+
+      def program
+        @program ||= Parser.parse(SOURCE, filename: 'built-in')
+      end
+
+      def flow_names
+        program.flow_names
+      end
+    end
+  end
+end