htm 0.0.17 → 0.0.20

data/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"
@@ -19,6 +19,7 @@ require_relative "htm/jobs/generate_tags_job"
 require_relative "htm/jobs/generate_propositions_job"
 require_relative "htm/loaders/markdown_chunker"
 require_relative "htm/loaders/markdown_loader"
+require_relative "htm/workflows/remember_workflow"
 require_relative "htm/observability"
 require_relative "htm/telemetry"
 require_relative "htm/working_memory_channel"
@@ -70,7 +71,7 @@ class HTM
   #
   # @param working_memory_size [Integer] Maximum tokens for working memory (default: 128,000)
   # @param robot_name [String] Human-readable name for this robot (auto-generated if not provided)
-  # @param db_config [Hash] Database configuration (uses ENV['HTM_DBURL'] if not provided)
+  # @param db_config [Hash] Database configuration (uses ENV['HTM_DATABASE__URL'] if not provided)
   # @param db_pool_size [Integer] Database connection pool size (default: 5)
   # @param db_query_timeout [Integer] Database query timeout in milliseconds (default: 30000)
   # @param db_cache_size [Integer] Number of database query results to cache (default: 1000, use 0 to disable)
@@ -170,7 +171,7 @@ class HTM
       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
@@ -251,7 +252,6 @@ class HTM
     normalized_timeframe = if timeframe == :auto
       result = HTM::Timeframe.normalize(:auto, query: topic)
       search_query = result.query  # Use cleaned query for search
-      HTM.logger.debug "Auto-extracted timeframe: #{result.extracted.inspect}" if result.extracted
       result.timeframe
     else
       HTM::Timeframe.normalize(timeframe)
@@ -595,7 +595,6 @@ class HTM
         tag = HTM::Models::Tag.find_or_create_by!(name: tag_name)
         HTM::Models::NodeTag.find_or_create_by!(node_id: node_id, tag_id: tag.id)
       end
-      HTM.logger.debug "Added #{manual_tags.length} manual tags to node #{node_id}"
     end
 
     # Enqueue tag generation using configured job backend
@@ -679,4 +678,125 @@ class HTM
     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

data/mkdocs.yml

@@ -48,7 +48,6 @@ theme:
     - navigation.tracking
     - navigation.tabs
     - navigation.tabs.sticky
-    - navigation.sections
     - navigation.path
     - navigation.indexes
     - navigation.top
@@ -166,7 +165,38 @@ extra:
 
 # Navigation
 nav:
-  - Home: index.md
+  - Home:
+      - Overview: index.md
+      - MCP (htm_mcp):
+          - Server (htm_mcp): guides/mcp-server.md
+          - Example Usage: examples/mcp-client.md
+      - Robots!:
+          - robots/index.md
+          - Why "Robots"?: robots/why-robots.md
+          - Hive Mind: robots/hive-mind.md
+          - Two-Tier Memory: robots/two-tier-memory.md
+          - Multi-Robot Systems: robots/multi-robot.md
+          - Robot Groups: robots/robot-groups.md
+      - Additional Features:
+          - Configuration: guides/configuration.md
+          - Hierarchical Tags: guides/tags.md
+          - Propositions: guides/propositions.md
+          - File Loading: guides/file-loading.md
+          - Telemetry: guides/telemetry.md
+          - Search Strategies: guides/search-strategies.md
+      - Examples:
+          - examples/index.md
+          - Basic Usage: examples/basic-usage.md
+          - Standalone App: examples/standalone-app.md
+          - LLM Configuration: examples/llm-configuration.md
+          - Config Files: examples/config-files.md
+          - File Loading: examples/file-loading.md
+          - Timeframes: examples/timeframes.md
+          - Robot Groups: examples/robot-groups.md
+          - Telemetry: examples/telemetry.md
+          - Framework Integration:
+              - Rails App: examples/rails-integration.md
+              - Sinatra App: examples/sinatra-integration.md
   - Getting Started:
       - getting-started/index.md
       - Installation: getting-started/installation.md
@@ -174,8 +204,6 @@ nav:
   - Architecture:
       - architecture/index.md
       - Overview: architecture/overview.md
-      - Two-Tier Memory: architecture/two-tier-memory.md
-      - Hive Mind: architecture/hive-mind.md
       - ADRs:
           - architecture/adrs/index.md
           - ADR-001 PostgreSQL & TimescaleDB: architecture/adrs/001-postgresql-timescaledb.md
@@ -196,10 +224,7 @@ nav:
       - Recalling Memories: guides/recalling-memories.md
       - Working Memory: guides/working-memory.md
       - Long-Term Memory: guides/long-term-memory.md
-      - Multi-Robot Usage: guides/multi-robot.md
-      - Search Strategies: guides/search-strategies.md
       - Context Assembly: guides/context-assembly.md
-      - MCP Server: guides/mcp-server.md
   - API Reference:
       - api/index.md
       - HTM Class: api/htm.md
@@ -211,7 +236,7 @@ nav:
           - api/yard-reference.md
           - HTM Module: api/yard/HTM.md
           - Core Classes:
-              - Configuration: api/yard/HTM/Configuration.md
+              - Configuration: api/yard/HTM/Config.md
               - Database: api/yard/HTM/Database.md
               - LongTermMemory: api/yard/HTM/LongTermMemory.md
               - WorkingMemory: api/yard/HTM/WorkingMemory.md

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: htm
 version: !ruby/object:Gem::Version
-  version: 0.0.17
+  version: 0.0.20
 platform: ruby
 authors:
 - Dewayne VanHoozer
@@ -149,6 +149,48 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: anyway_config
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.6'
+- !ruby/object:Gem::Dependency
+  name: simple_flow
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: async
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -291,7 +333,6 @@ files:
 - Rakefile
 - SETUP.md
 - bin/htm_mcp
-- config/database.yml
 - db/migrate/00001_enable_extensions.rb
 - db/migrate/00002_create_robots.rb
 - db/migrate/00003_create_file_sources.rb
@@ -316,7 +357,8 @@ files:
 - docs/api/yard/HTM/AuthorizationError.md
 - docs/api/yard/HTM/CircuitBreaker.md
 - docs/api/yard/HTM/CircuitBreakerOpenError.md
-- docs/api/yard/HTM/Configuration.md
+- docs/api/yard/HTM/Config.md
+- docs/api/yard/HTM/ConfigSection.md
 - docs/api/yard/HTM/Database.md
 - docs/api/yard/HTM/DatabaseError.md
 - docs/api/yard/HTM/EmbeddingError.md
@@ -359,16 +401,17 @@ files:
 - docs/architecture/adrs/010-redis-working-memory-rejected.md
 - docs/architecture/adrs/011-pgai-integration.md
 - docs/architecture/adrs/index.md
-- docs/architecture/hive-mind.md
 - docs/architecture/index.md
 - docs/architecture/overview.md
-- docs/architecture/two-tier-memory.md
 - docs/assets/css/custom.css
 - docs/assets/images/adr-010-current-architecture.svg
 - docs/assets/images/adr-010-proposed-architecture.svg
 - docs/assets/images/adr-dependency-tree.svg
+- docs/assets/images/balanced-strategy-decay.svg
 - docs/assets/images/class-hierarchy.svg
+- docs/assets/images/eviction-priority.svg
 - docs/assets/images/exception-hierarchy.svg
+- docs/assets/images/hive-mind-shared-memory.svg
 - docs/assets/images/htm-architecture-overview.svg
 - docs/assets/images/htm-complete-memory-flow.svg
 - docs/assets/images/htm-context-assembly-flow.svg
@@ -385,10 +428,12 @@ files:
 - docs/assets/images/htm-working-memory-architecture.svg
 - docs/assets/images/htm.jpg
 - docs/assets/images/htm_demo.gif
+- docs/assets/images/memory-topology.svg
 - docs/assets/images/multi-provider-failover.svg
 - docs/assets/images/project-structure.svg
 - docs/assets/images/robot-group-architecture.svg
 - docs/assets/images/test-directory-structure.svg
+- docs/assets/images/two-tier-memory-architecture.svg
 - docs/assets/js/mathjax.js
 - docs/assets/videos/htm_video.mp4
 - docs/database/README.md
@@ -429,31 +474,55 @@ files:
 - docs/development/schema.md
 - docs/development/setup.md
 - docs/development/testing.md
+- docs/examples/basic-usage.md
+- docs/examples/config-files.md
+- docs/examples/file-loading.md
+- docs/examples/index.md
+- docs/examples/llm-configuration.md
+- docs/examples/mcp-client.md
+- docs/examples/rails-integration.md
+- docs/examples/robot-groups.md
+- docs/examples/sinatra-integration.md
+- docs/examples/standalone-app.md
+- docs/examples/telemetry.md
+- docs/examples/timeframes.md
 - docs/getting-started/index.md
 - docs/getting-started/installation.md
 - docs/getting-started/quick-start.md
 - docs/guides/adding-memories.md
+- docs/guides/configuration.md
 - docs/guides/context-assembly.md
+- docs/guides/file-loading.md
 - docs/guides/getting-started.md
 - docs/guides/index.md
 - docs/guides/long-term-memory.md
 - docs/guides/mcp-server.md
-- docs/guides/multi-robot.md
+- docs/guides/propositions.md
 - docs/guides/recalling-memories.md
-- docs/guides/robot-groups.md
 - docs/guides/search-strategies.md
+- docs/guides/tags.md
+- docs/guides/telemetry.md
 - docs/guides/working-memory.md
 - docs/images/htm-er-diagram.svg
 - docs/images/telemetry-architecture.svg
 - docs/index.md
 - docs/multi_framework_support.md
+- docs/robots/hive-mind.md
+- docs/robots/index.md
+- docs/robots/multi-robot.md
+- docs/robots/robot-groups.md
+- docs/robots/two-tier-memory.md
+- docs/robots/why-robots.md
 - docs/setup_local_database.md
-- docs/telemetry.md
 - docs/using_rake_tasks_in_your_app.md
 - examples/README.md
 - examples/basic_usage.rb
 - examples/cli_app/README.md
 - examples/cli_app/htm_cli.rb
+- examples/config_file_example/README.md
+- examples/config_file_example/config/htm.local.yml
+- examples/config_file_example/custom_config.yml
+- examples/config_file_example/show_config.rb
 - examples/custom_llm_configuration.rb
 - examples/example_app/Rakefile
 - examples/example_app/app.rb
@@ -523,7 +592,8 @@ files:
 - lib/htm.rb
 - lib/htm/active_record_config.rb
 - lib/htm/circuit_breaker.rb
-- lib/htm/configuration.rb
+- lib/htm/config.rb
+- lib/htm/config/defaults.yml
 - lib/htm/database.rb
 - lib/htm/embedding_service.rb
 - lib/htm/errors.rb
@@ -532,8 +602,10 @@ files:
 - lib/htm/jobs/generate_embedding_job.rb
 - lib/htm/jobs/generate_propositions_job.rb
 - lib/htm/jobs/generate_tags_job.rb
+- lib/htm/loaders/defaults_loader.rb
 - lib/htm/loaders/markdown_chunker.rb
 - lib/htm/loaders/markdown_loader.rb
+- lib/htm/loaders/xdg_config_loader.rb
 - lib/htm/long_term_memory.rb
 - lib/htm/long_term_memory/fulltext_search.rb
 - lib/htm/long_term_memory/hybrid_search.rb
@@ -565,6 +637,7 @@ files:
 - lib/htm/timeframe.rb
 - lib/htm/timeframe_extractor.rb
 - lib/htm/version.rb
+- lib/htm/workflows/remember_workflow.rb
 - lib/htm/working_memory.rb
 - lib/htm/working_memory_channel.rb
 - lib/tasks/db.rake
@@ -596,7 +669,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.1
+rubygems_version: 4.0.2
 specification_version: 4
 summary: Hierarchical Temporal Memory for LLM robots
 test_files: []

data/config/database.yml

@@ -1,77 +0,0 @@
-# HTM Database Configuration
-# Uses ERB to read from environment variables
-#
-# Priority:
-# 1. HTM_DBURL - Full connection URL (preferred for development/production)
-# 2. Individual HTM_DB* variables - Host, name, user, password, port
-# 3. Defaults for development/test
-#
-# Example HTM_DBURL format:
-#   postgresql://user:password@host:port/database?sslmode=require
-#
-# Environment detection priority:
-#   HTM_ENV > RAILS_ENV > RACK_ENV > 'development'
-#
-# Test database:
-#   Tests always use htm_test database.
-#   Set HTM_ENV=test (or RAILS_ENV=test) to use the test configuration.
-
-<%
-  require 'uri'
-
-  # Determine current environment (HTM_ENV takes priority for non-Rails users)
-  current_env = ENV['HTM_ENV'] || ENV['RAILS_ENV'] || ENV['RACK_ENV'] || 'development'
-
-  # Parse connection from HTM_DBURL or use individual variables
-  if ENV['HTM_DBURL']
-    uri = URI.parse(ENV['HTM_DBURL'])
-    params = URI.decode_www_form(uri.query || '').to_h
-    base_database = uri.path[1..-1]
-
-    # Extract base name (remove _development, _test, _production suffixes if present)
-    base_name = base_database.sub(/_(development|test|production)$/, '')
-
-    db_config = {
-      'host' => uri.host,
-      'port' => uri.port || 5432,
-      'base_name' => base_name,
-      'username' => uri.user,
-      'password' => uri.password,
-      'sslmode' => params['sslmode'] || 'prefer'
-    }
-  else
-    db_config = {
-      'host' => ENV.fetch('HTM_DBHOST', 'localhost'),
-      'port' => ENV.fetch('HTM_DBPORT', 5432).to_i,
-      'base_name' => ENV.fetch('HTM_DBNAME', 'htm').sub(/_(development|test|production)$/, ''),
-      'username' => ENV.fetch('HTM_DBUSER', ENV['USER']),
-      'password' => ENV.fetch('HTM_DBPASS', ''),
-      'sslmode' => ENV.fetch('HTM_SSLMODE', 'prefer')
-    }
-  end
-%>
-
-default: &default
-  adapter: postgresql
-  encoding: unicode
-  pool: <%= ENV.fetch("HTM_DB_POOL_SIZE", "10").to_i %>
-  timeout: 5000
-  prepared_statements: false
-  advisory_locks: false
-  host: <%= db_config['host'] %>
-  port: <%= db_config['port'] %>
-  username: <%= db_config['username'] %>
-  password: <%= db_config['password'] %>
-  sslmode: <%= db_config['sslmode'] %>
-
-development:
-  <<: *default
-  database: <%= db_config['base_name'] %>_development
-
-test:
-  <<: *default
-  database: <%= db_config['base_name'] %>_test
-
-production:
-  <<: *default
-  database: <%= db_config['base_name'] %>_production