htm 0.0.18 → 0.0.30

data/examples/{cli_app → 07_cli_app}/htm_cli.rb

@@ -9,15 +9,18 @@
 # - Progress feedback
 # - Database persistence
 #
+# Prerequisites:
+# 1. Set up examples database: rake examples:setup
+# 2. Install dependencies: bundle install
+#
 # Usage:
-#   ruby htm_cli.rb
+#   ruby examples/cli_app/htm_cli.rb
 #
 # Environment:
-#   HTM_DATABASE__URL - PostgreSQL connection URL (required)
 #   OLLAMA_URL - Ollama server URL (default: http://localhost:11434)
 #
 
-require_relative '../../lib/htm'
+require_relative '../examples_helper'
 require 'io/console'
 require 'ruby_llm'
 
@@ -86,7 +89,7 @@ class HTMCli
 
     loop do
       print "\nhtm> "
-      input = gets&.chomp
+      input = $stdin.gets&.chomp
       break if input.nil? || input == 'exit'
 
       handle_command(input)
@@ -139,7 +142,7 @@ class HTMCli
     puts "[✓] Stored as node #{node_id} (#{duration}ms)"
 
     # Show what was generated (inline mode, so already complete)
-    node = HTM::Models::Node.includes(:tags).find(node_id)
+    node = HTM::Models::Node[node_id]
 
     if node.embedding
       puts "    Embedding: #{node.embedding_dimension} dimensions"
@@ -217,7 +220,7 @@ class HTMCli
       end
 
       # Show tags if any
-      node = HTM::Models::Node.includes(:tags).find(memory['id'])
+      node = HTM::Models::Node[memory['id']]
       if node.tags.any?
         puts "   Tags: #{node.tags.map(&:name).join(', ')}"
       else
@@ -259,10 +262,10 @@ class HTMCli
     puts
 
     # Get all tags with their nodes, optionally filtered by prefix
-    tags_query = HTM::Models::Tag.includes(:nodes).order(:name)
-    tags_query = tags_query.where("name LIKE ?", "#{filter}%") if filter && !filter.empty?
+    tags_query = HTM::Models::Tag.order(:name)
+    tags_query = tags_query.where(Sequel.like(:name, "#{filter}%")) if filter && !filter.empty?
 
-    tags = tags_query.to_a
+    tags = tags_query.eager(:nodes).all
 
     if tags.empty?
       if filter
@@ -308,8 +311,8 @@ class HTMCli
     puts
 
     total_nodes = HTM::Models::Node.count
-    nodes_with_embeddings = HTM::Models::Node.where.not(embedding: nil).count
-    nodes_with_tags = HTM::Models::Node.joins(:tags).distinct.count
+    nodes_with_embeddings = HTM::Models::Node.exclude(embedding: nil).count
+    nodes_with_tags = HTM::Models::NodeTag.distinct.select(:node_id).count
     total_tags = HTM::Models::Tag.count
     total_robots = HTM::Models::Robot.count
 
@@ -376,17 +379,7 @@ class HTMCli
 end
 
 # Check database configuration
-unless ENV['HTM_DATABASE__URL']
-  puts
-  puts "[✗] Error: HTM_DATABASE__URL environment variable not set"
-  puts
-  puts "Please set your database connection URL:"
-  puts "  export HTM_DATABASE__URL='postgresql://postgres@localhost:5432/htm_development'"
-  puts
-  puts "See SETUP.md for database setup instructions."
-  puts
-  exit 1
-end
+ExamplesHelper.require_database!
 
 # Check Ollama connection (optional but recommended)
 begin

data/examples/08_sinatra_app/Gemfile.lock

@@ -0,0 +1,241 @@
+PATH
+  remote: ../..
+  specs:
+    htm (0.0.21)
+      activesupport
+      anyway_config (>= 2.6)
+      async (~> 2.0)
+      baran
+      chronic
+      fast-mcp
+      lru_redux
+      pg (>= 1.5.0)
+      ruby-progressbar
+      ruby_llm
+      sequel (>= 5.0)
+      sequel_pg
+      simple_flow
+      tiktoken_ruby
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    activesupport (8.1.2)
+      base64
+      bigdecimal
+      concurrent-ruby (~> 1.0, >= 1.3.1)
+      connection_pool (>= 2.2.5)
+      drb
+      i18n (>= 1.6, < 2)
+      json
+      logger (>= 1.4.2)
+      minitest (>= 5.1)
+      securerandom (>= 0.3)
+      tzinfo (~> 2.0, >= 2.0.5)
+      uri (>= 0.13.1)
+    addressable (2.8.8)
+      public_suffix (>= 2.0.2, < 8.0)
+    anyway_config (2.7.2)
+      ruby-next-core (~> 1.0)
+    async (2.36.0)
+      console (~> 1.29)
+      fiber-annotation
+      io-event (~> 1.11)
+      metrics (~> 0.12)
+      traces (~> 0.18)
+    baran (0.2.1)
+    base64 (0.3.0)
+    bigdecimal (4.0.1)
+    chronic (0.10.2)
+    concurrent-ruby (1.3.6)
+    connection_pool (3.0.2)
+    console (1.34.2)
+      fiber-annotation
+      fiber-local (~> 1.1)
+      json
+    drb (2.2.3)
+    dry-configurable (1.3.0)
+      dry-core (~> 1.1)
+      zeitwerk (~> 2.6)
+    dry-core (1.2.0)
+      concurrent-ruby (~> 1.0)
+      logger
+      zeitwerk (~> 2.6)
+    dry-inflector (1.3.1)
+    dry-initializer (3.2.0)
+    dry-logic (1.6.0)
+      bigdecimal
+      concurrent-ruby (~> 1.0)
+      dry-core (~> 1.1)
+      zeitwerk (~> 2.6)
+    dry-schema (1.15.0)
+      concurrent-ruby (~> 1.0)
+      dry-configurable (~> 1.0, >= 1.0.1)
+      dry-core (~> 1.1)
+      dry-initializer (~> 3.2)
+      dry-logic (~> 1.6)
+      dry-types (~> 1.8)
+      zeitwerk (~> 2.6)
+    dry-types (1.9.0)
+      bigdecimal (>= 3.0)
+      concurrent-ruby (~> 1.0)
+      dry-core (~> 1.0)
+      dry-inflector (~> 1.0)
+      dry-logic (~> 1.4)
+      zeitwerk (~> 2.6)
+    event_stream_parser (1.0.0)
+    faraday (2.14.0)
+      faraday-net_http (>= 2.0, < 3.5)
+      json
+      logger
+    faraday-multipart (1.2.0)
+      multipart-post (~> 2.0)
+    faraday-net_http (3.4.2)
+      net-http (~> 0.5)
+    faraday-retry (2.4.0)
+      faraday (~> 2.0)
+    fast-mcp (1.6.0)
+      addressable (~> 2.8)
+      base64
+      dry-schema (~> 1.14)
+      json (~> 2.0)
+      mime-types (~> 3.4)
+      rack (>= 2.0, < 4.0)
+    ffi (1.17.3-aarch64-linux-gnu)
+    ffi (1.17.3-aarch64-linux-musl)
+    ffi (1.17.3-arm-linux-gnu)
+    ffi (1.17.3-arm-linux-musl)
+    ffi (1.17.3-arm64-darwin)
+    ffi (1.17.3-x86_64-darwin)
+    ffi (1.17.3-x86_64-linux-gnu)
+    ffi (1.17.3-x86_64-linux-musl)
+    fiber-annotation (0.2.0)
+    fiber-local (1.1.0)
+      fiber-storage
+    fiber-storage (1.0.1)
+    i18n (1.14.8)
+      concurrent-ruby (~> 1.0)
+    io-event (1.14.2)
+    json (2.18.0)
+    listen (3.10.0)
+      logger
+      rb-fsevent (~> 0.10, >= 0.10.3)
+      rb-inotify (~> 0.9, >= 0.9.10)
+    logger (1.7.0)
+    lru_redux (1.1.0)
+    marcel (1.1.0)
+    metrics (0.15.0)
+    mime-types (3.7.0)
+      logger
+      mime-types-data (~> 3.2025, >= 3.2025.0507)
+    mime-types-data (3.2026.0113)
+    minitest (6.0.1)
+      prism (~> 1.5)
+    multi_json (1.19.1)
+    multipart-post (2.4.1)
+    mustermann (3.0.4)
+      ruby2_keywords (~> 0.0.1)
+    net-http (0.9.1)
+      uri (>= 0.11.1)
+    nio4r (2.7.5)
+    pg (1.6.3)
+    pg (1.6.3-aarch64-linux)
+    pg (1.6.3-aarch64-linux-musl)
+    pg (1.6.3-arm64-darwin)
+    pg (1.6.3-x86_64-darwin)
+    pg (1.6.3-x86_64-linux)
+    pg (1.6.3-x86_64-linux-musl)
+    prism (1.8.0)
+    public_suffix (7.0.2)
+    puma (6.6.1)
+      nio4r (~> 2.0)
+    rack (2.2.21)
+    rack-protection (3.2.0)
+      base64 (>= 0.1.0)
+      rack (~> 2.2, >= 2.2.4)
+    rb-fsevent (0.11.2)
+    rb-inotify (0.11.1)
+      ffi (~> 1.0)
+    redis (5.4.1)
+      redis-client (>= 0.22.0)
+    redis-client (0.26.3)
+      connection_pool
+    rerun (0.14.0)
+      listen (~> 3.0)
+    ruby-next-core (1.2.0)
+    ruby-progressbar (1.13.0)
+    ruby2_keywords (0.0.5)
+    ruby_llm (1.11.0)
+      base64
+      event_stream_parser (~> 1)
+      faraday (>= 1.10.0)
+      faraday-multipart (>= 1)
+      faraday-net_http (>= 1)
+      faraday-retry (>= 1)
+      marcel (~> 1.0)
+      ruby_llm-schema (~> 0.2.1)
+      zeitwerk (~> 2)
+    ruby_llm-schema (0.2.5)
+    securerandom (0.4.1)
+    sequel (5.100.0)
+      bigdecimal
+    sequel_pg (1.18.2)
+      pg (>= 0.18.0, != 1.2.0)
+      sequel (>= 4.38.0)
+    sidekiq (7.3.9)
+      base64
+      connection_pool (>= 2.3.0)
+      logger
+      rack (>= 2.2.4)
+      redis-client (>= 0.22.2)
+    simple_flow (0.3.0)
+    sinatra (3.2.0)
+      mustermann (~> 3.0)
+      rack (~> 2.2, >= 2.2.4)
+      rack-protection (= 3.2.0)
+      tilt (~> 2.0)
+    sinatra-contrib (3.2.0)
+      multi_json (>= 0.0.2)
+      mustermann (~> 3.0)
+      rack-protection (= 3.2.0)
+      sinatra (= 3.2.0)
+      tilt (~> 2.0)
+    tiktoken_ruby (0.0.15.1-aarch64-linux)
+    tiktoken_ruby (0.0.15.1-aarch64-linux-musl)
+    tiktoken_ruby (0.0.15.1-arm-linux)
+    tiktoken_ruby (0.0.15.1-arm64-darwin)
+    tiktoken_ruby (0.0.15.1-x86_64-darwin)
+    tiktoken_ruby (0.0.15.1-x86_64-linux)
+    tiktoken_ruby (0.0.15.1-x86_64-linux-musl)
+    tilt (2.7.0)
+    traces (0.18.2)
+    tzinfo (2.0.6)
+      concurrent-ruby (~> 1.0)
+    uri (1.1.1)
+    zeitwerk (2.7.4)
+
+PLATFORMS
+  aarch64-linux
+  aarch64-linux-gnu
+  aarch64-linux-musl
+  arm-linux
+  arm-linux-gnu
+  arm-linux-musl
+  arm64-darwin
+  x86_64-darwin
+  x86_64-linux
+  x86_64-linux-gnu
+  x86_64-linux-musl
+
+DEPENDENCIES
+  htm!
+  multi_json
+  puma (~> 6.0)
+  redis (~> 5.0)
+  rerun
+  sidekiq (~> 7.0)
+  sinatra (~> 3.0)
+  sinatra-contrib (~> 3.0)
+
+BUNDLED WITH
+   2.7.2

data/examples/{sinatra_app → 08_sinatra_app}/app.rb

@@ -9,12 +9,15 @@
 # - RESTful API endpoints
 # - Thread-safe concurrent request handling
 #
+# Prerequisites:
+# 1. Set up examples database: rake examples:setup
+# 2. Install dependencies: cd examples/sinatra_app && bundle install
+#
 # Usage:
-#   bundle install
+#   cd examples/sinatra_app
 #   bundle exec ruby app.rb
 #
 # Environment:
-#   HTM_DATABASE__URL - PostgreSQL connection URL (required)
 #   REDIS_URL - Redis connection URL (for Sidekiq, default: redis://localhost:6379/0)
 #   OLLAMA_URL - Ollama server URL (default: http://localhost:11434)
 #
@@ -23,7 +26,7 @@ require 'sinatra'
 require 'sinatra/json'
 require 'sidekiq'
 require 'securerandom'
-require_relative '../../lib/htm'
+require_relative '../examples_helper'
 require_relative '../../lib/htm/integrations/sinatra'
 
 # Sidekiq configuration
@@ -112,8 +115,8 @@ class HTMApp < Sinatra::Base
   # API: Get memory statistics
   get '/api/stats' do
     total_nodes = HTM::Models::Node.count
-    nodes_with_embeddings = HTM::Models::Node.where.not(embedding: nil).count
-    nodes_with_tags = HTM::Models::Node.joins(:tags).distinct.count
+    nodes_with_embeddings = HTM::Models::Node.exclude(embedding: nil).count
+    nodes_with_tags = HTM::Models::NodeTag.distinct.select(:node_id).count
     total_tags = HTM::Models::Tag.count
 
     robot_nodes = HTM::Models::RobotNode.where(robot_id: htm.robot_id).count
@@ -139,19 +142,17 @@ class HTMApp < Sinatra::Base
     json(
       status: 'ok',
       job_backend: HTM.configuration.job_backend,
-      database: HTM::ActiveRecordConfig.connected?,
+      database: HTM::SequelConfig.connected?,
       timestamp: Time.now.iso8601
     )
   end
 
   # API: Get all tags as a tree structure
   get '/api/tags' do
-    tags = HTM::Models::Tag.all
-
     json(
       status: 'ok',
-      count: tags.count,
-      tree: tags.tree
+      count: HTM::Models::Tag.count,
+      tree: HTM::Models::Tag.tree_string
     )
   end
 
@@ -182,11 +183,11 @@ class HTMApp < Sinatra::Base
       token_count: memory['token_count']
     }
 
-    # Include hybrid search scoring if available
-    if memory['similarity']
+    # Include hybrid search scoring if available (RRF-based)
+    if memory['rrf_score']
       result[:similarity] = memory['similarity'].to_f.round(4)
-      result[:tag_boost] = memory['tag_boost'].to_f.round(4)
-      result[:combined_score] = memory['combined_score'].to_f.round(4)
+      result[:tag_depth_score] = memory['tag_depth_score'].to_f.round(4)
+      result[:rrf_score] = memory['rrf_score'].to_f.round(4)
     end
 
     result
@@ -292,7 +293,7 @@ __END__
 
   <div class="section">
     <h2>Recall Memories</h2>
-    <p><small>Hybrid search uses combined scoring: (similarity × 0.7) + (tag_boost × 0.3)</small></p>
+    <p><small>Hybrid search uses Reciprocal Rank Fusion (RRF) combining vector, fulltext, and tag results</small></p>
     <input type="text" id="recallTopic" placeholder="Enter topic to search...">
     <div class="filter-row">
       <select id="recallStrategy">
@@ -382,10 +383,10 @@ __END__
             // Format timeframe for display
             const timeframeDisplay = formatTimeframe(data.timeframe);
             const memoriesHtml = data.memories.map(m => {
-              // Build scoring info if available (hybrid search)
+              // Build scoring info if available (hybrid search with RRF)
               let scoreInfo = '';
-              if (m.combined_score !== undefined) {
-                scoreInfo = `<br><small class="scores">Score: ${m.combined_score.toFixed(3)} (similarity: ${m.similarity.toFixed(3)}, tag boost: ${m.tag_boost.toFixed(3)})</small>`;
+              if (m.rrf_score !== undefined) {
+                scoreInfo = `<br><small class="scores">RRF Score: ${m.rrf_score.toFixed(3)} (similarity: ${m.similarity.toFixed(3)}, tag depth: ${m.tag_depth_score.toFixed(3)})</small>`;
               }
               // Calculate age of memory
               const age = formatAge(m.created_at);

data/examples/{mcp_client.rb → 09_mcp_client.rb}

@@ -8,9 +8,9 @@
 # using a local Ollama model.
 #
 # Prerequisites:
-# 1. Install gems: gem install ruby_llm-mcp
-# 2. Have Ollama running with gpt-oss model: ollama pull gpt-oss
-# 3. Set HTM_DATABASE__URL environment variable
+# 1. Set up examples database: rake examples:setup
+# 2. Install gems: gem install ruby_llm-mcp
+# 3. Have Ollama running with gpt-oss model: ollama pull gpt-oss
 # 4. The htm_mcp executable must be available (this client will launch it)
 #
 # Usage:
@@ -23,6 +23,7 @@
 # - List tags and statistics
 # - All through conversational AI with tool calling
 
+require_relative 'examples_helper'
 require 'ruby_llm'
 require 'ruby_llm/mcp'
 
@@ -57,11 +58,7 @@ class HTMMcpClient
   private
 
   def validate_environment
-    unless ENV['HTM_DATABASE__URL']
-      warn 'Error: HTM_DATABASE__URL not set.'
-      warn '  export HTM_DATABASE__URL="postgresql://postgres@localhost:5432/htm_development"'
-      exit 1
-    end
+    ExamplesHelper.require_database!
 
     unless File.exist?(MCP_SERVER_PATH)
       warn "Error: MCP server not found at #{MCP_SERVER_PATH}"

data/examples/{telemetry → 10_telemetry}/SETUP_README.md

@@ -1,6 +1,6 @@
 # HTM Telemetry Demo Setup
 
-This guide walks you through setting up Prometheus and Grafana to visualize HTM metrics.
+This guide walks you through setting up Prometheus and Grafana to visualize HTM metrics.  Its intended as a guid for your own applications.  The demo.rb program in this directory takes care of all of the setup steps before it starts it HTM process to generate the telemetry.
 
 ## Prerequisites
 

data/examples/{telemetry → 10_telemetry}/demo.rb

@@ -7,8 +7,9 @@
 # locally installed Prometheus and Grafana (via Homebrew).
 #
 # Prerequisites:
-#   brew install grafana prometheus
-#   gem install prometheus-client webrick
+#   1. Set up examples database: rake examples:setup
+#   2. brew install grafana prometheus
+#   3. gem install prometheus-client webrick
 #
 # Usage:
 #   cd examples/telemetry
@@ -101,11 +102,14 @@ class TelemetryDemo
   def load_htm
     puts "Loading HTM..."
 
-    # Use bundler for HTM and its dependencies
-    require 'bundler/setup'
-    require_relative '../../lib/htm'
+    # Use examples_helper which sets up examples environment and database
+    require_relative '../examples_helper'
 
     puts "  [OK] HTM #{HTM::VERSION}"
+    puts "  [OK] Environment: #{HTM.config.environment}"
+    puts "  [OK] Database: #{HTM.config.actual_database_name}"
+
+    ExamplesHelper.require_database!
     puts
   end
 
@@ -306,21 +310,21 @@ class TelemetryDemo
 
     begin
       # Find the robot
-      robot = HTM::Models::Robot.find_by(name: ROBOT_NAME)
+      robot = HTM::Models::Robot.first(name: ROBOT_NAME)
 
       if robot
         # Find all nodes associated with this robot
-        node_ids = HTM::Models::RobotNode.where(robot_id: robot.id).pluck(:node_id)
+        node_ids = HTM::Models::RobotNode.where(robot_id: robot.id).select_map(:node_id)
 
         if node_ids.any?
           # Hard delete the nodes
-          deleted_count = HTM::Models::Node.where(id: node_ids).delete_all
+          deleted_count = HTM::Models::Node.where(id: node_ids).delete
 
           # Clean up robot_nodes join table
-          HTM::Models::RobotNode.where(robot_id: robot.id).delete_all
+          HTM::Models::RobotNode.where(robot_id: robot.id).delete
 
           # Clean up any orphaned node_tags
-          HTM::Models::NodeTag.where(node_id: node_ids).delete_all
+          HTM::Models::NodeTag.where(node_id: node_ids).delete
 
           puts "  [OK] Deleted #{deleted_count} previous demo nodes"
         else