Module: Observ::AgentPhaseable

Extended by:
ActiveSupport::Concern
Defined in:
app/models/concerns/observ/agent_phaseable.rb

Overview

AgentPhaseable adds phase tracking capabilities to Chat models

This concern is optional and should only be included if your agents need to track multi-phase workflows (e.g., scoping -> research -> writing).

Prerequisites:

- Chat model must have a `current_phase` string column
- Chat model must include `Observ::ObservabilityInstrumentation`
- Run: rails generate observ:add_phase_tracking

Usage:

class Chat < ApplicationRecord
include Observ::ObservabilityInstrumentation
include Observ::AgentPhaseable
end

Example:

chat = Chat.create!
chat.transition_to_phase('research')
chat.current_phase # => 'research'

Instance Method Summary collapse

Instance Method Details

#allowed_phases ⇒ Array<String>

Get a list of allowed phases Override this method in your Chat model to define valid phases

Example:

class Chat < ApplicationRecord
include Observ::AgentPhaseable

def allowed_phases
  %w[scoping research writing review]
end
end


118
119
120
121
122
 
# File 'app/models/concerns/observ/agent_phaseable.rb', line 118

def allowed_phases
  # Default: allow any phase
  # Override in your model to restrict to specific phases
  nil
end

#in_phase?(phase) ⇒ Boolean

Check if currently in a specific phase

Example:

chat.in_phase?('research') # => true


101
102
103
 
# File 'app/models/concerns/observ/agent_phaseable.rb', line 101

def in_phase?(phase)
  current_phase == phase.to_s
end

#observability_context ⇒ Object

Override observability_context to include phase information



48
49
50
51
52
 
# File 'app/models/concerns/observ/agent_phaseable.rb', line 48

def observability_context
  context = super
  context[:phase] = current_phase if current_phase.present?
  context
end

#observability_metadata ⇒ Object

Override observability_metadata to include phase information



41
42
43
44
45
 
# File 'app/models/concerns/observ/agent_phaseable.rb', line 41

def observability_metadata
  metadata = super
  metadata[:agent_phase] = current_phase if current_phase.present?
  metadata
end

#transition_to_phase(new_phase, **metadata) ⇒ Boolean

Transition to a new phase with observability tracking

Example:

chat.transition_to_phase('research', depth: 'deep')


63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
 
# File 'app/models/concerns/observ/agent_phaseable.rb', line 63

def transition_to_phase(new_phase, **metadata)
  old_phase = current_phase
  new_phase = new_phase.to_s

  # Validate phase if allowed_phases is defined
  if respond_to?(:allowed_phases) && !allowed_phases.include?(new_phase)
    raise ArgumentError, "Invalid phase: #{new_phase}. Allowed phases: #{allowed_phases.join(', ')}"
  end

  self.current_phase = new_phase
  save!

  # Update observability context if session exists
  if observ_session
    transition_metadata = {
      phase: new_phase,
      phase_transition: "#{old_phase || 'initial'} -> #{new_phase}"
    }.merge(metadata)

    update_observability_context(transition_metadata)
  end

  Rails.logger.info "[AgentPhase] #{self.class.name}##{id} transitioned: #{old_phase || 'initial'} -> #{new_phase}"

  true
rescue StandardError => e
  Rails.logger.error "[AgentPhase] Failed to transition to #{new_phase}: #{e.message}"
  false
end