htm 0.0.1

data/lib/htm/errors.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+# HTM error classes
+class HTM
+  # Base error class for all HTM errors
+  class Error < StandardError; end
+
+  # Validation errors
+  class ValidationError < Error; end
+
+  # Resource exhausted errors (memory, tokens, etc.)
+  class ResourceExhaustedError < Error; end
+
+  # Resource not found errors
+  class NotFoundError < Error; end
+
+  # Embedding service errors
+  class EmbeddingError < Error; end
+
+  # Tag service errors
+  class TagError < Error; end
+
+  # Database operation errors
+  class DatabaseError < Error; end
+
+  # Query timeout errors
+  class QueryTimeoutError < DatabaseError; end
+
+  # Authorization errors
+  class AuthorizationError < Error; end
+
+  # Circuit breaker errors
+  class CircuitBreakerOpenError < EmbeddingError; end
+end

data/lib/htm/job_adapter.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+class HTM
+  # Job adapter for pluggable background job backends
+  #
+  # Supports multiple job backends to work seamlessly across different
+  # application types (CLI, Sinatra, Rails).
+  #
+  # Supported backends:
+  # - :active_job - Rails ActiveJob (recommended for Rails apps)
+  # - :sidekiq - Direct Sidekiq integration (recommended for Sinatra apps)
+  # - :inline - Synchronous execution (recommended for CLI and tests)
+  # - :thread - Background thread (legacy, for standalone apps)
+  #
+  # @example Configure job backend
+  #   HTM.configure do |config|
+  #     config.job_backend = :active_job
+  #   end
+  #
+  # @example Enqueue a job
+  #   HTM::JobAdapter.enqueue(HTM::Jobs::GenerateEmbeddingJob, node_id: 123)
+  #
+  # @see ADR-016: Async Embedding and Tag Generation
+  #
+  module JobAdapter
+    class << self
+      # Enqueue a background job using the configured backend
+      #
+      # @param job_class [Class] Job class to enqueue (must respond to :perform)
+      # @param params [Hash] Parameters to pass to the job
+      # @return [void]
+      #
+      # @raise [HTM::Error] If job backend is unknown
+      #
+      def enqueue(job_class, **params)
+        backend = HTM.configuration.job_backend
+
+        case backend
+        when :active_job
+          enqueue_active_job(job_class, **params)
+        when :sidekiq
+          enqueue_sidekiq(job_class, **params)
+        when :inline
+          enqueue_inline(job_class, **params)
+        when :thread
+          enqueue_thread(job_class, **params)
+        else
+          raise HTM::Error, "Unknown job backend: #{backend}. Supported backends: :active_job, :sidekiq, :inline, :thread"
+        end
+      end
+
+      private
+
+      # Enqueue job using ActiveJob (Rails)
+      def enqueue_active_job(job_class, **params)
+        unless defined?(ActiveJob)
+          raise HTM::Error, "ActiveJob is not available. Add 'activejob' gem or use a different backend."
+        end
+
+        # Convert job class to ActiveJob if needed
+        active_job_class = to_active_job_class(job_class)
+        active_job_class.perform_later(**params)
+
+        HTM.logger.debug "Enqueued #{job_class.name} via ActiveJob with params: #{params.inspect}"
+      end
+
+      # Enqueue job using Sidekiq directly
+      def enqueue_sidekiq(job_class, **params)
+        unless defined?(Sidekiq)
+          raise HTM::Error, "Sidekiq is not available. Add 'sidekiq' gem or use a different backend."
+        end
+
+        # Convert job class to Sidekiq worker if needed
+        sidekiq_class = to_sidekiq_worker(job_class)
+        sidekiq_class.perform_async(**params)
+
+        HTM.logger.debug "Enqueued #{job_class.name} via Sidekiq with params: #{params.inspect}"
+      end
+
+      # Execute job inline (synchronously)
+      def enqueue_inline(job_class, **params)
+        HTM.logger.debug "Executing #{job_class.name} inline with params: #{params.inspect}"
+
+        begin
+          job_class.perform(**params)
+          HTM.logger.debug "Completed #{job_class.name} inline execution"
+        rescue StandardError => e
+          HTM.logger.error "Inline job #{job_class.name} failed: #{e.class.name} - #{e.message}"
+          HTM.logger.debug e.backtrace.first(5).join("\n")
+        end
+      end
+
+      # Execute job in background thread (legacy)
+      def enqueue_thread(job_class, **params)
+        Thread.new do
+          HTM.logger.debug "Executing #{job_class.name} in thread with params: #{params.inspect}"
+
+          begin
+            job_class.perform(**params)
+            HTM.logger.debug "Completed #{job_class.name} thread execution"
+          rescue StandardError => e
+            HTM.logger.error "Thread job #{job_class.name} failed: #{e.class.name} - #{e.message}"
+            HTM.logger.debug e.backtrace.first(5).join("\n")
+          end
+        end
+
+        HTM.logger.debug "Started thread for #{job_class.name}"
+      rescue StandardError => e
+        HTM.logger.error "Failed to start thread for #{job_class.name}: #{e.message}"
+      end
+
+      # Convert HTM job class to ActiveJob class
+      def to_active_job_class(job_class)
+        # If it's already an ActiveJob, return it
+        return job_class if job_class < ActiveJob::Base
+
+        # Create wrapper ActiveJob class
+        Class.new(ActiveJob::Base) do
+          queue_as :htm
+
+          define_method(:perform) do |**params|
+            job_class.perform(**params)
+          end
+
+          # Set descriptive name
+          define_singleton_method(:name) do
+            "#{job_class.name}ActiveJobWrapper"
+          end
+        end
+      end
+
+      # Convert HTM job class to Sidekiq worker
+      def to_sidekiq_worker(job_class)
+        # If it's already a Sidekiq worker, return it
+        return job_class if job_class.included_modules.include?(Sidekiq::Worker)
+
+        # Create wrapper Sidekiq worker
+        Class.new do
+          include Sidekiq::Worker
+          sidekiq_options queue: :htm, retry: 3
+
+          define_method(:perform) do |**params|
+            job_class.perform(**params)
+          end
+
+          # Set descriptive name
+          define_singleton_method(:name) do
+            "#{job_class.name}SidekiqWrapper"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/htm/jobs/generate_embedding_job.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require_relative '../errors'
+require_relative '../models/node'
+require_relative '../embedding_service'
+
+class HTM
+  module Jobs
+    # Background job to generate and store vector embeddings for nodes
+    #
+    # This job is enqueued after a node is saved to avoid blocking the
+    # main request path. It generates embeddings asynchronously and updates
+    # the node record with the embedding vector.
+    #
+    # @see ADR-016: Async Embedding and Tag Generation
+    #
+    class GenerateEmbeddingJob
+      # Generate embedding for a node
+      #
+      # Uses the configured embedding generator (HTM.embed) which delegates
+      # to the application-provided or default RubyLLM implementation.
+      #
+      # @param node_id [Integer] ID of the node to process
+      #
+      def self.perform(node_id:)
+        node = HTM::Models::Node.find_by(id: node_id)
+
+        unless node
+          HTM.logger.warn "GenerateEmbeddingJob: Node #{node_id} not found"
+          return
+        end
+
+        # Skip if already has embedding
+        if node.embedding.present?
+          HTM.logger.debug "GenerateEmbeddingJob: Node #{node_id} already has embedding, skipping"
+          return
+        end
+
+        begin
+          HTM.logger.debug "GenerateEmbeddingJob: Generating embedding for node #{node_id}"
+
+          # Generate and process embedding using EmbeddingService
+          result = HTM::EmbeddingService.generate(node.content)
+
+          # Update node with processed embedding
+          node.update!(
+            embedding: result[:storage_embedding],
+            embedding_dimension: result[:dimension]
+          )
+
+          HTM.logger.info "GenerateEmbeddingJob: Successfully generated embedding for node #{node_id} (#{result[:dimension]} dimensions)"
+
+        rescue HTM::EmbeddingError => e
+          # Log embedding-specific errors
+          HTM.logger.error "GenerateEmbeddingJob: Embedding generation failed for node #{node_id}: #{e.message}"
+
+        rescue StandardError => e
+          # Log unexpected errors
+          HTM.logger.error "GenerateEmbeddingJob: Unexpected error for node #{node_id}: #{e.class.name} - #{e.message}"
+          HTM.logger.debug e.backtrace.first(5).join("\n")
+        end
+      end
+    end
+  end
+end

data/lib/htm/jobs/generate_tags_job.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require_relative '../errors'
+require_relative '../models/node'
+require_relative '../models/tag'
+require_relative '../models/node_tag'
+require_relative '../tag_service'
+
+class HTM
+  module Jobs
+    # Background job to generate and associate tags for nodes
+    #
+    # This job is enqueued after a node is saved to avoid blocking the
+    # main request path. It uses LLM to extract hierarchical tags from
+    # node content and creates the necessary database associations.
+    #
+    # @see ADR-016: Async Embedding and Tag Generation
+    # @see ADR-015: Hierarchical Tag Ontology and LLM Extraction
+    #
+    class GenerateTagsJob
+      # Generate tags for a node
+      #
+      # Uses the configured tag extractor (HTM.extract_tags) which delegates
+      # to the application-provided or default RubyLLM implementation.
+      #
+      # @param node_id [Integer] ID of the node to process
+      #
+      def self.perform(node_id:)
+        node = HTM::Models::Node.find_by(id: node_id)
+
+        unless node
+          HTM.logger.warn "GenerateTagsJob: Node #{node_id} not found"
+          return
+        end
+
+        begin
+          HTM.logger.debug "GenerateTagsJob: Extracting tags for node #{node_id}"
+
+          # Get existing ontology for context (sample of recent tags)
+          existing_ontology = HTM::Models::Tag
+            .order(created_at: :desc)
+            .limit(100)
+            .pluck(:name)
+
+          # Extract and validate tags using TagService
+          tag_names = HTM::TagService.extract(node.content, existing_ontology: existing_ontology)
+
+          if tag_names.empty?
+            HTM.logger.debug "GenerateTagsJob: No tags extracted for node #{node_id}"
+            return
+          end
+
+          # Create or find tags and associate with node
+          tag_names.each do |tag_name|
+            tag = HTM::Models::Tag.find_or_create_by!(name: tag_name)
+
+            # Create association if it doesn't exist
+            HTM::Models::NodeTag.find_or_create_by!(
+              node_id: node.id,
+              tag_id: tag.id
+            )
+          end
+
+          HTM.logger.info "GenerateTagsJob: Successfully generated #{tag_names.length} tags for node #{node_id}: #{tag_names.join(', ')}"
+
+        rescue HTM::TagError => e
+          # Log tag-specific errors
+          HTM.logger.error "GenerateTagsJob: Tag generation failed for node #{node_id}: #{e.message}"
+
+        rescue ActiveRecord::RecordInvalid => e
+          # Log validation errors
+          HTM.logger.error "GenerateTagsJob: Database validation failed for node #{node_id}: #{e.message}"
+
+        rescue StandardError => e
+          # Log unexpected errors
+          HTM.logger.error "GenerateTagsJob: Unexpected error for node #{node_id}: #{e.class.name} - #{e.message}"
+          HTM.logger.debug e.backtrace.first(5).join("\n")
+        end
+      end
+    end
+  end
+end