htm 0.0.1 → 0.0.10

data/.envrc

@@ -9,6 +9,7 @@ export HTM_DBNAME=htm_development
 export HTM_DBUSER=${USER}
 export HTM_DBPASS=
 export HTM_DBURL="postgresql://${HTM_DBUSER}@${HTM_DBHOST}:${HTM_DBPORT}/${HTM_DBNAME}?sslmode=disable"
+# export HTM_DBURL="postgresql://dewayne@localhost:5432/htm_development"
 
 # Uncomment if using TimescaleDB Cloud instead:
 # export HTM_SERVICE_NAME=$TIGER_SERVICE_NAME

data/.irbrc

@@ -1,97 +1,144 @@
 # frozen_string_literal: true
 
-# HTM IRB Configuration
-# Load this with: irb -r ./.irbrc
-# Or just: irb (if in the htm directory)
+# HTM Interactive Development Console
+# Usage: HTM_DBURL="postgresql://user@localhost:5432/htm_development" irb
 
-puts "Loading HTM library..."
-
-# Load the HTM library
 require_relative 'lib/htm'
+require 'debug_me'
 
-# Establish database connection
-HTM::ActiveRecordConfig.establish_connection! unless HTM::ActiveRecordConfig.connected?
+puts "=" * 60
+puts "HTM Interactive Console"
+puts "=" * 60
 
-# Configure HTM with Ollama for embedding and tag generation
-HTM.configure do |c|
-  c.embedding_provider   = :ollama
-  c.embedding_model      = 'nomic-embed-text'
-  c.embedding_dimensions = 768
-  c.tag_provider = :ollama
-  c.tag_model    = 'gemma3'
-  c.reset_to_defaults
+# Database Connection
+begin
+  HTM::ActiveRecordConfig.establish_connection! unless HTM::ActiveRecordConfig.connected?
+  db_name = HTM::Database.default_config[:dbname] rescue 'unknown'
+  puts "✓ Database connected: #{db_name}"
+rescue => e
+  puts "✗ Database connection failed: #{e.message}"
 end
 
-# Convenience aliases for models
-Node    = HTM::Models::Node
-Tag     = HTM::Models::Tag
-NodeTag = HTM::Models::NodeTag
-Robot   = HTM::Models::Robot
+# 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.reset_to_defaults
+end
+puts "✓ HTM configured (inline jobs, Ollama provider)"
 
-# Helper methods
-def reload!
-  puts "Reloading HTM library..."
-  load 'lib/htm.rb'
-  puts "✓ Reloaded"
+# Model shortcuts (constants for easy access)
+Node       = HTM::Models::Node
+Tag        = HTM::Models::Tag
+NodeTag    = HTM::Models::NodeTag
+Robot      = HTM::Models::Robot
+RobotNode  = HTM::Models::RobotNode
+FileSource = HTM::Models::FileSource
+
+# Pre-built HTM instances for common testing scenarios
+def user
+  @user ||= HTM.new(robot_name: "User")
 end
 
+def assistant
+  @assistant ||= HTM.new(robot_name: "Assistant")
+end
+
+def researcher
+  @researcher ||= HTM.new(robot_name: "Researcher")
+end
+
+def coder
+  @coder ||= HTM.new(robot_name: "Coder")
+end
+
+def htm
+  @htm ||= HTM.new(robot_name: "IRB Console")
+end
+
+# RubyLLM shortcuts
+def llm
+  require 'ruby_llm' unless defined?(RubyLLM)
+  RubyLLM
+end
+
+def chat(message, model: 'gemma3:latest')
+  llm.chat(messages: [{ role: 'user', content: message }], model: model).content
+end
+
+def embed(text, model: 'nomic-embed-text:latest')
+  llm.embed(text, model: model)
+end
+
+# Database utilities
 def db_stats
   puts <<~STATS
 
     === Database Statistics ===
-    Nodes:     #{Node.count}
-    Tags:      #{Tag.count}
-    NodeTags:  #{NodeTag.count}
-    Robots:    #{Robot.count}
+    Nodes:       #{Node.count} (#{Node.deleted.count} deleted)
+    Tags:        #{Tag.count}
+    NodeTags:    #{NodeTag.count}
+    Robots:      #{Robot.count}
+    RobotNodes:  #{RobotNode.count}
+    FileSources: #{FileSource.count}
 
   STATS
 end
 
+def health
+  HTM::Observability.health_check
+end
+
+def healthy?
+  HTM::Observability.healthy?
+end
+
+# Node exploration
 def recent_nodes(limit = 5)
   puts "\n=== Recent Nodes ==="
   Node.order(created_at: :desc).limit(limit).each do |node|
     tags = node.tags.pluck(:name).join(', ')
     tags_str = tags.empty? ? "(no tags)" : tags
-    puts "Node #{node.id}: #{node.content[0..60]}..."
+    content_preview = node.content.to_s[0..60].gsub("\n", " ")
+    puts "Node #{node.id}: #{content_preview}..."
     puts "  Tags: #{tags_str}"
-    puts "  Embedding: #{node.embedding ? '✓' : '✗'}"
-    puts ""
+    puts "  Embedding: #{node.embedding ? "✓ (#{node.embedding.size}d)" : '✗'}"
+    puts "  Created: #{node.created_at}"
+    puts
   end
+  nil
 end
 
-def recent_tags(limit = 10)
-  puts "\n=== Recent Tags ==="
-  Tag.order(created_at: :desc).limit(limit).each do |tag|
-    count = tag.nodes.count
-    puts "#{tag.name} (#{count} nodes)"
-  end
-  puts
-end
+def recent_by_robot(robot_name, limit = 10)
+  robot = Robot.find_by(name: robot_name)
+  return puts("Robot '#{robot_name}' not found") unless robot
 
-def search_tags(pattern)
-  puts "\n=== Tags matching '#{pattern}' ==="
-  Tag.where("name LIKE ?", "%#{pattern}%").each do |tag|
-    count = tag.nodes.count
-    puts "#{tag.name} (#{count} nodes)"
+  puts "\n=== Recent Nodes by #{robot_name} ==="
+  robot.nodes.order(created_at: :desc).limit(limit).each do |node|
+    content_preview = node.content.to_s[0..60].gsub("\n", " ")
+    puts "Node #{node.id}: #{content_preview}..."
   end
-  puts
+  nil
 end
 
-def node_with_tags(node_id)
-  node = Node.includes(:tags).find(node_id)
-  embedding_info = if node.embedding
-    "✓ (#{node.embedding.size} dimensions)"
-  else
-    '✗'
-  end
+def node_info(node_id)
+  node = Node.includes(:tags, :robots).find(node_id)
+  embedding_info = node.embedding ? "✓ (#{node.embedding.size} dimensions)" : '✗'
 
   puts <<~NODE_INFO
 
     === Node #{node_id} ===
     Content: #{node.content}
-    Source: #{node.source}
+    Type: #{node.memory_type}
+    Importance: #{node.importance}
     Created: #{node.created_at}
+    Last Accessed: #{node.last_accessed}
     Embedding: #{embedding_info}
+    Deleted: #{node.deleted_at ? "Yes (#{node.deleted_at})" : 'No'}
 
     Tags:
   NODE_INFO
@@ -101,45 +148,201 @@ def node_with_tags(node_id)
   else
     puts "  (no tags)"
   end
+
+  puts "\n    Robots:"
+  if node.robots.any?
+    node.robots.each { |robot| puts "  - #{robot.name}" }
+  else
+    puts "  (no robots)"
+  end
   puts
   node
 end
 
-def create_test_node(content, source: "irb")
-  htm = HTM.new(robot_name: "IRB User")
-  node_id = htm.remember(content, source: source)
-  puts "✓ Created node #{node_id}"
-  node_id
+# Tag exploration
+def tag_tree(prefix = nil)
+  scope = prefix ? Tag.where("name LIKE ?", "#{prefix}%") : Tag.all
+  puts scope.tree_string
+  nil
+end
+
+def recent_tags(limit = 10)
+  puts "\n=== Recent Tags ==="
+  Tag.order(created_at: :desc).limit(limit).each do |tag|
+    count = tag.nodes.count
+    puts "#{tag.name} (#{count} nodes)"
+  end
+  nil
+end
+
+def popular_tags(limit = 20)
+  puts "\n=== Popular Tags ==="
+  Tag.joins(:nodes)
+     .group('tags.id', 'tags.name')
+     .order('COUNT(nodes.id) DESC')
+     .limit(limit)
+     .pluck('tags.name', 'COUNT(nodes.id)')
+     .each { |name, count| puts "#{name} (#{count} nodes)" }
+  nil
+end
+
+def search_tags(pattern)
+  puts "\n=== Tags matching '#{pattern}' ==="
+  Tag.where("name LIKE ?", "%#{pattern}%").each do |tag|
+    count = tag.nodes.count
+    puts "#{tag.name} (#{count} nodes)"
+  end
+  nil
+end
+
+# Robot exploration
+def list_robots
+  puts "\n=== Robots ==="
+  Robot.all.each do |robot|
+    node_count = robot.nodes.count
+    puts "#{robot.name} (#{node_count} nodes) - created #{robot.created_at}"
+  end
+  nil
+end
+
+# Memory operations
+def remember(content, type: :fact, importance: 5.0, tags: [])
+  node = htm.remember(content, type: type, importance: importance, tags: tags)
+  puts "✓ Created node #{node.id}"
+  node
+end
+
+def recall(query, limit: 5, raw: false)
+  htm.recall(query, limit: limit, raw: raw)
+end
+
+def search(query, strategy: :hybrid, limit: 10)
+  htm.long_term_memory.search(query, strategy: strategy, limit: limit)
+end
+
+def similar_to(node_id, limit: 5)
+  node = Node.find(node_id)
+  node.nearest_neighbors(:embedding, distance: :cosine).limit(limit)
+end
+
+# Timeframe helpers
+def today
+  Date.today.beginning_of_day..Date.today.end_of_day
+end
+
+def yesterday
+  1.day.ago.beginning_of_day..1.day.ago.end_of_day
+end
+
+def this_week
+  Date.today.beginning_of_week..Date.today.end_of_day
+end
+
+def last_week
+  1.week.ago.beginning_of_week..1.week.ago.end_of_week
+end
+
+def nodes_in(timeframe)
+  Node.where(created_at: timeframe)
+end
+
+# File loading helpers
+def load_file(path, force: false)
+  htm.load_file(path, force: force)
+end
+
+def load_directory(path, pattern: '**/*.md', force: false)
+  htm.load_directory(path, pattern: pattern, force: force)
 end
 
+def loaded_files
+  puts "\n=== Loaded Files ==="
+  FileSource.all.each do |fs|
+    sync_status = fs.needs_sync? ? "needs sync" : "synced"
+    puts "#{fs.file_path} (#{fs.chunks.count} chunks, #{sync_status})"
+  end
+  nil
+end
+
+# Reload helper
+def reload!
+  puts "Reloading HTM library..."
+  load 'lib/htm.rb'
+  @htm = nil
+  @user = nil
+  @assistant = nil
+  @researcher = nil
+  @coder = nil
+  puts "✓ Reloaded"
+end
+
+# Help
 def htm_help
-  puts <<~WELCOME
+  puts <<~HELP
 
     ============================================================
       HTM Interactive Console
     ============================================================
 
-    Available models:
-      - Node      (HTM::Models::Node)
-      - Tag       (HTM::Models::Tag)
-      - NodeTag   (HTM::Models::NodeTag)
-      - Robot     (HTM::Models::Robot)
+    ROBOT INSTANCES (lazy-loaded):
+      htm          - Default console instance
+      user         - "User" robot (the human)
+      assistant    - "Assistant" robot
+      researcher   - "Researcher" robot
+      coder        - "Coder" robot
+
+    MODEL CONSTANTS:
+      Node, Tag, NodeTag, Robot, RobotNode, FileSource
+
+    MEMORY OPERATIONS:
+      remember(content, type:, importance:, tags:)
+      recall(query, limit:, raw:)
+      search(query, strategy:, limit:)
+      similar_to(node_id, limit:)
+
+    NODE EXPLORATION:
+      recent_nodes(limit)
+      recent_by_robot(robot_name, limit)
+      node_info(node_id)
+      nodes_in(timeframe)
+
+    TAG EXPLORATION:
+      tag_tree(prefix)
+      recent_tags(limit)
+      popular_tags(limit)
+      search_tags(pattern)
+
+    ROBOT EXPLORATION:
+      list_robots
 
-    Helper methods:
-      htm_help              # Reprints this message
-      db_stats              # Show database statistics
-      recent_nodes(n)       # Show n recent nodes (default: 5)
-      recent_tags(n)        # Show n recent tags (default: 10)
-      search_tags(pattern)  # Search tags by pattern
-      node_with_tags(id)    # Show node details with tags
-      create_test_node(str) # Create a test node
-      reload!               # Reload HTM library
+    FILE LOADING:
+      load_file(path, force:)
+      load_directory(path, pattern:, force:)
+      loaded_files
 
-    Database: #{HTM::Database.default_config[:dbname]}
-  WELCOME
+    TIMEFRAME HELPERS:
+      today, yesterday, this_week, last_week
+
+    RUBYLLM:
+      llm                   - RubyLLM module
+      chat(message, model:) - Quick chat
+      embed(text, model:)   - Generate embedding
+
+    DATABASE:
+      db_stats     - Show table counts
+      health       - Full health check
+      healthy?     - Quick boolean check
+
+    UTILITIES:
+      reload!      - Reload HTM library
+      htm_help     - Show this help
+
+  HELP
+  nil
 end
 
-htm_help
-db_stats
+puts "✓ Helpers loaded"
+puts "=" * 60
+puts "\nType 'htm_help' for available commands\n\n"
 
-print "HTM Ready!\n\n"
+db_stats

data/.tbls.yml

@@ -0,0 +1,31 @@
+# tbls configuration for HTM database documentation
+# https://github.com/k1LoW/tbls
+
+# Database connection - uses HTM_DBURL environment variable
+# tbls expands environment variables with $VAR or ${VAR} syntax
+dsn: $HTM_DBURL
+
+# Output documentation to docs/database directory
+docPath: docs/database
+
+# Documentation format options
+format:
+  adjust_table_width: true
+  sort: true
+
+# ER diagram settings
+er:
+  format: svg
+  comment: true
+  distance: 2
+
+# Include schema metadata
+include:
+  - public.*
+
+# Lint rules for schema quality
+lint:
+  requireColumnComment:
+    enabled: false
+  requireTableComment:
+    enabled: false