htm 0.0.20 → 0.0.31

data/lib/htm/config.rb

@@ -1,81 +1,19 @@
 # frozen_string_literal: true
 
-require 'anyway_config'
+require 'myway_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 < MywayConfig::Base
   end
+end
+
+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,38 +52,18 @@ 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
+    defaults_path File.expand_path('config/defaults.yml', __dir__)
 
-    # ==========================================================================
-    # Schema Definition (loaded from defaults.yml - single source of truth)
-    # ==========================================================================
-
-    # Path to bundled defaults file (defines both schema and default values)
-    DEFAULTS_PATH = File.expand_path('config/defaults.yml', __dir__).freeze
-
-    # Load schema from defaults.yml at class definition time
-    begin
-      defaults_content = File.read(DEFAULTS_PATH)
-      raw_yaml = YAML.safe_load(
-        defaults_content,
-        permitted_classes: [Symbol],
-        symbolize_names: true,
-        aliases: true
-      ) || {}
-      SCHEMA = raw_yaml[:defaults] || {}
-    rescue StandardError => e
-      warn "HTM: Could not load schema from #{DEFAULTS_PATH}: #{e.message}"
-      SCHEMA = {}
-    end
-
-    # Nested section attributes (defined as hashes, converted to ConfigSection)
-    attr_config :database, :service, :embedding, :tag, :proposition,
-                :chunking, :circuit_breaker, :relevance, :job, :providers
-
-    # Top-level scalar attributes
-    attr_config :week_start, :connection_timeout, :telemetry_enabled, :log_level
+    # Auto-configure attributes and coercions from defaults.yml schema
+    # This replaces manual attr_config and coerce_types declarations
+    auto_configure!
 
     # Custom environment detection: HTM_ENV > RAILS_ENV > RACK_ENV > 'development'
     class << self
@@ -158,72 +76,10 @@ class HTM
       end
     end
 
-    # ==========================================================================
-    # Type Coercion
-    # ==========================================================================
-
-    TO_SYMBOL = ->(v) { v.nil? ? nil : v.to_s.to_sym }
-
-    # Create a coercion that merges incoming value with SCHEMA defaults for a section.
-    # This ensures env vars like HTM_DATABASE__URL don't lose other defaults.
-    def self.config_section_with_defaults(section_key)
-      defaults = SCHEMA[section_key] || {}
-      ->(v) {
-        return v if v.is_a?(ConfigSection)
-        incoming = v || {}
-        # Deep merge: defaults first, then overlay incoming values
-        merged = deep_merge_hashes(defaults.dup, incoming)
-        ConfigSection.new(merged)
-      }
-    end
-
-    # Deep merge helper for coercion
-    def self.deep_merge_hashes(base, overlay)
-      base.merge(overlay) do |_key, old_val, new_val|
-        if old_val.is_a?(Hash) && new_val.is_a?(Hash)
-          deep_merge_hashes(old_val, new_val)
-        else
-          new_val.nil? ? old_val : new_val
-        end
-      end
-    end
-
-    coerce_types(
-      # Nested sections -> ConfigSection objects (with SCHEMA defaults merged)
-      database: config_section_with_defaults(:database),
-      service: config_section_with_defaults(:service),
-      embedding: config_section_with_defaults(:embedding),
-      tag: config_section_with_defaults(:tag),
-      proposition: config_section_with_defaults(:proposition),
-      chunking: config_section_with_defaults(:chunking),
-      circuit_breaker: config_section_with_defaults(:circuit_breaker),
-      relevance: config_section_with_defaults(:relevance),
-      job: config_section_with_defaults(:job),
-      providers: config_section_with_defaults(:providers),
-
-      # Top-level symbols
-      week_start: TO_SYMBOL,
-      log_level: TO_SYMBOL,
-
-      # Top-level integers
-      connection_timeout: :integer,
-
-      # Top-level booleans
-      telemetry_enabled: :boolean
-    )
-
     # ==========================================================================
     # 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 +93,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 +116,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
@@ -358,11 +176,11 @@ class HTM
 
     # Chunking convenience accessors
     def chunk_size
-      chunking.size.to_i
+      chunking.chunk_size.to_i
     end
 
     def chunk_overlap
-      chunking.overlap.to_i
+      chunking.chunk_overlap.to_i
     end
 
     # Circuit breaker convenience accessors
@@ -477,20 +295,52 @@ class HTM
     # Environment Helpers
     # ==========================================================================
 
-    def test?
-      self.class.env == 'test'
+    # Note: test?, development?, production? are auto-generated by MywayConfig::Base
+    # based on environment keys in defaults.yml
+
+    def environment
+      self.class.env
+    end
+
+    # ==========================================================================
+    # Environment Validation
+    # ==========================================================================
+
+    # Returns list of valid environment names from bundled defaults
+    # Inherited from MywayConfig::Base - delegates to DefaultsLoader
+    #
+    # @return [Array<Symbol>] valid environment names (e.g., [:development, :production, :test])
+    # Note: valid_environments is inherited from MywayConfig::Base
+
+    # Check if current environment is valid (defined in config)
+    #
+    # @return [Boolean] true if environment has a config section
+    def self.valid_environment?
+      MywayConfig::Loaders::DefaultsLoader.valid_environment?(config_name, env)
     end
 
-    def development?
-      self.class.env == 'development'
+    # 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 valid_environment?
+
+      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
 
-    def production?
-      self.class.env == 'production'
+    # Instance method delegates
+    def valid_environment?
+      self.class.valid_environment?
     end
 
-    def environment
-      self.class.env
+    def validate_environment!
+      self.class.validate_environment!
     end
 
     # ==========================================================================
@@ -498,7 +348,7 @@ class HTM
     # ==========================================================================
 
     def self.xdg_config_paths
-      HTM::Loaders::XdgConfigLoader.config_paths
+      MywayConfig::Loaders::XdgConfigLoader.config_paths(config_name)
     end
 
     def self.xdg_config_file
@@ -512,7 +362,7 @@ class HTM
     end
 
     def self.active_xdg_config_file
-      HTM::Loaders::XdgConfigLoader.find_config_file('htm')
+      MywayConfig::Loaders::XdgConfigLoader.find_config_file(config_name)
     end
 
     # ==========================================================================
@@ -598,101 +448,29 @@ 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
     # ==========================================================================
 
     def coerce_nested_types
       # Ensure nested provider sections are ConfigSections
-      if providers.is_a?(ConfigSection)
+      # 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] = ConfigSection.new(value) if value.is_a?(Hash)
+          providers[provider] = MywayConfig::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})")
+      if database&.pool_size && !database.pool_size.is_a?(Integer)
+        database.pool_size = database.pool_size.to_i
       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"
+      if database&.timeout && !database.timeout.is_a?(Integer)
+        database.timeout = database.timeout.to_i
       end
     end
 
@@ -716,173 +494,8 @@ 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
 
-# Register custom loaders after Config class is defined
-# Order matters: defaults (lowest priority) -> XDG -> project config -> ENV (highest)
-require_relative 'loaders/defaults_loader'
-require_relative 'loaders/xdg_config_loader'
+# myway_config provides DefaultsLoader and XdgConfigLoader automatically
+# Loaders are registered when MywayConfig.setup! is called (happens on require)