Module: RubyLLM::Modes::Mode

Included in:
RubyLLM::ModeAgent
Defined in:
lib/ruby_llm/modes/mode.rb

Overview

Extend into an Agent class to make it routable.

class TutorAgent < RubyLLM::Agent
extend RubyLLM::Modes::Mode
description "Explains words and grammar."
mode_name "tutor"   # optional
end

Neither value is inherited. A subclass declares its own description, and its name is derived from its own class name unless overridden.

Both texts follow Agent's prompt convention. A class that declares no description reads app/prompts//description.txt.erb when the file exists, rendered without locals; a class that declares no instructions reads instructions.txt.erb next to it, as any Agent does.

A mode takes one turn of a chat that already has its own system prompt, so its instructions default to append: true (added after the chat's prompt) and persist: false (kept out of a Rails record's history), for the template as well as for an explicit declaration. Declare either option to override.

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.derive_name(klass) ⇒ Object

Derives a registration name from a class name: the trailing "Agent" removed (a segment that is only "Agent" stays), namespaces kept as path segments, the rest underscored.

TutorAgent       -> "tutor"
Chat::TutorAgent -> "chat/tutor"
TutorModeAgent   -> "tutor_mode"

Returns nil for an anonymous class.



64
65
66
67
68
69
 
# File 'lib/ruby_llm/modes/mode.rb', line 64

def self.derive_name(klass)
  return if klass.name.nil?

  base = klass.name.sub(/(?<=\w)Agent\z/, "")
  RubyLLM::Support::Utils.underscore(base.gsub("::", "/"))
end

Instance Method Details

#description(text = nil) ⇒ Object

Tells the router what the mode does and when to pick it, as a Tool's description tells the model when to call the tool. Sets the text, or returns this class's own one: the declaration, else the description prompt file when it exists. Multi-line text is fine; surrounding whitespace is removed.



40
41
42
43
44
 
# File 'lib/ruby_llm/modes/mode.rb', line 40

def description(text = nil)
  return @description || description_from_prompt if text.nil?

  @description = text.to_s.strip
end

#instructions(text = nil, append: true, persist: false, **options, &block) ⇒ Object

Agent's instructions with mode defaults: append: true and persist: false. Everything else, including the getter form and prompt locals, is Agent's.



31
32
33
 
# File 'lib/ruby_llm/modes/mode.rb', line 31

def instructions(text = nil, append: true, persist: false, **options, &block)
  super
end

#mode_name(name = nil) ⇒ Object

Sets the registration name, or returns it: the override declared on this class, else the name derived from the class name (see Mode.derive_name).



49
50
51
52
53
 
# File 'lib/ruby_llm/modes/mode.rb', line 49

def mode_name(name = nil)
  return @mode_name || Mode.derive_name(self) if name.nil?

  @mode_name = name.to_s
end