htm 0.0.15 → 0.0.17

data/examples/rails_app/app/controllers/application_controller.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+class ApplicationController < ActionController::Base
+  # HTM instance for the current request
+  def htm
+    @htm ||= HTM.new(robot_name: current_robot_name)
+  end
+  helper_method :htm
+
+  # Allow switching robots via session
+  def current_robot_name
+    session[:robot_name] || 'explorer'
+  end
+  helper_method :current_robot_name
+
+  def current_robot_name=(name)
+    session[:robot_name] = name
+  end
+end

data/examples/rails_app/app/controllers/dashboard_controller.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+class DashboardController < ApplicationController
+  def index
+    # Note: HTM::Models::Node has a default_scope that excludes deleted nodes
+    # so we don't need to call .active explicitly
+    @stats = {
+      total_nodes: HTM::Models::Node.count,
+      nodes_with_embeddings: HTM::Models::Node.with_embeddings.count,
+      deleted_nodes: HTM::Models::Node.deleted.count,
+      total_tags: HTM::Models::Tag.count,
+      total_robots: HTM::Models::Robot.count,
+      total_file_sources: HTM::Models::FileSource.count
+    }
+
+    @recent_memories = HTM::Models::Node.recent.limit(5)
+
+    @top_tags = HTM::Models::Tag
+                .joins(:nodes)
+                .group('tags.id')
+                .order('COUNT(nodes.id) DESC')
+                .limit(10)
+                .select('tags.*, COUNT(nodes.id) as node_count')
+
+    @robots = HTM::Models::Robot.order(created_at: :desc).limit(5)
+  end
+end

data/examples/rails_app/app/controllers/files_controller.rb

@@ -0,0 +1,205 @@
+# frozen_string_literal: true
+
+class FilesController < ApplicationController
+  def index
+    @file_sources = HTM::Models::FileSource.order(updated_at: :desc)
+  end
+
+  def show
+    @file_source = HTM::Models::FileSource.find(params[:id])
+    @chunks = @file_source.chunks.order(:id)
+  end
+
+  def new
+  end
+
+  def create
+    path = params[:path]&.strip
+
+    if path.blank?
+      flash[:alert] = 'File path is required'
+      redirect_to new_file_path
+      return
+    end
+
+    unless File.exist?(path)
+      flash[:alert] = "File not found: #{path}"
+      redirect_to new_file_path
+      return
+    end
+
+    force = params[:force] == 'true'
+
+    begin
+      result = htm.load_file(path, force: force)
+      flash[:notice] = "File loaded: #{result[:chunks_created]} chunks created, #{result[:chunks_updated]} updated, #{result[:chunks_deleted]} deleted"
+      redirect_to file_path(result[:file_source_id])
+    rescue StandardError => e
+      flash[:alert] = "Error loading file: #{e.message}"
+      redirect_to new_file_path
+    end
+  end
+
+  def load_directory
+    path = params[:path]&.strip
+    pattern = params[:pattern] || '**/*.md'
+
+    if path.blank?
+      flash[:alert] = 'Directory path is required'
+      redirect_to new_file_path
+      return
+    end
+
+    unless Dir.exist?(path)
+      flash[:alert] = "Directory not found: #{path}"
+      redirect_to new_file_path
+      return
+    end
+
+    begin
+      results = htm.load_directory(path, pattern: pattern)
+      total_chunks = results.sum { |r| r[:chunks_created] }
+      flash[:notice] = "Loaded #{results.length} files with #{total_chunks} total chunks"
+      redirect_to files_path
+    rescue StandardError => e
+      flash[:alert] = "Error loading directory: #{e.message}"
+      redirect_to new_file_path
+    end
+  end
+
+  def upload
+    files = params[:files]
+    force = params[:force] == 'true'
+
+    if files.blank?
+      flash[:alert] = 'Please select at least one file'
+      redirect_to new_file_path
+      return
+    end
+
+    results = process_uploaded_files(files, force: force)
+
+    if results[:errors].any?
+      flash[:alert] = "Loaded #{results[:success_count]} files with #{results[:errors].length} errors: #{results[:errors].first}"
+    else
+      flash[:notice] = "Loaded #{results[:success_count]} files with #{results[:total_chunks]} total chunks"
+    end
+
+    if results[:last_file_source_id] && results[:success_count] == 1
+      redirect_to file_path(results[:last_file_source_id])
+    else
+      redirect_to files_path
+    end
+  end
+
+  def upload_directory
+    files = params[:files]
+    extension = params[:extension]
+
+    if files.blank?
+      flash[:alert] = 'Please select a directory'
+      redirect_to new_file_path
+      return
+    end
+
+    # Filter files by extension if specified
+    filtered_files = if extension.present?
+                       files.select { |f| f.original_filename.end_with?(extension) }
+                     else
+                       files.select { |f| f.original_filename.match?(/\.(md|markdown|txt)$/i) }
+                     end
+
+    if filtered_files.empty?
+      flash[:alert] = 'No matching files found in the selected directory'
+      redirect_to new_file_path
+      return
+    end
+
+    results = process_uploaded_files(filtered_files, force: false)
+
+    if results[:errors].any?
+      flash[:alert] = "Loaded #{results[:success_count]} files with #{results[:errors].length} errors"
+    else
+      flash[:notice] = "Loaded #{results[:success_count]} files with #{results[:total_chunks]} total chunks"
+    end
+
+    redirect_to files_path
+  end
+
+  def sync
+    @file_source = HTM::Models::FileSource.find(params[:id])
+
+    begin
+      result = htm.load_file(@file_source.file_path, force: true)
+      flash[:notice] = "File synced: #{result[:chunks_created]} created, #{result[:chunks_updated]} updated, #{result[:chunks_deleted]} deleted"
+    rescue StandardError => e
+      flash[:alert] = "Error syncing file: #{e.message}"
+    end
+
+    redirect_to file_path(@file_source)
+  end
+
+  def destroy
+    @file_source = HTM::Models::FileSource.find(params[:id])
+
+    begin
+      htm.unload_file(@file_source.file_path)
+      flash[:notice] = 'File unloaded successfully'
+    rescue StandardError => e
+      flash[:alert] = "Error unloading file: #{e.message}"
+    end
+
+    redirect_to files_path
+  end
+
+  def sync_all
+    synced = 0
+    errors = 0
+
+    HTM::Models::FileSource.find_each do |source|
+      if source.needs_sync?
+        begin
+          htm.load_file(source.file_path, force: true)
+          synced += 1
+        rescue StandardError
+          errors += 1
+        end
+      end
+    end
+
+    if errors.zero?
+      flash[:notice] = "Synced #{synced} files"
+    else
+      flash[:alert] = "Synced #{synced} files with #{errors} errors"
+    end
+
+    redirect_to files_path
+  end
+
+  private
+
+  def process_uploaded_files(files, force: false)
+    results = { success_count: 0, total_chunks: 0, errors: [], last_file_source_id: nil }
+
+    # Create uploads directory if it doesn't exist
+    uploads_dir = Rails.root.join('tmp', 'uploads')
+    FileUtils.mkdir_p(uploads_dir)
+
+    files.each do |file|
+      # Save uploaded file to temp location
+      temp_path = uploads_dir.join(file.original_filename)
+      File.open(temp_path, 'wb') { |f| f.write(file.read) }
+
+      begin
+        result = htm.load_file(temp_path.to_s, force: force)
+        results[:success_count] += 1
+        results[:total_chunks] += result[:chunks_created]
+        results[:last_file_source_id] = result[:file_source_id]
+      rescue StandardError => e
+        results[:errors] << "#{file.original_filename}: #{e.message}"
+      end
+    end
+
+    results
+  end
+end

data/examples/rails_app/app/controllers/memories_controller.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+class MemoriesController < ApplicationController
+  before_action :set_memory, only: [:show, :edit, :update, :destroy, :restore]
+
+  def index
+    # Default scope excludes deleted nodes, so no .active needed
+    @memories = HTM::Models::Node.includes(:tags)
+                                 .order(created_at: :desc)
+
+    if params[:tag].present?
+      @memories = @memories.joins(:tags).where(tags: { name: params[:tag] })
+    end
+
+    if params[:search].present?
+      @memories = @memories.where('content ILIKE ?', "%#{params[:search]}%")
+    end
+
+    # Simple pagination without Kaminari
+    @page = (params[:page] || 1).to_i
+    @per_page = 20
+    @total_count = @memories.count
+    @total_pages = (@total_count.to_f / @per_page).ceil
+    @memories = @memories.offset((@page - 1) * @per_page).limit(@per_page)
+  end
+
+  def show
+    @related = htm.recall(@memory.content, limit: 5, strategy: :vector, raw: true)
+                  .reject { |m| m['id'] == @memory.id }
+  end
+
+  def new
+    @memory = HTM::Models::Node.new
+  end
+
+  def create
+    content = params[:content] || params.dig(:node, :content)
+    tags = params[:tags] || params.dig(:node, :tags)
+    metadata = params[:metadata] || params.dig(:node, :metadata)
+
+    if content.blank?
+      flash[:alert] = 'Content is required'
+      redirect_to new_memory_path
+      return
+    end
+
+    tag_array = tags.present? ? tags.split(',').map(&:strip) : []
+    metadata_hash = metadata.present? ? JSON.parse(metadata) : {}
+
+    node_id = htm.remember(content, tags: tag_array, metadata: metadata_hash)
+    flash[:notice] = 'Memory stored successfully'
+    redirect_to memory_path(node_id)
+  rescue JSON::ParserError
+    flash[:alert] = 'Invalid metadata JSON format'
+    redirect_to new_memory_path
+  end
+
+  def edit
+  end
+
+  def update
+    content = params[:content] || params.dig(:node, :content)
+
+    if content.blank?
+      flash[:alert] = 'Content is required'
+      redirect_to edit_memory_path(@memory)
+      return
+    end
+
+    @memory.update!(content: content)
+    flash[:notice] = 'Memory updated successfully'
+    redirect_to memory_path(@memory)
+  end
+
+  def destroy
+    soft = params[:permanent] != 'true'
+    if soft
+      htm.forget(@memory.id)
+      flash[:notice] = 'Memory moved to trash. You can restore it later.'
+    else
+      htm.forget(@memory.id, soft: false, confirm: :confirmed)
+      flash[:notice] = 'Memory permanently deleted.'
+    end
+    redirect_to memories_path
+  end
+
+  def restore
+    htm.restore(@memory.id)
+    flash[:notice] = 'Memory restored successfully.'
+    redirect_to memory_path(@memory)
+  end
+
+  def deleted
+    @memories = HTM::Models::Node.deleted.order(deleted_at: :desc)
+  end
+
+  private
+
+  def set_memory
+    @memory = HTM::Models::Node.with_deleted.find(params[:id])
+  end
+end

data/examples/rails_app/app/controllers/robots_controller.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+class RobotsController < ApplicationController
+  def index
+    @robots = HTM::Models::Robot.order(created_at: :desc)
+  end
+
+  def show
+    @robot = HTM::Models::Robot.find(params[:id])
+    # Default scope already excludes deleted nodes, so no .active needed
+    @memory_count = @robot.nodes.count
+    @recent_memories = @robot.nodes.order(created_at: :desc).limit(10)
+  end
+
+  def new
+  end
+
+  def create
+    name = params[:name]&.strip
+
+    if name.blank?
+      flash[:alert] = 'Robot name is required'
+      redirect_to new_robot_path
+      return
+    end
+
+    if HTM::Models::Robot.exists?(name: name)
+      flash[:alert] = 'A robot with that name already exists'
+      redirect_to new_robot_path
+      return
+    end
+
+    robot = HTM::Models::Robot.create!(name: name, metadata: {})
+    flash[:notice] = "Robot '#{name}' created successfully"
+    redirect_to robot_path(robot)
+  end
+
+  def switch
+    robot = HTM::Models::Robot.find(params[:id])
+    self.current_robot_name = robot.name
+    flash[:notice] = "Switched to robot '#{robot.name}'"
+    redirect_to root_path
+  end
+end

data/examples/rails_app/app/controllers/search_controller.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+class SearchController < ApplicationController
+  def index
+    @query = params[:query]
+    @strategies = %i[vector fulltext hybrid]
+    @selected_strategy = (params[:strategy] || 'hybrid').to_sym
+    @limit = (params[:limit] || 10).to_i
+    @timeframe = params[:timeframe].presence || 'all time'
+
+    @results = {}
+    @errors = {}
+
+    return unless @query.present?
+
+    # Convert "all time" to nil for HTM (no timeframe filter)
+    timeframe_param = @timeframe == 'all time' ? nil : @timeframe
+
+    if params[:compare] == 'true'
+      # Compare all strategies
+      @strategies.each do |strategy|
+        start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        begin
+          @results[strategy] = htm.recall(@query, limit: @limit, strategy: strategy, timeframe: timeframe_param, raw: true)
+        rescue StandardError => e
+          @results[strategy] = []
+          @errors[strategy] = e.message
+        end
+        end_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        @results["#{strategy}_time".to_sym] = ((end_time - start_time) * 1000).round(2)
+      end
+    else
+      # Single strategy search
+      start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      begin
+        @results[@selected_strategy] = htm.recall(@query, limit: @limit, strategy: @selected_strategy, timeframe: timeframe_param, raw: true)
+      rescue StandardError => e
+        @results[@selected_strategy] = []
+        @errors[@selected_strategy] = e.message
+        flash.now[:alert] = "Search error: #{e.message}"
+      end
+      end_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      @results["#{@selected_strategy}_time".to_sym] = ((end_time - start_time) * 1000).round(2)
+    end
+  end
+end

data/examples/rails_app/app/controllers/tags_controller.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+class TagsController < ApplicationController
+  def index
+    @view_type = params[:view] || 'list'
+
+    case @view_type
+    when 'tree'
+      @tree_string = HTM::Models::Tag.all.tree_string
+      @tree_svg = HTM::Models::Tag.all.tree_svg(title: 'HTM Tag Hierarchy')
+    when 'mermaid'
+      @tree_mermaid = HTM::Models::Tag.all.tree_mermaid
+    else
+      @tags = HTM::Models::Tag
+              .left_joins(:nodes)
+              .group('tags.id')
+              .select('tags.*, COUNT(nodes.id) as node_count')
+              .order(:name)
+
+      if params[:prefix].present?
+        @tags = @tags.where('tags.name LIKE ?', "#{params[:prefix]}%")
+      end
+    end
+  end
+
+  def show
+    @tag = HTM::Models::Tag.find(params[:id])
+    @memories = @tag.nodes.active.includes(:tags).order(created_at: :desc)
+  end
+end

data/examples/rails_app/app/javascript/application.js

@@ -0,0 +1,4 @@
+// Configure your import map in config/importmap.rb
+
+import "@hotwired/turbo-rails"
+import "controllers"

data/examples/rails_app/app/javascript/controllers/application.js

@@ -0,0 +1,9 @@
+import { Application } from "@hotwired/stimulus"
+
+const application = Application.start()
+
+// Configure Stimulus development experience
+application.debug = false
+window.Stimulus = application
+
+export { application }

data/examples/rails_app/app/javascript/controllers/index.js

@@ -0,0 +1,6 @@
+// Import and register all your controllers from the importmap via controllers/**/*_controller
+import { application } from "controllers/application"
+
+// Eager load all controllers defined in the import map under controllers/**/*_controller
+import { eagerLoadControllersFrom } from "@hotwired/stimulus-loading"
+eagerLoadControllersFrom("controllers", application)

data/examples/rails_app/app/views/dashboard/index.html.erb

@@ -0,0 +1,123 @@
+<div class="space-y-8">
+  <!-- Header -->
+  <div>
+    <h1 class="text-2xl font-bold text-white">HTM Memory Explorer</h1>
+    <p class="mt-1 text-sm text-gray-400">Monitor and explore your Hierarchical Temporal Memory system</p>
+  </div>
+
+  <!-- Stats Grid -->
+  <div class="grid grid-cols-1 gap-5 sm:grid-cols-2 lg:grid-cols-3">
+    <%= render 'shared/stat_card', title: 'Total Memories', value: @stats[:total_nodes], icon: 'memory', color: 'indigo' %>
+    <%= render 'shared/stat_card', title: 'With Embeddings', value: @stats[:nodes_with_embeddings], icon: 'vector', color: 'green' %>
+    <%= render 'shared/stat_card', title: 'Deleted', value: @stats[:deleted_nodes], icon: 'trash', color: 'red' %>
+    <%= render 'shared/stat_card', title: 'Tags', value: @stats[:total_tags], icon: 'tag', color: 'yellow' %>
+    <%= render 'shared/stat_card', title: 'Robots', value: @stats[:total_robots], icon: 'robot', color: 'purple' %>
+    <%= render 'shared/stat_card', title: 'File Sources', value: @stats[:total_file_sources], icon: 'file', color: 'blue' %>
+  </div>
+
+  <!-- Two Column Layout -->
+  <div class="grid grid-cols-1 gap-6 lg:grid-cols-2">
+    <!-- Recent Memories -->
+    <div class="rounded-lg bg-gray-800 border border-gray-700 p-6">
+      <div class="flex items-center justify-between mb-4">
+        <h2 class="text-lg font-medium text-white">Recent Memories</h2>
+        <%= link_to 'View All', memories_path, class: 'text-sm text-indigo-400 hover:text-indigo-300' %>
+      </div>
+      <% if @recent_memories.any? %>
+        <ul class="space-y-3">
+          <% @recent_memories.each do |memory| %>
+            <li class="rounded-md bg-gray-700/50 p-3">
+              <p class="text-sm text-gray-300 line-clamp-2"><%= truncate(memory.content, length: 120) %></p>
+              <div class="mt-2 flex items-center gap-2 text-xs text-gray-500">
+                <span><%= time_ago_in_words(memory.created_at) %> ago</span>
+                <% if memory.embedding.present? %>
+                  <span class="inline-flex items-center rounded-full bg-green-900/50 px-2 py-0.5 text-xs text-green-400">embedded</span>
+                <% end %>
+              </div>
+            </li>
+          <% end %>
+        </ul>
+      <% else %>
+        <p class="text-sm text-gray-500">No memories stored yet. <%= link_to 'Add one', new_memory_path, class: 'text-indigo-400 hover:text-indigo-300' %>.</p>
+      <% end %>
+    </div>
+
+    <!-- Top Tags -->
+    <div class="rounded-lg bg-gray-800 border border-gray-700 p-6">
+      <div class="flex items-center justify-between mb-4">
+        <h2 class="text-lg font-medium text-white">Top Tags</h2>
+        <%= link_to 'View All', tags_path, class: 'text-sm text-indigo-400 hover:text-indigo-300' %>
+      </div>
+      <% if @top_tags.any? %>
+        <div class="flex flex-wrap gap-2">
+          <% @top_tags.each do |tag| %>
+            <%= link_to tag_path(tag), class: 'group' do %>
+              <span class="inline-flex items-center gap-1 rounded-full bg-indigo-900/50 border border-indigo-500/30 px-3 py-1 text-sm text-indigo-300 hover:bg-indigo-800/50 hover:border-indigo-500/50 transition-colors">
+                <%= tag.name %>
+                <span class="text-xs text-indigo-400/70">(<%= tag.node_count %>)</span>
+              </span>
+            <% end %>
+          <% end %>
+        </div>
+      <% else %>
+        <p class="text-sm text-gray-500">No tags created yet.</p>
+      <% end %>
+    </div>
+  </div>
+
+  <!-- Robots Section -->
+  <div class="rounded-lg bg-gray-800 border border-gray-700 p-6">
+    <div class="flex items-center justify-between mb-4">
+      <h2 class="text-lg font-medium text-white">Active Robots</h2>
+      <%= link_to 'View All', robots_path, class: 'text-sm text-indigo-400 hover:text-indigo-300' %>
+    </div>
+    <% if @robots.any? %>
+      <div class="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 gap-4">
+        <% @robots.each do |robot| %>
+          <%= link_to robot_path(robot), class: 'block rounded-md bg-gray-700/50 p-4 hover:bg-gray-700 transition-colors' do %>
+            <div class="flex items-center gap-3">
+              <div class="flex-shrink-0">
+                <div class="h-10 w-10 rounded-full bg-purple-900/50 flex items-center justify-center">
+                  <svg class="h-5 w-5 text-purple-400" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+                    <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M9 3v2m6-2v2M9 19v2m6-2v2M5 9H3m2 6H3m18-6h-2m2 6h-2M7 19h10a2 2 0 002-2V7a2 2 0 00-2-2H7a2 2 0 00-2 2v10a2 2 0 002 2zM9 9h6v6H9V9z" />
+                  </svg>
+                </div>
+              </div>
+              <div>
+                <p class="text-sm font-medium text-white"><%= robot.name %></p>
+                <p class="text-xs text-gray-500">Created <%= time_ago_in_words(robot.created_at) %> ago</p>
+              </div>
+            </div>
+          <% end %>
+        <% end %>
+      </div>
+    <% else %>
+      <p class="text-sm text-gray-500">No robots registered yet.</p>
+    <% end %>
+  </div>
+
+  <!-- Quick Actions -->
+  <div class="rounded-lg bg-gray-800 border border-gray-700 p-6">
+    <h2 class="text-lg font-medium text-white mb-4">Quick Actions</h2>
+    <div class="flex flex-wrap gap-3">
+      <%= link_to new_memory_path, class: 'inline-flex items-center gap-2 rounded-md bg-indigo-600 px-4 py-2 text-sm font-medium text-white hover:bg-indigo-500 transition-colors' do %>
+        <svg class="h-4 w-4" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+          <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M12 4v16m8-8H4" />
+        </svg>
+        Add Memory
+      <% end %>
+      <%= link_to search_path, class: 'inline-flex items-center gap-2 rounded-md bg-gray-700 px-4 py-2 text-sm font-medium text-white hover:bg-gray-600 transition-colors' do %>
+        <svg class="h-4 w-4" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+          <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M21 21l-6-6m2-5a7 7 0 11-14 0 7 7 0 0114 0z" />
+        </svg>
+        Search Memories
+      <% end %>
+      <%= link_to tags_path(view: 'tree'), class: 'inline-flex items-center gap-2 rounded-md bg-gray-700 px-4 py-2 text-sm font-medium text-white hover:bg-gray-600 transition-colors' do %>
+        <svg class="h-4 w-4" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+          <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M4 6h16M4 12h16m-7 6h7" />
+        </svg>
+        View Tag Tree
+      <% end %>
+    </div>
+  </div>
+</div>