htm 0.0.1

data/examples/custom_llm_configuration.rb

@@ -0,0 +1,183 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Example: Custom LLM Configuration for HTM
+#
+# This example demonstrates how to configure HTM with custom LLM methods
+# for embedding generation and tag extraction, as well as using defaults.
+
+require_relative '../lib/htm'
+
+puts "HTM Custom LLM Configuration Example"
+puts "=" * 50
+
+# Example 1: Use Default Configuration (RubyLLM with Ollama)
+puts "\n1. Using Default Configuration (RubyLLM + Ollama)"
+puts "-" * 50
+
+HTM.configure  # Uses defaults
+
+htm = HTM.new(robot_name: "DefaultBot")
+puts "✓ HTM initialized with default LLM configuration"
+puts "  Embedding provider: #{HTM.configuration.embedding_provider}"
+puts "  Embedding model: #{HTM.configuration.embedding_model}"
+puts "  Tag provider: #{HTM.configuration.tag_provider}"
+puts "  Tag model: #{HTM.configuration.tag_model}"
+
+# Example 2: Custom Configuration with Lambdas
+puts "\n2. Custom Configuration with Lambdas"
+puts "-" * 50
+
+HTM.configure do |config|
+  # Custom embedding generator
+  config.embedding_generator = lambda do |text|
+    puts "  → Custom embedding generator called for: #{text[0..50]}..."
+    # Simulate custom embedding service
+    # In real application, this would call your LLM infrastructure
+    Array.new(768) { rand }  # Returns 768-dimensional random vector
+  end
+
+  # Custom tag extractor
+  config.tag_extractor = lambda do |text, existing_ontology|
+    puts "  → Custom tag extractor called for: #{text[0..50]}..."
+    puts "  → Existing ontology size: #{existing_ontology.size}"
+    # Simulate custom tag extraction
+    # In real application, this would call your LLM infrastructure
+    ['custom:tag:example', 'test:automated']
+  end
+end
+
+htm = HTM.new(robot_name: "CustomBot")
+puts "✓ HTM initialized with custom LLM configuration"
+
+# Test the custom methods
+embedding = HTM.embed("This is a test message")
+puts "✓ Custom embedding generated: #{embedding.length} dimensions"
+
+tags = HTM.extract_tags("PostgreSQL is a powerful database", existing_ontology: ['database:sql'])
+puts "✓ Custom tags extracted: #{tags.join(', ')}"
+
+# Example 3: Configure with Custom Class
+puts "\n3. Custom Configuration with Service Object"
+puts "-" * 50
+
+# Define a custom LLM service class
+class MyAppLLMService
+  def self.embed(text)
+    puts "  → MyAppLLMService.embed called"
+    # Your application's embedding logic here
+    # Could integrate with LangChain, LlamaIndex, or custom infrastructure
+    Array.new(1024) { rand }  # 1024-dimensional embeddings
+  end
+
+  def self.extract_tags(text, ontology)
+    puts "  → MyAppLLMService.extract_tags called"
+    # Your application's tag extraction logic here
+    ['app:feature:memory', 'app:component:llm']
+  end
+end
+
+HTM.configure do |config|
+  config.embedding_generator = ->(text) { MyAppLLMService.embed(text) }
+  config.tag_extractor = ->(text, ontology) { MyAppLLMService.extract_tags(text, ontology) }
+end
+
+htm = HTM.new(robot_name: "ServiceBot")
+puts "✓ HTM initialized with service object configuration"
+
+embedding = HTM.embed("Another test message")
+puts "✓ Service embedding generated: #{embedding.length} dimensions"
+
+# Example 4: Mixed Configuration (Custom Embedding, Default Tags)
+puts "\n4. Mixed Configuration (Custom + Default)"
+puts "-" * 50
+
+HTM.configure do |config|
+  # Use custom embedding
+  config.embedding_generator = ->(text) {
+    puts "  → Using custom embedder"
+    Array.new(512) { rand }
+  }
+
+  # Keep default tag extraction
+  # (Already set by default, but showing explicit control)
+  config.reset_to_defaults  # Reset both
+
+  # Then override just embedding
+  config.embedding_generator = ->(text) {
+    puts "  → Using custom embedder with default tagger"
+    Array.new(512) { rand }
+  }
+end
+
+htm = HTM.new(robot_name: "MixedBot")
+puts "✓ HTM initialized with mixed configuration"
+
+# Example 5: Configure Provider Settings for Defaults
+puts "\n5. Configuring Default Provider Settings"
+puts "-" * 50
+
+HTM.configure do |config|
+  # Customize the default RubyLLM configuration
+  config.embedding_provider = :ollama
+  config.embedding_model = 'nomic-embed-text'
+  config.embedding_dimensions = 768
+
+  config.tag_provider = :ollama
+  config.tag_model = 'llama3'
+
+  config.ollama_url = ENV['OLLAMA_URL'] || 'http://localhost:11434'
+
+  # Reset to use these new settings with default implementations
+  config.reset_to_defaults
+end
+
+htm = HTM.new(robot_name: "ConfiguredDefaultBot")
+puts "✓ HTM initialized with configured default settings"
+puts "  Embedding model: #{HTM.configuration.embedding_model}"
+puts "  Tag model: #{HTM.configuration.tag_model}"
+puts "  Ollama URL: #{HTM.configuration.ollama_url}"
+
+# Example 6: Integration with HTM Operations
+puts "\n6. Using Custom Configuration in HTM Operations"
+puts "-" * 50
+
+# Configure with test implementation
+HTM.configure do |config|
+  config.embedding_generator = ->(text) {
+    puts "  → Embedding: #{text[0..40]}..."
+    Array.new(768) { rand }
+  }
+
+  config.tag_extractor = ->(text, ontology) {
+    puts "  → Tagging: #{text[0..40]}..."
+    ['example:ruby:gem', 'memory:llm']
+  }
+end
+
+htm = HTM.new(robot_name: "IntegrationBot")
+
+# Remember information - will use custom LLM configuration
+puts "\nRemembering information in HTM..."
+node_id = htm.remember(
+  "PostgreSQL with pgvector enables efficient vector similarity search",
+  source: 'user'
+)
+
+puts "✓ Information remembered with node_id: #{node_id}"
+puts "  Note: Embedding and LLM-generated tags will be processed asynchronously"
+
+# The async jobs will call:
+# - HTM.embed(content) for embedding generation
+# - HTM.extract_tags(content, existing_ontology) for tag extraction
+
+puts "\n" + "=" * 50
+puts "Configuration Summary"
+puts "=" * 50
+puts "Applications can configure HTM by:"
+puts "1. Using HTM.configure with a block"
+puts "2. Providing embedding_generator callable (String → Array<Float>)"
+puts "3. Providing tag_extractor callable (String, Array<String> → Array<String>)"
+puts "4. Or using sensible defaults with RubyLLM + Ollama"
+puts "\nHTM delegates all LLM operations to these configured methods,"
+puts "allowing complete flexibility in LLM infrastructure."

data/examples/example_app/Rakefile

@@ -0,0 +1,71 @@
+# Example Application Rakefile
+#
+# This demonstrates how to integrate HTM rake tasks into your application.
+# Simply require 'htm/tasks' and all database management tasks become available.
+
+require 'bundler/setup'
+
+# Load HTM database tasks - that's it!
+require 'htm/tasks'
+
+# Your application's custom tasks
+namespace :app do
+  desc "Start the example application"
+  task :start do
+    puts "\n=== Starting Example HTM Application ==="
+    puts "Database configured: #{ENV['HTM_DBURL'] ? 'Yes' : 'No'}"
+    puts "\nRun 'rake -T' to see all available tasks"
+    puts "Run 'rake -T htm:db' to see HTM database tasks\n\n"
+
+    # Your app code here
+    require_relative 'app'
+    ExampleApp.run
+  end
+
+  desc "Bootstrap application (setup database + start)"
+  task :bootstrap => ['htm:db:setup', :start]
+end
+
+namespace :dev do
+  desc "Reset database for development (WARNING: destructive!)"
+  task :reset => ['htm:db:reset', 'htm:db:seed']
+end
+
+# Default task
+task default: 'app:start'
+
+# Show usage help
+desc "Show usage help"
+task :help do
+  puts <<~HELP
+
+    Example HTM Application - Available Commands
+    ============================================
+
+    Setup & Start:
+      rake app:bootstrap     Bootstrap app (setup DB + start)
+      rake app:start         Start the application (default)
+
+    Database Management:
+      rake htm:db:setup      Set up HTM database schema
+      rake htm:db:migrate    Run pending migrations
+      rake htm:db:status     Show migration status
+      rake htm:db:info       Show database information
+      rake htm:db:test       Test database connection
+      rake htm:db:console    Open PostgreSQL console
+      rake htm:db:seed       Seed with sample data
+
+    Development:
+      rake dev:reset         Reset database (drop/create/seed)
+
+    Destructive (Use with caution!):
+      rake htm:db:drop       Drop all HTM tables
+      rake htm:db:reset      Drop and recreate database
+
+    Environment:
+      export HTM_DBURL="postgresql://user:pass@host:port/dbname"
+
+    See docs/using_rake_tasks_in_your_app.md for more information.
+
+  HELP
+end

data/examples/example_app/app.rb

@@ -0,0 +1,206 @@
+#!/usr/bin/env ruby
+# Example HTM Application
+#
+# This demonstrates a simple application using the HTM gem with full RubyLLM integration.
+
+require_relative '../../lib/htm'
+require 'ruby_llm'
+require 'logger'
+
+class ExampleApp
+  def self.run
+    puts "\n=== HTM Full-Featured Example Application ==="
+    puts "\nChecking database connection..."
+
+    # Check if database is configured
+    config = HTM::Database.default_config
+    unless config
+      puts "\n⚠ Database not configured!"
+      puts "Set HTM_DBURL environment variable:"
+      puts "  export HTM_DBURL='postgresql://user:pass@host:port/dbname'"
+      puts "\nOr run: rake app:bootstrap"
+      return
+    end
+
+    puts "✓ Database configured: #{config[:dbname]} @ #{config[:host]}"
+
+    # Configure HTM with RubyLLM for embeddings and tag generation
+    puts "\nConfiguring HTM with RubyLLM..."
+    HTM.configure do |c|
+      # Configure logger
+      c.logger = Logger.new($stdout)
+      c.logger.level = Logger::INFO
+
+      # Configure embedding generation (using Ollama)
+      c.embedding_provider = :ollama
+      c.embedding_model = 'nomic-embed-text'
+      c.embedding_dimensions = 768
+      c.ollama_url = ENV['OLLAMA_URL'] || 'http://localhost:11434'
+
+      # Configure tag extraction (using Ollama - using smaller/faster model)
+      c.tag_provider = :ollama
+      c.tag_model = 'gemma3'  # Smaller model (3.3GB) for faster tag generation
+
+      # Apply default implementations
+      c.reset_to_defaults
+    end
+
+    puts "✓ Configured with Ollama:"
+    puts "  - Embeddings: #{HTM.configuration.embedding_model}"
+    puts "  - Tags: #{HTM.configuration.tag_model}"
+    puts "  - Ollama URL: #{HTM.configuration.ollama_url}"
+
+    # Check if Ollama is running
+    puts "\nChecking Ollama connection..."
+    begin
+      require 'net/http'
+      uri = URI(HTM.configuration.ollama_url)
+      response = Net::HTTP.get_response(uri)
+      puts "✓ Ollama is running"
+    rescue StandardError => e
+      puts "⚠ Warning: Cannot connect to Ollama (#{e.message})"
+      puts "  Embeddings and tags will not be generated."
+      puts "  Install Ollama: https://ollama.ai"
+    end
+
+    # Create HTM instance
+    puts "\nInitializing HTM..."
+    htm = HTM.new(robot_name: "Example App Robot")
+
+    # Remember some conversation (simulating a conversation)
+    puts "\nRemembering example conversation..."
+    puts "(Tags will be auto-extracted by LLM in background)"
+
+    node_1 = htm.remember(
+      "HTM provides intelligent memory management for LLM-based applications",
+      source: "assistant"
+    )
+
+    node_2 = htm.remember(
+      "The two-tier architecture includes working memory and long-term storage",
+      source: "assistant"
+    )
+
+    node_3 = htm.remember(
+      "Can you explain how the working memory eviction algorithm works?",
+      source: "user"
+    )
+
+    puts "✓ Remembered 3 conversation messages (nodes #{node_1}, #{node_2}, #{node_3})"
+    puts "  Embeddings and tags are being generated asynchronously..."
+
+    # Wait for background jobs to complete
+    # Note: Tag generation with LLM can take 10-15 seconds depending on model size
+    puts "\nWaiting for background jobs to complete (15 seconds)..."
+    puts "(Embeddings are fast, but tag generation requires LLM inference)"
+    sleep 15
+
+    # Check what was generated
+    puts "\n--- Generated Tags ---"
+    [node_1, node_2, node_3].each do |node_id|
+      node = HTM::Models::Node.includes(:tags).find(node_id)
+      if node.tags.any?
+        puts "Node #{node_id}:"
+        node.tags.each { |tag| puts "  - #{tag.name}" }
+      else
+        puts "Node #{node_id}: (no tags yet)"
+      end
+    end
+
+    # Check embeddings
+    puts "\n--- Embedding Status ---"
+    [node_1, node_2, node_3].each do |node_id|
+      node = HTM::Models::Node.find(node_id)
+      if node.embedding
+        dimensions = node.embedding.is_a?(Array) ? node.embedding.size : node.embedding_dimension
+        status = "✓ Generated (#{dimensions} dimensions)"
+      else
+        status = "⏳ Pending"
+      end
+      puts "Node #{node_id}: #{status}"
+    end
+
+    # Demonstrate different recall strategies
+    puts "\n--- Recall Strategies Comparison ---"
+
+    # 1. Full-text search (doesn't require embeddings)
+    puts "\n1. Full-text Search for 'memory':"
+    fulltext_memories = htm.recall(
+      "memory",
+      timeframe: (Time.now - 3600)..Time.now,
+      strategy: :fulltext,
+      limit: 3
+    )
+    puts "Found #{fulltext_memories.length} memories:"
+    fulltext_memories.each do |memory|
+      puts "  - Node #{memory['id']}: #{memory['content'][0..60]}..."
+    end
+
+    # 2. Vector search (requires embeddings)
+    puts "\n2. Vector Search for 'intelligent memory system':"
+    begin
+      vector_memories = htm.recall(
+        "intelligent memory system",
+        timeframe: (Time.now - 3600)..Time.now,
+        strategy: :vector,
+        limit: 3
+      )
+      puts "Found #{vector_memories.length} memories:"
+      vector_memories.each do |memory|
+        puts "  - Node #{memory['id']}: #{memory['content'][0..60]}..."
+      end
+    rescue StandardError => e
+      puts "  ⚠ Vector search error: #{e.message}"
+      puts "     #{e.class}: #{e.backtrace.first}"
+    end
+
+    # 3. Hybrid search (combines both)
+    puts "\n3. Hybrid Search for 'working memory architecture':"
+    begin
+      hybrid_memories = htm.recall(
+        "working memory architecture",
+        timeframe: (Time.now - 3600)..Time.now,
+        strategy: :hybrid,
+        limit: 3
+      )
+      puts "Found #{hybrid_memories.length} memories:"
+      hybrid_memories.each do |memory|
+        puts "  - Node #{memory['id']}: #{memory['content'][0..60]}..."
+      end
+    rescue StandardError => e
+      puts "  ⚠ Hybrid search error: #{e.message}"
+      puts "     #{e.class}: #{e.backtrace.first}"
+    end
+
+    # Summary
+    puts "\n" + "="*60
+    puts "✓ Demo Complete!"
+    puts "="*60
+    puts "\nThe HTM API provides 3 core methods:"
+    puts "  1. htm.remember(content, source:)"
+    puts "     - Stores information in long-term memory"
+    puts "     - Adds to working memory for immediate use"
+    puts "     - Generates embeddings and tags in background"
+    puts ""
+    puts "  2. htm.recall(timeframe:, topic:, strategy:, limit:)"
+    puts "     - Retrieves relevant memories"
+    puts "     - Strategies: :fulltext, :vector, :hybrid"
+    puts "     - Results added to working memory"
+    puts ""
+    puts "  3. htm.forget(node_id, confirm: :confirmed)"
+    puts "     - Permanently deletes a memory node"
+    puts "     - Requires explicit confirmation"
+    puts ""
+    puts "Background Features:"
+    puts "  - Automatic embedding generation (#{HTM.configuration.embedding_model})"
+    puts "  - Automatic hierarchical tag extraction (#{HTM.configuration.tag_model})"
+    puts "  - Token counting for context management"
+    puts "  - Multi-robot shared memory (hive mind)"
+    puts ""
+  end
+end
+
+# Run directly if called as script
+if __FILE__ == $0
+  ExampleApp.run
+end

data/examples/sinatra_app/Gemfile

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+# Web framework
+gem 'sinatra', '~> 3.0'
+gem 'puma', '~> 6.0'
+
+# Background jobs
+gem 'sidekiq', '~> 7.0'
+gem 'redis', '~> 5.0'
+
+# HTM (use local development version)
+gem 'htm', path: '../..'
+
+# JSON handling
+gem 'multi_json'
+
+group :development do
+  gem 'rerun' # Auto-reload on file changes
+end