Class: Smith::Agent

Inherits:
RubyLLM::Agent
  • Object
show all
Defined in:
lib/smith/agent.rb,
lib/smith/agent/registry.rb,
lib/smith/agent/lifecycle.rb,
lib/smith/agent/registry_binding.rb,
lib/smith/agent/registry/introspection.rb,
lib/smith/agent/registry/mutation_boundary.rb,
lib/smith/agent/registry/execution_binding_capture.rb

Defined Under Namespace

Modules: Lifecycle, Registry Classes: RegistryBinding

Constant Summary collapse

RESERVED_INPUT_NAMES =

Reserved input names auto-injected by the normalizer into runtime_context. User-side inputs :name calls cannot redeclare these names; the override raises Smith::AgentError if they try. The getter merges user-declared inputs WITH reserved so subclasses don't lose reserved names when declaring their own.

%i[model_id provider endpoint_mode].freeze

Class Attribute Summary collapse

Class Method Summary collapse

Class Attribute Details

.model_block ⇒ Object (readonly)

Returns the value of attribute model_block.



119
120
121
 
# File 'lib/smith/agent.rb', line 119

def model_block
  @model_block
end

Class Method Details

.budget(**opts) ⇒ Object 



26
27
28
29
30
 
# File 'lib/smith/agent.rb', line 26

def budget(**opts)
  return @budget_config if opts.empty?

  @budget_config = opts
end

.chat(**kwargs) ⇒ Object

Closes the inputs contract at the chat() boundary AND runs the Smith::Models::Normalizer. Hook lives here (not in Lifecycle#attempt_model) so direct callers that construct a chat outside the workflow lifecycle are normalized too. Without this placement, model-specific request translation would only fire for workflow-driven calls.

Single profile lookup: resolved once via Models.find_or_infer and passed through both inject_reserved_inputs and Normalizer.apply!.



174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
 
# File 'lib/smith/agent.rb', line 174

def chat(**kwargs)
  # Resolve model from explicit kwarg first, then fall back to the
  # class-level chat_kwargs[:model] (set by `model "..."`). The
  # explicit kwarg path fires from Lifecycle#attempt_model (passes
  # the resolved primary or fallback model); the chat_kwargs path
  # fires from direct callers like `Agent.chat` with no args.
  model_id = kwargs[:model] || chat_kwargs[:model]
  profile = resolve_profile(model_id)
  kwargs = inject_reserved_inputs(kwargs, profile)
  kwargs = nil_fill_declared_inputs(kwargs)

  llm_chat = super
  Smith::Models::Normalizer.apply!(llm_chat, profile: profile) if profile
  llm_chat
end

.data_volume(value = nil) ⇒ Object 



44
45
46
47
48
 
# File 'lib/smith/agent.rb', line 44

def data_volume(value = nil)
  return @data_volume if value.nil?

  @data_volume = value
end

.fallback_models(*models) ⇒ Object

Raises:



50
51
52
53
54
55
56
57
 
# File 'lib/smith/agent.rb', line 50

def fallback_models(*models)
  return @fallback_models_list if models.empty?

  entries = models.flatten.compact.map(&:to_s)
  raise Smith::WorkflowError, "fallback_models entries must not be blank" if entries.any?(&:empty?)

  @fallback_models_list = entries.uniq
end

.guardrails(klass = nil) ⇒ Object 



32
33
34
35
36
 
# File 'lib/smith/agent.rb', line 32

def guardrails(klass = nil)
  return @guardrails_class if klass.nil?

  @guardrails_class = klass
end

.headers(**headers_kwargs, &block) ⇒ Object 



231
232
233
234
235
 
# File 'lib/smith/agent.rb', line 231

def headers(**headers_kwargs, &block)
  return super unless block

  super(&wrap_runtime_block(block))
end

.inherited(subclass) ⇒ Object 



15
16
17
18
19
20
21
22
23
24
 
# File 'lib/smith/agent.rb', line 15

def inherited(subclass)
  super
  subclass.instance_variable_set(:@budget_config, @budget_config)
  subclass.instance_variable_set(:@guardrails_class, @guardrails_class)
  subclass.instance_variable_set(:@output_schema_class, @output_schema_class)
  subclass.instance_variable_set(:@data_volume, @data_volume)
  subclass.instance_variable_set(:@fallback_models_list, @fallback_models_list&.dup)
  subclass.instance_variable_set(:@model_block, @model_block)
  subclass.instance_variable_set(:@registered_name, nil)
end

.inputs(*names) ⇒ Object

MERGING override: getter always returns user-declared ∪ reserved; setter validates user names against reserved + stores only user names. RubyLLM's bare @input_names = names (agent.rb:96) REPLACES; this override prevents subclasses from losing reserved names when they declare their own inputs.



146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
 
# File 'lib/smith/agent.rb', line 146

def inputs(*names)
  if names.empty?
    user = @input_names || []
    return (user + RESERVED_INPUT_NAMES).uniq.freeze
  end

  user_names = names.flatten.map(&:to_sym)
  collisions = user_names & RESERVED_INPUT_NAMES
  if collisions.any?
    raise Smith::AgentError,
          "agent input names #{collisions.inspect} are reserved by Smith. " \
          "Reserved names #{RESERVED_INPUT_NAMES.inspect} are auto-injected by " \
          "Smith::Models::Normalizer into runtime_context. " \
          "Rename your inputs to avoid the collision."
  end

  @input_names = user_names.freeze
end

.instructions(text = nil, **prompt_locals, &block) ⇒ Object 



219
220
221
222
223
 
# File 'lib/smith/agent.rb', line 219

def instructions(text = nil, **prompt_locals, &block)
  return super unless block

  super(text, **prompt_locals, &wrap_runtime_block(block))
end

.model(model_id = nil, **options, &block) ⇒ Object

Extends RubyLLM::Agent.model with a block-form for context-driven resolution at chat-construction time.

Static form model "gpt-5-mini":

Stores into @chat_kwargs[:model] via RubyLLM's existing path.
Model id is fixed at class-load time.

Block form model { |context| ... }:

Stores the block as @model_block. Smith's lifecycle resolves it
at chat-construction time using the workflow's @context (Hash).
Return value must be a non-empty string; non-string / empty / nil
returns surface as Smith::AgentError at the resolution point
(see Smith::Agent::Lifecycle#build_model_chain).

Mutually exclusive within a single declaration: passing both a string id and a block raises ArgumentError. Redeclaring with the other form clears the previous setting (static replaces block, block replaces static).

Composes with fallback_models: resolved primary, then declared fallbacks, in order. Same path as static-form fallback.



96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
 
# File 'lib/smith/agent.rb', line 96

def model(model_id = nil, **options, &block)
  if block
    raise ArgumentError, "model can take a string id OR a block, not both" if model_id || !options.empty?

    @model_block = block
    # Clear any stale `@chat_kwargs[:model]` from a prior static-form
    # declaration. Smith's workflow lifecycle resolves block-form
    # correctly via `build_model_chain` (which checks @model_block
    # first), but RubyLLM's direct `chat()` and `with_rails_chat_record`
    # paths splat `**chat_kwargs` to the constructor; without this
    # delete, those paths would silently use the stale static id.
    # This is the only place Smith mutates a RubyLLM-owned ivar; the
    # mutation is well-scoped (only :model, only on block-form
    # declaration) and matches RubyLLM's own pattern of dup'ing
    # @chat_kwargs through its `inherited` hook.
    @chat_kwargs ||= {}
    @chat_kwargs.delete(:model)
  else
    @model_block = nil
    super
  end
end

.model_configured? ⇒ Boolean

Whether this agent class has any model configured (static or block). Smith::Workflow::Execution uses this as a precondition for invoking the agent; agents declared without a model are skipped.

Returns:

  • (Boolean) 


137
138
139
 
# File 'lib/smith/agent.rb', line 137

def model_configured?
  !chat_kwargs[:model].nil? || !@model_block.nil?
end

.output_schema(klass = nil) ⇒ Object 



38
39
40
41
42
 
# File 'lib/smith/agent.rb', line 38

def output_schema(klass = nil)
  return @output_schema_class if klass.nil?

  @output_schema_class = klass
end

.params(**params_kwargs, &block) ⇒ Object 



225
226
227
228
229
 
# File 'lib/smith/agent.rb', line 225

def params(**params_kwargs, &block)
  return super unless block

  super(&wrap_runtime_block(block))
end

.publish_registration! ⇒ Object

Raises:



68
69
70
71
72
73
 
# File 'lib/smith/agent.rb', line 68

def publish_registration!
  name = @registered_name
  raise Smith::AgentRegistryError, "agent registration identity is not configured" unless name

  Registry.ensure_registered(name.to_sym, self)
end

.register_as(name = nil, publish: true) ⇒ Object

Raises:

  • (ArgumentError) 


59
60
61
62
63
64
65
66
 
# File 'lib/smith/agent.rb', line 59

def register_as(name = nil, publish: true)
  return @registered_name if name.nil?

  raise ArgumentError, "publish must be true or false" unless [true, false].include?(publish)

  @registered_name = canonical_registration_name(name)
  publish ? publish_registration! : self
end

.schema(value = nil, &block) ⇒ Object 



237
238
239
240
241
 
# File 'lib/smith/agent.rb', line 237

def schema(value = nil, &block)
  return super unless block

  super(&wrap_runtime_block(block))
end

.tools(*tools, &block) ⇒ Object

Normalizes the |ctx| DSL across RubyLLM's block-form attribute setters.

RubyLLM evaluates these blocks via runtime.instance_exec(&block), which sets self to the runtime_context but passes NO positional arguments, so tools do |ctx| ctx.form_kind end would silently bind ctx = nil and crash on the first method call. Smith's model block-form already uses block.call(@context) (an explicit Hash arg), giving agent authors a uniform |ctx| mental model. These overrides carry that convention through to RubyLLM's setters by wrapping any block so |ctx| receives the runtime_context AND self is still the runtime (preserving RubyLLM's bare-method-dispatch convention for zero-arity blocks).

Behavior matrix:

tools do            ... end  (arity 0): preserved as-is; bare method
                                       calls dispatch to runtime via
                                       instance_exec (RubyLLM idiom)
tools do |ctx|      ... end  (arity 1): wrapped; ctx receives runtime
                                       AND self is runtime, so both
                                       `ctx.x` and bare `x` work

Lambdas with arity 0 are preserved as-is (strict-arity safe). The wrapping path uses Proc semantics, so extra args don't raise.



213
214
215
216
217
 
# File 'lib/smith/agent.rb', line 213

def tools(*tools, &block)
  return super unless block

  super(&wrap_runtime_block(block))
end