ace-support-models 0.9.0

data/lib/ace/support/models/cli/providers_cli.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require "ace/support/cli"
+require "ace/core"
+require_relative "../version"
+
+# Reuse existing provider command classes
+require_relative "commands/providers/list"
+require_relative "commands/providers/show"
+require_relative "commands/providers/sync"
+
+module Ace
+  module Support
+    module Models
+      # Flat CLI registry for ace-llm-providers (LLM provider management).
+      #
+      # Replaces the nested `ace-models providers <subcommand>` pattern with
+      # flat `ace-llm-providers <command>` invocations.
+      module ProvidersCLI
+        extend Ace::Support::Cli::RegistryDsl
+
+        PROGRAM_NAME = "ace-llm-providers"
+
+        # Application commands with descriptions (for help output)
+        REGISTERED_COMMANDS = [
+          ["list", "List all available LLM providers"],
+          ["show", "Show detailed information for a provider"],
+          ["sync", "Synchronize provider configurations"]
+        ].freeze
+
+        HELP_EXAMPLES = [
+          "ace-llm-providers",
+          "ace-llm-providers show openai",
+          "ace-llm-providers sync --apply",
+          "ace-llm-providers sync -p anthropic"
+        ].freeze
+
+        # Register flat commands (reusing existing command classes)
+        register "list", CLI::Commands::Providers::List
+        register "show", CLI::Commands::Providers::Show
+        register "sync", CLI::Commands::Providers::Sync
+
+        # Register version command
+        version_cmd = Ace::Support::Cli::VersionCommand.build(
+          gem_name: PROGRAM_NAME,
+          version: VERSION
+        )
+        register "version", version_cmd
+        register "--version", version_cmd
+
+        # Register help command
+        help_cmd = Ace::Support::Cli::HelpCommand.build(
+          program_name: PROGRAM_NAME,
+          version: VERSION,
+          commands: REGISTERED_COMMANDS,
+          examples: HELP_EXAMPLES
+        )
+        register "help", help_cmd
+        register "--help", help_cmd
+        register "-h", help_cmd
+
+        # Entry point for CLI invocation (used by tests and exe/)
+        #
+        # @param args [Array<String>] Command-line arguments
+        # @return [Integer] Exit code (0 for success, non-zero for errors)
+        def self.start(args)
+          Ace::Support::Cli::Runner.new(self).call(args: args)
+        end
+      end
+    end
+  end
+end

data/lib/ace/support/models/cli.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require "ace/support/cli"
+require "json"
+require "ace/core"
+
+# Load CLI command classes (Hanami pattern: CLI::Commands::)
+require_relative "cli/commands/cache/sync"
+require_relative "cli/commands/cache/status"
+require_relative "cli/commands/cache/diff"
+require_relative "cli/commands/cache/clear"
+require_relative "cli/commands/models/search"
+require_relative "cli/commands/models/info"
+require_relative "cli/commands/models/cost"
+
+module Ace
+  module Support
+    module Models
+      # CLI for ace-models using ace-support-cli.
+      #
+      # After the split, ace-models handles cache and model operations.
+      # Provider management moved to ace-llm-providers.
+      module CLI
+        extend Ace::Support::Cli::RegistryDsl
+
+        PROGRAM_NAME = "ace-models"
+
+        # Application commands with descriptions (for help output)
+        REGISTERED_COMMANDS = [
+          ["search", "Search for models by name or pattern"],
+          ["info", "Show detailed model information"],
+          ["cost", "Calculate token cost for a model"],
+          ["sync", "Sync model cache from models.dev"],
+          ["status", "Show cache sync status"],
+          ["diff", "Show changes since last sync"],
+          ["clear", "Clear the model cache"]
+        ].freeze
+
+        HELP_EXAMPLES = [
+          "ace-models search claude              # Find models by name",
+          "ace-models info claude-sonnet-4-6     # Pricing and context window",
+          "ace-models cost claude-opus-4-6       # Token cost calculator",
+          "ace-models sync                       # Update from models.dev"
+        ].freeze
+
+        # Register flat commands (previously nested under cache/models namespaces)
+        register "search", CLI::Commands::ModelsSubcommands::Search
+        register "info", CLI::Commands::ModelsSubcommands::Info
+        register "cost", CLI::Commands::ModelsSubcommands::Cost
+        register "sync", CLI::Commands::Cache::Sync
+        register "status", CLI::Commands::Cache::Status
+        register "diff", CLI::Commands::Cache::Diff
+        register "clear", CLI::Commands::Cache::Clear
+
+        # Version command
+        version_cmd = Ace::Support::Cli::VersionCommand.build(
+          gem_name: PROGRAM_NAME,
+          version: VERSION
+        )
+        register "version", version_cmd
+        register "--version", version_cmd
+
+        # Help command
+        help_cmd = Ace::Support::Cli::HelpCommand.build(
+          program_name: PROGRAM_NAME,
+          version: VERSION,
+          commands: REGISTERED_COMMANDS,
+          examples: HELP_EXAMPLES
+        )
+        register "help", help_cmd
+        register "--help", help_cmd
+        register "-h", help_cmd
+
+        # Entry point for CLI invocation (used by tests and exe/)
+        #
+        # @param args [Array<String>] Command-line arguments
+        # @return [Integer] Exit code (0 for success, non-zero for errors)
+        def self.start(args)
+          Ace::Support::Cli::Runner.new(self).call(args: args)
+        end
+      end
+    end
+  end
+end

data/lib/ace/support/models/errors.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Ace
+  module Support
+    module Models
+      # Base error class for ace-support-models gem
+      class Error < StandardError; end
+
+      # Network-related errors
+      class NetworkError < Error; end
+
+      # API response errors
+      class ApiError < Error
+        attr_reader :status_code
+
+        def initialize(message, status_code: nil)
+          @status_code = status_code
+          super(message)
+        end
+      end
+
+      # Cache-related errors
+      class CacheError < Error; end
+
+      # Validation errors
+      class ValidationError < Error; end
+
+      # Model not found error
+      class ModelNotFoundError < ValidationError
+        attr_reader :model_id, :suggestions
+
+        def initialize(model_id, suggestions: [])
+          @model_id = model_id
+          @suggestions = suggestions
+          message = "Model '#{model_id}' not found"
+          message += ". Did you mean: #{suggestions.join(", ")}?" if suggestions.any?
+          super(message)
+        end
+      end
+
+      # Configuration errors
+      class ConfigError < Error; end
+
+      # Provider not found error
+      class ProviderNotFoundError < ValidationError
+        attr_reader :provider_id
+
+        def initialize(provider_id)
+          @provider_id = provider_id
+          super("Provider '#{provider_id}' not found")
+        end
+      end
+    end
+  end
+end

data/lib/ace/support/models/models/diff_result.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module Ace
+  module Support
+    module Models
+      module Models
+        # Represents the diff between two API versions
+        class DiffResult
+          attr_reader :added_models, :removed_models, :updated_models,
+            :added_providers, :removed_providers,
+            :previous_sync_at, :current_sync_at
+
+          # Initialize diff result
+          def initialize(attrs = {})
+            @added_models = attrs[:added_models] || []
+            @removed_models = attrs[:removed_models] || []
+            @updated_models = attrs[:updated_models] || []
+            @added_providers = attrs[:added_providers] || []
+            @removed_providers = attrs[:removed_providers] || []
+            @previous_sync_at = attrs[:previous_sync_at]
+            @current_sync_at = attrs[:current_sync_at]
+          end
+
+          # Check if there are any changes
+          # @return [Boolean]
+          def any_changes?
+            added_models.any? || removed_models.any? || updated_models.any? ||
+              added_providers.any? || removed_providers.any?
+          end
+
+          # Total number of changes
+          # @return [Integer]
+          def total_changes
+            added_models.size + removed_models.size + updated_models.size +
+              added_providers.size + removed_providers.size
+          end
+
+          # Summary string
+          # @return [String]
+          def summary
+            parts = []
+            parts << "#{added_models.size} new model(s)" if added_models.any?
+            parts << "#{removed_models.size} removed model(s)" if removed_models.any?
+            parts << "#{updated_models.size} updated model(s)" if updated_models.any?
+            parts << "#{added_providers.size} new provider(s)" if added_providers.any?
+            parts << "#{removed_providers.size} removed provider(s)" if removed_providers.any?
+
+            return "No changes" if parts.empty?
+
+            parts.join(", ")
+          end
+
+          # Convert to hash
+          # @return [Hash]
+          def to_h
+            {
+              added_models: added_models,
+              removed_models: removed_models,
+              updated_models: updated_models,
+              added_providers: added_providers,
+              removed_providers: removed_providers,
+              previous_sync_at: previous_sync_at&.iso8601,
+              current_sync_at: current_sync_at&.iso8601,
+              summary: summary
+            }
+          end
+        end
+
+        # Represents an update to a model
+        class ModelUpdate
+          attr_reader :model_id, :changes
+
+          def initialize(model_id:, changes:)
+            @model_id = model_id
+            @changes = changes
+          end
+
+          # Convert to hash
+          def to_h
+            {
+              model_id: model_id,
+              changes: changes
+            }
+          end
+
+          # Summary of changes
+          def summary
+            changes.map { |field, (old_val, new_val)| "#{field}: #{old_val} → #{new_val}" }.join(", ")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/support/models/models/model_info.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+module Ace
+  module Support
+    module Models
+      module Models
+        # Represents information about a single model
+        class ModelInfo
+          attr_reader :id, :name, :provider_id, :pricing, :context_limit, :output_limit,
+            :modalities, :capabilities, :status, :knowledge_date, :release_date,
+            :last_updated, :open_weights
+
+          # Initialize model info
+          def initialize(attrs = {})
+            @id = attrs[:id]
+            @name = attrs[:name]
+            @provider_id = attrs[:provider_id]
+            @pricing = attrs[:pricing] || PricingInfo.new
+            @context_limit = attrs[:context_limit]
+            @output_limit = attrs[:output_limit]
+            @modalities = attrs[:modalities] || {input: [], output: []}
+            @capabilities = attrs[:capabilities] || {}
+            @status = attrs[:status]
+            @knowledge_date = attrs[:knowledge_date]
+            @release_date = attrs[:release_date]
+            @last_updated = attrs[:last_updated]
+            @open_weights = attrs[:open_weights]
+          end
+
+          # Create from API hash
+          # @param hash [Hash] Model hash from API
+          # @param provider_id [String] Provider ID
+          # @return [ModelInfo] Parsed model info
+          def self.from_hash(hash, provider_id:)
+            new(
+              id: hash["id"],
+              name: hash["name"],
+              provider_id: provider_id,
+              pricing: PricingInfo.from_hash(hash["cost"]),
+              context_limit: hash.dig("limit", "context"),
+              output_limit: hash.dig("limit", "output"),
+              modalities: parse_modalities(hash["modalities"]),
+              capabilities: parse_capabilities(hash),
+              status: hash["status"],
+              knowledge_date: hash["knowledge"],
+              release_date: hash["release_date"],
+              last_updated: hash["last_updated"],
+              open_weights: hash["open_weights"]
+            )
+          end
+
+          # Full model identifier
+          # @return [String] provider:model format
+          def full_id
+            "#{provider_id}:#{id}"
+          end
+
+          # Check if model is deprecated
+          # @return [Boolean]
+          def deprecated?
+            status == "deprecated"
+          end
+
+          # Check if model is in preview/alpha/beta
+          # @return [Boolean]
+          def preview?
+            %w[alpha beta preview].include?(status)
+          end
+
+          # Check if model supports a capability
+          # @param capability [Symbol, String] Capability name
+          # @return [Boolean]
+          def supports?(capability)
+            capabilities[capability.to_sym] == true
+          end
+
+          # Convert to hash
+          # @return [Hash]
+          def to_h
+            {
+              id: id,
+              name: name,
+              provider_id: provider_id,
+              full_id: full_id,
+              pricing: pricing.to_h,
+              context_limit: context_limit,
+              output_limit: output_limit,
+              modalities: modalities,
+              capabilities: capabilities,
+              status: status,
+              knowledge_date: knowledge_date,
+              release_date: release_date,
+              last_updated: last_updated,
+              open_weights: open_weights
+            }
+          end
+
+          private
+
+          def self.parse_modalities(hash)
+            return {input: [], output: []} if hash.nil?
+
+            unless hash.is_a?(Hash)
+              warn "[ModelInfo] Unexpected modalities type: #{hash.class}, expected Hash"
+              return {input: [], output: []}
+            end
+
+            {
+              input: Array(hash["input"]),
+              output: Array(hash["output"])
+            }
+          end
+          private_class_method :parse_modalities
+
+          def self.parse_capabilities(hash)
+            {
+              attachment: hash["attachment"] == true,
+              reasoning: hash["reasoning"] == true,
+              tool_call: hash["tool_call"] == true,
+              structured_output: hash["structured_output"] == true,
+              temperature: hash["temperature"] == true
+            }
+          end
+          private_class_method :parse_capabilities
+        end
+      end
+    end
+  end
+end

data/lib/ace/support/models/models/pricing_info.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Ace
+  module Support
+    module Models
+      module Models
+        # Represents pricing information for a model (per million tokens)
+        class PricingInfo
+          attr_reader :input, :output, :reasoning, :cache_read, :cache_write
+
+          # Initialize pricing info
+          # @param input [Float, nil] Input cost per million tokens
+          # @param output [Float, nil] Output cost per million tokens
+          # @param reasoning [Float, nil] Reasoning cost per million tokens
+          # @param cache_read [Float, nil] Cache read cost per million tokens
+          # @param cache_write [Float, nil] Cache write cost per million tokens
+          def initialize(input: nil, output: nil, reasoning: nil, cache_read: nil, cache_write: nil)
+            @input = input
+            @output = output
+            @reasoning = reasoning
+            @cache_read = cache_read
+            @cache_write = cache_write
+          end
+
+          # Create from API hash
+          # @param hash [Hash] Cost hash from API
+          # @return [PricingInfo] Parsed pricing info
+          def self.from_hash(hash)
+            return new if hash.nil?
+
+            new(
+              input: hash["input"],
+              output: hash["output"],
+              reasoning: hash["reasoning"],
+              cache_read: hash["cache_read"],
+              cache_write: hash["cache_write"]
+            )
+          end
+
+          # Convert to hash
+          # @return [Hash] Pricing as hash
+          def to_h
+            {
+              input: input,
+              output: output,
+              reasoning: reasoning,
+              cache_read: cache_read,
+              cache_write: cache_write
+            }.compact
+          end
+
+          # Check if pricing data is available
+          # @return [Boolean] true if any pricing data exists
+          def available?
+            input || output
+          end
+
+          # Calculate total cost for token counts
+          # @param input_tokens [Integer] Input token count
+          # @param output_tokens [Integer] Output token count
+          # @param reasoning_tokens [Integer] Reasoning token count
+          # @return [Float] Total cost in dollars
+          def calculate(input_tokens:, output_tokens:, reasoning_tokens: 0)
+            total = 0.0
+            total += (input_tokens / 1_000_000.0) * input if input
+            total += (output_tokens / 1_000_000.0) * output if output
+            total += (reasoning_tokens / 1_000_000.0) * reasoning if reasoning && reasoning_tokens > 0
+            total
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/support/models/models/provider_info.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Ace
+  module Support
+    module Models
+      module Models
+        # Represents information about a provider
+        class ProviderInfo
+          attr_reader :id, :name, :env_keys, :npm_package, :api_url, :doc_url, :models
+
+          # Initialize provider info
+          def initialize(attrs = {})
+            @id = attrs[:id]
+            @name = attrs[:name]
+            @env_keys = attrs[:env_keys] || []
+            @npm_package = attrs[:npm_package]
+            @api_url = attrs[:api_url]
+            @doc_url = attrs[:doc_url]
+            @models = attrs[:models] || {}
+          end
+
+          # Create from API hash
+          # @param hash [Hash] Provider hash from API
+          # @return [ProviderInfo] Parsed provider info
+          def self.from_hash(hash)
+            provider_id = hash["id"]
+            models_hash = hash["models"] || {}
+
+            models = models_hash.transform_values do |model_hash|
+              ModelInfo.from_hash(model_hash, provider_id: provider_id)
+            end
+
+            new(
+              id: provider_id,
+              name: hash["name"],
+              env_keys: Array(hash["env"]),
+              npm_package: hash["npm"],
+              api_url: hash["api"],
+              doc_url: hash["doc"],
+              models: models
+            )
+          end
+
+          # Get model by ID
+          # @param model_id [String] Model ID
+          # @return [ModelInfo, nil] Model info or nil
+          def model(model_id)
+            models[model_id]
+          end
+
+          # List all model IDs
+          # @return [Array<String>] Model IDs
+          def model_ids
+            models.keys
+          end
+
+          # Count models
+          # @return [Integer] Number of models
+          def model_count
+            models.size
+          end
+
+          # Convert to hash
+          # @return [Hash]
+          def to_h
+            {
+              id: id,
+              name: name,
+              env_keys: env_keys,
+              npm_package: npm_package,
+              api_url: api_url,
+              doc_url: doc_url,
+              model_count: model_count,
+              models: models.transform_values(&:to_h)
+            }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+require "ace/core"
+
+require_relative "version"
+require_relative "errors"
+
+# Atoms - Pure functions
+require_relative "atoms/cache_path_resolver"
+require_relative "atoms/api_fetcher"
+require_relative "atoms/json_parser"
+require_relative "atoms/file_reader"
+require_relative "atoms/file_writer"
+require_relative "atoms/model_filter"
+require_relative "atoms/provider_config_reader"
+require_relative "atoms/provider_config_writer"
+require_relative "atoms/model_name_canonicalizer"
+
+# Models - Data structures
+require_relative "models/provider_info"
+require_relative "models/model_info"
+require_relative "models/pricing_info"
+require_relative "models/diff_result"
+
+# Molecules - Composed operations
+require_relative "molecules/cache_manager"
+require_relative "molecules/model_validator"
+require_relative "molecules/cost_calculator"
+require_relative "molecules/diff_generator"
+require_relative "molecules/model_searcher"
+require_relative "molecules/provider_sync_diff"
+
+# Organisms - Business logic
+require_relative "organisms/sync_orchestrator"
+require_relative "organisms/provider_sync_orchestrator"
+
+module Ace
+  module Support
+    module Models
+      API_URL = "https://models.dev/api.json"
+
+      class << self
+        # Get the default cache directory
+        # @return [String] Path to cache directory
+        def cache_dir
+          Atoms::CachePathResolver.resolve
+        end
+
+        # Sync models from API
+        # @param force [Boolean] Force sync even if cache is fresh
+        # @return [Hash] Sync result with stats
+        def sync(force: false)
+          Organisms::SyncOrchestrator.new.sync(force: force)
+        end
+
+        # Validate a model exists
+        # @param model_id [String] Model ID in format provider:model
+        # @return [Boolean] true if valid
+        # @raise [ModelNotFoundError] if model doesn't exist
+        def validate(model_id)
+          Molecules::ModelValidator.new.validate(model_id)
+        end
+
+        # Validate a model exists (returns boolean, no exception)
+        # @param model_id [String] Model ID in format provider:model
+        # @return [Boolean] true if valid, false otherwise
+        def valid?(model_id)
+          validate(model_id)
+          true
+        rescue ModelNotFoundError, ProviderNotFoundError
+          false
+        end
+
+        # Calculate cost for a query
+        # @param model_id [String] Model ID
+        # @param input_tokens [Integer] Input token count
+        # @param output_tokens [Integer] Output token count
+        # @param reasoning_tokens [Integer] Reasoning token count (optional)
+        # @return [Hash] Cost breakdown
+        def cost(model_id, input_tokens:, output_tokens:, reasoning_tokens: 0)
+          Molecules::CostCalculator.new.calculate(
+            model_id,
+            input_tokens: input_tokens,
+            output_tokens: output_tokens,
+            reasoning_tokens: reasoning_tokens
+          )
+        end
+
+        # Get diff between cached versions
+        # @return [Models::DiffResult] Changes since last sync
+        def diff
+          Molecules::DiffGenerator.new.generate
+        end
+      end
+    end
+  end
+end