rubyllm-observ 0.5.0

data/db/migrate/013_create_observ_dataset_run_items.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+class CreateObservDatasetRunItems < ActiveRecord::Migration[7.0]
+  def change
+    create_table :observ_dataset_run_items do |t|
+      t.references :dataset_run, null: false, foreign_key: { to_table: :observ_dataset_runs }
+      t.references :dataset_item, null: false, foreign_key: { to_table: :observ_dataset_items }
+      t.references :trace, foreign_key: { to_table: :observ_traces }
+      t.references :observation, foreign_key: { to_table: :observ_observations }
+      t.text :error
+      t.timestamps
+
+      t.index [ :dataset_run_id, :dataset_item_id ], unique: true, name: "idx_run_items_on_run_and_item"
+    end
+  end
+end

data/db/migrate/014_create_observ_scores.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+class CreateObservScores < ActiveRecord::Migration[7.0]
+  def change
+    create_table :observ_scores do |t|
+      t.references :dataset_run_item, null: false, foreign_key: { to_table: :observ_dataset_run_items }
+      t.references :trace, null: false, foreign_key: { to_table: :observ_traces }
+      t.references :observation, foreign_key: { to_table: :observ_observations }
+
+      t.string :name, null: false
+      t.decimal :value, precision: 10, scale: 4, null: false
+      t.integer :data_type, default: 0, null: false
+      t.integer :source, default: 0, null: false
+
+      t.text :comment
+      t.string :string_value
+      t.string :created_by
+
+      t.timestamps
+
+      t.index [ :dataset_run_item_id, :name, :source ], unique: true, name: "idx_scores_on_run_item_name_source"
+      t.index [ :trace_id, :name ]
+      t.index :name
+    end
+  end
+end

data/lib/generators/observ/add_phase_tracking/add_phase_tracking_generator.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/active_record"
+
+module Observ
+  module Generators
+    # Generator for adding phase tracking to Observ chats
+    #
+    # This generator adds the ability to track multi-phase agent workflows
+    # by adding a current_phase column and including the AgentPhaseable concern.
+    #
+    # Prerequisites:
+    #   - Observ chat feature already installed (rails generate observ:install:chat)
+    #   - Chat model exists at app/models/chat.rb
+    #   - ObservChatEnhancements concern exists
+    #
+    # Usage:
+    #   rails generate observ:add_phase_tracking
+    #
+    # What it does:
+    #   1. Adds current_phase column to chats table
+    #   2. Includes Observ::AgentPhaseable in ObservChatEnhancements
+    #
+    class AddPhaseTrackingGenerator < Rails::Generators::Base
+      include ActiveRecord::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+
+      def check_prerequisites
+        say "\n"
+        say "=" * 80, :cyan
+        say "Adding Phase Tracking to Observ Chats", :cyan
+        say "=" * 80, :cyan
+        say "\n"
+
+        check_chat_model_exists
+        check_concern_exists
+      end
+
+      def create_migration
+        say "Creating migration for current_phase column...", :cyan
+        say "-" * 80, :cyan
+
+        migration_template "migration.rb.tt",
+                          "db/migrate/add_phase_tracking_to_chats.rb"
+
+        say "  ✓ Created migration for current_phase column", :green
+        say "\n"
+      end
+
+      def update_chat_enhancements
+        say "Updating ObservChatEnhancements concern...", :cyan
+        say "-" * 80, :cyan
+
+        concern_path = Rails.root.join("app/models/concerns/observ_chat_enhancements.rb")
+        concern_content = File.read(concern_path)
+
+        if concern_content.include?("Observ::AgentPhaseable")
+          say "  ⚠ AgentPhaseable already included in ObservChatEnhancements", :yellow
+        else
+          inject_into_file concern_path,
+                          after: "include Observ::ObservabilityInstrumentation\n" do
+            "    include Observ::AgentPhaseable\n"
+          end
+          say "  ✓ Included AgentPhaseable in ObservChatEnhancements", :green
+        end
+
+        say "\n"
+      end
+
+      def show_post_install_instructions
+        say "\n"
+        say "=" * 80, :green
+        say "Phase Tracking Installation Complete!", :green
+        say "=" * 80, :green
+        say "\n"
+
+        say "Next steps:", :cyan
+        say "\n"
+
+        say "1. Run migrations:", :cyan
+        say "   rails db:migrate", :white
+        say "\n"
+
+        say "2. (Optional) Define allowed phases in your Chat model:", :cyan
+        say "   # app/models/chat.rb", :white
+        say "   class Chat < ApplicationRecord", :white
+        say "     # ...", :white
+        say "     def allowed_phases", :white
+        say "       %w[scoping research writing review]", :white
+        say "     end", :white
+        say "   end", :white
+        say "\n"
+
+        say "3. Use phase transitions in your agents:", :cyan
+        say "   chat.transition_to_phase('research')", :white
+        say "   chat.in_phase?('research') # => true", :white
+        say "   chat.current_phase # => 'research'", :white
+        say "\n"
+
+        say "Documentation:", :cyan
+        say "  • See app/models/concerns/observ/agent_phaseable.rb for full API", :white
+        say "\n"
+      end
+
+      private
+
+      def check_chat_model_exists
+        unless File.exist?(Rails.root.join("app/models/chat.rb"))
+          raise Thor::Error, <<~ERROR
+            Chat model not found!
+
+            This generator requires the Chat model to exist.
+
+            Please run:
+              rails generate observ:install:chat
+              rails db:migrate
+            #{'  '}
+            Then run this generator again.
+          ERROR
+        end
+        say "  ✓ Chat model found", :green
+      end
+
+      def check_concern_exists
+        concern_path = Rails.root.join("app/models/concerns/observ_chat_enhancements.rb")
+        unless File.exist?(concern_path)
+          raise Thor::Error, <<~ERROR
+            ObservChatEnhancements concern not found!
+
+            This generator requires observ:install:chat to be run first.
+
+            Please run:
+              rails generate observ:install:chat
+              rails db:migrate
+            #{'  '}
+            Then run this generator again.
+          ERROR
+        end
+        say "  ✓ ObservChatEnhancements concern found", :green
+      end
+
+      # Helper for migration timestamps
+      def migration_version
+        "[#{Rails::VERSION::MAJOR}.#{Rails::VERSION::MINOR}]"
+      end
+    end
+  end
+end

data/lib/generators/observ/add_phase_tracking/templates/migration.rb.tt

@@ -0,0 +1,6 @@
+class AddPhaseTrackingToChats < ActiveRecord::Migration<%= migration_version %>
+  def change
+    add_column :chats, :current_phase, :string
+    add_index :chats, :current_phase
+  end
+end

data/lib/generators/observ/install/USAGE

@@ -0,0 +1,27 @@
+Description:
+    Install Observ assets (stylesheets and JavaScript controllers) in your Rails application.
+    
+    This generator will:
+    - Copy Observ stylesheets to your app
+    - Copy Observ JavaScript Stimulus controllers to your app
+    - Generate index files for easy importing
+    - Check if controllers are properly registered
+
+Examples:
+    rails generate observ:install
+
+        This will install assets to default locations:
+        - Styles: app/javascript/stylesheets/observ
+        - JavaScript: app/javascript/controllers/observ
+
+    rails generate observ:install --styles-dest=app/assets/stylesheets/observ
+
+        This will install stylesheets to a custom location
+
+    rails generate observ:install --js-dest=app/javascript/controllers/custom_observ
+
+        This will install JavaScript controllers to a custom location
+
+    rails generate observ:install --skip-index
+
+        This will skip generation of index files (useful if you want to manage imports manually)

data/lib/generators/observ/install/install_generator.rb

@@ -0,0 +1,270 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "observ/asset_installer"
+
+module Observ
+  module Generators
+    # Generator for installing Observ assets in a Rails application
+    #
+    # Usage:
+    #   rails generate observ:install
+    #   rails generate observ:install --styles-dest=custom/path
+    #   rails generate observ:install --js-dest=custom/path
+    #   rails generate observ:install --skip-index
+    #   rails generate observ:install --skip-routes  # Don't auto-mount engine
+    #   rails generate observ:install --force        # Skip confirmation prompt
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      class_option :styles_dest,
+                   type: :string,
+                   desc: "Destination path for stylesheets (default: app/javascript/stylesheets/observ)",
+                   default: nil
+
+      class_option :js_dest,
+                   type: :string,
+                   desc: "Destination path for JavaScript controllers (default: app/javascript/controllers/observ)",
+                   default: nil
+
+      class_option :skip_index,
+                   type: :boolean,
+                   desc: "Skip generation of index files",
+                   default: false
+
+      class_option :force,
+                   type: :boolean,
+                   desc: "Skip confirmation prompt",
+                   default: false
+
+      class_option :skip_routes,
+                   type: :boolean,
+                   desc: "Skip automatic route mounting",
+                   default: false
+
+      def confirm_installation
+        return if options[:force]
+
+        styles_dest = options[:styles_dest] || Observ::AssetInstaller::DEFAULT_STYLES_DEST
+        js_dest = options[:js_dest] || Observ::AssetInstaller::DEFAULT_JS_DEST
+
+        say "\n"
+        say "=" * 80, :cyan
+        say "Observ Installation", :cyan
+        say "=" * 80, :cyan
+        say "\n"
+
+        # Collect files that will actually be copied
+        stylesheets_to_copy = collect_files_to_copy("stylesheets", "*.scss", styles_dest)
+        js_files_to_copy = collect_files_to_copy("javascripts", "*.js", js_dest)
+        index_will_be_generated = !options[:skip_index] && will_generate_index?(js_dest)
+        route_will_be_added = !options[:skip_routes] && !route_already_exists?
+
+        # Check if there are any changes to make
+        total_changes = stylesheets_to_copy.count + js_files_to_copy.count +
+                       (index_will_be_generated ? 1 : 0) + (route_will_be_added ? 1 : 0)
+
+        if total_changes == 0
+          say "No changes needed - all files are up to date!", :green
+          say "\n"
+          return
+        end
+
+        say "The following changes will be made:", :yellow
+        say "\n"
+
+        # Show stylesheet files that will be copied
+        if stylesheets_to_copy.any?
+          say "Stylesheets (#{stylesheets_to_copy.count} files to #{styles_dest}):", :yellow
+          stylesheets_to_copy.each do |file|
+            say "  • #{File.basename(file)}", :white
+          end
+          say "\n"
+        end
+
+        # Show JavaScript files that will be copied
+        if js_files_to_copy.any?
+          say "JavaScript Controllers (#{js_files_to_copy.count} files to #{js_dest}):", :yellow
+          js_files_to_copy.each do |file|
+            say "  • #{File.basename(file)}", :white
+          end
+          say "\n"
+        end
+
+        # Show generated files
+        if index_will_be_generated
+          say "Generated Files:", :yellow
+          say "  • #{js_dest}/index.js (controller index)", :white
+          say "\n"
+        end
+
+        # Show routes
+        if route_will_be_added
+          say "Routes (will be added to config/routes.rb):", :yellow
+          say '  mount Observ::Engine, at: "/observ"', :white
+          say "\n"
+        elsif !options[:skip_routes]
+          say "Routes:", :green
+          say "  Engine already mounted in config/routes.rb", :green
+          say "\n"
+        end
+
+        unless yes?("Do you want to proceed with the installation? (y/n)", :yellow)
+          say "\nInstallation cancelled.", :red
+          exit 0
+        end
+        say "\n"
+      end
+
+      def mount_engine
+        return if options[:skip_routes]
+
+        say "Checking routes...", :cyan
+        say "-" * 80, :cyan
+
+        if route_already_exists?
+          say "  Engine already mounted in config/routes.rb", :yellow
+        else
+          route 'mount Observ::Engine, at: "/observ"'
+          say "  ✓ Added route: mount Observ::Engine, at: \"/observ\"", :green
+        end
+        say "\n"
+      end
+
+      def install_assets
+        installer = Observ::AssetInstaller.new(
+          gem_root: Observ::Engine.root,
+          app_root: Rails.root,
+          logger: GeneratorLogger.new(self)
+        )
+
+        @result = installer.install(
+          styles_dest: options[:styles_dest],
+          js_dest: options[:js_dest],
+          generate_index: !options[:skip_index]
+        )
+      end
+
+      def show_post_install_message
+        say "\n"
+        say "=" * 80, :green
+        say "Observ installed successfully!", :green
+        say "=" * 80, :green
+        say "\n"
+
+        if @result[:registration] && @result[:registration][:suggestions]
+          say "⚠ Action required:", :yellow
+          @result[:registration][:suggestions].each do |suggestion|
+            say "  #{suggestion}", :yellow
+          end
+          say "\n"
+        end
+
+        say "Next steps:", :cyan
+        say "  1. Import stylesheets in your application", :cyan
+        say "     Add to app/javascript/application.js:", :cyan
+        say "     import 'observ'", :cyan
+        say "\n"
+        say "  2. Restart your development server", :cyan
+        say "     bin/dev or rails server", :cyan
+        say "\n"
+        say "  3. Visit /observ in your browser", :cyan
+        unless options[:skip_routes]
+          say "     (Engine mounted at /observ)", :cyan
+        end
+        say "\n"
+      end
+
+      private
+
+      def route_already_exists?
+        routes_file = Rails.root.join("config/routes.rb")
+        return false unless routes_file.exist?
+
+        routes_content = File.read(routes_file)
+        routes_content.match?(/mount\s+Observ::Engine/)
+      end
+
+      # Collect only files that will actually be copied (new or modified)
+      # @param asset_type [String] "stylesheets" or "javascripts"
+      # @param pattern [String] File glob pattern (e.g., "*.scss", "*.js")
+      # @param dest_path [String] Destination directory path
+      # @return [Array<String>] List of source file paths that will be copied
+      def collect_files_to_copy(asset_type, pattern, dest_path)
+        source_path = get_source_path(asset_type)
+        return [] unless source_path.directory?
+
+        dest_path = Rails.root.join(dest_path)
+
+        files_to_copy = []
+        Dir.glob(source_path.join(pattern)).sort.each do |source_file|
+          filename = File.basename(source_file)
+          dest_file = dest_path.join(filename)
+
+          if should_copy_file?(source_file, dest_file)
+            files_to_copy << source_file
+          end
+        end
+
+        files_to_copy
+      end
+
+      # Get the source path for the given asset type
+      # @param asset_type [String] "stylesheets" or "javascripts"
+      # @return [Pathname] Source directory path
+      def get_source_path(asset_type)
+        if asset_type == "stylesheets"
+          Observ::Engine.root.join("app", "assets", "stylesheets", "observ")
+        else
+          Observ::Engine.root.join("app", "assets", "javascripts", "observ", "controllers")
+        end
+      end
+
+      # Determine if a file should be copied (matches AssetSyncer logic)
+      # @param source_file [String] Path to source file
+      # @param dest_file [Pathname] Path to destination file
+      # @return [Boolean] true if file should be copied
+      def should_copy_file?(source_file, dest_file)
+        !dest_file.exist? || !FileUtils.identical?(source_file, dest_file.to_s)
+      end
+
+      # Check if index.js will be generated (new or different content)
+      # @param js_dest [String] Destination path for JavaScript controllers
+      # @return [Boolean] true if index.js will be generated
+      def will_generate_index?(js_dest)
+        index_file = Rails.root.join(js_dest, "index.js")
+        # Index file will be generated if it doesn't exist
+        # (we don't check content as the generator always creates it)
+        !index_file.exist?
+      end
+
+      # Logger adapter for Rails generator
+      class GeneratorLogger
+        def initialize(generator)
+          @generator = generator
+        end
+
+        def puts(message)
+          # Remove color codes and special characters for cleaner output
+          clean_message = message.gsub(/[✓✗⚠-]/, "").strip
+
+          if message.include?("✓") || message.include?("Copied")
+            @generator.say("  #{clean_message}", :green)
+          elsif message.include?("⚠")
+            @generator.say("  #{clean_message}", :yellow)
+          elsif message.include?("=") || message.start_with?("Syncing", "Generating", "Checking")
+            @generator.say(clean_message, :cyan)
+          elsif message.include?("Skipped")
+            @generator.say("  #{clean_message}", :white)
+          else
+            @generator.say(clean_message)
+          end
+        end
+
+        def info(message)
+          puts(message)
+        end
+      end
+    end
+  end
+end