chore(config): refactor configuration management and add local config support

This commit introduces several configuration-related changes:
- Migrated from custom configuration to Anyway::Config for more robust configuration management
- Updated config access from direct attributes to nested configuration
- Added support for local configuration file (config/htm.local.yml)
- Updated examples and version to reflect configuration changes

Refs: #config_refactor

Author: MadBomber

.gitignore

@@ -65,3 +65,6 @@ build-iPhoneSimulator/
 
 # Used by RuboCop. Remote config files pulled in from inherit_from directive.
 # .rubocop-https?--*
+
+# Local configuration (anyway_config local overrides)
+config/htm.local.yml

.irbrc

@@ -21,12 +21,12 @@ end
 
 # Configure HTM with sensible defaults for interactive use
 HTM.configure do |config|
-  config.job_backend = :inline
-  config.embedding_provider = :ollama
-  config.embedding_model = 'nomic-embed-text:latest'
-  config.embedding_dimensions = 768
-  config.tag_provider = :ollama
-  config.tag_model = 'gemma3:latest'
+  config.job.backend = :inline
+  config.embedding.provider = :ollama
+  config.embedding.model = 'nomic-embed-text:latest'
+  config.embedding.dimensions = 768
+  config.tag.provider = :ollama
+  config.tag.model = 'gemma3:latest'
   config.reset_to_defaults
 end
 puts "✓ HTM configured (inline jobs, Ollama provider)"

Gemfile.lock

@@ -1,8 +1,9 @@
 PATH
   remote: .
   specs:
-    htm (0.0.17)
+    htm (0.0.18)
       activerecord
+      anyway_config (>= 2.6)
       baran
       chronic
       fast-mcp
@@ -38,6 +39,8 @@ GEM
     addressable (2.8.8)
       public_suffix (>= 2.0.2, < 8.0)
     ansi (1.5.0)
+    anyway_config (2.7.2)
+      ruby-next-core (~> 1.0)
     baran (0.2.1)
     base64 (0.3.0)
     bigdecimal (3.3.1)
@@ -144,6 +147,7 @@ GEM
     rb_sys (0.9.123)
       rake-compiler-dock (= 1.10.0)
     rexml (3.4.4)
+    ruby-next-core (1.1.2)
     ruby-progressbar (1.13.0)
     ruby_llm (1.9.1)
       base64
@@ -168,7 +172,7 @@ GEM
       simplecov_json_formatter (~> 0.1)
     simplecov-html (0.13.2)
     simplecov_json_formatter (0.1.4)
-    tiktoken_ruby (0.0.13)
+    tiktoken_ruby (0.0.14.1)
       rb_sys (~> 0.9)
     timeout (0.6.0)
     tzinfo (2.0.6)

examples/cli_app/htm_cli.rb

@@ -39,7 +39,7 @@ def initialize
     # Configure HTM for CLI usage
     HTM.configure do |config|
       # Use inline mode for synchronous execution
-      config.job_backend = :inline
+      config.job.backend = :inline
 
       # CLI-friendly logging
       config.logger.level = Logger::INFO

htm.gemspec

@@ -46,6 +46,7 @@ Gem::Specification.new do |spec|
   spec.add_dependency "chronic"
   spec.add_dependency "fast-mcp"
   spec.add_dependency "baran"
+  spec.add_dependency "anyway_config", ">= 2.6"
   # Optional runtime dependencies for different job backends
   # - ActiveJob (bundled with Rails)
   # - Sidekiq (add to Gemfile if using :sidekiq backend)

lib/htm.rb

@@ -2,7 +2,7 @@
 
 require_relative "htm/version"
 require_relative "htm/errors"
-require_relative "htm/configuration"
+require_relative "htm/config"
 require_relative "htm/circuit_breaker"
 require_relative "htm/active_record_config"
 require_relative "htm/database"
@@ -170,7 +170,7 @@ def remember(content, tags: [], metadata: {})
       enqueue_tags_job(node_id, manual_tags: tags)
 
       # Enqueue proposition extraction if enabled and not already a proposition
-      if HTM.configuration.extract_propositions && !metadata[:is_proposition]
+      if HTM.config.extract_propositions && !metadata[:is_proposition]
         enqueue_propositions_job(node_id)
       end
     else
@@ -679,4 +679,125 @@ def validate_metadata!(metadata)
     end
   end
 
+  # ===========================================================================
+  # Class Methods
+  # ===========================================================================
+
+  class << self
+    # Get current configuration (singleton)
+    #
+    # @return [HTM::Config]
+    #
+    def config
+      @config ||= Config.new
+    end
+
+    # Alias for backward compatibility
+    alias configuration config
+
+    # Configure HTM
+    #
+    # @yield [config] Configuration object
+    # @yieldparam config [HTM::Config]
+    #
+    # @example Custom configuration
+    #   HTM.configure do |config|
+    #     config.embedding_generator = ->(text) { MyEmbedder.embed(text) }
+    #     config.tag_extractor = ->(text, ontology) { MyTagger.extract(text, ontology) }
+    #   end
+    #
+    # @example Default configuration
+    #   HTM.configure  # Uses RubyLLM defaults
+    #
+    def configure
+      yield(config) if block_given?
+      config.validate!
+      config
+    end
+
+    # Reset configuration to defaults
+    def reset_configuration!
+      @config = nil
+    end
+
+    # Get current environment
+    #
+    # @return [String] Current environment name
+    #
+    def env
+      Config.env
+    end
+
+    # Check if running in test environment
+    #
+    # @return [Boolean]
+    #
+    def test?
+      env == 'test'
+    end
+
+    # Check if running in development environment
+    #
+    # @return [Boolean]
+    #
+    def development?
+      env == 'development'
+    end
+
+    # Check if running in production environment
+    #
+    # @return [Boolean]
+    #
+    def production?
+      env == 'production'
+    end
+
+    # Generate embedding using EmbeddingService
+    #
+    # @param text [String] Text to embed
+    # @return [Array<Float>] Embedding vector (original, not padded)
+    #
+    def embed(text)
+      result = HTM::EmbeddingService.generate(text)
+      result[:embedding]
+    end
+
+    # Extract tags using TagService
+    #
+    # @param text [String] Text to analyze
+    # @param existing_ontology [Array<String>] Sample of existing tags for context
+    # @return [Array<String>] Extracted and validated tag names
+    #
+    def extract_tags(text, existing_ontology: [])
+      HTM::TagService.extract(text, existing_ontology: existing_ontology)
+    end
+
+    # Extract propositions using PropositionService
+    #
+    # @param text [String] Text to analyze
+    # @return [Array<String>] Extracted atomic propositions
+    #
+    def extract_propositions(text)
+      HTM::PropositionService.extract(text)
+    end
+
+    # Count tokens using configured counter
+    #
+    # @param text [String] Text to count tokens for
+    # @return [Integer] Token count
+    #
+    def count_tokens(text)
+      config.token_counter.call(text)
+    rescue StandardError => e
+      raise HTM::ValidationError, "Token counting failed: #{e.message}"
+    end
+
+    # Get configured logger
+    #
+    # @return [Logger] Configured logger instance
+    #
+    def logger
+      config.logger
+    end
+  end
 end

lib/htm/active_record_config.rb

@@ -3,14 +3,18 @@
 require 'active_record'
 require 'pg'
 require 'neighbor'
-require 'erb'
-require 'yaml'
 
 class HTM
   # ActiveRecord database configuration and model loading
+  #
+  # Uses HTM::Config for database settings. Configuration can come from:
+  # - config/htm.yml (environment-specific)
+  # - Environment variables (HTM_DB_URL, HTM_DB_HOST, etc.)
+  # - Programmatic configuration via HTM.configure
+  #
   class ActiveRecordConfig
     class << self
-      # Establish database connection from config/database.yml
+      # Establish database connection from HTM::Config
       def establish_connection!
         config = load_database_config
 
@@ -25,27 +29,26 @@ def establish_connection!
         true
       end
 
-      # Load and parse database configuration from YAML with ERB
+      # Load database configuration from HTM::Config
+      #
+      # @return [Hash] ActiveRecord-compatible configuration hash
+      #
       def load_database_config
-        config_path = File.expand_path('../../config/database.yml', __dir__)
-
-        unless File.exist?(config_path)
-          raise "Database configuration file not found at #{config_path}"
+        htm_config = HTM.config
+
+        # If we have a database URL, parse it
+        if htm_config.database_url
+          htm_config.database_config
+        else
+          # Fall back to legacy config/database.yml if it exists and no config in HTM::Config
+          legacy_config_path = File.expand_path('../../config/database.yml', __dir__)
+
+          if File.exist?(legacy_config_path) && !htm_config.database_configured?
+            load_legacy_database_config(legacy_config_path)
+          else
+            htm_config.database_config
+          end
         end
-
-        # Read and parse ERB
-        erb_content = ERB.new(File.read(config_path)).result
-        db_config = YAML.safe_load(erb_content, aliases: true)
-
-        # Get configuration for current environment
-        config = db_config[HTM.env]
-
-        unless config
-          raise "No database configuration found for environment: #{HTM.env}"
-        end
-
-        # Convert string keys to symbols for ActiveRecord
-        config.transform_keys(&:to_sym)
       end
 
       # Check if connection is established and active
@@ -103,6 +106,27 @@ def connection_stats
 
       private
 
+      # Load legacy database.yml configuration (for backward compatibility)
+      #
+      # @param config_path [String] Path to database.yml
+      # @return [Hash] ActiveRecord-compatible configuration hash
+      #
+      def load_legacy_database_config(config_path)
+        require 'erb'
+        require 'yaml'
+
+        erb_content = ERB.new(File.read(config_path)).result
+        db_config = YAML.safe_load(erb_content, aliases: true)
+
+        config = db_config[HTM.env]
+
+        unless config
+          raise "No database configuration found for environment: #{HTM.env}"
+        end
+
+        config.transform_keys(&:to_sym)
+      end
+
       # Require all model files
       def require_models
         require_relative 'models/robot'