class LittleGhost::Invocation
Carry one application request into an agent run. An invocation keeps framework fields and application-specific context in one indifferent-key environment.
invocation = LittleGhost::Invocation.new( message: "Why is transfer 481 pending?", account_id: "account-1", metadata: {channel: "customer_support"} ) invocation.message.text # => "Why is transfer 481 pending?" invocation[:account_id] # => "account-1" invocation.account_id # => "account-1"
String and symbol keys address the same field. Known fields have named accessors, while unknown application fields remain available through hash access and dynamic readers or writers. message and every history entry are normalized to Message objects; deadline_at lazily parses ISO 8601 text.
Missing run, invocation, and session identifiers are generated when the object is built. Actor identity is never inferred: applications that use it for persistence or tenant isolation must pass a value established by their trusted authentication boundary. Invalid payloads, messages, keys, or deadlines raise InvocationError.
Public Class Methods
Source
# File lib/little_ghost/invocation.rb, line 50 def initialize(env = {}) invalid!("Invocation payload must be an object") unless env.is_a?(Hash) @env = env.to_h { |key, value| [normalize_key(key), duplicate_value(value)] } DEFAULTS.each { |key, default| @env[key] = default.call unless @env.key?(key) } self.history = history self.message = message initialize_identifiers! end
Copies env, normalizes known framework fields, and fills missing identifiers.
The payload must be a Hash and must contain a non-blank message.
Public Instance Methods
Source
# File lib/little_ghost/invocation.rb, line 176 def [](key) = env[normalize_key(key)]
Looks up key after normalizing it to a String.
Source
# File lib/little_ghost/invocation.rb, line 181 def []=(key, value) normalized = normalize_key(key) value = normalize_message(value) if normalized == "message" value = Array(value).map { |message| Message.coerce(message) }.freeze if normalized == "history" env[normalized] = value end
Stores value under a normalized String key.
The message and history fields are normalized before storage.
Source
# File lib/little_ghost/invocation.rb, line 119
The explicit actor identifier supplied by the application.
Source
# File lib/little_ghost/invocation.rb, line 170 ACCESSORS.each do |name| define_method(name) { self[name] } define_method(:"#{name}=") { |value| self[name] = value } unless %i[message history].include?(name) end
Replaces the application-established actor identifier.
Source
# File lib/little_ghost/invocation.rb, line 81
JSON-like state made available to the agent run.
Source
# File lib/little_ghost/invocation.rb, line 131
Replaces the JSON-like agent state.
Source
# File lib/little_ghost/invocation.rb, line 203 def deadline_at value = self[:deadline_at] return value if value.nil? || value.is_a?(Time) self[:deadline_at] = Time.iso8601(String(value)) rescue ArgumentError, TypeError invalid!("deadline_at must be a valid time") end
The request deadline as a Time, parsing ISO 8601 text on first access.
Source
# File lib/little_ghost/invocation.rb, line 213 def deadline_at=(value) self[:deadline_at] = value end
Replaces the deadline; parsing is deferred until deadline_at is read.
Source
# File lib/little_ghost/invocation.rb, line 192 def dig(key, *names) = env.dig(normalize_key(key), *names)
Traverses the environment from normalized key through names.
# File lib/little_ghost/invocation.rb, line 189 def fetch(key, *defaults, &block) = env.fetch(normalize_key(key), *defaults, &block)
Fetches key with the same default and block behavior as Hash#fetch.
# File lib/little_ghost/invocation.rb, line 68
Frozen, normalized Messages that precede the current message.
Source
# File lib/little_ghost/invocation.rb, line 223 def history=(value) self[:history] = value end
Replaces and freezes the normalized message history.
Source
# File lib/little_ghost/invocation.rb, line 107
The invocation identifier, defaulting to run_id.
# File lib/little_ghost/invocation.rb, line 155
Replaces the invocation identifier.
Source
# File lib/little_ghost/invocation.rb, line 195 def key?(key) = env.key?(normalize_key(key))
Whether the environment contains key after normalization.
# File lib/little_ghost/invocation.rb, line 62
The normalized current Message.
Source
# File lib/little_ghost/invocation.rb, line 218 def message=(value) self[:message] = value end
Replaces and normalizes the current message.
Source
# File lib/little_ghost/invocation.rb, line 87
Application metadata carried with the request.
Source
# File lib/little_ghost/invocation.rb, line 137
Replaces the application metadata.
Source
# File lib/little_ghost/invocation.rb, line 95
Per-request overrides for logical model profiles. Overrides can select a provider and model, so applications must construct or allowlist them at a trusted control-plane boundary.
# File lib/little_ghost/invocation.rb, line 143
Replaces the trusted per-request model profile overrides.
Source
# File lib/little_ghost/invocation.rb, line 101
The caller-supplied or generated top-level run identifier.
Source
# File lib/little_ghost/invocation.rb, line 149
Replaces the top-level run identifier.
Source
# File lib/little_ghost/invocation.rb, line 113
The session identifier, defaulting to run_id.
Source
# File lib/little_ghost/invocation.rb, line 161
Replaces the session identifier used for persistence.
Source
# File lib/little_ghost/invocation.rb, line 75
Per-request model settings merged after profile defaults. Treat these as trusted application policy, not unchecked request or model input.
Source
# File lib/little_ghost/invocation.rb, line 125
Replaces the trusted request-scoped model settings.
Source
# File lib/little_ghost/invocation.rb, line 200 def to_h = duplicate_value(env)
Produces a mutable copy of the invocation environment.
Nested hashes, arrays, strings, and other duplicable values are copied.