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

Defined Under Namespace

Modules: Lifecycle, Registry

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.



110
111
112
 
# File 'lib/smith/agent.rb', line 110

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 like hadithi-xl’s InvokeCleaner.chat (which constructs a chat outside the workflow lifecycle) are normalized too. Without this placement, Cleaner’s Opus 4.7 adaptive thinking 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!.



153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
 
# File 'lib/smith/agent.rb', line 153

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 



210
211
212
213
214
 
# File 'lib/smith/agent.rb', line 210

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.



124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
 
# File 'lib/smith/agent.rb', line 124

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 



198
199
200
201
202
 
# File 'lib/smith/agent.rb', line 198

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.



87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
 
# File 'lib/smith/agent.rb', line 87

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) 


115
116
117
 
# File 'lib/smith/agent.rb', line 115

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 



204
205
206
207
208
 
# File 'lib/smith/agent.rb', line 204

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

  super(&wrap_runtime_block(block))
end

.register_as(name = nil) ⇒ Object 



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

def register_as(name = nil)
  return @registered_name if name.nil?

  @registered_name = name
  Registry.ensure_registered(name.to_sym, self)
end

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



216
217
218
219
220
 
# File 'lib/smith/agent.rb', line 216

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.



192
193
194
195
196
 
# File 'lib/smith/agent.rb', line 192

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

  super(&wrap_runtime_block(block))
end