htm 0.0.2 → 0.0.10

data/examples/timeframe_demo.rb

@@ -0,0 +1,276 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Timeframe Demo - Demonstrates the various ways to use timeframes with recall
+#
+# Run with:
+#   HTM_DBURL="postgresql://localhost/htm_development" ruby examples/timeframe_demo.rb
+
+require_relative "../lib/htm"
+
+puts <<~HEADER
+  ╔══════════════════════════════════════════════════════════════════╗
+  ║                    HTM Timeframe Demo                            ║
+  ║                                                                  ║
+  ║  Demonstrates the flexible timeframe options for recall queries ║
+  ╚══════════════════════════════════════════════════════════════════╝
+
+HEADER
+
+# Configure week start (optional - defaults to :sunday)
+HTM.configure do |config|
+  config.week_start = :sunday  # or :monday
+end
+
+puts "Configuration:"
+puts "  week_start: #{HTM.configuration.week_start}"
+puts
+
+# Initialize HTM
+htm = HTM.new(robot_name: "Timeframe Demo Robot")
+
+puts "=" * 70
+puts "TIMEFRAME OPTIONS FOR RECALL"
+puts "=" * 70
+puts
+
+# ─────────────────────────────────────────────────────────────────────────────
+# 1. No timeframe filter (nil)
+# ─────────────────────────────────────────────────────────────────────────────
+puts "1. NO TIMEFRAME FILTER (nil)"
+puts "   When timeframe is nil, no time-based filtering is applied."
+puts
+puts "   Code:"
+puts "     htm.recall('PostgreSQL', timeframe: nil)"
+puts
+puts "   SQL equivalent: No WHERE clause on created_at"
+puts
+
+# ─────────────────────────────────────────────────────────────────────────────
+# 2. Date object - entire day
+# ─────────────────────────────────────────────────────────────────────────────
+puts "2. DATE OBJECT (entire day)"
+puts "   A Date is expanded to cover 00:00:00 to 23:59:59 of that day."
+puts
+puts "   Code:"
+puts "     htm.recall('meetings', timeframe: Date.today)"
+puts "     htm.recall('notes', timeframe: Date.new(2025, 11, 15))"
+puts
+
+today = Date.today
+range = HTM::Timeframe.normalize(today)
+puts "   Date.today (#{today}) normalizes to:"
+puts "     #{range.begin} .. #{range.end}"
+puts
+
+# ─────────────────────────────────────────────────────────────────────────────
+# 3. DateTime object - treated same as Date
+# ─────────────────────────────────────────────────────────────────────────────
+puts "3. DATETIME OBJECT (entire day)"
+puts "   DateTime is treated the same as Date - the entire day is included."
+puts
+puts "   Code:"
+puts "     htm.recall('events', timeframe: DateTime.now)"
+puts
+
+datetime = DateTime.now
+range = HTM::Timeframe.normalize(datetime)
+puts "   DateTime.now normalizes to:"
+puts "     #{range.begin} .. #{range.end}"
+puts
+
+# ─────────────────────────────────────────────────────────────────────────────
+# 4. Time object - entire day
+# ─────────────────────────────────────────────────────────────────────────────
+puts "4. TIME OBJECT (entire day)"
+puts "   Time is also normalized to cover the entire day."
+puts
+puts "   Code:"
+puts "     htm.recall('logs', timeframe: Time.now)"
+puts
+
+time = Time.now
+range = HTM::Timeframe.normalize(time)
+puts "   Time.now normalizes to:"
+puts "     #{range.begin} .. #{range.end}"
+puts
+
+# ─────────────────────────────────────────────────────────────────────────────
+# 5. Range - passed through directly
+# ─────────────────────────────────────────────────────────────────────────────
+puts "5. RANGE (passed through)"
+puts "   A Range of Time objects is used directly for precise control."
+puts
+puts "   Code:"
+puts "     start_time = Time.now - (7 * 24 * 60 * 60)  # 7 days ago"
+puts "     end_time = Time.now"
+puts "     htm.recall('updates', timeframe: start_time..end_time)"
+puts
+
+start_time = Time.now - (7 * 24 * 60 * 60)
+end_time = Time.now
+puts "   Range example:"
+puts "     #{start_time} .. #{end_time}"
+puts
+
+# ─────────────────────────────────────────────────────────────────────────────
+# 6. String - natural language parsing via Chronic
+# ─────────────────────────────────────────────────────────────────────────────
+puts "6. STRING (natural language)"
+puts "   Natural language time expressions are parsed using the Chronic gem."
+puts
+puts "   Standard expressions:"
+puts "     htm.recall('notes', timeframe: 'yesterday')"
+puts "     htm.recall('notes', timeframe: 'last week')"
+puts "     htm.recall('notes', timeframe: 'last month')"
+puts "     htm.recall('notes', timeframe: 'this morning')"
+puts
+
+expressions = ["yesterday", "last week", "last month", "today"]
+expressions.each do |expr|
+  result = HTM::Timeframe.normalize(expr)
+  if result
+    puts "   '#{expr}' => #{result.begin.strftime('%Y-%m-%d %H:%M')} .. #{result.end.strftime('%Y-%m-%d %H:%M')}"
+  end
+end
+puts
+
+puts "   'Few' keyword (maps to 3):"
+puts "     htm.recall('notes', timeframe: 'few days ago')"
+puts "     htm.recall('notes', timeframe: 'a few hours ago')"
+puts "     htm.recall('notes', timeframe: 'few weeks ago')"
+puts
+
+few_expressions = ["few days ago", "a few hours ago", "few weeks ago"]
+few_expressions.each do |expr|
+  result = HTM::Timeframe.normalize(expr)
+  if result
+    time_point = result.is_a?(Range) ? result.begin : result
+    puts "   '#{expr}' => #{time_point.strftime('%Y-%m-%d %H:%M')}"
+  end
+end
+puts
+
+puts "   Weekend expressions:"
+puts "     htm.recall('notes', timeframe: 'last weekend')"
+puts "     htm.recall('notes', timeframe: 'weekend before last')"
+puts "     htm.recall('notes', timeframe: '2 weekends ago')"
+puts "     htm.recall('notes', timeframe: 'three weekends ago')"
+puts
+
+weekend_expressions = ["last weekend", "weekend before last", "2 weekends ago"]
+weekend_expressions.each do |expr|
+  result = HTM::Timeframe.normalize(expr)
+  if result && result.is_a?(Range)
+    puts "   '#{expr}' =>"
+    puts "     #{result.begin.strftime('%A %Y-%m-%d')} .. #{result.end.strftime('%A %Y-%m-%d')}"
+  end
+end
+puts
+
+# ─────────────────────────────────────────────────────────────────────────────
+# 7. :auto - extract timeframe from query text
+# ─────────────────────────────────────────────────────────────────────────────
+puts "7. :auto (EXTRACT FROM QUERY)"
+puts "   The timeframe is extracted from the query text automatically."
+puts "   The temporal expression is removed from the search query."
+puts
+puts "   Code:"
+puts "     htm.recall('what did we discuss last week about databases', timeframe: :auto)"
+puts
+
+queries = [
+  "what did we discuss last week about databases",
+  "show me notes from yesterday about PostgreSQL",
+  "what happened few days ago with the API",
+  "recent discussions about embeddings",
+  "show me weekend before last notes about Ruby"
+]
+
+puts "   Examples:"
+queries.each do |query|
+  result = HTM::Timeframe.normalize(:auto, query: query)
+  puts
+  puts "   Original: '#{query}'"
+  puts "   Cleaned:  '#{result.query}'"
+  puts "   Extracted: '#{result.extracted}'"
+  if result.timeframe
+    if result.timeframe.is_a?(Range)
+      puts "   Timeframe: #{result.timeframe.begin.strftime('%Y-%m-%d %H:%M')} .. #{result.timeframe.end.strftime('%Y-%m-%d %H:%M')}"
+    else
+      puts "   Timeframe: #{result.timeframe.strftime('%Y-%m-%d %H:%M')}"
+    end
+  end
+end
+puts
+
+# ─────────────────────────────────────────────────────────────────────────────
+# 8. Array of Ranges - multiple time windows (OR'd together)
+# ─────────────────────────────────────────────────────────────────────────────
+puts "8. ARRAY OF RANGES (multiple time windows)"
+puts "   Multiple time windows are OR'd together in the query."
+puts
+puts "   Code:"
+puts "     today = Date.today"
+puts "     last_friday = today - ((today.wday + 2) % 7)"
+puts "     two_fridays_ago = last_friday - 7"
+puts "     "
+puts "     htm.recall('standup notes', timeframe: [last_friday, two_fridays_ago])"
+puts
+
+today = Date.today
+# Calculate last Friday
+days_since_friday = (today.wday + 2) % 7
+days_since_friday = 7 if days_since_friday == 0
+last_friday = today - days_since_friday
+two_fridays_ago = last_friday - 7
+
+ranges = HTM::Timeframe.normalize([last_friday, two_fridays_ago])
+puts "   Dates: #{last_friday} and #{two_fridays_ago}"
+puts "   Normalized to #{ranges.length} ranges:"
+ranges.each_with_index do |range, i|
+  puts "     [#{i + 1}] #{range.begin} .. #{range.end}"
+end
+puts
+puts "   SQL equivalent:"
+puts "     WHERE (created_at BETWEEN '...' AND '...')"
+puts "        OR (created_at BETWEEN '...' AND '...')"
+puts
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Summary
+# ─────────────────────────────────────────────────────────────────────────────
+puts "=" * 70
+puts "SUMMARY OF TIMEFRAME OPTIONS"
+puts "=" * 70
+puts
+puts "  | Input Type      | Behavior                                    |"
+puts "  |-----------------|---------------------------------------------|"
+puts "  | nil             | No time filter                              |"
+puts "  | Date            | Entire day (00:00:00 to 23:59:59)           |"
+puts "  | DateTime        | Entire day (same as Date)                   |"
+puts "  | Time            | Entire day (same as Date)                   |"
+puts "  | Range           | Exact time window                           |"
+puts "  | String          | Natural language parsing via Chronic        |"
+puts "  | :auto           | Extract from query, return cleaned query    |"
+puts "  | Array<Range>    | Multiple time windows OR'd together         |"
+puts
+
+puts "=" * 70
+puts "SPECIAL KEYWORDS"
+puts "=" * 70
+puts
+puts "  | Keyword                   | Meaning                          |"
+puts "  |---------------------------|----------------------------------|"
+puts "  | few, a few, several       | Maps to #{HTM::TimeframeExtractor::FEW} (configurable via FEW constant) |"
+puts "  | recently, recent          | Last #{HTM::TimeframeExtractor::FEW} days                  |"
+puts "  | weekend before last       | 2 weekends ago (Sat-Mon)         |"
+puts "  | N weekends ago            | N weekends back (Sat-Mon range)  |"
+puts
+
+puts <<~FOOTER
+
+  ╔══════════════════════════════════════════════════════════════════╗
+  ║                      Demo Complete                               ║
+  ╚══════════════════════════════════════════════════════════════════╝
+FOOTER

data/lib/htm/active_record_config.rb

@@ -113,7 +113,7 @@ class HTM
         require_relative 'models/robot_node'
         require_relative 'models/tag'
         require_relative 'models/node_tag'
-        require_relative 'models/working_memory_entry'
+        require_relative 'models/file_source'
       end
     end
   end

data/lib/htm/circuit_breaker.rb

@@ -0,0 +1,202 @@
+# frozen_string_literal: true
+
+require_relative 'errors'
+
+class HTM
+  # Circuit Breaker - Prevents cascading failures from external LLM services
+  #
+  # Implements the circuit breaker pattern to protect against repeated failures
+  # when calling external LLM APIs for embeddings or tag extraction.
+  #
+  # States:
+  # - :closed - Normal operation, requests flow through
+  # - :open - Circuit tripped, requests fail fast with CircuitBreakerOpenError
+  # - :half_open - Testing if service recovered, allows limited requests
+  #
+  # @example Basic usage
+  #   breaker = HTM::CircuitBreaker.new(name: 'embedding')
+  #   result = breaker.call { external_api_call }
+  #
+  # @example With custom thresholds
+  #   breaker = HTM::CircuitBreaker.new(
+  #     name: 'tag_extraction',
+  #     failure_threshold: 3,
+  #     reset_timeout: 30
+  #   )
+  #
+  class CircuitBreaker
+    attr_reader :name, :state, :failure_count, :last_failure_time
+
+    # Default configuration
+    DEFAULT_FAILURE_THRESHOLD = 5      # Failures before opening circuit
+    DEFAULT_RESET_TIMEOUT = 60         # Seconds before trying half-open
+    DEFAULT_HALF_OPEN_MAX_CALLS = 3    # Successful calls to close circuit
+
+    # Initialize a new circuit breaker
+    #
+    # @param name [String] Identifier for this circuit breaker (for logging)
+    # @param failure_threshold [Integer] Number of failures before opening circuit
+    # @param reset_timeout [Integer] Seconds to wait before attempting recovery
+    # @param half_open_max_calls [Integer] Successful calls needed to close circuit
+    #
+    def initialize(
+      name:,
+      failure_threshold: DEFAULT_FAILURE_THRESHOLD,
+      reset_timeout: DEFAULT_RESET_TIMEOUT,
+      half_open_max_calls: DEFAULT_HALF_OPEN_MAX_CALLS
+    )
+      @name = name
+      @failure_threshold = failure_threshold
+      @reset_timeout = reset_timeout
+      @half_open_max_calls = half_open_max_calls
+
+      @state = :closed
+      @failure_count = 0
+      @success_count = 0
+      @last_failure_time = nil
+      @mutex = Mutex.new
+    end
+
+    # Execute a block with circuit breaker protection
+    #
+    # @yield Block containing the protected operation
+    # @return [Object] Result of the block if successful
+    # @raise [CircuitBreakerOpenError] If circuit is open
+    # @raise [StandardError] If the block raises an error (after recording failure)
+    #
+    def call
+      @mutex.synchronize do
+        case @state
+        when :open
+          check_reset_timeout
+          if @state == :open
+            HTM.logger.warn "CircuitBreaker[#{@name}]: Circuit is OPEN, failing fast"
+            raise CircuitBreakerOpenError, "Circuit breaker '#{@name}' is open. Service unavailable."
+          end
+        when :half_open
+          HTM.logger.debug "CircuitBreaker[#{@name}]: Circuit is HALF-OPEN, testing service"
+        end
+      end
+
+      begin
+        result = yield
+        record_success
+        result
+      rescue StandardError => e
+        record_failure(e)
+        raise
+      end
+    end
+
+    # Check if circuit is currently open
+    #
+    # @return [Boolean] true if circuit is open
+    #
+    def open?
+      @mutex.synchronize { @state == :open }
+    end
+
+    # Check if circuit is currently closed (normal operation)
+    #
+    # @return [Boolean] true if circuit is closed
+    #
+    def closed?
+      @mutex.synchronize { @state == :closed }
+    end
+
+    # Check if circuit is in half-open state (testing recovery)
+    #
+    # @return [Boolean] true if circuit is half-open
+    #
+    def half_open?
+      @mutex.synchronize { @state == :half_open }
+    end
+
+    # Manually reset the circuit breaker to closed state
+    #
+    # @return [void]
+    #
+    def reset!
+      @mutex.synchronize do
+        @state = :closed
+        @failure_count = 0
+        @success_count = 0
+        @last_failure_time = nil
+        HTM.logger.info "CircuitBreaker[#{@name}]: Manually reset to CLOSED"
+      end
+    end
+
+    # Get current circuit breaker statistics
+    #
+    # @return [Hash] Statistics including state, failure count, etc.
+    #
+    def stats
+      @mutex.synchronize do
+        {
+          name: @name,
+          state: @state,
+          failure_count: @failure_count,
+          success_count: @success_count,
+          last_failure_time: @last_failure_time,
+          failure_threshold: @failure_threshold,
+          reset_timeout: @reset_timeout
+        }
+      end
+    end
+
+    private
+
+    # Record a successful call
+    def record_success
+      @mutex.synchronize do
+        case @state
+        when :half_open
+          @success_count += 1
+          if @success_count >= @half_open_max_calls
+            @state = :closed
+            @failure_count = 0
+            @success_count = 0
+            HTM.logger.info "CircuitBreaker[#{@name}]: Service recovered, circuit CLOSED"
+          end
+        when :closed
+          # Reset failure count on success in closed state
+          @failure_count = 0 if @failure_count > 0
+        end
+      end
+    end
+
+    # Record a failed call
+    def record_failure(error)
+      @mutex.synchronize do
+        @failure_count += 1
+        @last_failure_time = Time.now
+        @success_count = 0
+
+        HTM.logger.warn "CircuitBreaker[#{@name}]: Failure ##{@failure_count} - #{error.class}: #{error.message}"
+
+        case @state
+        when :closed
+          if @failure_count >= @failure_threshold
+            @state = :open
+            HTM.logger.error "CircuitBreaker[#{@name}]: Threshold reached (#{@failure_threshold}), circuit OPEN"
+          end
+        when :half_open
+          @state = :open
+          HTM.logger.warn "CircuitBreaker[#{@name}]: Failed during recovery test, circuit OPEN"
+        end
+      end
+    end
+
+    # Check if reset timeout has elapsed and transition to half-open
+    def check_reset_timeout
+      return unless @state == :open && @last_failure_time
+
+      elapsed = Time.now - @last_failure_time
+      if elapsed >= @reset_timeout
+        @state = :half_open
+        @success_count = 0
+        HTM.logger.info "CircuitBreaker[#{@name}]: Reset timeout elapsed (#{@reset_timeout}s), circuit HALF-OPEN"
+      end
+    end
+  end
+end

data/lib/htm/configuration.rb

@@ -63,6 +63,7 @@ class HTM
     attr_accessor :embedding_timeout, :tag_timeout, :connection_timeout
     attr_accessor :logger
     attr_accessor :job_backend
+    attr_accessor :week_start
 
     # Provider-specific API keys and endpoints
     attr_accessor :openai_api_key, :openai_organization, :openai_project
@@ -131,6 +132,14 @@ class HTM
       # Auto-detect job backend based on environment
       @job_backend = detect_job_backend
 
+      # Timeframe parsing configuration
+      # :sunday (default) or :monday for week start day
+      @week_start = :sunday
+
+      # Thread-safe Ollama model refresh tracking
+      @ollama_models_refreshed = false
+      @ollama_refresh_mutex = Mutex.new
+
       # Set default implementations
       reset_to_defaults
     end
@@ -164,6 +173,10 @@ class HTM
         raise HTM::ValidationError, "job_backend must be one of: :active_job, :sidekiq, :inline, :thread (got #{@job_backend.inspect})"
       end
 
+      unless [:sunday, :monday].include?(@week_start)
+        raise HTM::ValidationError, "week_start must be :sunday or :monday (got #{@week_start.inspect})"
+      end
+
       # Validate provider if specified
       if @embedding_provider && !SUPPORTED_PROVIDERS.include?(@embedding_provider)
         raise HTM::ValidationError, "embedding_provider must be one of: #{SUPPORTED_PROVIDERS.join(', ')} (got #{@embedding_provider.inspect})"
@@ -301,10 +314,14 @@ class HTM
         # Configure RubyLLM for the embedding provider
         configure_ruby_llm(@embedding_provider)
 
-        # Refresh models for Ollama to discover local models
-        if @embedding_provider == :ollama && !@ollama_models_refreshed
-          RubyLLM.models.refresh!
-          @ollama_models_refreshed = true
+        # Refresh models for Ollama to discover local models (thread-safe)
+        if @embedding_provider == :ollama
+          @ollama_refresh_mutex.synchronize do
+            unless @ollama_models_refreshed
+              RubyLLM.models.refresh!
+              @ollama_models_refreshed = true
+            end
+          end
         end
 
         # Normalize Ollama model name (ensure it has a tag like :latest)
@@ -369,10 +386,14 @@ class HTM
         # Configure RubyLLM for the tag provider
         configure_ruby_llm(@tag_provider)
 
-        # Refresh models for Ollama to discover local models
-        if @tag_provider == :ollama && !@ollama_models_refreshed
-          RubyLLM.models.refresh!
-          @ollama_models_refreshed = true
+        # Refresh models for Ollama to discover local models (thread-safe)
+        if @tag_provider == :ollama
+          @ollama_refresh_mutex.synchronize do
+            unless @ollama_models_refreshed
+              RubyLLM.models.refresh!
+              @ollama_models_refreshed = true
+            end
+          end
         end
 
         # Normalize Ollama model name (ensure it has a tag like :latest)
@@ -394,18 +415,43 @@ class HTM
 
           Rules:
           - Use lowercase letters, numbers, and hyphens only
-          - Maximum depth: 5 levels
+          - Maximum depth: 4 levels (to prevent excessive nesting)
           - Return 2-5 tags per text
           - Tags should be reusable and consistent
           - Prefer existing ontology tags when applicable
           - Use hyphens for multi-word terms (e.g., natural-language-processing)
 
-          Text: #{text}
+          CRITICAL CONSTRAINTS:
+          - NO CIRCULAR REFERENCES: A concept cannot appear at both the root and leaf of the same path
+          - NO REDUNDANT DUPLICATES: Do not create the same concept in multiple branches
+            Example (WRONG): database:postgresql vs database-management:relational-databases:postgresql
+            Example (RIGHT): Choose ONE primary location
+          - CONSISTENT DEPTH: Similar concept types should be at similar depth levels
+            Example (WRONG): age:numeric vs name:individual:specific-name:john
+            Example (RIGHT): Both should be at similar depths under personal-data
+          - NO SELF-CONTAINMENT: A parent concept should never contain itself as a descendant
+            Example (WRONG): age:personal-information:personal-data:age
+            Example (RIGHT): personal-information:personal-data:age
+          - AVOID AMBIGUOUS CROSS-DOMAIN CONCEPTS: Each concept should have ONE primary parent
+            If a concept truly belongs in multiple domains, use the most specific/primary domain
+
+          TEXT: #{text}
 
           Return ONLY the topic tags, one per line, no explanations.
         PROMPT
 
-        system_prompt = 'You are a precise topic extraction system. Output only topic tags in hierarchical format: root:subtopic:detail'
+        system_prompt = <<~SYSTEM.strip
+          You are a precise topic extraction system that prevents ontological errors.
+
+          Your job is to:
+          1. Extract hierarchical tags in format: root:subtopic:detail
+          2. Maintain consistency with existing ontology (no duplicates)
+          3. Prevent circular references and self-containing concepts
+          4. Keep hierarchies at consistent depth levels
+          5. Choose PRIMARY locations for concepts (no multi-parent confusion)
+
+          Output ONLY topic tags, one per line.
+        SYSTEM
 
         # Use RubyLLM chat for tag extraction
         chat = RubyLLM.chat(model: model)
@@ -423,8 +469,8 @@ class HTM
           tag =~ /^[a-z0-9\-]+(:[a-z0-9\-]+)*$/
         end
 
-        # Limit depth to 5 levels (4 colons maximum)
-        valid_tags.select { |tag| tag.count(':') < 5 }
+        # Limit depth to 4 levels (3 colons maximum)
+        valid_tags.select { |tag| tag.count(':') < 4 }
       end
     end