omnizip 0.3.1

data/lib/omnizip/eta/exponential_smoothing_estimator.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+#
+# Copyright (C) 2025 Ribose Inc.
+#
+
+require_relative "time_estimator"
+require_relative "../models/eta_result"
+
+module Omnizip
+  module ETA
+    # ETA estimator using exponential smoothing.
+    #
+    # This estimator uses exponential smoothing to give more weight to
+    # recent samples while still considering historical data. This provides
+    # a good balance between responsiveness and stability.
+    #
+    # The smoothing factor (alpha) determines how much weight to give to
+    # new samples: 0.0 = ignore new data, 1.0 = only use new data.
+    class ExponentialSmoothingEstimator < TimeEstimator
+      attr_reader :smoothing_factor, :smoothed_rate
+
+      # Initialize a new exponential smoothing estimator
+      #
+      # @param smoothing_factor [Float] Alpha value (0.0-1.0), default 0.3
+      # @param sample_history [SampleHistory] History of samples
+      # @param rate_calculator [RateCalculator] Rate calculator
+      def initialize(smoothing_factor: 0.3, **options)
+        super(**options)
+        @smoothing_factor = smoothing_factor.clamp(0.0, 1.0)
+        @smoothed_rate = nil
+      end
+
+      # Estimate time remaining using exponential smoothing
+      #
+      # @param remaining_bytes [Integer] Bytes remaining to process
+      # @return [Models::ETAResult] ETA result with confidence interval
+      def estimate(remaining_bytes)
+        return zero_result if remaining_bytes <= 0
+
+        unless sufficient_samples?
+          return Models::ETAResult.new.tap do |result|
+            result.seconds_remaining = 0.0
+            result.formatted = "calculating..."
+            result.confidence_lower = 0.0
+            result.confidence_upper = 0.0
+          end
+        end
+
+        # Update smoothed rate
+        current_rate = rate_calculator.bytes_per_second
+
+        @smoothed_rate = if @smoothed_rate.nil?
+                           current_rate
+                         else
+                           (smoothing_factor * current_rate) +
+                             ((1.0 - smoothing_factor) * @smoothed_rate)
+                         end
+
+        # Calculate ETA
+        seconds_remaining = if @smoothed_rate.positive?
+                              remaining_bytes / @smoothed_rate
+                            else
+                              Float::INFINITY
+                            end
+
+        # Calculate confidence interval
+        lower, upper = confidence_interval(seconds_remaining)
+
+        Models::ETAResult.new.tap do |result|
+          result.seconds_remaining = seconds_remaining
+          result.formatted = format_time(seconds_remaining)
+          result.confidence_lower = lower
+          result.confidence_upper = upper
+        end
+      end
+
+      # Reset smoothed rate (e.g., when operation changes significantly)
+      def reset
+        @smoothed_rate = nil
+      end
+
+      private
+
+      # Return zero result for completed operation
+      #
+      # @return [Models::ETAResult] Zero result
+      def zero_result
+        Models::ETAResult.new.tap do |result|
+          result.seconds_remaining = 0.0
+          result.formatted = "0s"
+          result.confidence_lower = 0.0
+          result.confidence_upper = 0.0
+        end
+      end
+    end
+  end
+end

data/lib/omnizip/eta/moving_average_estimator.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+#
+# Copyright (C) 2025 Ribose Inc.
+#
+
+require_relative "time_estimator"
+require_relative "../models/eta_result"
+
+module Omnizip
+  module ETA
+    # ETA estimator using simple moving average.
+    #
+    # This estimator calculates the average rate over recent samples and
+    # uses that to estimate time remaining. Simpler than exponential
+    # smoothing but may be less responsive to changes.
+    class MovingAverageEstimator < TimeEstimator
+      attr_reader :window_size
+
+      # Initialize a new moving average estimator
+      #
+      # @param window_size [Integer] Number of recent samples to average
+      # @param sample_history [SampleHistory] History of samples
+      # @param rate_calculator [RateCalculator] Rate calculator
+      def initialize(window_size: 10, **options)
+        super(**options)
+        @window_size = window_size
+      end
+
+      # Estimate time remaining using moving average
+      #
+      # @param remaining_bytes [Integer] Bytes remaining to process
+      # @return [Models::ETAResult] ETA result with confidence interval
+      def estimate(remaining_bytes)
+        return zero_result if remaining_bytes <= 0
+
+        unless sufficient_samples?
+          return Models::ETAResult.new.tap do |result|
+            result.seconds_remaining = 0.0
+            result.formatted = "calculating..."
+            result.confidence_lower = 0.0
+            result.confidence_upper = 0.0
+          end
+        end
+
+        # Get average rate over recent samples
+        avg_rate = calculate_average_rate
+
+        # Calculate ETA
+        seconds_remaining = if avg_rate.positive?
+                              remaining_bytes / avg_rate
+                            else
+                              Float::INFINITY
+                            end
+
+        # Calculate confidence interval
+        lower, upper = confidence_interval(seconds_remaining)
+
+        Models::ETAResult.new.tap do |result|
+          result.seconds_remaining = seconds_remaining
+          result.formatted = format_time(seconds_remaining)
+          result.confidence_lower = lower
+          result.confidence_upper = upper
+        end
+      end
+
+      private
+
+      # Calculate average rate over recent window
+      #
+      # @return [Float] Average bytes per second
+      def calculate_average_rate
+        samples = sample_history.samples
+        return 0.0 if samples.size < 2
+
+        # Get last N samples (or all if less than N)
+        recent = samples.last([window_size, samples.size].min)
+        return 0.0 if recent.size < 2
+
+        # Calculate rate between first and last of window
+        first = recent.first
+        last = recent.last
+        last.rate_since(first)
+      end
+
+      # Return zero result for completed operation
+      #
+      # @return [Models::ETAResult] Zero result
+      def zero_result
+        Models::ETAResult.new.tap do |result|
+          result.seconds_remaining = 0.0
+          result.formatted = "0s"
+          result.confidence_lower = 0.0
+          result.confidence_upper = 0.0
+        end
+      end
+    end
+  end
+end

data/lib/omnizip/eta/rate_calculator.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+#
+# Copyright (C) 2025 Ribose Inc.
+#
+
+module Omnizip
+  module ETA
+    # Calculates processing rates from sample history.
+    #
+    # This class computes various rates (bytes/sec, files/sec) with
+    # smoothing over a time window to reduce noise from fluctuations.
+    class RateCalculator
+      attr_reader :sample_history, :window_seconds
+
+      # Initialize a new rate calculator
+      #
+      # @param sample_history [SampleHistory] History of samples
+      # @param window_seconds [Float] Time window for rate calculation
+      def initialize(sample_history:, window_seconds: 10.0)
+        @sample_history = sample_history
+        @window_seconds = window_seconds
+      end
+
+      # Calculate current bytes per second rate
+      #
+      # @return [Float] Bytes per second over recent window
+      def bytes_per_second
+        sample_history.recent_rate(window_seconds)
+      end
+
+      # Calculate current megabytes per second rate
+      #
+      # @return [Float] Megabytes per second
+      def megabytes_per_second
+        bytes_per_second / (1024.0 * 1024.0)
+      end
+
+      # Calculate current files per second rate
+      #
+      # @return [Float] Files per second over recent window
+      def files_per_second
+        recent = sample_history.recent_samples(window_seconds)
+        return 0.0 if recent.size < 2
+
+        first = recent.first
+        last = recent.last
+
+        time_diff = last.timestamp - first.timestamp
+        return 0.0 if time_diff <= 0
+
+        files_diff = last.files_processed - first.files_processed
+        files_diff / time_diff
+      end
+
+      # Calculate instantaneous rate (last two samples)
+      #
+      # @return [Float] Bytes per second between last two samples
+      def instantaneous_rate
+        return 0.0 if sample_history.size < 2
+
+        samples = sample_history.samples
+        last = samples[-1]
+        previous = samples[-2]
+
+        last.rate_since(previous)
+      end
+
+      # Format bytes per second as human-readable string
+      #
+      # @param rate [Float] Rate in bytes/second
+      # @return [String] Formatted rate (e.g., "2.5 MB/s")
+      def format_rate(rate = bytes_per_second)
+        return "0 B/s" if rate.zero?
+
+        if rate < 1024
+          "#{rate.round(1)} B/s"
+        elsif rate < 1024 * 1024
+          "#{(rate / 1024.0).round(1)} KB/s"
+        elsif rate < 1024 * 1024 * 1024
+          "#{(rate / (1024.0 * 1024.0)).round(1)} MB/s"
+        else
+          "#{(rate / (1024.0 * 1024.0 * 1024.0)).round(1)} GB/s"
+        end
+      end
+
+      # Check if rate is stable (low variance)
+      #
+      # @param threshold [Float] Max coefficient of variation for stability
+      # @return [Boolean] true if rate is stable
+      def stable?(threshold: 0.2)
+        return false if sample_history.size < 5
+
+        mean_rate = bytes_per_second
+        return true if mean_rate.zero? # No data = stable
+
+        std_dev = sample_history.rate_std_dev
+        coefficient_of_variation = std_dev / mean_rate
+
+        coefficient_of_variation < threshold
+      end
+    end
+  end
+end

data/lib/omnizip/eta/sample_history.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+#
+# Copyright (C) 2025 Ribose Inc.
+#
+
+module Omnizip
+  module ETA
+    # Stores historical samples for ETA calculation.
+    #
+    # This class maintains a time-series of progress samples with a limited
+    # size to avoid unbounded memory growth. It provides statistics on the
+    # samples for rate calculation and trend analysis.
+    class SampleHistory
+      # Single sample data point
+      Sample = Struct.new(:timestamp, :bytes_processed, :files_processed) do
+        # Calculate bytes/second rate between two samples
+        #
+        # @param other [Sample] Earlier sample
+        # @return [Float] Bytes per second
+        def rate_since(other)
+          time_diff = timestamp - other.timestamp
+          return 0.0 if time_diff <= 0
+
+          bytes_diff = bytes_processed - other.bytes_processed
+          bytes_diff / time_diff
+        end
+      end
+
+      attr_reader :max_size, :samples
+
+      # Initialize a new sample history
+      #
+      # @param max_size [Integer] Maximum number of samples to retain
+      def initialize(max_size: 100)
+        @max_size = max_size
+        @samples = []
+      end
+
+      # Add a new sample to the history
+      #
+      # @param bytes_processed [Integer] Total bytes processed so far
+      # @param files_processed [Integer] Total files processed so far
+      # @param timestamp [Time] Sample timestamp (defaults to now)
+      def add_sample(bytes_processed:, files_processed:, timestamp: Time.now)
+        sample = Sample.new(timestamp, bytes_processed, files_processed)
+        @samples << sample
+
+        # Trim oldest samples if we exceed max size
+        @samples.shift if @samples.size > max_size
+      end
+
+      # Get the most recent sample
+      #
+      # @return [Sample, nil] Most recent sample or nil if empty
+      def latest
+        @samples.last
+      end
+
+      # Get the oldest sample
+      #
+      # @return [Sample, nil] Oldest sample or nil if empty
+      def oldest
+        @samples.first
+      end
+
+      # Get samples from a specific time window
+      #
+      # @param seconds [Float] Number of seconds to look back
+      # @return [Array<Sample>] Samples within the time window
+      def recent_samples(seconds)
+        return [] if @samples.empty?
+
+        cutoff_time = Time.now - seconds
+        @samples.select { |s| s.timestamp >= cutoff_time }
+      end
+
+      # Calculate average rate over all samples
+      #
+      # @return [Float] Average bytes per second
+      def average_rate
+        return 0.0 if @samples.size < 2
+
+        first = @samples.first
+        last = @samples.last
+        last.rate_since(first)
+      end
+
+      # Calculate average rate over recent time window
+      #
+      # @param seconds [Float] Time window in seconds
+      # @return [Float] Average bytes per second over window
+      def recent_rate(seconds = 10.0)
+        recent = recent_samples(seconds)
+        return 0.0 if recent.size < 2
+
+        first = recent.first
+        last = recent.last
+        last.rate_since(first)
+      end
+
+      # Calculate standard deviation of recent rates
+      #
+      # @param window_size [Integer] Number of samples to use
+      # @return [Float] Standard deviation of rates
+      def rate_std_dev(window_size = 10)
+        return 0.0 if @samples.size < 3
+
+        recent = @samples.last([window_size, @samples.size].min)
+        rates = []
+
+        1.upto(recent.size - 1) do |i|
+          rates << recent[i].rate_since(recent[i - 1])
+        end
+
+        return 0.0 if rates.empty?
+
+        mean = rates.sum / rates.size
+        variance = rates.sum { |r| (r - mean)**2 } / rates.size
+        Math.sqrt(variance)
+      end
+
+      # Clear all samples
+      def clear
+        @samples.clear
+      end
+
+      # Get number of samples
+      #
+      # @return [Integer] Number of samples stored
+      def size
+        @samples.size
+      end
+
+      # Check if history is empty
+      #
+      # @return [Boolean] true if no samples
+      def empty?
+        @samples.empty?
+      end
+    end
+  end
+end

data/lib/omnizip/eta/time_estimator.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+#
+# Copyright (C) 2025 Ribose Inc.
+#
+
+module Omnizip
+  module ETA
+    # Abstract base class for time estimation strategies.
+    #
+    # This class defines the interface for ETA estimators and provides
+    # common functionality. Subclasses implement specific estimation
+    # algorithms (exponential smoothing, moving average, etc.).
+    class TimeEstimator
+      attr_reader :sample_history, :rate_calculator
+
+      # Initialize a new time estimator
+      #
+      # @param sample_history [SampleHistory] History of samples
+      # @param rate_calculator [RateCalculator] Rate calculator
+      def initialize(sample_history: nil, rate_calculator: nil)
+        @sample_history = sample_history || SampleHistory.new
+        @rate_calculator = rate_calculator ||
+          RateCalculator.new(sample_history: @sample_history)
+      end
+
+      # Add a sample to the history
+      #
+      # @param bytes_processed [Integer] Total bytes processed
+      # @param files_processed [Integer] Total files processed
+      # @param timestamp [Time] Sample timestamp
+      def add_sample(bytes_processed:, files_processed:, timestamp: Time.now)
+        sample_history.add_sample(
+          bytes_processed: bytes_processed,
+          files_processed: files_processed,
+          timestamp: timestamp,
+        )
+      end
+
+      # Estimate time remaining (to be implemented by subclasses)
+      #
+      # @param remaining_bytes [Integer] Bytes remaining to process
+      # @return [Models::ETAResult] ETA result
+      # @raise [NotImplementedError] if not implemented by subclass
+      def estimate(remaining_bytes)
+        raise NotImplementedError, "#{self.class} must implement #estimate"
+      end
+
+      # Format seconds as human-readable string
+      #
+      # @param seconds [Float] Seconds to format
+      # @return [String] Formatted time (e.g., "2m 30s", "1h 15m")
+      def format_time(seconds)
+        return "0s" if seconds <= 0
+        return "∞" if seconds.infinite?
+
+        hours = (seconds / 3600).floor
+        minutes = ((seconds % 3600) / 60).floor
+        secs = (seconds % 60).round
+
+        parts = []
+        parts << "#{hours}h" if hours.positive?
+        parts << "#{minutes}m" if minutes.positive? || hours.positive?
+        parts << "#{secs}s"
+
+        parts.join(" ")
+      end
+
+      # Calculate confidence interval based on rate variance
+      #
+      # @param estimated_seconds [Float] Estimated time in seconds
+      # @param confidence_level [Float] Confidence level (0.95 = 95%)
+      # @return [Array<Float>] [lower_bound, upper_bound] in seconds
+      def confidence_interval(estimated_seconds, confidence_level: 0.95)
+        return [0.0, 0.0] if sample_history.size < 3
+
+        # Use standard deviation of rates to calculate confidence interval
+        std_dev = sample_history.rate_std_dev
+        current_rate = rate_calculator.bytes_per_second
+
+        return [estimated_seconds, estimated_seconds] if current_rate.zero?
+
+        # Calculate coefficient of variation
+        cv = std_dev / current_rate
+
+        # Z-score for confidence level (approximation)
+        z_score = confidence_level >= 0.99 ? 2.576 : 1.96
+
+        # Calculate interval as percentage of estimate
+        margin = estimated_seconds * cv * z_score
+
+        lower = [estimated_seconds - margin, 0.0].max
+        upper = estimated_seconds + margin
+
+        [lower, upper]
+      end
+
+      # Check if we have enough samples for reliable estimation
+      #
+      # @return [Boolean] true if enough samples
+      def sufficient_samples?
+        sample_history.size >= 3
+      end
+    end
+  end
+end

data/lib/omnizip/eta.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+#
+# Copyright (C) 2025 Ribose Inc.
+#
+
+require_relative "eta/sample_history"
+require_relative "eta/rate_calculator"
+require_relative "eta/time_estimator"
+require_relative "eta/exponential_smoothing_estimator"
+require_relative "eta/moving_average_estimator"
+
+module Omnizip
+  # ETA (Estimated Time to Arrival) calculation module.
+  #
+  # This module provides time estimation capabilities for long-running
+  # operations. It tracks historical progress samples and uses various
+  # estimation strategies to predict completion time.
+  #
+  # @example Basic usage
+  #   estimator = Omnizip::ETA.create_estimator(:exponential_smoothing)
+  #   estimator.add_sample(bytes_processed: 1000, files_processed: 10)
+  #   # ... more samples ...
+  #   eta = estimator.estimate(remaining_bytes: 5000)
+  #   puts "ETA: #{eta.formatted}"
+  module ETA
+    # Create a new time estimator
+    #
+    # @param strategy [Symbol] Estimation strategy (:exponential_smoothing, :moving_average)
+    # @param options [Hash] Strategy-specific options
+    # @return [TimeEstimator] Configured estimator
+    def self.create_estimator(strategy = :exponential_smoothing, **options)
+      case strategy
+      when :exponential_smoothing
+        ExponentialSmoothingEstimator.new(**options)
+      when :moving_average
+        MovingAverageEstimator.new(**options)
+      else
+        raise ArgumentError, "Unknown estimation strategy: #{strategy}"
+      end
+    end
+
+    # Format seconds as human-readable time string
+    #
+    # @param seconds [Float] Seconds to format
+    # @return [String] Formatted time (e.g., "2m 30s")
+    def self.format_time(seconds)
+      return "0s" if seconds <= 0
+      return "∞" if seconds.infinite?
+
+      hours = (seconds / 3600).floor
+      minutes = ((seconds % 3600) / 60).floor
+      secs = (seconds % 60).round
+
+      parts = []
+      parts << "#{hours}h" if hours.positive?
+      parts << "#{minutes}m" if minutes.positive? || hours.positive?
+      parts << "#{secs}s"
+
+      parts.join(" ")
+    end
+  end
+end