Class: Vangrail::Config

Inherits:
Object
  • Object
show all
Defined in:
lib/vangrail/config.rb

Overview

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.

Constant Summary collapse

SELF_CHECK_TASKS = 
{ 'self_check_input' => :input, 'self_check_output' => :output }.freeze

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(name:, models: [], rails: {}, prompts: [], flows: {}, instructions: nil, sample_conversation: nil, path: nil) ⇒ Config

Returns a new instance of Config.



41
42
43
44
45
46
47
48
49
50
51
 
# File 'lib/vangrail/config.rb', line 41

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

Instance Attribute Details

#flows ⇒ Object (readonly)

Returns the value of attribute flows.



39
40
41
 
# File 'lib/vangrail/config.rb', line 39

def flows
  @flows
end

#instructions ⇒ Object (readonly)

Returns the value of attribute instructions.



39
40
41
 
# File 'lib/vangrail/config.rb', line 39

def instructions
  @instructions
end

#models ⇒ Object (readonly)

Returns the value of attribute models.



39
40
41
 
# File 'lib/vangrail/config.rb', line 39

def models
  @models
end

#name ⇒ Object (readonly)

Returns the value of attribute name.



39
40
41
 
# File 'lib/vangrail/config.rb', line 39

def name
  @name
end

#path ⇒ Object (readonly)

Returns the value of attribute path.



39
40
41
 
# File 'lib/vangrail/config.rb', line 39

def path
  @path
end

#prompts ⇒ Object (readonly)

Returns the value of attribute prompts.



39
40
41
 
# File 'lib/vangrail/config.rb', line 39

def prompts
  @prompts
end

#rails ⇒ Object (readonly)

Returns the value of attribute rails.



39
40
41
 
# File 'lib/vangrail/config.rb', line 39

def rails
  @rails
end

#sample_conversation ⇒ Object (readonly)

Returns the value of attribute sample_conversation.



39
40
41
 
# File 'lib/vangrail/config.rb', line 39

def sample_conversation
  @sample_conversation
end

Class Method Details

.for_provider(provider, name: 'handbook', main_model: nil, judge_model: nil, subject: 'a public documentation handbook') ⇒ Object

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.



208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
 
# File 'lib/vangrail/config.rb', line 208

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

.load(dir) ⇒ Object

--- reading ---

Raises:



55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
 
# File 'lib/vangrail/config.rb', line 55

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

.load_yaml(file) ⇒ Object 



76
77
78
79
80
 
# File 'lib/vangrail/config.rb', line 76

def self.load_yaml(file)
  return nil unless File.file?(file)

  YAML.safe_load_file(file, aliases: true)
end

.model_entry(type, model, base_url) ⇒ Object 



239
240
241
 
# File 'lib/vangrail/config.rb', line 239

def self.model_entry(type, model, base_url)
  { 'type' => type, 'engine' => 'openai', 'model' => model, 'parameters' => { 'base_url' => base_url } }
end

.self_check_prompt(rail, subject) ⇒ Object

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.



245
246
247
248
249
250
251
252
253
254
255
256
257
258
 
# File 'lib/vangrail/config.rb', line 245

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

Instance Method Details

#config_yaml ⇒ Object 



269
270
271
 
# File 'lib/vangrail/config.rb', line 269

def config_yaml
  YAML.dump(to_h)
end

#conversation(prior:, stdlib: true, **kwargs) ⇒ Object

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.



133
134
135
 
# File 'lib/vangrail/config.rb', line 133

def conversation(prior:, stdlib: true, **kwargs)
  Conversation.new(engine(stdlib: stdlib), prior: prior, **kwargs)
end

#engine(provider: nil, chat: nil, actions: {}, on_error: :allow, cache: true, stdlib: false) ⇒ Object

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.

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.



119
120
121
122
123
124
125
126
127
128
 
# File 'lib/vangrail/config.rb', line 119

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: 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,
  )
end

#flow_names(side) ⇒ Object 



92
93
94
95
96
97
 
# File 'lib/vangrail/config.rb', line 92

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

#model_for(type) ⇒ Object 



104
105
106
 
# File 'lib/vangrail/config.rb', line 104

def model_for(type)
  models.detect { |m| m['type'].to_s == type.to_s }
end

#program ⇒ Object

Every flow this configuration can execute: the ones it ships plus the built-ins it is allowed to name without defining.



86
87
88
89
90
 
# File 'lib/vangrail/config.rb', line 86

def program
  @program ||= flows.reduce(Colang::Library.program) do |acc, (file, source)|
    acc.merge(Colang::Parser.parse(source, filename: "#{file}.co"))
  end
end

#prompt_for(task) ⇒ Object 



99
100
101
102
 
# File 'lib/vangrail/config.rb', line 99

def prompt_for(task)
  entry = prompts.detect { |p| p['task'].to_s == task.to_s }
  entry && entry['content'].to_s
end

#prompts_yaml ⇒ Object 



273
274
275
 
# File 'lib/vangrail/config.rb', line 273

def prompts_yaml
  YAML.dump('prompts' => prompts)
end

#rails_for(side, registry) ⇒ Object 



137
138
139
140
141
142
143
144
145
146
147
 
# File 'lib/vangrail/config.rb', line 137

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

#to_h ⇒ Object 



260
261
262
263
264
265
266
267
 
# File 'lib/vangrail/config.rb', line 260

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

#write!(root) ⇒ Object

Writes //. Returns the directory it wrote.



278
279
280
281
282
283
284
285
286
287
288
 
# File 'lib/vangrail/config.rb', line 278

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