ace-support-models 0.9.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 451533dc289b010f698dcd3ce6ab3e0a459a769f8a54a30431623fb78cfa3550
+  data.tar.gz: 37e77876733d1a94e9dfbf6278e848d1408492a8c8e29f18b1cd8824c562da22
+SHA512:
+  metadata.gz: 387e58aef48d5dc364aca965839d2cb883583ed9551648bc02514b565ac12a81779904634e52d9e17dc0c4b47d0a7d9b71a51548e21d6a13a47a86b189a89b9a
+  data.tar.gz: e06be949d2190b9b46a76b4e027c03808ece2356b9ac39cf534fbb0e8da1f46b4e9780f42920b34d38634a5c820e9b25ff297ed2777c8b050339ef26ce45d33a

data/CHANGELOG.md

@@ -0,0 +1,162 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.9.0] - 2026-03-23
+
+### Changed
+- Added `ace-models` and `ace-llm-providers` CLI references to README intro and new Quick Start section with usage examples.
+
+### Technical
+- Removed phantom `handbook/**/*` glob from gemspec (no handbook directory exists).
+
+## [0.8.2] - 2026-03-23
+
+### Fixed
+- Normalize provider and model data shapes in cache manager — handles wrapped (`{"providers" => ...}`), array-of-hashes, and flat hash formats so cache reads don't break when the upstream response shape varies.
+
+## [0.8.1] - 2026-03-22
+
+### Changed
+- Refreshed README structure with a dedicated purpose section, dual installation paths, a basic usage entry point, and the ACE project footer link.
+
+## [0.8.0] - 2026-03-21
+
+### Changed
+- Added initial `TS-MODELS-001` value-gated smoke E2E coverage for `ace-models` and `ace-llm-providers`, including ADD/SKIP decision evidence.
+
+## [0.7.1] - 2026-03-18
+
+### Changed
+- Migrated CLI namespace from `Ace::Core::CLI::*` to `Ace::Support::Cli::*` (ace-support-cli is now the canonical home for CLI infrastructure).
+
+
+## [0.7.0] - 2026-03-18
+
+### Changed
+- Removed legacy backward-compatibility behavior as part of the 0.10 cleanup release.
+
+
+## [0.6.3] - 2026-03-15
+
+### Changed
+- Migrated CLI framework from dry-cli to ace-support-cli
+
+## [0.6.2] - 2026-02-23
+
+### Technical
+- Updated internal dependency version constraints to current releases
+
+## [0.6.1] - 2026-02-22
+
+### Changed
+- Migrate ace-llm-providers CLI to standard help pattern
+  - Remove DefaultRouting extension and DWIM default behavior
+  - Add HelpCommand registration for `--help` and `-h`
+  - Update REGISTERED_COMMANDS to [name, description] format
+  - Add explicit start(args) method for CLI invocation
+
+## [0.6.0] - 2026-02-22
+
+### Added
+- Migrate CLI to standard help pattern with HelpCommand
+  - Register `--help` and `-h` for formatted help output
+  - No args now shows help instead of command list
+
+### Changed
+- Remove DefaultRouting extension and DWIM default behavior
+  - Remove KNOWN_COMMANDS, DEFAULT_COMMAND, BUILTIN_COMMANDS constants
+  - Update REGISTERED_COMMANDS to [name, description] format
+  - Convert HELP_EXAMPLES to simple string array
+  - Add explicit start(args) method for CLI invocation
+- Centralize CLI help routing and formatting (shared with ace-support-core)
+- Centralize CLI error handling and exit code management (shared)
+
+### Technical
+- Update CLI command usage in README
+- Lower Ruby version requirement to >= 3.2.0
+
+## [0.5.2] - 2026-02-02
+
+### Technical
+- Update support-packages metadata
+
+## [0.5.1] - 2026-01-15
+
+### Changed
+- Migrate CLI commands to Hanami pattern
+  - Move commands from `commands/` to `cli/commands/`
+  - Update namespace from `Commands::*` to `CLI::Commands::*`
+  - Models subcommands use `ModelsSubcommands::` to avoid namespace conflict
+  - Update test file references for new namespace
+
+## [0.5.0] - 2026-01-13
+
+### Changed
+- **BREAKING: Package renamed** from `ace-llm-models-dev` to `ace-support-models`
+  - Follows `ace-support-*` naming pattern for infrastructure gems
+  - CLI executable renamed: `ace-llm-models` → `ace-models`
+  - Ruby module renamed: `Ace::LLM::ModelsDev` → `Ace::Support::Models`
+  - Require path changed: `require 'ace/llm/models/dev'` → `require 'ace/support/models'`
+  - Cache directory changed: `~/.cache/ace-llm-models-dev` → `~/.cache/ace-models`
+  - All functionality remains identical
+- **CLI migrated to dry-cli** (task 179.16)
+  - Replaced Thor-based CLI with dry-cli registry pattern
+  - Thor dependency replaced with dry-cli ~> 1.1 in gemspec
+  - Removed old Thor subcommand files (cache_cli.rb, providers_cli.rb, models_cli.rb)
+  - New command classes in `cli/{cache,providers,models}/` directories
+  - Commands now use keyword arguments for options
+  - Subcommands registered hierarchically: `cache sync`, `providers list`, etc.
+- **Internal refactor**: Renamed `Cli::` module to `Commands::` for consistency with other ACE gems
+  - Directory renamed: `lib/ace/support/models/cli/` → `lib/ace/support/models/commands/`
+  - All command classes now use `Commands::` namespace
+
+## [0.4.1] - 2026-01-05
+
+### Added
+- Thor CLI migration with ConfigSummary display
+
+### Changed
+- Adopted Ace::Core::CLI::Base for standardized options
+
+
+## [0.4.0] - 2026-01-03
+
+### Changed
+- **BREAKING**: Minimum Ruby version raised to 3.3.0 (was 3.1.0)
+- Standardized gemspec file patterns with deterministic Dir.glob
+- Added MIT LICENSE file
+
+## [0.3.3] - 2025-12-30
+
+### Changed
+
+- Update provider config path references from `.ace.example` to `.ace-defaults`
+
+## [0.3.2] - 2025-12-08
+
+### Fixed
+
+- OpenRouter model sync false positives for suffixed models (`:nitro`, `:floor`, `:online`, etc.)
+- ModelNameCanonicalizer now strips known routing suffixes before comparing against models.dev
+
+### Added
+
+- ModelNameCanonicalizer atom for OpenRouter model name canonicalization
+
+---
+
+*For history prior to 0.3.2 (versions 0.1.0-0.3.1), see git history under the original gem name `ace-llm-models-dev`.*
+
+
+## [0.5.2] - 2026-02-22
+
+### Fixed
+- Added command grouping (Cache, Providers, Models, Shortcuts)
+- Fixed namespace subcommand help (cache/providers/models --help) to exit 0 and print to stdout
+- Standardized quiet, verbose, debug option descriptions to canonical strings

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Michal Czyz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,39 @@
+<div align="center">
+  <h1> ACE - Support Models </h1>
+
+  Shared model metadata and pricing helpers for ACE provider tooling.
+
+  <img src="https://raw.githubusercontent.com/cs3b/ace/main/docs/brand/AgenticCodingEnvironment.Logo.XS.jpg" alt="ACE Logo" width="480">
+  <br><br>
+
+  <a href="https://rubygems.org/gems/ace-support-models"><img alt="Gem Version" src="https://img.shields.io/gem/v/ace-support-models.svg" /></a>
+  <a href="https://www.ruby-lang.org"><img alt="Ruby" src="https://img.shields.io/badge/Ruby-3.2+-CC342D?logo=ruby" /></a>
+  <a href="https://opensource.org/licenses/MIT"><img alt="License: MIT" src="https://img.shields.io/badge/License-MIT-blue.svg" /></a>
+
+</div>
+
+> Works with: Claude Code, Codex CLI, OpenCode, Gemini CLI, pi-agent, and more.
+
+`ace-support-models` normalizes provider and model metadata into a single canonical source so ACE tools that reason about LLM capabilities, pricing, and compatibility do not duplicate catalogs or drift out of sync. Includes `ace-models` for search, pricing, and cache sync, and `ace-llm-providers` for provider listing.
+
+## Use Cases
+
+**Resolve model metadata consistently** - avoid duplicated model catalogs across ACE features by querying one shared registry used by [ace-llm](../ace-llm) and [ace-review](../ace-review).
+
+**Calculate usage expectations** - support stable cost and compatibility assumptions during tool workflows with shared pricing and capability primitives.
+
+**Share validation rules** - apply one metadata model for provider and model checks so that [ace-llm-providers-cli](../ace-llm-providers-cli) and other provider-aware packages stay aligned.
+
+## Quick Start
+
+```bash
+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 cache from models.dev
+ace-llm-providers list                # List known providers
+```
+
+---
+
+Part of [ACE](https://github.com/cs3b/ace)

data/Rakefile

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/*_test.rb"]
+end
+
+task spec: :test
+task default: :test

data/exe/ace-llm-providers

@@ -0,0 +1,19 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+lib = File.expand_path("../lib", __dir__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+
+require "ace/support/models"
+require "ace/support/models/cli/providers_cli"
+
+# No args → show help
+args = ARGV.empty? ? ["--help"] : ARGV
+
+# Start ace-support-cli with exception-based exit code handling (per ADR-023)
+begin
+  Ace::Support::Models::ProvidersCLI.start(args)
+rescue Ace::Support::Cli::Error => e
+  warn e.message
+  exit(e.exit_code)
+end

data/exe/ace-models

@@ -0,0 +1,23 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "../lib/ace/support/models"
+require_relative "../lib/ace/support/models/cli"
+
+# Migration warning: Help users clean up old cache directory
+old_cache_path = File.join(Dir.home, ".cache", "ace-llm-models-dev")
+if Dir.exist?(old_cache_path)
+  warn "Note: Old cache detected at ~/.cache/ace-llm-models-dev"
+  warn "Run: ace-models sync && rm -rf ~/.cache/ace-llm-models-dev"
+end
+
+# No args → show help
+args = ARGV.empty? ? ["--help"] : ARGV
+
+# Start ace-support-cli with exception-based exit code handling (per ADR-023)
+begin
+  Ace::Support::Models::CLI.start(args)
+rescue Ace::Support::Cli::Error => e
+  warn e.message
+  exit(e.exit_code)
+end

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

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "faraday/retry"
+
+module Ace
+  module Support
+    module Models
+      module Atoms
+        # Fetches data from the models.dev API using Faraday (ADR-010 compliant)
+        class ApiFetcher
+          API_URL = "https://models.dev/api.json"
+          TIMEOUT = 30
+          OPEN_TIMEOUT = 10
+          MAX_RETRIES = 2
+          RETRY_INTERVAL = 0.5
+
+          class << self
+            # Fetch the API JSON
+            # @param url [String] API URL (default: models.dev)
+            # @return [String] Raw JSON response
+            # @raise [NetworkError] on network failures
+            # @raise [ApiError] on non-200 responses
+            def fetch(url = API_URL)
+              response = connection.get(url)
+
+              unless response.success?
+                raise ApiError.new(
+                  "API request failed: #{response.status} #{response.reason_phrase}",
+                  status_code: response.status
+                )
+              end
+
+              response.body
+            rescue Faraday::TimeoutError => e
+              raise NetworkError, "Request timed out: #{e.message}"
+            rescue Faraday::ConnectionFailed => e
+              raise NetworkError, "Connection failed: #{e.message}"
+            rescue Faraday::SSLError => e
+              raise NetworkError, "SSL error: #{e.message}"
+            rescue Faraday::Error => e
+              raise NetworkError, "Network error fetching API: #{e.message}"
+            end
+
+            private
+
+            # Build Faraday connection with retry middleware
+            # @return [Faraday::Connection]
+            def connection
+              @connection ||= Faraday.new do |faraday|
+                faraday.options.timeout = TIMEOUT
+                faraday.options.open_timeout = OPEN_TIMEOUT
+
+                # Retry middleware for transient failures (ADR-010)
+                faraday.request :retry, {
+                  max: MAX_RETRIES,
+                  interval: RETRY_INTERVAL,
+                  interval_randomness: 0.5,
+                  backoff_factor: 2,
+                  retry_statuses: [429, 500, 502, 503, 504],
+                  methods: [:get]
+                }
+
+                # Set headers
+                faraday.headers["User-Agent"] = "ace-models/#{VERSION}"
+                faraday.headers["Accept"] = "application/json"
+
+                faraday.adapter Faraday.default_adapter
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Ace
+  module Support
+    module Models
+      module Atoms
+        # Resolves the cache directory path following XDG conventions
+        class CachePathResolver
+          DEFAULT_CACHE_DIR = "ace-models"
+
+          class << self
+            # Resolve the cache directory path
+            # @return [String] Full path to cache directory
+            def resolve
+              base_dir = xdg_cache_home || default_cache_home
+              File.join(base_dir, DEFAULT_CACHE_DIR)
+            end
+
+            private
+
+            # Get XDG_CACHE_HOME if set
+            # @return [String, nil] XDG cache home or nil
+            def xdg_cache_home
+              xdg = ENV["XDG_CACHE_HOME"]
+              xdg if xdg && !xdg.empty?
+            end
+
+            # Get default cache home (~/.cache)
+            # @return [String] Default cache directory
+            def default_cache_home
+              File.join(Dir.home, ".cache")
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Ace
+  module Support
+    module Models
+      module Atoms
+        # Reads files from the cache
+        class FileReader
+          class << self
+            # Read file contents
+            # @param path [String] File path
+            # @return [String, nil] File contents or nil if not found
+            def read(path)
+              return nil unless File.exist?(path)
+
+              File.read(path)
+            rescue Errno::EACCES => e
+              raise CacheError, "Permission denied reading #{path}: #{e.message}"
+            rescue Errno::ENOENT
+              nil
+            end
+
+            # Check if file exists
+            # @param path [String] File path
+            # @return [Boolean] true if file exists
+            def exist?(path)
+              File.exist?(path)
+            end
+
+            # Get file modification time
+            # @param path [String] File path
+            # @return [Time, nil] Modification time or nil
+            def mtime(path)
+              return nil unless File.exist?(path)
+
+              File.mtime(path)
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Ace
+  module Support
+    module Models
+      module Atoms
+        # Writes files to the cache
+        class FileWriter
+          class << self
+            # Write content to file
+            # @param path [String] File path
+            # @param content [String] Content to write
+            # @return [Boolean] true on success
+            # @raise [CacheError] on write errors
+            def write(path, content)
+              ensure_directory(File.dirname(path))
+              File.write(path, content)
+              true
+            rescue Errno::EACCES => e
+              raise CacheError, "Permission denied writing #{path}: #{e.message}"
+            rescue Errno::ENOSPC => e
+              raise CacheError, "No space left writing #{path}: #{e.message}"
+            end
+
+            # Ensure directory exists
+            # @param dir [String] Directory path
+            # @return [Boolean] true if created or exists
+            def ensure_directory(dir)
+              FileUtils.mkdir_p(dir) unless Dir.exist?(dir)
+              true
+            rescue Errno::EACCES => e
+              raise CacheError, "Permission denied creating directory #{dir}: #{e.message}"
+            end
+
+            # Delete file
+            # @param path [String] File path
+            # @return [Boolean] true on success
+            def delete(path)
+              File.delete(path) if File.exist?(path)
+              true
+            rescue Errno::EACCES => e
+              raise CacheError, "Permission denied deleting #{path}: #{e.message}"
+            end
+
+            # Rename/move file
+            # @param from [String] Source path
+            # @param to [String] Destination path
+            # @return [Boolean] true on success
+            def rename(from, to)
+              ensure_directory(File.dirname(to))
+              File.rename(from, to)
+              true
+            rescue Errno::EACCES => e
+              raise CacheError, "Permission denied moving file: #{e.message}"
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Ace
+  module Support
+    module Models
+      module Atoms
+        # Parses JSON responses from the API
+        class JsonParser
+          class << self
+            # Parse JSON string
+            # @param json_string [String] JSON to parse
+            # @return [Hash] Parsed data
+            # @raise [ApiError] on parse errors
+            def parse(json_string)
+              JSON.parse(json_string)
+            rescue JSON::ParserError => e
+              raise ApiError, "Failed to parse JSON: #{e.message}"
+            end
+
+            # Convert hash to JSON string
+            # @param data [Hash] Data to convert
+            # @param pretty [Boolean] Pretty print output
+            # @return [String] JSON string
+            def to_json(data, pretty: false)
+              if pretty
+                JSON.pretty_generate(data)
+              else
+                JSON.generate(data)
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+module Ace
+  module Support
+    module Models
+      module Atoms
+        # Filters models based on various criteria
+        class ModelFilter
+          # Supported filter predicates
+          FILTERS = {
+            # Provider filter
+            provider: ->(model, value) { model.provider_id == value },
+
+            # Capability filters (boolean)
+            reasoning: ->(model, value) { model.capabilities[:reasoning] == parse_boolean(value) },
+            tool_call: ->(model, value) { model.capabilities[:tool_call] == parse_boolean(value) },
+            attachment: ->(model, value) { model.capabilities[:attachment] == parse_boolean(value) },
+            structured_output: ->(model, value) { model.capabilities[:structured_output] == parse_boolean(value) },
+            temperature: ->(model, value) { model.capabilities[:temperature] == parse_boolean(value) },
+
+            # Open weights filter
+            open_weights: ->(model, value) { model.open_weights == parse_boolean(value) },
+
+            # Modality filter (checks input modalities)
+            modality: ->(model, value) { model.modalities[:input]&.include?(value) },
+
+            # Numeric filters
+            min_context: ->(model, value) { (model.context_limit || 0) >= value.to_i },
+            max_input_cost: lambda { |model, value|
+              pricing_input = model.pricing&.input
+              return false unless pricing_input
+
+              pricing_input <= value.to_f
+            }
+          }.freeze
+
+          class << self
+            # Apply filters to a list of models
+            # @param models [Array<Models::ModelInfo>] Models to filter
+            # @param filters [Hash] Filter key-value pairs
+            # @return [Array<Models::ModelInfo>] Filtered models
+            def apply(models, filters)
+              return models if filters.nil? || filters.empty?
+
+              models.select do |model|
+                filters.all? do |key, value|
+                  filter = FILTERS[key.to_sym]
+                  # Unknown filters are ignored (forward compatibility)
+                  filter.nil? || filter.call(model, value)
+                end
+              end
+            end
+
+            # Parse a filter string into key-value pair
+            # @param filter_string [String] Filter in "key:value" format
+            # @return [Array<Symbol, String>, nil] [key, value] or nil if invalid
+            def parse(filter_string)
+              return nil unless filter_string.is_a?(String)
+
+              parts = filter_string.split(":", 2)
+              return nil if parts.size != 2 || parts.any?(&:empty?)
+
+              [parts[0].to_sym, parts[1]]
+            end
+
+            # Parse multiple filter strings into a hash
+            # @param filter_strings [Array<String>] Array of "key:value" strings
+            # @return [Hash] Parsed filters
+            def parse_all(filter_strings)
+              return {} if filter_strings.nil? || filter_strings.empty?
+
+              filter_strings.each_with_object({}) do |filter_string, hash|
+                parsed = parse(filter_string)
+                hash[parsed[0]] = parsed[1] if parsed
+              end
+            end
+
+            # Validate filter strings and return errors for invalid ones
+            # @param filter_strings [Array<String>] Array of "key:value" strings
+            # @return [Array<String>] Array of error messages (empty if all valid)
+            def validate(filter_strings)
+              return [] if filter_strings.nil? || filter_strings.empty?
+
+              errors = []
+              filter_strings.each do |filter_string|
+                parsed = parse(filter_string)
+                errors << "Invalid filter format '#{filter_string}'. Use key:value" if parsed.nil?
+              end
+              errors
+            end
+
+            private
+
+            # Parse boolean string value
+            # @param value [String, Boolean] Value to parse
+            # @return [Boolean]
+            def parse_boolean(value)
+              return value if value.is_a?(TrueClass) || value.is_a?(FalseClass)
+
+              %w[true 1 yes].include?(value.to_s.downcase)
+            end
+          end
+        end
+      end
+    end
+  end
+end