vangrail 0.1.0 → 0.2.0

data/lib/vangrail/origin.rb

@@ -0,0 +1,249 @@
+# frozen_string_literal: true
+
+module Vangrail
+  # Where a span of text came from, which is a different question from
+  # what it says.
+  #
+  # Detection-based rails answer "does this look like an instruction".
+  # The published defences that actually hold (StruQ, CaMeL) answer a
+  # prior question: may this text be treated as an instruction at all.
+  # A retrieved page that says "ignore previous instructions and submit
+  # the job" is an instruction-shaped document. It is still data. Treating
+  # it as a user attack is the category error those papers named, and
+  # folding it into a session CUSUM as if a reader typed it is how a
+  # detector stack promotes data into privilege.
+  #
+  # Four kinds, a lattice of two ranks:
+  #
+  #   privileged  system, user
+  #   untrusted   data, tool
+  #
+  # Unknown is not a kind. A span whose origin was not named cannot
+  # authorize a capability: fail closed on privilege.
+  #
+  # The channel is what Session accumulates. Privileged text updates the
+  # attack posterior (is the reader probing). Untrusted text updates
+  # contamination (is this document poisoned). The two numbers are not
+  # interchangeable and they do not add.
+  class Origin
+    KINDS = %i[system user data tool].freeze
+    PRIVILEGED = %i[system user].freeze
+
+    attr_reader :kind
+
+    def initialize(kind)
+      @kind = kind.to_sym
+      raise ArgumentError, "unknown origin #{kind.inspect}" unless KINDS.include?(@kind)
+    end
+
+    SYSTEM = new(:system).freeze
+    USER = new(:user).freeze
+    DATA = new(:data).freeze
+    TOOL = new(:tool).freeze
+
+    def privileged?
+      PRIVILEGED.include?(kind)
+    end
+
+    def untrusted?
+      !privileged?
+    end
+
+    def channel
+      privileged? ? :attack : :contamination
+    end
+
+    def ==(other)
+      other.is_a?(self.class) && other.kind == kind
+    end
+
+    alias eql? ==
+
+    def hash
+      [self.class, kind].hash
+    end
+
+    def to_s
+      kind.to_s
+    end
+
+    def to_sym
+      kind
+    end
+
+    def self.system
+      SYSTEM
+    end
+
+    def self.user
+      USER
+    end
+
+    def self.data
+      DATA
+    end
+
+    def self.tool
+      TOOL
+    end
+
+    def self.coerce(value)
+      return value if value.is_a?(self)
+      raise ArgumentError, 'origin is required' if value.nil?
+
+      case value.to_sym
+      when :system then SYSTEM
+      when :user then USER
+      when :data then DATA
+      when :tool then TOOL
+      else new(value)
+      end
+    end
+
+    def self.default_for(side)
+      case side.to_sym
+      when :input then USER
+      when :context then DATA
+      else TOOL
+      end
+    end
+  end
+
+  # A value tagged with every origin that produced it.
+  #
+  # Mixing is a union: concatenate a user question with a retrieved page
+  # and the result carries both origins. Any untrusted origin taints the
+  # cell. Taint does not wash off by quoting, summarising, or extracting
+  # a field. That is a policy over tagged cells, not CaMeL.
+  class Cell
+    attr_reader :value, :origins, :capabilities
+
+    def initialize(value, origins:, capabilities: nil)
+      @value = value
+      @origins = Array(origins).map { |origin| Origin.coerce(origin) }.uniq.freeze
+      raise ArgumentError, 'a cell needs at least one origin' if @origins.empty?
+
+      @capabilities = capabilities.nil? ? nil : Array(capabilities).map(&:to_sym).uniq.freeze
+    end
+
+    def self.system(value, capabilities: nil)
+      new(value, origins: Origin.system, capabilities: capabilities)
+    end
+
+    def self.user(value, capabilities: nil)
+      new(value, origins: Origin.user, capabilities: capabilities)
+    end
+
+    def self.data(value, capabilities: nil)
+      new(value, origins: Origin.data, capabilities: capabilities)
+    end
+
+    def self.tool(value, capabilities: nil)
+      new(value, origins: Origin.tool, capabilities: capabilities)
+    end
+
+    def self.text_of(document)
+      return document.value.to_s if document.is_a?(self)
+      return document.to_s unless document.is_a?(Hash)
+
+      (document['text'] || document[:text]).to_s
+    end
+
+    def privileged?
+      origins.all?(&:privileged?)
+    end
+
+    def tainted?
+      origins.any?(&:untrusted?)
+    end
+
+    # Union of origins. The value is the caller's combination; this only
+    # tracks what touched it.
+    def mix(other, value: self.value)
+      self.class.new(value,
+                     origins: origins + other.origins,
+                     capabilities: merge_capabilities(other))
+    end
+
+    # A quoted or extracted form still carries every origin and every
+    # remaining capability. Quoting is not a privilege escalation.
+    def quote
+      self.class.new(value, origins: origins, capabilities: capabilities)
+    end
+
+    def to_h
+      {
+        'value' => value,
+        'origins' => origins.map(&:to_s),
+        'tainted' => tainted?,
+        'capabilities' => capabilities,
+      }.compact
+    end
+
+    private
+
+    # Any untrusted parent zeros the token set: data brings no authority.
+    # Two privileged parents intersect; nil on both sides stays unrestricted.
+    def merge_capabilities(other)
+      return [] if tainted? || other.tainted?
+      return nil if capabilities.nil? && other.capabilities.nil?
+      return other.capabilities if capabilities.nil?
+      return capabilities if other.capabilities.nil?
+
+      capabilities & other.capabilities
+    end
+  end
+
+  # Whether a named capability may be exercised, given the cell that
+  # asked and the cell that supplied the arguments.
+  #
+  # Two questions, because they are not the same. Who requested the
+  # tool is the planner's question: only privileged origin may ask.
+  # What the arguments were derived from is the policy's question: a
+  # deployment that wants retrieved data to feed `cite` says so. A
+  # deployment that does not say so cannot be surprised by a wiki
+  # page that asked for a shell.
+  #
+  #   gate = Admission.new(allow: { cite: %i[data], search: [] })
+  #   gate.permit?(:cite, request: Cell.user(q), arguments: Cell.data(page))
+  #   # => true
+  #   gate.permit?(:search, request: Cell.user(q))
+  #   # => true
+  #   gate.permit?(:shell, request: Cell.user(q))
+  #   # => false
+  #   gate.permit?(:shell, request: Cell.data(page))
+  #   # => false
+  #
+  # An empty gate grants nothing. A key in `allow` is the grant; the
+  # value is which untrusted origins may supply arguments. A request
+  # cell that carries its own capability set must include the name.
+  class Admission
+    def initialize(allow: {})
+      @allow = allow.transform_keys(&:to_sym)
+                    .transform_values { |kinds| Array(kinds).map(&:to_sym) }
+                    .freeze
+    end
+
+    def permit?(capability, request:, arguments: nil)
+      raise ArgumentError, 'request must be a Cell' unless request.is_a?(Cell)
+      raise ArgumentError, 'arguments must be a Cell' if !arguments.nil? && !arguments.is_a?(Cell)
+
+      cap = capability.to_sym
+      return false unless request.privileged?
+      return false unless granted?(cap, request)
+      return true if arguments.nil? || arguments.privileged?
+
+      allowed = @allow[cap] || []
+      arguments.origins.all? { |origin| origin.privileged? || allowed.include?(origin.kind) }
+    end
+
+    private
+
+    def granted?(capability, request)
+      return false unless @allow.key?(capability)
+      return request.capabilities.include?(capability) if request.capabilities
+
+      true
+    end
+  end
+end

data/lib/vangrail/parsers.rb

@@ -27,7 +27,7 @@ module Vangrail
       'S11' => 'Suicide & Self-Harm',
       'S12' => 'Sexual Content',
       'S13' => 'Elections',
-      'S14' => 'Code Interpreter Abuse'
+      'S14' => 'Code Interpreter Abuse',
     }.freeze
 
     # "safe" or "unsafe\nS1,S10".
@@ -51,8 +51,8 @@ module Vangrail
       return reasoned if reasoned
 
       lines = clean_lines(text)
-      safety = lines.find { |l| l.match?(/\A(safe|unsafe)/i) }
-      adversarial = lines.find { |l| l.match?(/\A(non_adversarial|adversarial)/i) }
+      safety = lines.detect { |l| l.match?(/\A(safe|unsafe)/i) }
+      adversarial = lines.detect { |l| l.match?(/\A(non_adversarial|adversarial)/i) }
       return undecided(text) if safety.nil? && adversarial.nil?
 
       unsafe = safety.to_s.match?(/\Aunsafe/i)
@@ -81,9 +81,9 @@ module Vangrail
       fields = {}
       body.each_line do |line|
         m = line.chomp.match(
-          /\A(safety_risks_class|safety_risks_categories|adversarial_attacks_class)\s*:\s*(.*)\z/
+          /\A(safety_risks_class|safety_risks_categories|adversarial_attacks_class)\s*:\s*(.*)\z/,
         )
-        fields[m[1]] = m[2].strip.sub(/,\z/, '') if m
+        fields[m[1]] = m[2].strip.delete_suffix(',') if m
       end
       unsafe = fields['safety_risks_class'].to_s.match?(/unsafe/i)
       attack = fields['adversarial_attacks_class'].to_s.match?(/\Aadversarial/i)

data/lib/vangrail/profile.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+require_relative 'errors'
+
+module Vangrail
+  # A named, session-pinned posture. Copied from Grok Build's sandbox
+  # and permission model, not from a detector paper.
+  #
+  # Grok Build pins the sandbox profile for the life of a session and
+  # refuses to change it on resume. Deny rules still apply under
+  # always-approve. Child processes do not inherit KEY/SECRET/TOKEN.
+  # The same four facts live here:
+  #
+  #   Profile.workspace   cite and search; mutating names are denied
+  #   Profile.strict      cite only; only read-only tools
+  #   Profile.read_only   no invoke of a mutating tool
+  #   Profile.off         no grants
+  #
+  # The profile is chosen at Conversation construction and cannot be
+  # widened later. Deny always wins over allow and over the plan.
+  # Extra `allow:` / `deny:` on a named profile is a conflict, not a
+  # merge: `resolve` raises. Deny-wins merge applies when composing
+  # from hashes alone.
+  class Profile
+    NAMES = %i[off read_only workspace strict].freeze
+    SECRET = /key|secret|token|password|passwd|authorization/i
+
+    attr_reader :name, :allow, :deny, :readonly, :strip_secrets
+
+    def initialize(name:, allow: {}, deny: [], readonly: false, strip_secrets: true)
+      @name = name.to_sym
+      @allow = allow.transform_keys(&:to_sym)
+                    .transform_values { |kinds| Array(kinds).map(&:to_sym) }
+                    .freeze
+      @deny = Array(deny).map { |rule| rule.to_s.freeze }.freeze
+      @readonly = readonly
+      @strip_secrets = strip_secrets
+    end
+
+    def readonly?
+      @readonly
+    end
+
+    def strip_secrets?
+      @strip_secrets
+    end
+
+    def denied?(tool)
+      needle = tool.to_s
+      deny.any? { |rule| File.fnmatch?(rule, needle, File::FNM_EXTGLOB) }
+    end
+
+    def self.off
+      new(name: :off, allow: {}, deny: [], readonly: true)
+    end
+
+    def self.read_only
+      new(name: :read_only, allow: {}, deny: [], readonly: true)
+    end
+
+    def self.workspace
+      new(name: :workspace,
+          allow: { cite: %i[data], search: [] },
+          deny: %w[delete_* dump_* shell],
+          readonly: false)
+    end
+
+    def self.strict
+      new(name: :strict,
+          allow: { cite: %i[data] },
+          deny: %w[delete_* dump_* shell],
+          readonly: true)
+    end
+
+    def self.resolve(value, allow: {}, deny: [])
+      extra = !allow.empty? || !Array(deny).empty?
+      return from_allow(allow, deny: deny) if value.nil?
+      raise ArgumentError, 'pass profile: or allow:/deny:, not both' if extra
+      return value if value.is_a?(self)
+
+      named(value)
+    end
+
+    def self.named(value)
+      case value.to_sym
+      when :off then off
+      when :read_only then read_only
+      when :workspace then workspace
+      when :strict then strict
+      else raise ArgumentError, "unknown profile #{value.inspect}"
+      end
+    end
+
+    def self.glob_denied?(name, rules)
+      needle = name.to_s
+      rules.any? { |rule| File.fnmatch?(rule, needle, File::FNM_EXTGLOB) }
+    end
+
+    def self.from_allow(allow, deny: [])
+      deny_list = Array(deny).map(&:to_s)
+      cleaned = allow.transform_keys(&:to_sym)
+                     .reject { |name, _| glob_denied?(name, deny_list) }
+      new(name: :custom, allow: cleaned, deny: deny, readonly: false, strip_secrets: true)
+    end
+
+    def self.strip_secrets(env)
+      env.each_with_object({}) do |(key, value), kept|
+        next if key.to_s.match?(SECRET)
+
+        kept[key] = value
+      end
+    end
+  end
+end

data/lib/vangrail/prompt.rb

@@ -23,7 +23,7 @@ module Vangrail
     FILTERS = {
       'upper' => lambda(&:upcase),
       'lower' => lambda(&:downcase),
-      'trim' => lambda(&:strip)
+      'trim' => lambda(&:strip),
     }.freeze
 
     TAG = /\{%\s*(\w+)\s*([^%]*?)\s*%\}/
@@ -63,9 +63,20 @@ module Vangrail
 
     def lookup(vars, name)
       name.split('.').reduce(vars) do |acc, part|
-        break nil unless acc.respond_to?(:[])
+        break nil unless acc
 
-        acc[part] || (acc.respond_to?(:key?) ? acc[part.to_sym] : nil)
+        fetch_key(acc, part)
+      end
+    end
+
+    def fetch_key(acc, part)
+      if acc.respond_to?(:key?)
+        return acc[part] if acc.key?(part)
+        return acc[part.to_sym] if acc.key?(part.to_sym)
+
+        nil
+      elsif acc.respond_to?(:[])
+        acc[part]
       end
     end
 

data/lib/vangrail/provider.rb

@@ -1,7 +1,11 @@
 # frozen_string_literal: true
 
 require_relative 'chat'
+require_relative 'completion'
+require_relative 'embeddings'
 require_relative 'errors'
+require_relative 'http'
+require_relative 'providers/gateway'
 
 module Vangrail
   # Where the model-backed rails call, and what they may ask for there.
@@ -9,7 +13,7 @@ module Vangrail
   # Every endpoint this gem talks to is OpenAI-compatible, so the differences
   # that matter are not protocol at all. They are: how a credential resolves,
   # whether the endpoint is up, and which model roles it can actually serve. A
-  # local proxy has a key sitting in a constant and may need starting; a shared
+  # local proxy is named by environment and may need starting; a shared
   # gateway resolves a token from three places and is either up or not; neither
   # necessarily hosts a safety classifier.
   #
@@ -20,84 +24,82 @@ module Vangrail
   #   provider = Vangrail::Provider.resolve          # from the environment
   #   provider.chat(:judge)                                # => Chat, ready to ask
   class Provider
-    ROLES = %i[guard judge].freeze
+    ROLES = %i[guard judge embed].freeze
+    ENDPOINTS = { chat: Chat, embeddings: Embeddings, completion: Completion }.freeze
 
-    class << self
-      # Presets by name, in the order `resolve` tries them.
-      def registry
-        @registry ||= {}
-      end
+    # Presets by name, in the order `resolve` tries them.
+    def self.registry
+      @registry ||= {}
+    end
 
-      def register(provider)
-        registry[provider.name] = provider
-        provider
-      end
+    def self.register(provider)
+      registry[provider.name] = provider
+      provider
+    end
 
-      def [](name)
-        registry[name.to_s]
-      end
+    def self.[](name)
+      registry[name.to_s]
+    end
 
-      def names
-        registry.keys
-      end
+    def self.names
+      registry.keys
+    end
 
-      # Picks a provider from the environment.
-      #
-      #   GUARDRAILS_PROVIDER=<name>   take this one, and fail loudly if it is
-      #                                unknown rather than falling back
-      #   GUARDRAILS_API_BASE + key    an endpoint nobody registered
-      #   otherwise                    the first registered provider that is
-      #                                actually available, in registration order
-      #
-      # Returning nil is a legitimate answer: no endpoint is reachable, and the
-      # caller builds an engine with only the offline rails on it.
-      def resolve(env = ENV)
-        candidates = registry.each_value.to_a + [gateway_in(env)].compact
-
-        wanted = present(env['GUARDRAILS_PROVIDER'])
-        if wanted
-          found = candidates.find { |p| p.name == wanted }
-          raise ConfigError, "unknown provider #{wanted.inspect}; known: #{names.join(', ')}" unless found
-
-          return found.with_env(env)
-        end
-
-        explicit = from_env_pair(env)
-        return explicit if explicit
-
-        candidates.map { |p| p.with_env(env) }.find(&:available?)
+    # Picks a provider from the environment.
+    #
+    #   GUARDRAILS_PROVIDER=<name>   take this one, and fail loudly if it is
+    #                                unknown rather than falling back
+    #   GUARDRAILS_API_BASE + key    an endpoint nobody registered
+    #   otherwise                    the first registered provider that is
+    #                                actually available, in registration order
+    #
+    # Returning nil is a legitimate answer: no endpoint is reachable, and the
+    # caller builds an engine with only the offline rails on it.
+    def self.resolve(env = ENV)
+      candidates = registry.each_value.to_a + [gateway_in(env)].compact
+
+      wanted = present(env['GUARDRAILS_PROVIDER'])
+      if wanted
+        found = candidates.detect { |p| p.name == wanted }
+        raise ConfigError, "unknown provider #{wanted.inspect}; known: #{names.join(', ')}" unless found
+
+        return found.with_env(env)
       end
 
-      # A gateway described by the environment this call was handed, rather than
-      # by the one the registry happened to be installed from. Resolution is
-      # then a function of (registry, env), which is what a caller passing an
-      # env hash is entitled to assume.
-      def gateway_in(env)
-        return nil if env.equal?(ENV)
-
-        spec = Providers::Gateway.from_environment(env)
-        spec && Providers::Gateway.provider(spec, env)
-      rescue NameError
-        nil
-      end
+      explicit = from_env_pair(env)
+      return explicit if explicit
 
-      # An endpoint given directly, which is how anything unregistered is used.
-      def from_env_pair(env)
-        base = present(env['GUARDRAILS_API_BASE'])
-        return nil unless base
-
-        new(
-          name: 'env',
-          base_url: base,
-          key_resolver: -> { present(env['GUARDRAILS_API_KEY']) },
-          models: { judge: present(env['GUARDRAILS_JUDGE_MODEL']), guard: present(env['GUARDRAILS_MODEL']) }
-        )
-      end
+      candidates.map { |p| p.with_env(env) }.detect(&:available?)
+    end
 
-      def present(value)
-        s = value.to_s.strip
-        s.empty? ? nil : s
-      end
+    # A gateway described by the environment this call was handed, rather than
+    # by the one the registry happened to be installed from. Resolution is
+    # then a function of (registry, env), which is what a caller passing an
+    # env hash is entitled to assume.
+    def self.gateway_in(env)
+      return nil if env.equal?(ENV)
+
+      spec = Providers::Gateway.from_environment(env)
+      spec && Providers::Gateway.provider(spec, env)
+    end
+
+    # An endpoint given directly, which is how anything unregistered is used.
+    def self.from_env_pair(env)
+      base = present(env['GUARDRAILS_API_BASE'])
+      return nil unless base
+
+      new(
+        name: 'env',
+        base_url: base,
+        key_resolver: -> { present(env['GUARDRAILS_API_KEY']) },
+        models: { judge: present(env['GUARDRAILS_JUDGE_MODEL']), guard: present(env['GUARDRAILS_MODEL']),
+                  embed: present(env['GUARDRAILS_EMBED_MODEL']) },
+      )
+    end
+
+    def self.present(value)
+      s = value.to_s.strip
+      s.empty? ? nil : s
     end
 
     attr_reader :name, :base_url, :models, :guard_preset, :local
@@ -118,7 +120,8 @@ module Vangrail
     def with_env(env)
       overrides = {
         judge: self.class.present(env['GUARDRAILS_JUDGE_MODEL']),
-        guard: self.class.present(env['GUARDRAILS_MODEL'])
+        guard: self.class.present(env['GUARDRAILS_MODEL']),
+        embed: self.class.present(env['GUARDRAILS_EMBED_MODEL']),
       }.compact
       base = self.class.present(env["#{env_prefix}_API_BASE"]) || base_url
       key = self.class.present(env["#{env_prefix}_API_KEY"])
@@ -147,6 +150,16 @@ module Vangrail
       !model(:guard).nil? && !guard_preset.nil?
     end
 
+    # Can it embed. Named rather than assumed for the same reason `guard?` is:
+    # an endpoint serving chat need not serve embeddings, and a rail built on
+    # the assumption that it does is a rail that reports an error instead of a
+    # verdict. No default model is guessed either, because the name of an
+    # embedding model is deployment knowledge and a wrong guess is a 404 per
+    # check.
+    def embed?
+      !model(:embed).nil?
+    end
+
     # Up, and holding a credential. A local endpoint is probed, because a proxy
     # that is not running is the ordinary case rather than a failure.
     def available?
@@ -160,11 +173,23 @@ module Vangrail
       !@key_resolver.nil?
     end
 
+    def http
+      @http ||= HTTP.new(base_url: base_url, api_key: api_key)
+    end
+
     def chat(role = :judge, **kwargs)
-      name = model(role)
-      raise ConfigError, "provider #{self.name} has no #{role} model" unless name
+      endpoint(:chat, role, **kwargs)
+    end
+
+    def embeddings(role = :embed, **kwargs)
+      endpoint(:embeddings, role, **kwargs)
+    end
 
-      Chat.new(model: name, base_url: base_url, api_key: api_key, **kwargs)
+    # Scoring rather than generation, from whichever model answers questions.
+    # No separate role: any causal model can score text, and asking a
+    # deployment to name a second one for it would be ceremony.
+    def completion(role = :judge, **kwargs)
+      endpoint(:completion, role, **kwargs)
     end
 
     def to_h
@@ -174,7 +199,6 @@ module Vangrail
         'models' => models.transform_keys(&:to_s).compact,
         'guard_preset' => guard_preset&.to_s,
         'local' => local,
-        'available' => available?
       }.compact
     end
 
@@ -184,6 +208,13 @@ module Vangrail
 
     private
 
+    def endpoint(kind, role, **kwargs)
+      name = model(role)
+      raise ConfigError, "provider #{self.name} has no #{role} model" unless name
+
+      ENDPOINTS.fetch(kind).new(model: name, http: http, **kwargs)
+    end
+
     def env_prefix
       name.upcase.gsub(/[^A-Z0-9]/, '_')
     end