rubyllm-observ 0.5.0

data/lib/observ/asset_installer.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+module Observ
+  # Main service class for installing Observ assets in a Rails application
+  class AssetInstaller
+    attr_reader :gem_root, :app_root, :logger
+
+    DEFAULT_STYLES_DEST = "app/javascript/stylesheets/observ"
+    DEFAULT_JS_DEST = "app/javascript/controllers/observ"
+
+    # @param gem_root [String, Pathname] Root directory of the gem
+    # @param app_root [String, Pathname] Root directory of the host application
+    # @param logger [Logger, IO] Logger for output (defaults to STDOUT)
+    def initialize(gem_root:, app_root:, logger: $stdout)
+      @gem_root = Pathname.new(gem_root)
+      @app_root = Pathname.new(app_root)
+      @logger = logger
+    end
+
+    # Install assets with custom or default destinations
+    # @param styles_dest [String, nil] Custom destination for stylesheets
+    # @param js_dest [String, nil] Custom destination for JavaScript controllers
+    # @param generate_index [Boolean] Whether to generate index files
+    # @return [Hash] Installation results
+    def install(styles_dest: nil, js_dest: nil, generate_index: true)
+      styles_dest ||= DEFAULT_STYLES_DEST
+      js_dest ||= DEFAULT_JS_DEST
+
+      styles_dest_path = app_root.join(styles_dest)
+      js_dest_path = app_root.join(js_dest)
+
+      log_header(styles_dest_path, js_dest_path)
+
+      syncer = AssetSyncer.new(gem_root: gem_root, app_root: app_root, logger: logger)
+
+      # Sync stylesheets
+      styles_result = syncer.sync_stylesheets(styles_dest_path)
+      log ""
+
+      # Sync JavaScript controllers
+      js_result = syncer.sync_javascript_controllers(js_dest_path)
+      log ""
+
+      # Check controller registration if requested
+      # Note: index.js is already included in the gem's source files and gets synced,
+      # so we don't need to generate it - we just check if it's properly registered
+      registration_status = nil
+
+      if generate_index
+        generator = IndexFileGenerator.new(app_root: app_root, logger: logger)
+
+        log "Checking controller registration..."
+        log "-" * 80
+        registration_status = generator.check_main_controllers_registration
+
+        if registration_status[:suggestions]
+          registration_status[:suggestions].each { |msg| log "  #{msg}" }
+        elsif registration_status[:registered]
+          log "  ✓ Observ controllers are already registered"
+        end
+        log ""
+      end
+
+      log_footer(styles_dest_path, js_dest_path)
+
+      {
+        styles: styles_result,
+        javascript: js_result,
+        registration: registration_status,
+        paths: {
+          styles: styles_dest_path,
+          javascript: js_dest_path
+        }
+      }
+    end
+
+    # Sync existing assets (update only)
+    # @param styles_dest [String, nil] Custom destination for stylesheets
+    # @param js_dest [String, nil] Custom destination for JavaScript controllers
+    # @return [Hash] Sync results
+    def sync(styles_dest: nil, js_dest: nil)
+      install(styles_dest: styles_dest, js_dest: js_dest, generate_index: false)
+    end
+
+    private
+
+    # Log the header with configuration info
+    def log_header(styles_dest_path, js_dest_path)
+      log "=" * 80
+      log "Observ Asset Installation"
+      log "=" * 80
+      log ""
+      log "Gem location: #{gem_root}"
+      log "App location: #{app_root}"
+      log ""
+      log "Destinations:"
+      log "  Styles: #{styles_dest_path.relative_path_from(app_root)}"
+      log "  JavaScript: #{js_dest_path.relative_path_from(app_root)}"
+      log ""
+    end
+
+    # Log the footer with next steps
+    def log_footer(styles_dest_path, js_dest_path)
+      log "=" * 80
+      log "✓ Asset installation complete!"
+      log "=" * 80
+      log ""
+      log "Installed to:"
+      log "  Styles: #{styles_dest_path.relative_path_from(app_root)}"
+      log "  JavaScript: #{js_dest_path.relative_path_from(app_root)}"
+      log ""
+      log "Next steps:"
+      log "  1. Import the stylesheets in your application.scss or application.js"
+      log "  2. Ensure the controllers index imports './observ' (see above)"
+      log "  3. Restart your dev server (bin/dev)"
+      log "  4. Verify assets are loaded correctly"
+      log ""
+    end
+
+    # Log a message
+    # @param message [String] Message to log
+    def log(message)
+      if logger.respond_to?(:puts)
+        logger.puts(message)
+      else
+        logger.info(message)
+      end
+    end
+  end
+end

data/lib/observ/asset_syncer.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module Observ
+  # Service class for syncing assets from the gem to the host application
+  class AssetSyncer
+    attr_reader :gem_root, :app_root, :logger
+
+    # @param gem_root [String, Pathname] Root directory of the gem
+    # @param app_root [String, Pathname] Root directory of the host application
+    # @param logger [Logger, IO] Logger for output (defaults to STDOUT)
+    def initialize(gem_root:, app_root:, logger: $stdout)
+      @gem_root = Pathname.new(gem_root)
+      @app_root = Pathname.new(app_root)
+      @logger = logger
+    end
+
+    # Sync stylesheets to the destination path
+    # @param dest_path [String, Pathname] Destination directory
+    # @return [Hash] Statistics about the sync operation
+    def sync_stylesheets(dest_path)
+      source_path = gem_root.join("app", "assets", "stylesheets", "observ")
+      sync_files(
+        source_path: source_path,
+        dest_path: Pathname.new(dest_path),
+        pattern: "*.scss",
+        label: "stylesheets"
+      )
+    end
+
+    # Sync JavaScript controllers to the destination path
+    # @param dest_path [String, Pathname] Destination directory
+    # @return [Hash] Statistics about the sync operation
+    def sync_javascript_controllers(dest_path)
+      source_path = gem_root.join("app", "assets", "javascripts", "observ", "controllers")
+      sync_files(
+        source_path: source_path,
+        dest_path: Pathname.new(dest_path),
+        pattern: "*.js",
+        label: "JavaScript controllers"
+      )
+    end
+
+    private
+
+    # Sync files matching a pattern from source to destination
+    # @param source_path [Pathname] Source directory
+    # @param dest_path [Pathname] Destination directory
+    # @param pattern [String] File glob pattern
+    # @param label [String] Human-readable label for logging
+    # @return [Hash] Statistics about the sync operation
+    def sync_files(source_path:, dest_path:, pattern:, label:)
+      log "Syncing Observ #{label}..."
+      log "-" * 80
+
+      unless source_path.directory?
+        log "  ⚠ Source #{label} directory not found: #{source_path}"
+        return { files_copied: 0, files_skipped: 0, error: "Source directory not found" }
+      end
+
+      # Ensure destination directory exists
+      FileUtils.mkdir_p(dest_path)
+
+      files_copied = 0
+      files_skipped = 0
+
+      Dir.glob(source_path.join(pattern)).sort.each do |file|
+        filename = File.basename(file)
+        dest_file = dest_path.join(filename)
+
+        if should_copy_file?(file, dest_file)
+          FileUtils.cp(file, dest_file)
+          log "  ✓ Copied #{filename}"
+          files_copied += 1
+        else
+          log "  - Skipped #{filename} (no changes)"
+          files_skipped += 1
+        end
+      end
+
+      log ""
+      log "  Total: #{files_copied} file(s) updated, #{files_skipped} file(s) skipped"
+
+      { files_copied: files_copied, files_skipped: files_skipped }
+    end
+
+    # Determine if a file should be copied
+    # @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
+
+    # Log a message
+    # @param message [String] Message to log
+    def log(message)
+      if logger.respond_to?(:puts)
+        logger.puts(message)
+      else
+        logger.info(message)
+      end
+    end
+  end
+end

data/lib/observ/configuration.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module Observ
+  class Configuration
+    attr_accessor :prompt_management_enabled,
+                  :prompt_cache_ttl,
+                  :prompt_fallback_behavior,
+                  :prompt_cache_store,
+                  :prompt_cache_prefix,
+                  :prompt_cache_namespace,
+                  :prompt_max_versions,
+                  :prompt_default_state,
+                  :prompt_allow_production_deletion,
+                  :prompt_cache_warming_enabled,
+                  :prompt_cache_critical_prompts,
+                  :prompt_cache_monitoring_enabled,
+                  :prompt_config_schema,
+                  :prompt_config_schema_strict,
+                  :back_to_app_path,
+                  :back_to_app_label,
+                  :chat_ui_enabled,
+                  :agent_path,
+                  :pagination_per_page
+
+    def initialize
+      @prompt_management_enabled = true
+      @prompt_cache_ttl = 300 # 5 minutes
+      @prompt_fallback_behavior = :raise # or :return_nil, :use_fallback
+      @prompt_cache_store = :redis_cache_store
+      @prompt_cache_prefix = "observ:prompt"
+      @prompt_cache_namespace = "observ:prompt"
+      @prompt_max_versions = 100
+      @prompt_default_state = :production
+      @prompt_allow_production_deletion = false
+      @prompt_cache_warming_enabled = true
+      @prompt_cache_critical_prompts = []
+      @prompt_cache_monitoring_enabled = true
+      @prompt_config_schema = default_prompt_config_schema
+      @prompt_config_schema_strict = false
+      @back_to_app_path = -> { "/" }
+      @back_to_app_label = "← Back to App"
+      @chat_ui_enabled = -> { defined?(::Chat) && ::Chat.respond_to?(:acts_as_chat) }
+      @agent_path = nil # Defaults to Rails.root.join("app", "agents")
+      @pagination_per_page = 25
+    end
+
+    # Check if chat UI is enabled
+    # @return [Boolean]
+    def chat_ui_enabled?
+      return @chat_ui_enabled.call if @chat_ui_enabled.respond_to?(:call)
+      @chat_ui_enabled
+    end
+
+    # Default schema for prompt configuration validation
+    # @return [Hash]
+    def default_prompt_config_schema
+      {
+        temperature: {
+          type: :float,
+          required: false,
+          range: 0.0..2.0,
+          default: 0.7
+        },
+        max_tokens: {
+          type: :integer,
+          required: false,
+          range: 1..100000
+        },
+        top_p: {
+          type: :float,
+          required: false,
+          range: 0.0..1.0
+        },
+        frequency_penalty: {
+          type: :float,
+          required: false,
+          range: -2.0..2.0
+        },
+        presence_penalty: {
+          type: :float,
+          required: false,
+          range: -2.0..2.0
+        },
+        stop_sequences: {
+          type: :array,
+          required: false,
+          item_type: :string
+        },
+        model: {
+          type: :string,
+          required: false
+        },
+        response_format: {
+          type: :hash,
+          required: false
+        },
+        seed: {
+          type: :integer,
+          required: false
+        },
+        stream: {
+          type: :boolean,
+          required: false
+        }
+      }
+    end
+  end
+end

data/lib/observ/engine.rb

@@ -0,0 +1,50 @@
+module Observ
+  class Engine < ::Rails::Engine
+    isolate_namespace Observ
+
+    config.generators do |g|
+      g.test_framework :rspec
+      g.fixture_replacement :factory_bot
+      g.factory_bot dir: "spec/factories"
+    end
+
+    # Make concerns available to host app
+    initializer "observ.load_concerns" do
+      config.to_prepare do
+        Dir[Observ::Engine.root.join("app", "models", "concerns", "observ", "*.rb")].each do |concern|
+          require_dependency concern
+        end
+      end
+    end
+
+    # Asset configuration
+    initializer "observ.assets" do |app|
+      # Add engine assets to the asset pipeline
+      if app.config.respond_to?(:assets)
+        app.config.assets.paths << root.join("app/assets/stylesheets")
+        app.config.assets.paths << root.join("app/assets/javascripts")
+        app.config.assets.precompile += %w[ observ/application.css observ/application.js ]
+      end
+    end
+
+    # Configure cache warming
+    initializer "observ.configure_cache" do |app|
+      config.after_initialize do
+        next unless Observ.config.prompt_cache_warming_enabled
+
+        # Warm cache asynchronously to avoid blocking boot
+        Thread.new do
+          sleep 2  # Wait for app to fully boot
+          begin
+            if defined?(Observ::PromptManager)
+              Observ::PromptManager.warm_cache(Observ.config.prompt_cache_critical_prompts)
+              Rails.logger.info "Observ cache warming completed"
+            end
+          rescue => e
+            Rails.logger.error "Observ cache warming failed: #{e.message}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/observ/index_file_generator.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+module Observ
+  # Service class for generating index files for Stimulus controllers
+  class IndexFileGenerator
+    attr_reader :app_root, :logger
+
+    # @param app_root [String, Pathname] Root directory of the host application
+    # @param logger [Logger, IO] Logger for output (defaults to STDOUT)
+    def initialize(app_root:, logger: $stdout)
+      @app_root = Pathname.new(app_root)
+      @logger = logger
+    end
+
+    # Generate or update the Observ controllers index file
+    # @param controllers_path [String, Pathname] Path to the controllers directory
+    # @return [Hash] Result of the operation
+    def generate_controllers_index(controllers_path)
+      controllers_path = Pathname.new(controllers_path)
+      index_file = controllers_path.join("index.js")
+      file_existed = index_file.exist?
+
+      # Find all controller files
+      controller_files = Dir.glob(controllers_path.join("*_controller.js")).sort
+
+      if controller_files.empty?
+        log "  ⚠ No controller files found in #{controllers_path}"
+        return { created: false, error: "No controller files found" }
+      end
+
+      content = generate_index_content(controller_files, controllers_path)
+
+      if file_existed
+        existing_content = File.read(index_file)
+        if existing_content == content
+          log "  - Index file already up to date: #{index_file.relative_path_from(app_root)}"
+          return { created: false, updated: false, path: index_file }
+        else
+          log "  ✓ Updated index file: #{index_file.relative_path_from(app_root)}"
+        end
+      else
+        log "  ✓ Created index file: #{index_file.relative_path_from(app_root)}"
+      end
+
+      File.write(index_file, content)
+      { created: !file_existed, updated: file_existed, path: index_file }
+    end
+
+    # Check if Observ controllers are registered in the main controllers index
+    # @return [Hash] Registration status and suggestions
+    def check_main_controllers_registration
+      main_index = app_root.join("app", "javascript", "controllers", "index.js")
+
+      unless main_index.exist?
+        return {
+          registered: false,
+          main_index_exists: false,
+          suggestions: [
+            "Main controllers index file not found at: #{main_index.relative_path_from(app_root)}",
+            "You may need to manually import Observ controllers in your application"
+          ]
+        }
+      end
+
+      content = File.read(main_index)
+      registered = content.include?("observ")
+
+      if registered
+        { registered: true, main_index_exists: true, path: main_index }
+      else
+        {
+          registered: false,
+          main_index_exists: true,
+          path: main_index,
+          suggestions: [
+            "Add to #{main_index.relative_path_from(app_root)}:",
+            "  import './observ'"
+          ]
+        }
+      end
+    end
+
+    # Generate import statement for main controllers index
+    # @param relative_path [String] Relative path to observ controllers
+    # @return [String] Import statement
+    def generate_import_statement(relative_path = "./observ")
+      "\nimport '#{relative_path}'\n"
+    end
+
+    private
+
+    # Generate the content for the controllers index file
+    # @param controller_files [Array<String>] List of controller file paths
+    # @param controllers_path [Pathname] Base path for controllers
+    # @return [String] Generated content
+    def generate_index_content(controller_files, controllers_path)
+      imports = controller_files.map do |file|
+        basename = File.basename(file)
+        controller_name = basename.sub("_controller.js", "").tr("_", "-")
+        class_name = basename.sub(".js", "")
+          .split("_")
+          .map(&:capitalize)
+          .join
+          .sub("Controller", "Controller")
+
+        "import #{class_name} from \"./#{basename}\""
+      end
+
+      registrations = controller_files.map do |file|
+        basename = File.basename(file)
+        controller_name = basename.sub("_controller.js", "").tr("_", "-")
+        class_name = basename.sub(".js", "")
+          .split("_")
+          .map(&:capitalize)
+          .join
+          .sub("Controller", "Controller")
+
+        "application.register(\"observ--#{controller_name}\", #{class_name})"
+      end
+
+      <<~JAVASCRIPT
+        // Auto-generated index file for Observ Stimulus controllers
+        // Register all Observ controllers with the observ-- prefix
+        import { application } from "../application"
+
+        #{imports.join("\n")}
+
+        #{registrations.join("\n")}
+      JAVASCRIPT
+    end
+
+    # Log a message
+    # @param message [String] Message to log
+    def log(message)
+      if logger.respond_to?(:puts)
+        logger.puts(message)
+      else
+        logger.info(message)
+      end
+    end
+  end
+end

data/lib/observ/instrumenter/ruby_llm.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+# This file is only loaded if RubyLLM is defined
+# It provides the instrumentation hooks for RubyLLM chat tracking
+
+# RubyLLM instrumentation will be available through ChatInstrumenter service

data/lib/observ/version.rb

@@ -0,0 +1,3 @@
+module Observ
+  VERSION = "0.5.0"
+end

data/lib/observ.rb

@@ -0,0 +1,29 @@
+require "observ/version"
+require "observ/engine"
+require "observ/configuration"
+require "observ/asset_syncer"
+require "observ/asset_installer"
+require "observ/index_file_generator"
+require "kaminari"
+require "aasm"
+require "ruby_llm"
+require "ruby_llm/schema"
+require "csv"
+
+module Observ
+  class << self
+    attr_accessor :configuration
+  end
+
+  def self.configure
+    self.configuration ||= Configuration.new
+    yield(configuration)
+  end
+
+  def self.config
+    self.configuration ||= Configuration.new
+  end
+end
+
+# RubyLLM integration
+require "observ/instrumenter/ruby_llm"

data/lib/tasks/observ_tasks.rake

@@ -0,0 +1,75 @@
+namespace :observ do
+  desc "Sync Observ engine assets (CSS and JS) to main app
+
+  Usage:
+    rails observ:sync_assets                    # Use default destinations
+    rails observ:sync_assets[custom/path]       # Custom destination for styles
+    rails observ:sync_assets[styles,js]         # Custom destinations for both
+
+  Examples:
+    rails observ:sync_assets
+    rails observ:sync_assets[app/javascript/stylesheets/observ]
+    rails observ:sync_assets[app/assets/stylesheets/observ,app/javascript/controllers/observ]
+  "
+  task :sync_assets, [ :styles_dest, :js_dest ] => :environment do |t, args|
+    require "observ/asset_installer"
+
+    # Get the observ gem root (this task is in observ/lib/tasks)
+    # The gem is mounted as an engine within the Rails app
+    observ_gem_root = Observ::Engine.root
+
+    # Main Rails app root
+    app_root = Rails.root
+
+    # Use provided paths or let AssetInstaller use defaults
+    installer = Observ::AssetInstaller.new(
+      gem_root: observ_gem_root,
+      app_root: app_root,
+      logger: $stdout
+    )
+
+    installer.sync(
+      styles_dest: args[:styles_dest],
+      js_dest: args[:js_dest]
+    )
+  end
+
+  desc "Install Observ assets for the first time (includes index file generation)
+
+  Usage:
+    rails observ:install_assets                 # Use default destinations
+    rails observ:install_assets[custom/path]    # Custom destination for styles
+    rails observ:install_assets[styles,js]      # Custom destinations for both
+
+  Examples:
+    rails observ:install_assets
+    rails observ:install_assets[app/javascript/stylesheets/observ]
+    rails observ:install_assets[app/assets/stylesheets/observ,app/javascript/controllers/observ]
+  "
+  task :install_assets, [ :styles_dest, :js_dest ] => :environment do |t, args|
+    require "observ/asset_installer"
+
+    # Get the observ gem root
+    observ_gem_root = Observ::Engine.root
+
+    # Main Rails app root
+    app_root = Rails.root
+
+    # Use provided paths or let AssetInstaller use defaults
+    installer = Observ::AssetInstaller.new(
+      gem_root: observ_gem_root,
+      app_root: app_root,
+      logger: $stdout
+    )
+
+    installer.install(
+      styles_dest: args[:styles_dest],
+      js_dest: args[:js_dest],
+      generate_index: true
+    )
+  end
+end
+
+# Provide shorthand aliases
+task "observ:sync" => "observ:sync_assets"
+task "observ:install" => "observ:install_assets"