rubyllm-observ 0.5.0

data/app/helpers/observ/dashboard_helper.rb

@@ -0,0 +1,154 @@
+module Observ
+  module DashboardHelper
+    def format_currency(amount)
+      return "$0.00" if amount.nil? || amount.zero?
+      "$#{sprintf('%.4f', amount)}"
+    end
+
+    def format_duration_ms(ms)
+      return "0ms" if ms.nil? || ms.zero?
+      return "#{ms.round(0)}ms" if ms < 1000
+      "#{(ms / 1000.0).round(1)}s"
+    end
+
+    def format_duration_s(seconds)
+      return "0s" if seconds.nil? || seconds.zero?
+      return "#{seconds.round(1)}s" if seconds < 60
+      minutes = (seconds / 60).floor
+      remaining_seconds = (seconds % 60).round(0)
+      "#{minutes}m #{remaining_seconds}s"
+    end
+
+    def format_tokens(count)
+      return "0" if count.nil? || count.zero?
+      return count.to_s if count < 1000
+      return "#{(count / 1000.0).round(1)}K" if count < 1_000_000
+      "#{(count / 1_000_000.0).round(1)}M"
+    end
+
+    def format_number(number)
+      return "0" if number.nil? || number.zero?
+      number.to_s.reverse.gsub(/(\d{3})(?=\d)/, '\\1,').reverse
+    end
+
+    def observ_status_badge(status)
+      css_class = case status&.downcase
+      when "completed", "success"
+        "observ-badge--success"
+      when "active", "running", "in_progress"
+        "observ-badge--info"
+      when "failed", "error"
+        "observ-badge--danger"
+      else
+        "observ-badge--warning"
+      end
+
+      content_tag(:span, status&.titleize || "Unknown", class: "observ-badge #{css_class}")
+    end
+
+    def observ_trend_badge(percentage)
+      return content_tag(:span, "0%", class: "observ-trend observ-trend--neutral") if percentage.zero?
+
+      css_class = percentage.positive? ? "observ-trend--positive" : "observ-trend--negative"
+      icon = percentage.positive? ? "↑" : "↓"
+
+      content_tag(:span, class: "observ-trend #{css_class}") do
+        "#{icon} #{percentage.abs}%"
+      end
+    end
+
+    def truncate_id(id, length = 8)
+      return "" if id.nil?
+      id.to_s[0...length]
+    end
+
+    def observ_percentage(value)
+      "#{value.round(1)}%"
+    end
+
+    def observ_timestamp(time)
+      return "N/A" if time.nil?
+      time.strftime("%Y-%m-%d %H:%M:%S")
+    end
+
+    def observ_relative_time(time)
+      return "N/A" if time.nil?
+      distance_of_time_in_words_to_now(time) + " ago"
+    end
+
+    def observ_session_status(session)
+      session.end_time.present? ? "completed" : "active"
+    end
+
+    def observ_trace_status(trace)
+      trace.end_time.present? ? "completed" : "active"
+    end
+
+    def observ_model_badge(model)
+      return content_tag(:span, "Unknown", class: "observ-model-badge") if model.blank?
+
+      content_tag(:span, model, class: "observ-model-badge")
+    end
+
+    def observ_json_preview(json_data, max_length = 100)
+      return "" if json_data.nil?
+
+      text = json_data.is_a?(String) ? json_data : json_data.to_json
+      truncate(text, length: max_length)
+    end
+
+    def format_json_with_newlines(data)
+      return "" if data.nil?
+
+      # Convert to JSON with pretty formatting
+      json_string = JSON.pretty_generate(data)
+
+      # This regex finds string values in JSON and unescapes newlines within them
+      # It preserves the JSON structure while making newlines visible
+      json_string.gsub(/: "((?:[^"\\]|\\.)*)"/m) do |match|
+        content = $1
+        # Unescape the newlines in the string content
+        unescaped = content.gsub('\\n', "\n")
+                          .gsub('\\t', "\t")
+                          .gsub('\\r', "\r")
+        ': "' + unescaped + '"'
+      end
+    end
+
+    def render_json_viewer(data, compact: false)
+      return "" if data.nil?
+
+      css_classes = [ "observ-json-viewer" ]
+      css_classes << "observ-json-viewer--compact" if compact
+
+      content_tag(:div,
+        "",
+        class: css_classes.join(" "),
+        data: {
+          controller: "observ--json-viewer",
+          observ__json_viewer_data_value: data.to_json
+        }
+      )
+    end
+
+    def render_input_output(content, compact: false)
+      return "" if content.nil?
+
+      # Try to parse as JSON
+      begin
+        parsed_data = JSON.parse(content)
+        # If it's a Hash or Array, use the JSON viewer
+        if parsed_data.is_a?(Hash) || parsed_data.is_a?(Array)
+          return render_json_viewer(parsed_data, compact: compact)
+        end
+      rescue JSON::ParserError
+        # Not valid JSON, fall through to plain text display
+      end
+
+      # Display as plain text
+      css_classes = [ "observ-code-block" ]
+      css_classes << "observ-code-block--compact" if compact
+      content_tag(:pre, content, class: css_classes.join(" "))
+    end
+  end
+end

data/app/helpers/observ/datasets_helper.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Observ
+  module DatasetsHelper
+    # Returns the appropriate badge class for a run status
+    def run_status_badge_class(status)
+      case status.to_s
+      when "pending"
+        "observ-badge--default"
+      when "running"
+        "observ-badge--info"
+      when "completed"
+        "observ-badge--success"
+      when "failed"
+        "observ-badge--danger"
+      else
+        "observ-badge--default"
+      end
+    end
+
+    # Returns the appropriate badge class for a run item status
+    def run_item_status_badge_class(status)
+      case status.to_s
+      when "pending"
+        "observ-badge--default"
+      when "succeeded"
+        "observ-badge--success"
+      when "failed"
+        "observ-badge--danger"
+      else
+        "observ-badge--default"
+      end
+    end
+
+    # Formats JSON for display
+    def format_json_preview(data, max_length: 100)
+      return nil if data.blank?
+      text = data.is_a?(Hash) ? data.to_json : data.to_s
+      text.length > max_length ? "#{text[0...max_length]}..." : text
+    end
+
+    # Formats trace data for display in forms/previews
+    # Handles both JSON and string data
+    def format_trace_data(data)
+      return "" if data.blank?
+
+      if data.is_a?(Hash) || data.is_a?(Array)
+        JSON.pretty_generate(data)
+      elsif data.is_a?(String)
+        # Try to parse and pretty-print if it's JSON
+        begin
+          parsed = JSON.parse(data)
+          JSON.pretty_generate(parsed)
+        rescue JSON::ParserError
+          data
+        end
+      else
+        data.to_s
+      end
+    end
+  end
+end

data/app/helpers/observ/pagination_helper.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Observ
+  module PaginationHelper
+    # Renders pagination controls with info
+    # Usage: <%= observ_pagination(@collection) %>
+    def observ_pagination(collection)
+      return unless collection.respond_to?(:current_page)
+
+      content_tag(:div, class: "observ-pagination") do
+        safe_join([
+          pagination_info(collection),
+          pagination_links(collection)
+        ])
+      end
+    end
+
+    private
+
+    def pagination_info(collection)
+      return "" if collection.total_count.zero?
+
+      from = collection.offset_value + 1
+      to = [ collection.offset_value + collection.limit_value, collection.total_count ].min
+      total = collection.total_count
+
+      content_tag(:div, class: "observ-pagination__info") do
+        "Showing #{from}-#{to} of #{total}"
+      end
+    end
+
+    def pagination_links(collection)
+      content_tag(:div, class: "observ-pagination__links") do
+        paginate collection, theme: "observ"
+      end
+    end
+  end
+end

data/app/jobs/observ/application_job.rb

@@ -0,0 +1,4 @@
+module Observ
+  class ApplicationJob < ActiveJob::Base
+  end
+end

data/app/jobs/observ/dataset_runner_job.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Observ
+  # Background job for executing dataset evaluations asynchronously
+  #
+  # This job wraps the DatasetRunnerService to allow dataset runs
+  # to be processed in the background via ActiveJob.
+  #
+  # Usage:
+  #   DatasetRunnerJob.perform_later(dataset_run.id)
+  #
+  # The job will:
+  # - Find the dataset run by ID
+  # - Skip execution if the run is already completed or running
+  # - Execute the DatasetRunnerService
+  #
+  class DatasetRunnerJob < ApplicationJob
+    queue_as :default
+
+    # Retry on transient failures with exponential backoff
+    retry_on StandardError, wait: :polynomially_longer, attempts: 3 do |job, error|
+      # Mark the run as failed if all retries exhausted
+      dataset_run = Observ::DatasetRun.find_by(id: job.arguments.first)
+      if dataset_run
+        dataset_run.update!(
+          status: :failed,
+          metadata: dataset_run.metadata.merge(
+            error: error.message,
+            error_class: error.class.name,
+            failed_at: Time.current.iso8601,
+            retries_exhausted: true
+          )
+        )
+      end
+    end
+
+    def perform(dataset_run_id)
+      dataset_run = Observ::DatasetRun.find(dataset_run_id)
+
+      # Skip if already completed or failed
+      return if dataset_run.finished?
+
+      # Skip if already running (avoid duplicate execution)
+      return if dataset_run.running?
+
+      DatasetRunnerService.new(dataset_run).call
+    end
+  end
+end

data/app/mailers/observ/application_mailer.rb

@@ -0,0 +1,6 @@
+module Observ
+  class ApplicationMailer < ActionMailer::Base
+    default from: "from@example.com"
+    layout "mailer"
+  end
+end

data/app/models/concerns/observ/agent_phaseable.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module Observ
+  # 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'
+  #
+  module AgentPhaseable
+    extend ActiveSupport::Concern
+
+    included do
+      # Validate that the current_phase column exists
+      unless column_names.include?("current_phase")
+        raise "AgentPhaseable requires a 'current_phase' column. " \
+              "Run: rails generate observ:add_phase_tracking"
+      end
+
+      validates :current_phase,
+                inclusion: { in: :allowed_phases, allow_nil: true },
+                if: -> { respond_to?(:allowed_phases) }
+    end
+
+    # Override observability_metadata to include phase information
+    def observability_metadata
+      metadata = super
+      metadata[:agent_phase] = current_phase if current_phase.present?
+      metadata
+    end
+
+    # Override observability_context to include phase information
+    def observability_context
+      context = super
+      context[:phase] = current_phase if current_phase.present?
+      context
+    end
+
+    # Transition to a new phase with observability tracking
+    #
+    # @param new_phase [String, Symbol] The phase to transition to
+    # @param metadata [Hash] Optional additional metadata to record with the transition
+    # @return [Boolean] true if the transition was successful
+    #
+    # Example:
+    #   chat.transition_to_phase('research', depth: 'deep')
+    #
+    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
+
+    # Check if currently in a specific phase
+    #
+    # @param phase [String, Symbol] The phase to check
+    # @return [Boolean] true if in the specified phase
+    #
+    # Example:
+    #   chat.in_phase?('research') # => true
+    #
+    def in_phase?(phase)
+      current_phase == phase.to_s
+    end
+
+    # 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
+    #
+    # @return [Array<String>] List of allowed phase names
+    def allowed_phases
+      # Default: allow any phase
+      # Override in your model to restrict to specific phases
+      nil
+    end
+  end
+end

data/app/models/concerns/observ/agent_selectable.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Observ
+  # Interface contract for agents that can be selected in the Observ UI
+  # This module defines the required methods that any selectable agent must implement
+  #
+  # Usage:
+  #   class MyAgent < BaseAgent
+  #     include Observ::AgentSelectable
+  #
+  #     def self.display_name
+  #       "My Custom Agent"
+  #     end
+  #
+  #     def self.description
+  #       "Description of what this agent does"
+  #     end
+  #   end
+  module AgentSelectable
+    extend ActiveSupport::Concern
+
+    class_methods do
+      # Required: Human-readable name displayed in the UI
+      # @return [String] the display name for the agent
+      def display_name
+        raise NotImplementedError, "#{name} must implement .display_name class method"
+      end
+
+      # Required: Unique identifier for the agent (typically the class name)
+      # Used as the value in select dropdowns
+      # @return [String] the agent identifier
+      def agent_identifier
+        name
+      end
+
+      # Optional: Description of what the agent does
+      # Displayed as help text or tooltips in the UI
+      # @return [String, nil] the agent description
+      def description
+        nil
+      end
+
+      # Optional: Category for grouping agents in the UI
+      # @return [String] the category name
+      def category
+        "General"
+      end
+    end
+  end
+end

data/app/models/concerns/observ/chat_enhancements.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module Observ
+  # Concern for enhancing Chat models with observability and agent support
+  # This provides the integration between your Chat model and the Observ system
+  #
+  # Usage:
+  #   class Chat < ApplicationRecord
+  #     include Observ::ChatEnhancements
+  #
+  #     # Optional: Define agent_class method if using agents
+  #     def agent_class
+  #       return BaseAgent if agent_class_name.blank?
+  #       agent_class_name.constantize
+  #     end
+  #   end
+  module ChatEnhancements
+    extend ActiveSupport::Concern
+
+    included do
+      include Observ::ObservabilityInstrumentation
+
+      # Set the model from agent BEFORE RubyLLM's resolve_model_from_strings runs
+      # This ensures the prompt version override is applied when determining the model
+      before_save :set_model_from_agent, if: -> { respond_to?(:agent_class_name) && agent_class_name.present? }
+
+      # Initialize agent on creation (includes greeting message)
+      after_create :initialize_agent_on_create, if: -> { respond_to?(:agent_class_name) && agent_class_name.present? }
+    end
+
+    # Setup tools for the chat session
+    # Override this in your Chat model if you need custom tool setup
+    def setup_tools
+      return unless respond_to?(:agent_class)
+      agent_class.setup_tools(self)
+    end
+
+    # Ensure agent parameters are set when needed
+    # This is called lazily when the chat is actually used
+    #
+    # Note: Instructions are already set in initialize_agent_on_create (after_create callback)
+    # and should NOT be re-applied on every message. Only parameters need to be re-set
+    # because they are lost when the chat is reloaded from the database.
+    def ensure_agent_configured
+      return unless respond_to?(:agent_class) && agent_class_name.present?
+      return if @_agent_params_configured
+
+      # Set prompt version override if specified
+      if respond_to?(:prompt_version) && prompt_version.present? &&
+         agent_class.included_modules.include?(Observ::PromptManagement)
+        Thread.current[:observ_prompt_version_override] = prompt_version
+      end
+
+      begin
+        # Only re-apply parameters, not instructions
+        # Instructions were already set at creation time
+        agent_class.setup_parameters(self)
+        @_agent_params_configured = true
+      ensure
+        Thread.current[:observ_prompt_version_override] = nil
+      end
+    end
+
+    private
+
+    # Set the model from agent configuration before save
+    # This runs BEFORE RubyLLM's resolve_model_from_strings callback,
+    # ensuring the correct model is used when a specific prompt version is specified
+    def set_model_from_agent
+      return unless respond_to?(:agent_class)
+
+      # Set prompt version override if specified and agent supports prompt management
+      if respond_to?(:prompt_version) && prompt_version.present? &&
+         agent_class.included_modules.include?(Observ::PromptManagement)
+        Thread.current[:observ_prompt_version_override] = prompt_version
+      end
+
+      begin
+        # Set the model string so RubyLLM's resolve_model_from_strings uses the correct model
+        # This uses the agent's model method which respects the prompt version override
+        @model_string = agent_class.model
+      ensure
+        Thread.current[:observ_prompt_version_override] = nil
+      end
+    end
+
+    def initialize_agent_on_create
+      return unless respond_to?(:agent_class)
+
+      # If chat has a specific prompt version, temporarily set it for setup
+      if respond_to?(:prompt_version) && prompt_version.present? &&
+         agent_class.included_modules.include?(Observ::PromptManagement)
+        # Store the version temporarily so setup_instructions can use it
+        Thread.current[:observ_prompt_version_override] = prompt_version
+      end
+
+      begin
+        # Execute all agent setup steps in one consolidated callback
+        # This prevents redundant association loading between callbacks
+        agent_class.setup_instructions(self)
+        agent_class.setup_parameters(self)
+        agent_class.send_initial_greeting(self)
+      ensure
+        # Clean up thread-local storage
+        Thread.current[:observ_prompt_version_override] = nil
+      end
+    end
+  end
+end

data/app/models/concerns/observ/message_enhancements.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Observ
+  # Concern for enhancing Message models with observability and broadcasting support
+  # This provides the integration between your Message model and the Observ system
+  #
+  # Usage:
+  #   class Message < ApplicationRecord
+  #     include Observ::MessageEnhancements
+  #   end
+  module MessageEnhancements
+    extend ActiveSupport::Concern
+
+    included do
+      include Observ::TraceAssociation
+
+      # Broadcasts message updates to the chat channel
+      # Override the lambda if your chat_id attribute has a different name
+      broadcasts_to ->(message) { "chat_#{message.chat_id}" }, partial: "observ/messages/message"
+    end
+
+    # Broadcast a content chunk to the message
+    # Useful for streaming responses
+    def broadcast_append_chunk(content)
+      broadcast_append_to "chat_#{chat_id}",
+        target: "message_#{id}_content",
+        partial: "observ/messages/content",
+        locals: { content: content }
+    end
+  end
+end