htm 0.0.31 → 0.0.32

data/examples/examples_helper.rb

@@ -72,6 +72,31 @@ end
 
 # Module with helper methods for examples
 module ExamplesHelper
+  # Reset examples database if --reset flag is present in ARGV
+  #
+  # Drops and recreates htm_examples, then runs all migrations.
+  # Removes --reset from ARGV so downstream option parsers are unaffected.
+  #
+  # @return [void]
+  def self.reset_if_requested!
+    return unless ARGV.delete('--reset')
+
+    db_name = "#{ENV['HTM_SERVICE__NAME'] || 'htm'}_examples"
+    puts "Resetting examples database '#{db_name}'..."
+
+    HTM::SequelConfig.disconnect! if HTM::SequelConfig.db
+
+    abort "ERROR: Failed to drop '#{db_name}'" unless system("dropdb --if-exists #{db_name}")
+    abort "ERROR: Failed to create '#{db_name}'" unless system("createdb #{db_name}")
+
+    HTM::SequelConfig.establish_connection!(load_models: false)
+    HTM::Database.setup
+    HTM::SequelConfig.ensure_models_loaded!
+
+    puts "Database reset complete."
+    puts
+  end
+
   # Check if database is available and configured
   #
   # @return [Boolean] true if database is ready

data/lib/htm/circuit_breaker.rb

@@ -158,7 +158,7 @@ class HTM
           end
         when :closed
           # Reset failure count on success in closed state
-          @failure_count = 0 if @failure_count > 0
+          @failure_count = 0 if @failure_count.positive?
         end
       end
     end
@@ -190,11 +190,10 @@ class HTM
       return unless @state == :open && @last_failure_time
 
       elapsed = Time.now - @last_failure_time
-      if elapsed >= @reset_timeout
-        @state = :half_open
-        @success_count = 0
-        HTM.logger.info "CircuitBreaker[#{@name}]: Reset timeout elapsed (#{@reset_timeout}s), circuit HALF-OPEN"
-      end
+      return unless elapsed >= @reset_timeout
+      @state = :half_open
+      @success_count = 0
+      HTM.logger.info "CircuitBreaker[#{@name}]: Reset timeout elapsed (#{@reset_timeout}s), circuit HALF-OPEN"
     end
   end
 end

data/lib/htm/config/builder.rb

@@ -31,7 +31,7 @@ class HTM
           response = RubyLLM.embed(text, model: model)
           embedding = extract_embedding_from_response(response)
 
-          unless embedding.is_a?(Array) && embedding.all? { |v| v.is_a?(Numeric) }
+          unless embedding.is_a?(Array) && embedding.all?(Numeric)
             raise HTM::EmbeddingError, "Invalid embedding response format from #{embedding_provider}"
           end
 
@@ -119,17 +119,17 @@ class HTM
 
       def parse_tag_response(text)
         tags = text.to_s.split("\n").map(&:strip).reject(&:empty?)
-        valid_tags = tags.select { |tag| tag =~ /^[a-z0-9\-]+(:[a-z0-9\-]+)*$/ }
+        valid_tags = tags.grep(/^[a-z0-9-]+(:[a-z0-9-]+)*$/)
         valid_tags.select { |tag| tag.count(':') < max_tag_depth }
       end
 
       def parse_proposition_response(text)
         text.to_s
-          .split("\n")
-          .map(&:strip)
-          .map { |line| line.sub(/^[-*]\s*/, '') }
-          .map(&:strip)
-          .reject(&:empty?)
+            .split("\n")
+            .map(&:strip)
+            .map { |line| line.sub(/^[-*]\s*/, '') }
+            .map(&:strip)
+            .reject(&:empty?)
       end
 
       # ==========================================================================
@@ -138,11 +138,11 @@ class HTM
 
       def build_tag_extraction_prompt(text, existing_ontology)
         taxonomy_context = if existing_ontology.any?
-          sample_tags = existing_ontology.sample([existing_ontology.size, 20].min)
-          tag.taxonomy_context_existing % { sample_tags: sample_tags.join(', ') }
-        else
-          tag.taxonomy_context_empty
-        end
+                             sample_tags = existing_ontology.sample([existing_ontology.size, 20].min)
+                             tag.taxonomy_context_existing % { sample_tags: sample_tags.join(', ') }
+                           else
+                             tag.taxonomy_context_empty
+                           end
 
         tag.user_prompt_template % {
           text: text,

data/lib/htm/config/database.rb

@@ -87,9 +87,9 @@ class HTM
 
         unless database_configured?
           raise HTM::ConfigurationError,
-            "No database configured for environment '#{environment}'. " \
-            "Set HTM_DATABASE__URL or HTM_DATABASE__NAME, " \
-            "or add database.name to the '#{environment}:' section in your config."
+                "No database configured for environment '#{environment}'. " \
+                "Set HTM_DATABASE__URL or HTM_DATABASE__NAME, " \
+                "or add database.name to the '#{environment}:' section in your config."
         end
 
         true
@@ -165,16 +165,16 @@ class HTM
         return true if actual == expected
 
         raise HTM::ConfigurationError,
-          "Database name '#{actual}' does not match expected '#{expected}'.\n" \
-          "Database names must follow the convention: {service_name}_{environment}\n" \
-          "  Service name: #{service_name}\n" \
-          "  Environment:  #{environment}\n" \
-          "  Expected:     #{expected}\n" \
-          "  Actual:       #{actual}\n\n" \
-          "Either:\n" \
-          "  - Set HTM_DATABASE__URL to point to '#{expected}'\n" \
-          "  - Set HTM_DATABASE__NAME=#{expected}\n" \
-          "  - Change HTM_ENV to match the database suffix"
+              "Database name '#{actual}' does not match expected '#{expected}'.\n" \
+              "Database names must follow the convention: {service_name}_{environment}\n  " \
+              "Service name: #{service_name}\n  " \
+              "Environment:  #{environment}\n  " \
+              "Expected:     #{expected}\n  " \
+              "Actual:       #{actual}\n\n" \
+              "Either:\n  " \
+              "- Set HTM_DATABASE__URL to point to '#{expected}'\n  " \
+              "- Set HTM_DATABASE__NAME=#{expected}\n  " \
+              "- Change HTM_ENV to match the database suffix"
       end
 
       # Check if the database name matches the expected convention
@@ -216,23 +216,17 @@ class HTM
 
       def build_database_url
         return nil unless database.name && !database.name.empty?
-
-        auth = if database.user && !database.user.empty?
-          database.password && !database.password.empty? ? "#{database.user}:#{database.password}@" : "#{database.user}@"
-        else
-          ''
-        end
-
-        url = "postgresql://#{auth}#{database.host}:#{database.port}/#{database.name}"
-
-        # Add sslmode as query parameter if set
-        if database.sslmode && !database.sslmode.empty?
-          url += "?sslmode=#{database.sslmode}"
-        end
-
+        url = "postgresql://#{database_auth_segment}#{database.host}:#{database.port}/#{database.name}"
+        url += "?sslmode=#{database.sslmode}" if database.sslmode && !database.sslmode.empty?
         url
       end
 
+      def database_auth_segment
+        return '' unless database.user && !database.user.empty?
+        return "#{database.user}@" unless database.password && !database.password.empty?
+        "#{database.user}:#{database.password}@"
+      end
+
       # ==========================================================================
       # Database Configuration Reconciliation
       # ==========================================================================

data/lib/htm/config/validator.rb

@@ -27,32 +27,28 @@ class HTM
       def validate_provider(name, value)
         return if value.nil?
 
-        unless SUPPORTED_PROVIDERS.include?(value)
-          raise_validation_error("#{name} must be one of: #{SUPPORTED_PROVIDERS.join(', ')} (got #{value.inspect})")
-        end
+        return if SUPPORTED_PROVIDERS.include?(value)
+        raise_validation_error("#{name} must be one of: #{SUPPORTED_PROVIDERS.join(', ')} (got #{value.inspect})")
       end
 
       def validate_job_backend
         return unless job_backend
 
-        unless SUPPORTED_JOB_BACKENDS.include?(job_backend)
-          raise_validation_error("job.backend must be one of: #{SUPPORTED_JOB_BACKENDS.join(', ')} (got #{job_backend.inspect})")
-        end
+        return if SUPPORTED_JOB_BACKENDS.include?(job_backend)
+        raise_validation_error("job.backend must be one of: #{SUPPORTED_JOB_BACKENDS.join(', ')} (got #{job_backend.inspect})")
       end
 
       def validate_week_start
-        unless SUPPORTED_WEEK_STARTS.include?(week_start)
-          raise_validation_error("week_start must be one of: #{SUPPORTED_WEEK_STARTS.join(', ')} (got #{week_start.inspect})")
-        end
+        return if SUPPORTED_WEEK_STARTS.include?(week_start)
+        raise_validation_error("week_start must be one of: #{SUPPORTED_WEEK_STARTS.join(', ')} (got #{week_start.inspect})")
       end
 
       def validate_relevance_weights
         total = relevance_semantic_weight + relevance_tag_weight +
                 relevance_recency_weight + relevance_access_weight
 
-        unless (0.99..1.01).cover?(total)
-          raise_validation_error("relevance weights must sum to 1.0 (got #{total})")
-        end
+        return if (0.99..1.01).cover?(total)
+        raise_validation_error("relevance weights must sum to 1.0 (got #{total})")
       end
 
       def validate_callables
@@ -68,15 +64,13 @@ class HTM
           raise HTM::ValidationError, "proposition_extractor must be callable"
         end
 
-        unless @token_counter.respond_to?(:call)
-          raise HTM::ValidationError, "token_counter must be callable"
-        end
+        return if @token_counter.respond_to?(:call)
+        raise HTM::ValidationError, "token_counter must be callable"
       end
 
       def validate_logger
-        unless @logger.respond_to?(:info) && @logger.respond_to?(:warn) && @logger.respond_to?(:error)
-          raise HTM::ValidationError, "logger must respond to :info, :warn, and :error"
-        end
+        return if @logger.respond_to?(:info) && @logger.respond_to?(:warn) && @logger.respond_to?(:error)
+        raise HTM::ValidationError, "logger must respond to :info, :warn, and :error"
       end
     end
   end

data/lib/htm/config.rb

@@ -99,8 +99,7 @@ class HTM
     # Callable Accessors (not loaded from config sources)
     # ==========================================================================
 
-    attr_accessor :embedding_generator, :tag_extractor, :proposition_extractor
-    attr_accessor :token_counter, :logger
+    attr_accessor :embedding_generator, :tag_extractor, :proposition_extractor, :token_counter, :logger
 
     # ==========================================================================
     # Instance Methods
@@ -295,7 +294,7 @@ class HTM
     # Environment Helpers
     # ==========================================================================
 
-    # Note: test?, development?, production? are auto-generated by MywayConfig::Base
+    # NOTE: test?, development?, production? are auto-generated by MywayConfig::Base
     # based on environment keys in defaults.yml
 
     def environment
@@ -327,11 +326,11 @@ class HTM
       current = env
       return true if valid_environment?
 
-      valid = valid_environments.map(&:to_s).join(', ')
+      valid = valid_environments.join(', ')
       raise HTM::ConfigurationError,
-        "Invalid environment '#{current}'. " \
-        "Valid environments are: #{valid}. " \
-        "Set HTM_ENV to a valid environment or add a '#{current}:' section to your config."
+            "Invalid environment '#{current}'. " \
+            "Valid environments are: #{valid}. " \
+            "Set HTM_ENV to a valid environment or add a '#{current}:' section to your config."
     end
 
     # Instance method delegates
@@ -352,12 +351,12 @@ class HTM
     end
 
     def self.xdg_config_file
-      xdg_home = ENV['XDG_CONFIG_HOME']
+      xdg_home = ENV.fetch('XDG_CONFIG_HOME', nil)
       base = if xdg_home && !xdg_home.empty?
-        xdg_home
-      else
-        File.expand_path('~/.config')
-      end
+               xdg_home
+             else
+               File.expand_path('~/.config')
+             end
       File.join(base, 'htm', 'htm.yml')
     end
 
@@ -378,42 +377,8 @@ class HTM
 
     def configure_ruby_llm(provider = nil)
       require 'ruby_llm'
-
       provider ||= embedding_provider
-
-      RubyLLM.configure do |config|
-        case provider
-        when :openai
-          config.openai_api_key = openai_api_key if openai_api_key
-          config.openai_organization = openai_organization if openai_organization && config.respond_to?(:openai_organization=)
-          config.openai_project = openai_project if openai_project && config.respond_to?(:openai_project=)
-        when :anthropic
-          config.anthropic_api_key = anthropic_api_key if anthropic_api_key
-        when :gemini
-          config.gemini_api_key = gemini_api_key if gemini_api_key
-        when :azure
-          config.azure_api_key = azure_api_key if azure_api_key && config.respond_to?(:azure_api_key=)
-          config.azure_endpoint = azure_endpoint if azure_endpoint && config.respond_to?(:azure_endpoint=)
-          config.azure_api_version = azure_api_version if azure_api_version && config.respond_to?(:azure_api_version=)
-        when :ollama
-          ollama_api_base = if ollama_url.end_with?('/v1') || ollama_url.end_with?('/v1/')
-            ollama_url.sub(%r{/+$}, '')
-          else
-            "#{ollama_url.sub(%r{/+$}, '')}/v1"
-          end
-          config.ollama_api_base = ollama_api_base
-        when :huggingface
-          config.huggingface_api_key = huggingface_api_key if huggingface_api_key && config.respond_to?(:huggingface_api_key=)
-        when :openrouter
-          config.openrouter_api_key = openrouter_api_key if openrouter_api_key && config.respond_to?(:openrouter_api_key=)
-        when :bedrock
-          config.bedrock_api_key = bedrock_access_key if bedrock_access_key && config.respond_to?(:bedrock_api_key=)
-          config.bedrock_secret_key = bedrock_secret_key if bedrock_secret_key && config.respond_to?(:bedrock_secret_key=)
-          config.bedrock_region = bedrock_region if bedrock_region && config.respond_to?(:bedrock_region=)
-        when :deepseek
-          config.deepseek_api_key = deepseek_api_key if deepseek_api_key && config.respond_to?(:deepseek_api_key=)
-        end
-      end
+      RubyLLM.configure { |config| apply_provider_config(config, provider) }
     end
 
     def refresh_ollama_models!
@@ -453,27 +418,73 @@ class HTM
     # ==========================================================================
 
     def coerce_nested_types
-      # Ensure nested provider sections are ConfigSections
-      # myway_config handles top-level sections, but we need to handle nested ones
-      if providers.is_a?(MywayConfig::ConfigSection)
-        %i[openai anthropic gemini azure ollama huggingface openrouter bedrock deepseek].each do |provider|
-          value = providers[provider]
-          providers[provider] = MywayConfig::ConfigSection.new(value) if value.is_a?(Hash)
-        end
-      end
+      coerce_provider_sections
+      coerce_database_integers
+    end
 
-      # Coerce database numeric fields to integers (env vars are always strings)
-      if database&.port && !database.port.is_a?(Integer)
-        database.port = database.port.to_i
-      end
-      if database&.pool_size && !database.pool_size.is_a?(Integer)
-        database.pool_size = database.pool_size.to_i
-      end
-      if database&.timeout && !database.timeout.is_a?(Integer)
-        database.timeout = database.timeout.to_i
+    def coerce_provider_sections
+      return unless providers.is_a?(MywayConfig::ConfigSection)
+      %i[openai anthropic gemini azure ollama huggingface openrouter bedrock deepseek].each do |provider|
+        value = providers[provider]
+        providers[provider] = MywayConfig::ConfigSection.new(value) if value.is_a?(Hash)
       end
     end
 
+    def coerce_database_integers
+      return unless database
+      database.port      = database.port.to_i      if database.port && !database.port.is_a?(Integer)
+      database.pool_size = database.pool_size.to_i if database.pool_size && !database.pool_size.is_a?(Integer)
+      database.timeout   = database.timeout.to_i   if database.timeout && !database.timeout.is_a?(Integer)
+    end
+
+    def apply_provider_config(config, provider)
+      handler = :"apply_#{provider}_provider_config"
+      send(handler, config) if respond_to?(handler, true)
+    end
+
+    def apply_openai_provider_config(config)
+      config.openai_api_key      = openai_api_key     if openai_api_key
+      config.openai_organization = openai_organization if openai_organization && config.respond_to?(:openai_organization=)
+      config.openai_project      = openai_project      if openai_project && config.respond_to?(:openai_project=)
+    end
+
+    def apply_anthropic_provider_config(config)
+      config.anthropic_api_key = anthropic_api_key if anthropic_api_key
+    end
+
+    def apply_gemini_provider_config(config)
+      config.gemini_api_key = gemini_api_key if gemini_api_key
+    end
+
+    def apply_azure_provider_config(config)
+      config.azure_api_key     = azure_api_key     if azure_api_key && config.respond_to?(:azure_api_key=)
+      config.azure_endpoint    = azure_endpoint    if azure_endpoint && config.respond_to?(:azure_endpoint=)
+      config.azure_api_version = azure_api_version if azure_api_version && config.respond_to?(:azure_api_version=)
+    end
+
+    def apply_ollama_provider_config(config)
+      base = ollama_url.sub(%r{/+$}, '')
+      config.ollama_api_base = base.end_with?('/v1') ? base : "#{base}/v1"
+    end
+
+    def apply_huggingface_provider_config(config)
+      config.huggingface_api_key = huggingface_api_key if huggingface_api_key && config.respond_to?(:huggingface_api_key=)
+    end
+
+    def apply_openrouter_provider_config(config)
+      config.openrouter_api_key = openrouter_api_key if openrouter_api_key && config.respond_to?(:openrouter_api_key=)
+    end
+
+    def apply_bedrock_provider_config(config)
+      config.bedrock_api_key    = bedrock_access_key if bedrock_access_key && config.respond_to?(:bedrock_api_key=)
+      config.bedrock_secret_key = bedrock_secret_key if bedrock_secret_key && config.respond_to?(:bedrock_secret_key=)
+      config.bedrock_region     = bedrock_region     if bedrock_region && config.respond_to?(:bedrock_region=)
+    end
+
+    def apply_deepseek_provider_config(config)
+      config.deepseek_api_key = deepseek_api_key if deepseek_api_key && config.respond_to?(:deepseek_api_key=)
+    end
+
     # ==========================================================================
     # Setup Defaults Callback
     # ==========================================================================
@@ -484,7 +495,7 @@ class HTM
       @embedding_generator ||= build_default_embedding_generator
       @tag_extractor ||= build_default_tag_extractor
       @proposition_extractor ||= build_default_proposition_extractor
-      @token_counter ||= build_default_token_counter
+      @token_counter = build_default_token_counter if @token_counter.nil?
     end
 
     def detect_job_backend