ace-support-models 0.9.0

data/lib/ace/support/models/atoms/model_name_canonicalizer.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+module Ace
+  module Support
+    module Models
+      module Atoms
+        # Canonicalizes model names by stripping provider-specific suffixes
+        #
+        # OpenRouter uses dynamic and static suffixes that modify routing behavior
+        # but don't represent different models in the canonical model registry.
+        #
+        # @see https://openrouter.ai/docs/faq for suffix documentation
+        class ModelNameCanonicalizer
+          # OpenRouter dynamic suffixes (work across all models, modify routing)
+          OPENROUTER_DYNAMIC_SUFFIXES = %w[
+            nitro
+            floor
+            online
+          ].freeze
+
+          # OpenRouter static suffixes (apply to specific models only)
+          OPENROUTER_STATIC_SUFFIXES = %w[
+            free
+            extended
+            exacto
+            thinking
+          ].freeze
+
+          # Combined list of all known OpenRouter suffixes
+          OPENROUTER_SUFFIXES = (OPENROUTER_DYNAMIC_SUFFIXES + OPENROUTER_STATIC_SUFFIXES).freeze
+
+          # Provider-specific suffix configurations
+          # Maps provider ID to array of suffixes to strip
+          PROVIDER_SUFFIXES = {
+            "openrouter" => OPENROUTER_SUFFIXES
+          }.freeze
+
+          class << self
+            # Extract the canonical model name by stripping provider-specific suffixes
+            #
+            # @param model_id [String] The model ID (e.g., "openai/gpt-4:nitro")
+            # @param provider [String, nil] The provider ID to determine which suffixes to strip
+            # @return [String] The canonical model name (e.g., "openai/gpt-4")
+            #
+            # @example Strip OpenRouter :nitro suffix
+            #   canonicalize("openai/gpt-4:nitro", provider: "openrouter")
+            #   # => "openai/gpt-4"
+            #
+            # @example Preserve model with no suffix
+            #   canonicalize("openai/gpt-4", provider: "openrouter")
+            #   # => "openai/gpt-4"
+            #
+            # @example Non-OpenRouter provider keeps suffix
+            #   canonicalize("model:variant", provider: "other")
+            #   # => "model:variant"
+            def canonicalize(model_id, provider: nil)
+              return model_id if model_id.nil? || model_id.empty?
+
+              suffixes = PROVIDER_SUFFIXES[provider]
+              return model_id unless suffixes
+
+              strip_suffixes(model_id, suffixes)
+            end
+
+            # Check if a model ID has a known suffix for the given provider
+            #
+            # @param model_id [String] The model ID to check
+            # @param provider [String, nil] The provider ID
+            # @return [Boolean] true if the model has a strippable suffix
+            def has_suffix?(model_id, provider: nil)
+              return false if model_id.nil? || model_id.empty?
+
+              suffixes = PROVIDER_SUFFIXES[provider]
+              return false unless suffixes
+
+              suffix = extract_suffix(model_id)
+              suffix && suffixes.include?(suffix)
+            end
+
+            # Extract the suffix from a model ID if present
+            #
+            # @param model_id [String] The model ID
+            # @return [String, nil] The suffix without the colon, or nil if no suffix
+            def extract_suffix(model_id)
+              return nil if model_id.nil? || model_id.empty?
+
+              # Match the last :suffix pattern (handles model IDs like "org/model:suffix")
+              match = model_id.match(/:([^:\/]+)$/)
+              match&.captures&.first
+            end
+
+            # Get all known suffixes for a provider
+            #
+            # @param provider [String] The provider ID
+            # @return [Array<String>] Array of suffix strings (without colons)
+            def suffixes_for(provider)
+              PROVIDER_SUFFIXES[provider] || []
+            end
+
+            private
+
+            # Strip known suffixes from a model ID
+            #
+            # @param model_id [String] The model ID
+            # @param suffixes [Array<String>] Suffixes to strip
+            # @return [String] Model ID with suffix stripped
+            def strip_suffixes(model_id, suffixes)
+              suffix = extract_suffix(model_id)
+              return model_id unless suffix && suffixes.include?(suffix)
+
+              # Remove the :suffix from the end
+              model_id.sub(/:#{Regexp.escape(suffix)}$/, "")
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/support/models/atoms/provider_config_reader.rb

@@ -0,0 +1,218 @@
+# frozen_string_literal: true
+
+require "yaml"
+require "date"
+require "securerandom"
+
+module Ace
+  module Support
+    module Models
+      module Atoms
+        # Reads provider configuration files with cascade support:
+        # - Project: .ace/llm/providers/
+        # - User: ~/.ace/llm/providers/
+        # - Gem: ace-llm/.ace-defaults/llm/providers/ (single source of truth)
+        class ProviderConfigReader
+          class << self
+            # Find all provider config directories in cascade order
+            # @param config_dir [String, nil] Override config directory
+            # @return [Array<String>] List of directories (project first, then user, then gem)
+            def config_directories(config_dir: nil)
+              dirs = []
+
+              if config_dir
+                dirs << config_dir if Dir.exist?(config_dir)
+              else
+                # Project-level config
+                project_dir = project_config_dir
+                dirs << project_dir if project_dir && Dir.exist?(project_dir)
+
+                # User-level config
+                user_dir = user_config_dir
+                dirs << user_dir if user_dir && Dir.exist?(user_dir)
+
+                # Gem-level config (ace-llm/providers/)
+                gem_dir = gem_config_dir
+                dirs << gem_dir if gem_dir && Dir.exist?(gem_dir)
+              end
+
+              dirs
+            end
+
+            # Find the first writable config directory
+            # @param config_dir [String, nil] Override config directory
+            # @return [String, nil] Writable directory or nil
+            def writable_config_directory(config_dir: nil)
+              dirs = config_directories(config_dir: config_dir)
+              dirs.find { |dir| writable?(dir) }
+            end
+
+            # Read all provider configs from cascade
+            # @param config_dir [String, nil] Override config directory
+            # @return [Hash<String, Hash>] Provider name => config hash
+            def read_all(config_dir: nil)
+              configs = {}
+
+              # Read from all directories (later wins for same provider)
+              config_directories(config_dir: config_dir).reverse_each do |dir|
+                read_directory(dir).each do |name, config|
+                  configs[name] = config
+                end
+              end
+
+              configs
+            end
+
+            # Read provider configs from a specific directory
+            # @param dir [String] Directory path
+            # @return [Hash<String, Hash>] Provider name => config hash
+            def read_directory(dir)
+              configs = {}
+
+              Dir.glob(File.join(dir, "*.yml")).each do |file|
+                name = File.basename(file, ".yml")
+                next if name == "template" || name.end_with?(".example")
+
+                config = read_file(file)
+                configs[name] = config.merge("_source_file" => file) if config
+              end
+
+              configs
+            end
+
+            # Read a single provider config file
+            # @param path [String] File path
+            # @return [Hash, nil] Parsed YAML or nil on error
+            def read_file(path)
+              return nil unless File.exist?(path)
+
+              content = File.read(path)
+              YAML.safe_load(content, permitted_classes: [Symbol, Date])
+            rescue Errno::EACCES => e
+              raise CacheError, "Permission denied reading #{path}: #{e.message}"
+            rescue Psych::SyntaxError => e
+              raise ConfigError, "Invalid YAML in #{path}: #{e.message}"
+            end
+
+            # Extract models list from a provider config
+            # @param config [Hash] Provider config
+            # @return [Array<String>] List of model IDs
+            def extract_models(config)
+              models = config["models"]
+              return [] unless models
+
+              case models
+              when Array
+                models
+              when Hash
+                models.keys
+              else
+                []
+              end
+            end
+
+            # Extract models.dev provider ID from config
+            # Falls back to provider name if not specified
+            # @param config [Hash] Provider config
+            # @return [String] models.dev provider ID
+            def extract_models_dev_id(config)
+              config["models_dev_id"] || config["name"]
+            end
+
+            # Extract last_synced date from config
+            # @param config [Hash] Provider config
+            # @return [Date, nil] Last sync date or nil
+            def extract_last_synced(config)
+              value = config["last_synced"]
+              return nil unless value
+
+              case value
+              when Date
+                value
+              when String
+                Date.parse(value)
+              end
+            rescue ArgumentError
+              nil
+            end
+
+            private
+
+            def project_config_dir
+              # Use ace-core if available and has project_root method
+              if defined?(Ace::Core) && Ace::Core.respond_to?(:project_root)
+                project_root = Ace::Core.project_root
+                return File.join(project_root, ".ace", "llm", "providers") if project_root
+              end
+
+              # Fallback: traverse up from current dir looking for .ace or .git
+              find_project_root_dir
+            end
+
+            def user_config_dir
+              home = ENV["HOME"]
+              return nil unless home
+
+              File.join(home, ".ace", "llm", "providers")
+            end
+
+            def gem_config_dir
+              # Find ace-llm gem's providers directory (from .ace-defaults/ - single source of truth)
+              if defined?(Ace::LLM)
+                # Try to find via gem spec
+                spec = begin
+                  Gem::Specification.find_by_name("ace-llm")
+                rescue
+                  nil
+                end
+                return File.join(spec.gem_dir, ".ace-defaults", "llm", "providers") if spec
+              end
+
+              # Fallback: look relative to this gem in mono-repo development
+              # This enables development without installing ace-llm as a gem.
+              # Production/installed gem use goes through Gem::Specification above.
+              ace_llm_path = find_ace_llm_path
+              File.join(ace_llm_path, ".ace-defaults", "llm", "providers") if ace_llm_path
+            end
+
+            def find_project_root_dir
+              dir = Dir.pwd
+              while dir != "/"
+                if Dir.exist?(File.join(dir, ".ace")) || Dir.exist?(File.join(dir, ".git"))
+                  return File.join(dir, ".ace", "llm", "providers")
+                end
+                dir = File.dirname(dir)
+              end
+              nil
+            end
+
+            def find_ace_llm_path
+              # Look in common locations relative to this gem
+              candidates = [
+                File.expand_path("../../../../../../ace-llm", __FILE__),
+                File.expand_path("../../../../../../../ace-llm", __FILE__)
+              ]
+
+              candidates.find { |path| Dir.exist?(path) }
+            end
+
+            def writable?(dir)
+              return false unless Dir.exist?(dir)
+
+              # Initialize test_file before begin block to ensure it's available in ensure
+              test_file = File.join(dir, ".write_test_#{Process.pid}_#{SecureRandom.hex(4)}")
+              begin
+                File.write(test_file, "test")
+                true
+              rescue Errno::EACCES, Errno::EROFS
+                false
+              ensure
+                File.delete(test_file) if File.exist?(test_file)
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/support/models/atoms/provider_config_writer.rb

@@ -0,0 +1,230 @@
+# frozen_string_literal: true
+
+require "yaml"
+require "fileutils"
+require "date"
+
+module Ace
+  module Support
+    module Models
+      module Atoms
+        # Writes provider configuration files, preserving structure
+        # Updates only the models: section while keeping other fields intact
+        class ProviderConfigWriter
+          class << self
+            # Update the models list in a provider config file
+            # @param path [String] Path to config file
+            # @param models [Array<String>] New list of model IDs
+            # @return [Boolean] true on success
+            # @raise [ConfigError] on write errors
+            def update_models(path, models)
+              content = read_file_content(path)
+              raise ConfigError, "Config file not found: #{path}" unless content
+
+              updated_content = replace_models_section(content, models)
+              write_file(path, updated_content)
+              true
+            end
+
+            # Write a complete config file
+            # @param path [String] Path to config file
+            # @param config [Hash] Config hash
+            # @return [Boolean] true on success
+            def write(path, config)
+              ensure_directory(File.dirname(path))
+              content = YAML.dump(config)
+              write_file(path, content)
+              true
+            end
+
+            # Create a backup of a config file
+            # @param path [String] Path to config file
+            # @return [String] Path to backup file
+            def backup(path)
+              return nil unless File.exist?(path)
+
+              timestamp = Time.now.strftime("%Y%m%d_%H%M%S")
+              backup_path = "#{path}.backup.#{timestamp}"
+              FileUtils.cp(path, backup_path)
+              backup_path
+            end
+
+            # Update the last_synced field in a provider config file
+            # @param path [String] Path to config file
+            # @param date [Date] Date to set (defaults to today)
+            # @return [Boolean] true on success
+            # @raise [ConfigError] on write errors
+            def update_last_synced(path, date = Date.today)
+              content = read_file_content(path)
+              raise ConfigError, "Config file not found: #{path}" unless content
+
+              updated_content = replace_or_add_field(content, "last_synced", date.to_s)
+              write_file(path, updated_content)
+              true
+            end
+
+            # Update both models and last_synced in one operation
+            # @param path [String] Path to config file
+            # @param models [Array<String>] New list of model IDs
+            # @param date [Date] Date to set for last_synced
+            # @return [Boolean] true on success
+            def update_models_and_sync_date(path, models, date = Date.today)
+              content = read_file_content(path)
+              raise ConfigError, "Config file not found: #{path}" unless content
+
+              updated_content = replace_models_section(content, models)
+              updated_content = replace_or_add_field(updated_content, "last_synced", date.to_s)
+              write_file(path, updated_content)
+              true
+            end
+
+            private
+
+            def read_file_content(path)
+              return nil unless File.exist?(path)
+
+              File.read(path)
+            rescue Errno::EACCES => e
+              raise ConfigError, "Permission denied reading #{path}: #{e.message}"
+            end
+
+            def write_file(path, content)
+              # Validate YAML before writing to catch regex manipulation errors
+              YAML.safe_load(content, permitted_classes: [Symbol, Date])
+              File.write(path, content)
+            rescue Psych::SyntaxError => e
+              raise ConfigError, "Generated invalid YAML for #{path}: #{e.message}"
+            rescue Errno::EACCES => e
+              raise ConfigError, "Permission denied writing #{path}: #{e.message}"
+            rescue Errno::ENOSPC => e
+              raise ConfigError, "No space left writing #{path}: #{e.message}"
+            rescue Errno::EROFS => e
+              raise ConfigError, "Read-only filesystem: #{path}: #{e.message}"
+            end
+
+            def ensure_directory(dir)
+              FileUtils.mkdir_p(dir) unless Dir.exist?(dir)
+            rescue Errno::EACCES => e
+              raise ConfigError, "Permission denied creating directory #{dir}: #{e.message}"
+            end
+
+            # Replace the models section in YAML content while preserving structure
+            # @param content [String] Original YAML content
+            # @param models [Array<String>] New models list
+            # @return [String] Updated content
+            # @raise [ConfigError] if unsupported YAML styles are detected
+            def replace_models_section(content, models)
+              # Check for flow-style arrays which are not supported
+              if /^\s*models:\s*\[/m.match?(content)
+                raise ConfigError, "Flow-style arrays (models: [...]) are not supported for auto-update. " \
+                                   "Please convert to block style (models: followed by list items)."
+              end
+
+              # Check for inline comments on models: line which are not preserved
+              if /^\s*models:\s*#/m.match?(content)
+                raise ConfigError, "Inline comments on 'models:' line (e.g., 'models: # comment') are not supported. " \
+                                   "Please move the comment to a separate line above 'models:'."
+              end
+
+              lines = content.lines
+              result = []
+              in_models_section = false
+              models_base_indent = 0
+
+              lines.each do |line|
+                # Detect start of models section (with or without items on same line)
+                if line =~ /^(\s*)models:\s*$/
+                  in_models_section = true
+                  models_base_indent = $1.length
+                  result << line
+
+                  # Add new models with standard YAML indent
+                  models.each do |model|
+                    result << "#{" " * (models_base_indent + 2)}- #{model}\n"
+                  end
+                  next
+                end
+
+                # If in models section, skip old model items
+                if in_models_section
+                  # Check if this line is a list item (model entry)
+                  if line =~ /^(\s*)-\s+/
+                    item_indent = $1.length
+                    # Skip if it's at the expected indent for models (base + 0 or base + 2)
+                    if item_indent == models_base_indent || item_indent == models_base_indent + 2
+                      next
+                    end
+                  end
+
+                  # Empty line - keep but stay in models section
+                  if line.strip.empty?
+                    result << line
+                    next
+                  end
+
+                  # A new key at base level (not indented more) ends models section
+                  if line =~ /^(\s*)\S/
+                    current_indent = $1.length
+                    if current_indent <= models_base_indent
+                      in_models_section = false
+                      result << line
+                    end
+                    # Otherwise skip (shouldn't happen for well-formed YAML)
+                  end
+                  next
+                end
+
+                result << line
+              end
+
+              result.join
+            end
+
+            # Replace or add a field in YAML content
+            # @param content [String] Original YAML content
+            # @param field_name [String] Field name to replace or add
+            # @param value [String] New value
+            # @return [String] Updated content
+            def replace_or_add_field(content, field_name, value)
+              lines = content.lines
+
+              # Try to find and replace existing field
+              field_found = false
+              result = lines.map do |line|
+                if line =~ /^(\s*)#{Regexp.escape(field_name)}:\s*(.*)$/
+                  field_found = true
+                  "#{$1}#{field_name}: #{value}\n"
+                else
+                  line
+                end
+              end
+
+              # If field not found, add it after the name or first line
+              unless field_found
+                insert_index = 0
+                result.each_with_index do |line, idx|
+                  if /^name:/.match?(line)
+                    insert_index = idx + 1
+                    break
+                  end
+                end
+                # If no name field, add after first non-comment, non-blank line
+                if insert_index == 0
+                  result.each_with_index do |line, idx|
+                    next if line.strip.empty? || line.strip.start_with?("#") || line.strip.start_with?("---")
+
+                    insert_index = idx + 1
+                    break
+                  end
+                end
+                result.insert(insert_index, "#{field_name}: #{value}\n")
+              end
+
+              result.join
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/support/models/cli/commands/cache/clear.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Ace
+  module Support
+    module Models
+      module CLI
+        module Commands
+          module Cache
+            # Clear local cache
+            class Clear < Ace::Support::Cli::Command
+              include Ace::Support::Cli::Base
+
+              desc "Clear local cache"
+
+              option :json, type: :boolean, desc: "Output as JSON"
+
+              def call(**options)
+                cache_manager = Molecules::CacheManager.new
+                result = cache_manager.clear
+
+                if options[:json]
+                  puts JSON.pretty_generate(result)
+                  return
+                end
+
+                if result[:status] == :success
+                  puts "Cache cleared successfully"
+                  puts "Deleted: #{result[:deleted_files].join(", ")}" if result[:deleted_files]&.any?
+                else
+                  raise Ace::Support::Cli::Error.new(result[:message])
+                end
+              rescue => e
+                raise Ace::Support::Cli::Error.new(e.message)
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/support/models/cli/commands/cache/diff.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Ace
+  module Support
+    module Models
+      module CLI
+        module Commands
+          module Cache
+            # Show changes since last sync
+            class Diff < Ace::Support::Cli::Command
+              include Ace::Support::Cli::Base
+
+              desc "Show changes since last sync"
+
+              option :json, type: :boolean, desc: "Output as JSON"
+
+              def call(**options)
+                result = Molecules::DiffGenerator.new.generate
+
+                if options[:json]
+                  puts JSON.pretty_generate(result.to_h)
+                  return
+                end
+
+                unless result.any_changes?
+                  puts "No changes since last sync"
+                  return
+                end
+
+                if result.added_providers.any?
+                  puts "New providers:"
+                  result.added_providers.each { |p| puts "  + #{p}" }
+                  puts
+                end
+
+                if result.removed_providers.any?
+                  puts "Removed providers:"
+                  result.removed_providers.each { |p| puts "  - #{p}" }
+                  puts
+                end
+
+                if result.added_models.any?
+                  puts "New models:"
+                  result.added_models.each { |m| puts "  + #{m}" }
+                  puts
+                end
+
+                if result.removed_models.any?
+                  puts "Removed models:"
+                  result.removed_models.each { |m| puts "  - #{m}" }
+                  puts
+                end
+
+                if result.updated_models.any?
+                  puts "Updated models:"
+                  result.updated_models.each do |update|
+                    puts "  ~ #{update.model_id}: #{update.summary}"
+                  end
+                  puts
+                end
+
+                puts "Summary: #{result.summary}"
+              rescue CacheError => e
+                raise Ace::Support::Cli::Error.new(e.message)
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end