ace-llm 0.30.0

data/lib/ace/llm/molecules/file_io_handler.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "pathname"
+
+module Ace
+  module LLM
+    module Molecules
+      # FileIoHandler provides file I/O utilities for LLM query commands
+      # This is a molecule - it handles specific file operations with validation
+      class FileIoHandler
+        # File extensions that indicate different output formats
+        FORMAT_EXTENSIONS = {
+          ".json" => "json",
+          ".md" => "markdown",
+          ".markdown" => "markdown",
+          ".txt" => "text",
+          ".text" => "text"
+        }.freeze
+
+        # Maximum file size to read (10MB)
+        MAX_FILE_SIZE = 10 * 1024 * 1024
+
+        # Initialize file I/O handler
+        # @param options [Hash] Configuration options
+        # @option options [Integer] :max_file_size Maximum file size to read
+        def initialize(**options)
+          @max_file_size = options.fetch(:max_file_size, MAX_FILE_SIZE)
+        end
+
+        # Detect if input is a file path or inline content
+        # @param input [String] Input string to analyze
+        # @return [Boolean] True if input appears to be a file path
+        def file_path?(input)
+          return false if input.nil? || input.strip.empty?
+
+          # File paths must be single line strings
+          input_str = input.strip
+          return false if input_str.include?("\n") || input_str.include?("\r")
+
+          # Only consider it a file path if the file actually exists
+          begin
+            path = Pathname.new(input_str)
+            File.exist?(path.to_s)
+          rescue ArgumentError, SystemCallError
+            # Invalid path characters or other path-related errors
+            false
+          end
+        end
+
+        # Read content from file or return inline content
+        # @param input [String] File path or inline content
+        # @param auto_detect [Boolean] Whether to auto-detect file vs inline content
+        # @return [String] Content text
+        # @raise [Error] If file cannot be read or is too large
+        def read_content(input, auto_detect: true)
+          if auto_detect && file_path?(input)
+            read_file_content(input.strip)
+          else
+            validate_inline_content(input)
+          end
+        end
+
+        # Read content from a file with size validation
+        # @param file_path [String] Path to file to read
+        # @return [String] File content
+        # @raise [Error] If file cannot be read or is too large
+        def read_file_content(file_path)
+          path = Pathname.new(file_path).expand_path
+
+          # Check file size
+          file_size = File.size(path)
+          if file_size > @max_file_size
+            raise Ace::LLM::Error, "File too large: #{file_size} bytes (max: #{@max_file_size} bytes)"
+          end
+
+          # Read file content
+          File.read(path)
+        rescue Errno::ENOENT
+          raise Ace::LLM::Error, "File not found: #{file_path}"
+        rescue Errno::EACCES
+          raise Ace::LLM::Error, "Permission denied reading file: #{file_path}"
+        rescue SystemCallError => e
+          raise Ace::LLM::Error, "Error reading file: #{e.message}"
+        end
+
+        # Validate inline content
+        # @param content [String] Content to validate
+        # @return [String] The content (unchanged if valid)
+        # @raise [Error] If content is invalid
+        def validate_inline_content(content)
+          raise Ace::LLM::Error, "Content cannot be nil or empty" if content.nil? || content.strip.empty?
+          content
+        end
+
+        # Write content to file with format handling
+        # @param content [String] Content to write
+        # @param file_path [String] Output file path
+        # @param format [String, nil] Format override (json, markdown, text)
+        # @param force [Boolean] Whether to force overwrite without confirmation
+        # @return [String] Inferred or specified format
+        # @raise [Error] If file cannot be written
+        def write_content(content, file_path, format: nil, force: false)
+          path = Pathname.new(file_path).expand_path
+
+          # Check if file exists and handle overwrite
+          if !force && File.exist?(path)
+            raise Ace::LLM::Error, "File already exists: #{file_path}. Use --force to overwrite."
+          end
+
+          # Ensure parent directory exists
+          FileUtils.mkdir_p(path.dirname)
+
+          # Write content
+          File.write(path, content)
+
+          # Return format (inferred from extension or specified)
+          format || infer_format(file_path)
+        rescue Errno::EACCES
+          raise Ace::LLM::Error, "Permission denied writing to: #{file_path}"
+        rescue SystemCallError => e
+          raise Ace::LLM::Error, "Error writing file: #{e.message}"
+        end
+
+        # Infer output format from file extension
+        # @param file_path [String] File path
+        # @return [String] Format name (json, markdown, or text)
+        def infer_format(file_path)
+          return "text" if file_path.nil? || file_path.empty?
+
+          ext = File.extname(file_path).downcase
+          FORMAT_EXTENSIONS.fetch(ext, "text")
+        end
+
+        # Check if a path is safe to write to
+        # @param path [String] Path to check
+        # @return [Boolean] True if path appears safe
+        def safe_path?(path)
+          return false if path.nil? || path.empty?
+
+          # Reject paths with null bytes
+          return false if path.include?("\0")
+
+          # Reject paths trying to traverse up directories
+          return false if path.include?("..")
+
+          begin
+            expanded = Pathname.new(path).expand_path
+            # Must be absolute after expansion
+            expanded.absolute?
+          rescue
+            false
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/llm/molecules/format_handlers.rb

@@ -0,0 +1,183 @@
+# frozen_string_literal: true
+
+require "json"
+require "yaml"
+
+module Ace
+  module LLM
+    module Molecules
+      # Format handlers for different output formats
+      module FormatHandlers
+        # Base format handler class
+        class Base
+          # Format response for output
+          # @param response [Hash] Response with :text and normalized metadata
+          # @param options [Hash] Additional formatting options
+          # @return [String] Formatted output
+          def format(response, **options)
+            raise NotImplementedError, "Subclasses must implement #format"
+          end
+
+          # Generate summary for stdout when writing to file
+          # @param response [Hash] Response with :text and normalized metadata
+          # @param file_path [String] Output file path
+          # @return [String] Summary text
+          def generate_summary(response, file_path)
+            metadata = response[:metadata] || {}
+
+            summary_parts = []
+            summary_parts << "Response saved to: #{file_path}"
+
+            if metadata[:provider]
+              summary_parts << if metadata[:model]
+                "Provider: #{metadata[:provider]} (#{metadata[:model]})"
+              else
+                "Provider: #{metadata[:provider]}"
+              end
+            end
+
+            summary_parts << "Execution time: #{metadata[:took]}s" if metadata[:took]
+
+            if metadata[:input_tokens] && metadata[:output_tokens]
+              tokens_info = "Tokens: #{metadata[:input_tokens]} input, #{metadata[:output_tokens]} output"
+              if metadata[:cached_tokens] && metadata[:cached_tokens] > 0
+                tokens_info += ", #{metadata[:cached_tokens]} cached"
+              end
+              summary_parts << tokens_info
+            end
+
+            # Add cost information if available
+            if metadata[:cost]
+              cost_info = build_cost_summary(metadata[:cost])
+              summary_parts << cost_info if cost_info
+            end
+
+            summary_parts.join("\n")
+          end
+
+          # Build cost summary string from cost metadata
+          # @param cost_data [Hash] Cost breakdown data
+          # @return [String, nil] Formatted cost summary
+          def build_cost_summary(cost_data)
+            return nil unless cost_data && cost_data[:total]
+
+            cost_parts = []
+            cost_parts << "Cost: $#{format_cost(cost_data[:total])}"
+
+            if cost_data[:input] || cost_data[:output]
+              breakdown = []
+              breakdown << "input: $#{format_cost(cost_data[:input])}" if cost_data[:input]
+              breakdown << "output: $#{format_cost(cost_data[:output])}" if cost_data[:output]
+
+              if cost_data[:cache_creation] && cost_data[:cache_creation] > 0
+                breakdown << "cache creation: $#{format_cost(cost_data[:cache_creation])}"
+              end
+
+              if cost_data[:cache_read] && cost_data[:cache_read] > 0
+                breakdown << "cache read: $#{format_cost(cost_data[:cache_read])}"
+              end
+
+              cost_parts << " (#{breakdown.join(", ")})" unless breakdown.empty?
+            end
+
+            cost_parts.join
+          end
+
+          # Format cost value for display
+          # @param cost [Float, Numeric] Cost value
+          # @return [String] Formatted cost string
+          def format_cost(cost)
+            return "0.000000" if cost.nil? || cost.zero?
+
+            sprintf("%.6f", cost)
+          end
+
+          protected
+
+          # Validate response structure
+          # @param response [Hash] Response to validate
+          # @raise [Error] If response is invalid
+          def validate_response(response)
+            return if response.is_a?(Hash) && response[:text]
+
+            raise Ace::LLM::Error, "Invalid response format: missing :text field"
+          end
+        end
+
+        # JSON format handler
+        class JSON < Base
+          # Format response as JSON with full metadata
+          # @param response [Hash] Response with :text and normalized metadata
+          # @param options [Hash] Additional formatting options
+          # @return [String] JSON formatted output
+          def format(response, **_options)
+            validate_response(response)
+
+            output = {
+              text: response[:text],
+              metadata: response[:metadata] || {}
+            }
+
+            ::JSON.pretty_generate(output)
+          end
+        end
+
+        # Markdown format handler
+        class Markdown < Base
+          # Format response as Markdown with YAML front matter
+          # @param response [Hash] Response with :text and normalized metadata
+          # @param options [Hash] Additional formatting options
+          # @return [String] Markdown formatted output
+          def format(response, **_options)
+            validate_response(response)
+
+            metadata = response[:metadata] || {}
+            content = response[:text]
+
+            if metadata.empty?
+              content
+            else
+              # Create YAML front matter
+              yaml_front_matter = metadata.to_yaml.chomp
+              "#{yaml_front_matter}\n---\n\n#{content}"
+            end
+          end
+        end
+
+        # Plain text format handler
+        class Text < Base
+          # Format response as plain text (content only)
+          # @param response [Hash] Response with :text and normalized metadata
+          # @param options [Hash] Additional formatting options
+          # @return [String] Plain text output
+          def format(response, **_options)
+            validate_response(response)
+            response[:text]
+          end
+        end
+
+        # Factory method to get format handler
+        # @param format [String] Format type (json, markdown, text)
+        # @return [Base] Format handler instance
+        def self.get_handler(format)
+          case format.to_s.downcase
+          when "json"
+            JSON.new
+          when "markdown", "md"
+            Markdown.new
+          when "text", "txt"
+            Text.new
+          else
+            raise Ace::LLM::Error, "Unsupported format: #{format}"
+          end
+        end
+
+        # Get list of supported formats
+        # @return [Array<String>] List of supported formats
+        def self.supported_formats
+          ["json", "markdown", "text"]
+        end
+      end
+    end
+  end
+end

data/lib/ace/llm/molecules/llm_alias_resolver.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require_relative "client_registry"
+
+module Ace
+  module LLM
+    module Molecules
+      # LlmAliasResolver resolves LLM aliases to their actual model names
+      # Now delegates to ClientRegistry which manages aliases from provider configs
+      class LlmAliasResolver
+        attr_reader :registry
+
+        # Initialize alias resolver with optional registry
+        # @param registry [ClientRegistry, nil] Optional registry to use
+        def initialize(registry: nil)
+          @registry = registry || ClientRegistry.new
+        end
+
+        # Resolve an alias or model name to its actual provider:model format
+        # @param input [String] The input model name or alias
+        # @return [String] The resolved provider:model format
+        def resolve(input)
+          @registry.resolve_alias(input)
+        end
+
+        # Check if a given input is an alias
+        # @param input [String] The input to check
+        # @return [Boolean] True if the input is a recognized alias
+        def alias?(input)
+          resolved = @registry.resolve_alias(input)
+          resolved != input
+        end
+
+        # Get all available aliases
+        # @return [Hash] Hash containing global and model aliases
+        def available_aliases
+          @registry.available_aliases
+        end
+
+        # Get aliases for a specific provider
+        # @param provider [String] Provider name
+        # @return [Hash] Provider-specific model aliases
+        def provider_aliases(provider)
+          normalized = provider.to_s.strip.downcase.gsub(/[-_]/, "")
+          @registry.available_aliases[:model][normalized] || {}
+        end
+      end
+    end
+  end
+end

data/lib/ace/llm/molecules/openai_compatible_params.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Ace
+  module LLM
+    module Molecules
+      # Shared parameter extraction for OpenAI-compatible providers
+      # Preserves zero values using nil? check (0 is a valid penalty value)
+      module OpenAICompatibleParams
+        # Extract OpenAI-compatible generation options
+        # @param options [Hash] Raw options from caller
+        # @param gen_opts [Hash] Generation options to augment
+        # @return [Hash] Augmented generation options
+        def extract_openai_compatible_options(options, gen_opts)
+          gen_opts[:frequency_penalty] = options[:frequency_penalty] unless options[:frequency_penalty].nil?
+          gen_opts[:presence_penalty] = options[:presence_penalty] unless options[:presence_penalty].nil?
+          gen_opts
+        end
+      end
+    end
+  end
+end

data/lib/ace/llm/molecules/preset_loader.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require "ace/support/config"
+require_relative "config_loader"
+
+module Ace
+  module LLM
+    module Molecules
+      # Loads named execution presets from llm/presets/*.yml via config cascade.
+      class PresetLoader
+        class << self
+          def load(name)
+            preset_name = normalize_preset_name(name)
+            preset_hash = resolve_preset(preset_name)
+            if preset_hash.nil? || preset_hash.empty?
+              raise ConfigurationError,
+                "Preset '#{preset_name}' not found. Define .ace/llm/presets/#{preset_name}.yml"
+            end
+
+            preset_hash
+          rescue ConfigurationError
+            raise
+          rescue => e
+            raise ConfigurationError, "Failed to load preset '#{preset_name}': #{e.message}"
+          end
+
+          def load_for_provider(provider, preset_name)
+            normalized_provider = normalize_provider_name(provider)
+            normalized_preset_name = normalize_preset_name(preset_name)
+
+            global_preset = resolve_preset(normalized_preset_name)
+            provider_preset = resolve_preset("#{normalized_provider}/#{normalized_preset_name}")
+
+            if global_preset.empty? && provider_preset.empty?
+              raise ConfigurationError,
+                "Preset '#{normalized_preset_name}' not found for provider '#{normalized_provider}'. " \
+                "Define .ace/llm/presets/#{normalized_preset_name}.yml or " \
+                ".ace/llm/presets/#{normalized_provider}/#{normalized_preset_name}.yml"
+            end
+
+            Ace::Support::Config::Models::Config.wrap(
+              global_preset,
+              provider_preset,
+              source: "llm_preset_overlay"
+            )
+          rescue ConfigurationError
+            raise
+          rescue => e
+            raise ConfigurationError,
+              "Failed to load preset '#{normalized_preset_name}' for provider '#{normalized_provider}': #{e.message}"
+          end
+
+          private
+
+          def config_resolver
+            Ace::Support::Config.create(
+              config_dir: ".ace",
+              defaults_dir: ".ace-defaults",
+              gem_path: ConfigLoader.gem_root
+            )
+          end
+
+          def normalize_preset_name(name)
+            preset_name = name.to_s.strip
+            raise ConfigurationError, "Preset name cannot be empty" if preset_name.empty?
+
+            preset_name
+          end
+
+          def normalize_provider_name(provider)
+            normalized_provider = provider.to_s.strip.downcase.gsub(/[-_]/, "")
+            raise ConfigurationError, "Provider name cannot be empty" if normalized_provider.empty?
+
+            normalized_provider
+          end
+
+          def resolve_preset(preset_name)
+            config = config_resolver.resolve_namespace("llm", filename: "presets/#{preset_name}")
+            preset_hash = deep_stringify_keys(config.to_h)
+            preset_hash.is_a?(Hash) ? preset_hash : {}
+          end
+
+          def deep_stringify_keys(value)
+            case value
+            when Hash
+              value.each_with_object({}) do |(k, v), result|
+                result[k.to_s] = deep_stringify_keys(v)
+              end
+            when Array
+              value.map { |item| deep_stringify_keys(item) }
+            else
+              value
+            end
+          end
+        end
+      end
+    end
+  end
+end