Class: Riffer::Agent::Context

Inherits:
Object
  • Object
show all
Defined in:
lib/riffer/agent/context.rb

Overview

Typed value object wrapping the runtime context Hash held by a Riffer::Agent. Exposes first-class accessors for the framework-managed entries — skills and token_usage — and preserves #[] / #dig reads so tools (which receive context: as a keyword) keep working with both built-in and caller-provided keys.

Reserved keys (:skills, :token_usage) cannot be set by the caller at construction; they are owned by Riffer and written through the typed setters. Type invariants are enforced on write — skills must be a Riffer::Skills::Context (or nil); token_usage must be a Riffer::Providers::TokenUsage (or nil).

context = Riffer::Agent::Context.new(user_id: 42)
context[:user_id]    # => 42
context.skills       # => nil
context.token_usage  # => nil

Constant Summary collapse

RESERVED_KEYS =

Keys reserved for framework use. Passing any of these to the constructor raises Riffer::ArgumentError.

[:skills, :token_usage].freeze

Instance Method Summary collapse

Constructor Details

#initialize(data = {}) ⇒ Context

Builds a new context.

data

caller-provided Hash passed as Agent.new(context:). Duped before storage so caller mutations do not affect the agent. Must not contain any RESERVED_KEYS.

Raises Riffer::ArgumentError when data contains a reserved key.

– : (?Hash[Symbol, untyped]) -> void



36
37
38
39
40
41
42
43
44
45
46
 
# File 'lib/riffer/agent/context.rb', line 36

def initialize(data = {})
  reserved = data.keys & RESERVED_KEYS
  if reserved.any?
    raise Riffer::ArgumentError,
      "Reserved keys cannot be passed in context: #{reserved.join(", ")}"
  end

  @data = data.dup
  @data[:skills] = nil
  @data[:token_usage] = nil
end

Instance Method Details

#[](key) ⇒ Object

Hash-style read. Preserved so downstream tool runtimes pulling caller-provided keys via context[:agent] or context[:tenant] keep working unchanged.

– : (Symbol) -> untyped



104
105
106
 
# File 'lib/riffer/agent/context.rb', line 104

def [](key)
  @data[key]
end

#dig(*keys) ⇒ Object

Hash-style dig. Preserved for tools using context&.dig(:user_id).

– : (*Symbol) -> untyped



113
114
115
 
# File 'lib/riffer/agent/context.rb', line 113

def dig(*keys)
  @data.dig(*keys)
end

#skills ⇒ Object

The agent’s resolved Riffer::Skills::Context, or nil when skills are not configured.

– : () -> Riffer::Skills::Context?



53
54
55
 
# File 'lib/riffer/agent/context.rb', line 53

def skills
  @data[:skills]
end

#skills=(value) ⇒ Object

Sets the resolved skills context. Called once by Riffer::Agent during construction.

Raises Riffer::ArgumentError if value is neither nil nor a Riffer::Skills::Context.

– : (Riffer::Skills::Context?) -> Riffer::Skills::Context?



65
66
67
68
69
70
71
 
# File 'lib/riffer/agent/context.rb', line 65

def skills=(value)
  unless value.nil? || value.is_a?(Riffer::Skills::Context)
    raise Riffer::ArgumentError,
      "skills must be a Riffer::Skills::Context or nil, got #{value.class}"
  end
  @data[:skills] = value
end

#to_h ⇒ Object

Returns a copy of the underlying Hash. Mutating the result does not affect this context.

– : () -> Hash[Symbol, untyped]



122
123
124
 
# File 'lib/riffer/agent/context.rb', line 122

def to_h
  @data.dup
end

#token_usage ⇒ Object

The cumulative Riffer::Providers::TokenUsage across every Run on this agent, or nil before the first response is recorded.

– : () -> Riffer::Providers::TokenUsage?



78
79
80
 
# File 'lib/riffer/agent/context.rb', line 78

def token_usage
  @data[:token_usage]
end

#token_usage=(value) ⇒ Object

Sets the cumulative token usage. Called by Riffer::Agent::Run after each LLM response.

Raises Riffer::ArgumentError if value is neither nil nor a Riffer::Providers::TokenUsage.

– : (Riffer::Providers::TokenUsage?) -> Riffer::Providers::TokenUsage?



90
91
92
93
94
95
96
 
# File 'lib/riffer/agent/context.rb', line 90

def token_usage=(value)
  unless value.nil? || value.is_a?(Riffer::Providers::TokenUsage)
    raise Riffer::ArgumentError,
      "token_usage must be a Riffer::Providers::TokenUsage or nil, got #{value.class}"
  end
  @data[:token_usage] = value
end