htm 0.0.20 → 0.0.30

data/lib/htm/config/section.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+class HTM
+  # ConfigSection provides method access to nested configuration hashes
+  #
+  # @example
+  #   section = ConfigSection.new(host: 'localhost', port: 5432)
+  #   section.host  # => 'localhost'
+  #   section.port  # => 5432
+  #
+  class ConfigSection
+    def initialize(hash = {})
+      @data = {}
+      (hash || {}).each do |key, value|
+        @data[key.to_sym] = value.is_a?(Hash) ? ConfigSection.new(value) : value
+      end
+    end
+
+    def method_missing(method, *args, &block)
+      key = method.to_s
+      if key.end_with?('=')
+        @data[key.chomp('=').to_sym] = args.first
+      elsif @data.key?(method)
+        @data[method]
+      else
+        nil
+      end
+    end
+
+    def respond_to_missing?(method, include_private = false)
+      key = method.to_s.chomp('=').to_sym
+      @data.key?(key) || super
+    end
+
+    def to_h
+      @data.transform_values do |v|
+        v.is_a?(ConfigSection) ? v.to_h : v
+      end
+    end
+
+    def [](key)
+      @data[key.to_sym]
+    end
+
+    def []=(key, value)
+      @data[key.to_sym] = value
+    end
+
+    def merge(other)
+      other_hash = other.is_a?(ConfigSection) ? other.to_h : other
+      ConfigSection.new(deep_merge(to_h, other_hash || {}))
+    end
+
+    def keys
+      @data.keys
+    end
+
+    def each(&block)
+      @data.each(&block)
+    end
+
+    private
+
+    def deep_merge(base, overlay)
+      base.merge(overlay) do |_key, old_val, new_val|
+        if old_val.is_a?(Hash) && new_val.is_a?(Hash)
+          deep_merge(old_val, new_val)
+        else
+          new_val
+        end
+      end
+    end
+  end
+end

data/lib/htm/config/validator.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+class HTM
+  class Config
+    module Validator
+      SUPPORTED_PROVIDERS = %i[
+        openai anthropic gemini azure ollama
+        huggingface openrouter bedrock deepseek
+      ].freeze
+
+      SUPPORTED_JOB_BACKENDS = %i[active_job sidekiq inline thread fiber].freeze
+      SUPPORTED_WEEK_STARTS = %i[sunday monday].freeze
+
+      def validate_config
+        validate_providers
+        validate_job_backend
+        validate_week_start
+        validate_relevance_weights
+      end
+
+      def validate_providers
+        validate_provider(:embedding_provider, embedding_provider)
+        validate_provider(:tag_provider, tag_provider)
+        validate_provider(:proposition_provider, proposition_provider)
+      end
+
+      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
+      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
+      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
+      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
+      end
+
+      def validate_callables
+        unless @embedding_generator.respond_to?(:call)
+          raise HTM::ValidationError, "embedding_generator must be callable"
+        end
+
+        unless @tag_extractor.respond_to?(:call)
+          raise HTM::ValidationError, "tag_extractor must be callable"
+        end
+
+        unless @proposition_extractor.respond_to?(:call)
+          raise HTM::ValidationError, "proposition_extractor must be callable"
+        end
+
+        unless @token_counter.respond_to?(:call)
+          raise HTM::ValidationError, "token_counter must be callable"
+        end
+      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
+      end
+    end
+  end
+end

data/lib/htm/config.rb

@@ -4,78 +4,18 @@ require 'anyway_config'
 require 'logger'
 require 'yaml'
 
+# Define Config class first to establish superclass
 class HTM
-  # ConfigSection provides method access to nested configuration hashes
-  #
-  # @example
-  #   section = ConfigSection.new(host: 'localhost', port: 5432)
-  #   section.host  # => 'localhost'
-  #   section.port  # => 5432
-  #
-  class ConfigSection
-    def initialize(hash = {})
-      @data = {}
-      (hash || {}).each do |key, value|
-        @data[key.to_sym] = value.is_a?(Hash) ? ConfigSection.new(value) : value
-      end
-    end
-
-    def method_missing(method, *args, &block)
-      key = method.to_s
-      if key.end_with?('=')
-        @data[key.chomp('=').to_sym] = args.first
-      elsif @data.key?(method)
-        @data[method]
-      else
-        nil
-      end
-    end
-
-    def respond_to_missing?(method, include_private = false)
-      key = method.to_s.chomp('=').to_sym
-      @data.key?(key) || super
-    end
-
-    def to_h
-      @data.transform_values do |v|
-        v.is_a?(ConfigSection) ? v.to_h : v
-      end
-    end
-
-    def [](key)
-      @data[key.to_sym]
-    end
-
-    def []=(key, value)
-      @data[key.to_sym] = value
-    end
-
-    def merge(other)
-      other_hash = other.is_a?(ConfigSection) ? other.to_h : other
-      ConfigSection.new(deep_merge(to_h, other_hash || {}))
-    end
-
-    def keys
-      @data.keys
-    end
-
-    def each(&block)
-      @data.each(&block)
-    end
-
-    private
-
-    def deep_merge(base, overlay)
-      base.merge(overlay) do |_key, old_val, new_val|
-        if old_val.is_a?(Hash) && new_val.is_a?(Hash)
-          deep_merge(old_val, new_val)
-        else
-          new_val
-        end
-      end
-    end
+  class Config < Anyway::Config
   end
+end
+
+require_relative 'config/section'
+require_relative 'config/validator'
+require_relative 'config/database'
+require_relative 'config/builder'
 
+class HTM
   # HTM Configuration using Anyway Config
   #
   # Schema is defined in lib/htm/config/defaults.yml (single source of truth)
@@ -114,7 +54,11 @@ class HTM
   #     config.embedding.model = 'text-embedding-3-small'
   #   end
   #
-  class Config < Anyway::Config
+  class Config
+    include Validator
+    include Database
+    include Builder
+
     config_name :htm
     env_prefix :htm
 
@@ -216,14 +160,6 @@ class HTM
     # Validation
     # ==========================================================================
 
-    SUPPORTED_PROVIDERS = %i[
-      openai anthropic gemini azure ollama
-      huggingface openrouter bedrock deepseek
-    ].freeze
-
-    SUPPORTED_JOB_BACKENDS = %i[active_job sidekiq inline thread fiber].freeze
-    SUPPORTED_WEEK_STARTS = %i[sunday monday].freeze
-
     # Default embedding dimensions by provider
     DEFAULT_DIMENSIONS = {
       openai: 1536,
@@ -237,7 +173,7 @@ class HTM
       deepseek: 1536
     }.freeze
 
-    on_load :coerce_nested_types, :validate_config, :setup_defaults
+    on_load :coerce_nested_types, :reconcile_database_config, :validate_config, :setup_defaults
 
     # ==========================================================================
     # Callable Accessors (not loaded from config sources)
@@ -260,44 +196,6 @@ class HTM
     # Convenience Accessors (for common nested values)
     # ==========================================================================
 
-    # Database convenience methods
-    def database_url
-      url = database.url
-      return url if url && !url.empty?
-
-      build_database_url
-    end
-
-    def database_config
-      url = database_url
-      return {} unless url
-
-      require 'uri'
-      uri = URI.parse(url)
-
-      # Coercion now merges env vars with SCHEMA defaults, so pool_size/timeout
-      # are always available even when only HTM_DATABASE__URL is set
-      {
-        adapter: 'postgresql',
-        host: uri.host,
-        port: uri.port || 5432,
-        database: uri.path&.sub(%r{^/}, ''),
-        username: uri.user,
-        password: uri.password,
-        pool: database.pool_size.to_i,
-        timeout: database.timeout.to_i,
-        sslmode: database.sslmode,
-        encoding: 'unicode',
-        prepared_statements: false,
-        advisory_locks: false
-      }.compact
-    end
-
-    def database_configured?
-      url = database_url
-      (url && !url.empty?) || (database.name && !database.name.empty?)
-    end
-
     # Embedding convenience accessors
     def embedding_provider
       provider = embedding.provider
@@ -493,6 +391,48 @@ class HTM
       self.class.env
     end
 
+    # ==========================================================================
+    # Environment Validation
+    # ==========================================================================
+
+    # Returns list of valid environment names from bundled defaults
+    #
+    # @return [Array<Symbol>] valid environment names (e.g., [:development, :production, :test])
+    def self.valid_environments
+      HTM::Loaders::DefaultsLoader.valid_environments
+    end
+
+    # Check if current environment is valid (defined in config)
+    #
+    # @return [Boolean] true if environment has a config section
+    def self.valid_environment?
+      HTM::Loaders::DefaultsLoader.valid_environment?(env)
+    end
+
+    # Validate that the current environment is configured
+    #
+    # @raise [HTM::ConfigurationError] if environment is invalid
+    # @return [true] if environment is valid
+    def self.validate_environment!
+      current = env
+      return true if HTM::Loaders::DefaultsLoader.valid_environment?(current)
+
+      valid = valid_environments.map(&:to_s).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."
+    end
+
+    # Instance method delegates
+    def valid_environment?
+      self.class.valid_environment?
+    end
+
+    def validate_environment!
+      self.class.validate_environment!
+    end
+
     # ==========================================================================
     # XDG Config Path Helpers
     # ==========================================================================
@@ -598,18 +538,6 @@ class HTM
 
     private
 
-    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
-
-      "postgresql://#{auth}#{database.host}:#{database.port}/#{database.name}"
-    end
-
     # ==========================================================================
     # Type Coercion Callback
     # ==========================================================================
@@ -622,77 +550,16 @@ class HTM
           providers[provider] = ConfigSection.new(value) if value.is_a?(Hash)
         end
       end
-    end
-
-    # ==========================================================================
-    # Validation Callbacks
-    # ==========================================================================
-
-    def validate_config
-      validate_providers
-      validate_job_backend
-      validate_week_start
-      validate_relevance_weights
-    end
-
-    def validate_providers
-      validate_provider(:embedding_provider, embedding_provider)
-      validate_provider(:tag_provider, tag_provider)
-      validate_provider(:proposition_provider, proposition_provider)
-    end
-
-    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
-    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})")
+      # 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
-    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
-    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})")
+      if database&.pool_size && !database.pool_size.is_a?(Integer)
+        database.pool_size = database.pool_size.to_i
       end
-    end
-
-    def validate_callables
-      unless @embedding_generator.respond_to?(:call)
-        raise HTM::ValidationError, "embedding_generator must be callable"
-      end
-
-      unless @tag_extractor.respond_to?(:call)
-        raise HTM::ValidationError, "tag_extractor must be callable"
-      end
-
-      unless @proposition_extractor.respond_to?(:call)
-        raise HTM::ValidationError, "proposition_extractor must be callable"
-      end
-
-      unless @token_counter.respond_to?(:call)
-        raise HTM::ValidationError, "token_counter must be callable"
-      end
-    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"
+      if database&.timeout && !database.timeout.is_a?(Integer)
+        database.timeout = database.timeout.to_i
       end
     end
 
@@ -716,169 +583,6 @@ class HTM
 
       :fiber
     end
-
-    def build_default_logger
-      logger = Logger.new($stdout)
-      logger.level = log_level
-      logger.formatter = proc do |severity, datetime, _progname, msg|
-        "[#{datetime.strftime('%Y-%m-%d %H:%M:%S')}] #{severity} -- HTM: #{msg}\n"
-      end
-      logger
-    end
-
-    def build_default_token_counter
-      lambda do |text|
-        require 'tiktoken_ruby' unless defined?(Tiktoken)
-        encoder = Tiktoken.encoding_for_model("gpt-3.5-turbo")
-        encoder.encode(text).length
-      end
-    end
-
-    def build_default_embedding_generator
-      lambda do |text|
-        require 'ruby_llm' unless defined?(RubyLLM)
-
-        configure_ruby_llm(embedding_provider)
-        refresh_ollama_models! if embedding_provider == :ollama
-
-        model = embedding_provider == :ollama ? normalize_ollama_model(embedding_model) : embedding_model
-        response = RubyLLM.embed(text, model: model)
-        embedding = extract_embedding_from_response(response)
-
-        unless embedding.is_a?(Array) && embedding.all? { |v| v.is_a?(Numeric) }
-          raise HTM::EmbeddingError, "Invalid embedding response format from #{embedding_provider}"
-        end
-
-        embedding
-      end
-    end
-
-    def build_default_tag_extractor
-      lambda do |text, existing_ontology = []|
-        require 'ruby_llm' unless defined?(RubyLLM)
-
-        configure_ruby_llm(tag_provider)
-        refresh_ollama_models! if tag_provider == :ollama
-
-        model = tag_provider == :ollama ? normalize_ollama_model(tag_model) : tag_model
-
-        prompt = build_tag_extraction_prompt(text, existing_ontology)
-        system_prompt = build_tag_system_prompt
-
-        chat = RubyLLM.chat(model: model)
-        chat.with_instructions(system_prompt)
-        response = chat.ask(prompt)
-
-        parse_tag_response(extract_text_from_response(response))
-      end
-    end
-
-    def build_default_proposition_extractor
-      lambda do |text|
-        require 'ruby_llm' unless defined?(RubyLLM)
-
-        configure_ruby_llm(proposition_provider)
-        refresh_ollama_models! if proposition_provider == :ollama
-
-        model = proposition_provider == :ollama ? normalize_ollama_model(proposition_model) : proposition_model
-
-        prompt = build_proposition_extraction_prompt(text)
-        system_prompt = build_proposition_system_prompt
-
-        chat = RubyLLM.chat(model: model)
-        chat.with_instructions(system_prompt)
-        response = chat.ask(prompt)
-
-        parse_proposition_response(extract_text_from_response(response))
-      end
-    end
-
-    # ==========================================================================
-    # Response Extraction Helpers
-    # ==========================================================================
-
-    def extract_embedding_from_response(response)
-      return nil unless response
-
-      case response
-      when Array
-        response
-      when ->(r) { r.respond_to?(:vectors) }
-        vectors = response.vectors
-        vectors.is_a?(Array) && vectors.first.is_a?(Array) ? vectors.first : vectors
-      when ->(r) { r.respond_to?(:to_a) }
-        response.to_a
-      when ->(r) { r.respond_to?(:embedding) }
-        response.embedding
-      else
-        if response.respond_to?(:instance_variable_get)
-          vectors = response.instance_variable_get(:@vectors)
-          return vectors.first if vectors.is_a?(Array) && vectors.first.is_a?(Array)
-          return vectors if vectors.is_a?(Array)
-        end
-        raise HTM::EmbeddingError, "Cannot extract embedding from response: #{response.class}"
-      end
-    end
-
-    def extract_text_from_response(response)
-      return '' unless response
-
-      case response
-      when String then response
-      when ->(r) { r.respond_to?(:content) } then response.content.to_s
-      when ->(r) { r.respond_to?(:text) } then response.text.to_s
-      else response.to_s
-      end
-    end
-
-    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.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?)
-    end
-
-    # ==========================================================================
-    # Prompt Builders
-    #
-    # These methods use configurable prompt templates from defaults.yml.
-    # Templates use %{placeholder} syntax for runtime interpolation.
-    # ==========================================================================
-
-    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
-
-      tag.user_prompt_template % {
-        text: text,
-        max_depth: max_tag_depth,
-        taxonomy_context: taxonomy_context
-      }
-    end
-
-    def build_tag_system_prompt
-      tag.system_prompt.to_s.strip
-    end
-
-    def build_proposition_extraction_prompt(text)
-      proposition.user_prompt_template % { text: text }
-    end
-
-    def build_proposition_system_prompt
-      proposition.system_prompt.to_s.strip
-    end
   end
 end