jekyll-client-search 0.3.4 → 0.4.0

data/lib/jekyll/client_search/dropdown_tag.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require "cgi"
-
 module Jekyll
   module ClientSearch
     # Liquid tag that renders a compact live-search dropdown suitable for
@@ -15,27 +13,22 @@ module Jekyll
     #
     # When client_search is disabled the tag renders nothing.
     class DropdownTag < Liquid::Tag
+      include ScriptTags
+
       SYNTAX = /\A(max:(\d+))?\s*(scripts_only|no_scripts)?\z/
 
       def initialize(tag_name, markup, tokens)
         super
+        # No validation here: `{% comment %}` still parses nested tags, so
+        # `initialize` runs on commented-out tags. Validate in `render` —
+        # a bad tag inside a comment must not break the build.
         @markup = markup.to_s.strip
-        unless (match = @markup.match(SYNTAX))
-          raise Liquid::SyntaxError,
-                "search_dropdown: invalid syntax. Use {% search_dropdown %}, " \
-                "{% search_dropdown max:10 %}, {% search_dropdown scripts_only %}, " \
-                "or {% search_dropdown no_scripts %}"
-        end
-
-        @max_items = match[2].to_i if match[2]
-        raise Liquid::SyntaxError, "search_dropdown: max must be greater than zero" if @max_items && @max_items < 1
-
-        @mode = match[3] || "full"
         @input_id = "cs-dropdown-input-#{object_id}"
         @results_id = "cs-dropdown-results-#{object_id}"
       end
 
       def render(context)
+        validate_markup!
         site = context.registers[:site]
         return "" unless enabled?(site)
 
@@ -47,6 +40,23 @@ module Jekyll
 
       private
 
+      def validate_markup!
+        return if @validated
+
+        @validated = true
+        unless (match = @markup.match(SYNTAX))
+          raise Liquid::SyntaxError,
+                "search_dropdown: invalid syntax. Use {% search_dropdown %}, " \
+                "{% search_dropdown max:10 %}, {% search_dropdown scripts_only %}, " \
+                "or {% search_dropdown no_scripts %}"
+        end
+
+        @max_items = match[2].to_i if match[2]
+        raise Liquid::SyntaxError, "search_dropdown: max must be greater than zero" if @max_items && @max_items < 1
+
+        @mode = match[3] || "full"
+      end
+
       def enabled?(site)
         return false if site.nil?
 
@@ -62,7 +72,7 @@ module Jekyll
         form_html = build_form(max)
         return form_html if @mode == "no_scripts"
 
-        scripts = build_scripts(configuration, prefix)
+        scripts = script_tags(configuration, prefix, "client-search-dropdown.js")
         return scripts if @mode == "scripts_only"
 
         "#{form_html}\n#{scripts}"
@@ -87,33 +97,6 @@ module Jekyll
           </div>
         HTML
       end
-
-      def build_scripts(configuration, prefix)
-        scripts = []
-        engine = engine_script(configuration)
-        scripts << engine if engine
-        scripts << "<script src=\"#{prefix}/assets/search-runtime-config.js\"></script>"
-        scripts << "<script src=\"#{prefix}/assets/client-search-shared.js\"></script>"
-        scripts << "<script src=\"#{prefix}/assets/client-search-dropdown.js\"></script>"
-        scripts << "<script src=\"#{prefix}/assets/adapters/#{configuration.engine}.js\"></script>"
-        scripts.map { |script| "  #{script}" }.join("\n")
-      end
-
-      def engine_script(configuration)
-        url = configuration.engine_url
-        return nil unless url
-
-        attrs = ["src=\"#{CGI.escapeHTML(url)}\""]
-        if configuration.engine_crossorigin
-          crossorigin = CGI.escapeHTML(configuration.engine_crossorigin)
-          attrs << "crossorigin=\"#{crossorigin}\""
-        end
-        if configuration.engine_sri
-          integrity = CGI.escapeHTML(configuration.engine_sri)
-          attrs << "integrity=\"#{integrity}\""
-        end
-        "<script #{attrs.join(' ')}></script>"
-      end
     end
   end
 end

data/lib/jekyll/client_search/embedding_configuration.rb

@@ -9,9 +9,25 @@ module Jekyll
           "document" => "title: none | text: ",
           "query" => "task: search result | query: "
         },
+        "embeddinggemma-2" => {
+          "document" => "title: none | text: ",
+          "query" => "task: search result | query: "
+        },
         "nomic-embed-text" => {
           "document" => "search_document: ",
           "query" => "search_query: "
+        },
+        "voyage-4-nano" => {
+          "document" => "Represent the document for retrieval: ",
+          "query" => "Represent the query for retrieving supporting documents: "
+        },
+        "qwen3-embedding" => {
+          "document" => "",
+          "query" => "Instruct: Given a web search query, retrieve relevant passages that answer the query\nQuery: "
+        },
+        "bge-large" => {
+          "document" => "",
+          "query" => "Represent this sentence for searching relevant passages: "
         }
       }.freeze
 
@@ -44,43 +60,63 @@ module Jekyll
         configured.nil? ? engine == "semantic" : configured == true
       end
 
+      # Document prefix for the index model (semantic.index_model).
       def embedding_document_prefix
-        configured_prefix("document_prefix", "document")
+        configured_prefix("document", model: embedding_index_model, override: @semantic.document_prefix)
       end
 
+      # Query prefix for the index model — must match the browser query
+      # embedder's vector space.
       def embedding_query_prefix
-        configured_prefix("query_prefix", "query")
+        configured_prefix("query", model: embedding_index_model, override: @semantic.query_prefix)
+      end
+
+      # Document prefix for the related-analysis model (related.index_model).
+      def embedding_related_document_prefix
+        configured_prefix("document", model: embedding_related_model)
       end
 
       def embedding_identity
+        embedding_identity_for(model: embedding_index_model,
+                               document_prefix: embedding_document_prefix,
+                               query_prefix: embedding_query_prefix)
+      end
+
+      def embedding_related_identity
+        embedding_identity_for(model: embedding_related_model,
+                               document_prefix: embedding_related_document_prefix,
+                               query_prefix: configured_prefix("query", model: embedding_related_model))
+      end
+
+      private
+
+      def embedding_identity_for(model:, document_prefix:, query_prefix:)
         {
           "provider" => "ollama",
-          "model" => embedding_model,
+          "model" => model,
           "base_url" => embedding_base_url,
-          "document_prefix" => embedding_document_prefix,
-          "query_prefix" => embedding_query_prefix,
+          "document_prefix" => document_prefix,
+          "query_prefix" => query_prefix,
           "schema" => 2
         }
       end
 
-      private
+      def configured_prefix(role, model:, override: nil)
+        return override.to_s if override
 
-      def configured_prefix(config_key, role)
         embedding = @values.fetch("embedding")
-        return embedding.fetch(config_key).to_s if embedding.key?(config_key)
+        config_key = "#{role}_prefix"
+        return embedding[config_key].to_s if model == embedding_model && embedding.key?(config_key)
 
-        model_name = embedding_model.split(":").first
-        PREFIXES.fetch(model_name, {}).fetch(role, "")
+        PREFIXES.fetch(model.split(":").first, {}).fetch(role, "")
       end
 
       def positive_timeout(key)
         value = @values.fetch("embedding").fetch(key).to_f
-        unless value.positive? && value.finite?
-          raise Jekyll::Errors::FatalException,
-                "embedding #{key} must be a finite value greater than zero"
-        end
+        return value if value.positive? && value.finite?
 
-        value
+        raise Jekyll::Errors::FatalException,
+              "embedding #{key} must be a finite value greater than zero"
       end
 
       def validate_embedding!

data/lib/jekyll/client_search/generator.rb

@@ -25,6 +25,7 @@ module Jekyll
 
       def add_generated_pages(site, documents, configuration)
         add_related_page(site, documents, configuration) if configuration.related_enabled?
+        documents.each { |document| document.delete("related_embedding") }
         remove_embeddings(documents) unless configuration.embedding_include_in_index?
         site.pages << SearchIndexPage.new(site, configuration.output, documents)
         site.pages << RuntimeConfigPage.new(site, configuration) if configuration.copy_runtime?
@@ -39,18 +40,60 @@ module Jekyll
       end
 
       def enhance_with_embeddings(site, documents, configuration)
-        cache = IndexCache.new(site.source, embedding_identity: configuration.embedding_identity)
-        adapter = build_embedding_adapter(configuration)
-
-        documents.each { |entry| embed_document(entry, cache, adapter, configuration) }
-        cache.prune(documents.map { |doc| doc["id"] })
-        cache.save
+        embedding_jobs(configuration).each do |job|
+          cache = IndexCache.new(site.source, embedding_identity: job[:identity],
+                                              file_name: job[:cache_file])
+          adapter = build_embedding_adapter(configuration, model: job[:model])
+
+          documents.each { |entry| embed_document(entry, cache, adapter, configuration, job) }
+          cache.prune(documents.map { |doc| doc["id"] })
+          cache.save
+        end
         documents
       end
 
-      def build_embedding_adapter(configuration)
+      # Each job embeds every document once per model into a target field.
+      # The index model writes "embedding" (kept when include_in_index); a
+      # divergent related model writes "related_embedding" (stripped before
+      # the index is emitted). Identical models share a single pass.
+      def embedding_jobs(configuration)
+        jobs = []
+        jobs << index_embedding_job(configuration) if configuration.embedding_include_in_index?
+        jobs.concat(related_embedding_jobs(configuration)) if configuration.related_enabled?
+        jobs
+      end
+
+      def index_embedding_job(configuration)
+        {
+          model: configuration.embedding_index_model,
+          field: "embedding",
+          document_prefix: configuration.embedding_document_prefix,
+          identity: configuration.embedding_identity,
+          cache_file: IndexCache::CACHE_FILE
+        }
+      end
+
+      def related_embedding_jobs(configuration)
+        return [related_embedding_job("embedding", IndexCache::CACHE_FILE, configuration)] unless
+          configuration.embedding_include_in_index?
+        return [] if configuration.embedding_related_model == configuration.embedding_index_model
+
+        [related_embedding_job("related_embedding", IndexCache::RELATED_CACHE_FILE, configuration)]
+      end
+
+      def related_embedding_job(field, cache_file, configuration)
+        {
+          model: configuration.embedding_related_model,
+          field: field,
+          document_prefix: configuration.embedding_related_document_prefix,
+          identity: configuration.embedding_related_identity,
+          cache_file: cache_file
+        }
+      end
+
+      def build_embedding_adapter(configuration, model: configuration.embedding_model)
         OllamaEmbeddingAdapter.new(
-          model: configuration.embedding_model,
+          model: model,
           base_url: configuration.embedding_base_url,
           connect_timeout: configuration.embedding_connect_timeout,
           read_timeout: configuration.embedding_read_timeout
@@ -66,17 +109,13 @@ module Jekyll
         documents.each { |document| document.delete("embedding") }
       end
 
-      def embed_document(document, cache, adapter, configuration)
-        hash = IndexCache.content_hash(document)
-        cached = cache.lookup(document["id"], hash)
-        if cached && cached["embedding"]
-          document["embedding"] = cached["embedding"]
-          return
-        end
+      def embed_document(document, cache, adapter, configuration, job)
+        hash = IndexCache.content_hash(document.except("embedding", "related_embedding"))
+        return if embedding_restored?(document, cache, hash, job[:field])
 
-        embedding = adapter.embed(embedding_text(document, configuration))
+        embedding = adapter.embed(embedding_text(document, job[:document_prefix]))
         if embedding
-          document["embedding"] = embedding
+          document[job[:field]] = embedding
           cache.store(document["id"], hash, embedding)
         elsif configuration.embedding_fail_on_error?
           raise Jekyll::Errors::FatalException,
@@ -84,9 +123,17 @@ module Jekyll
         end
       end
 
-      def embedding_text(document, configuration)
+      def embedding_restored?(document, cache, hash, field)
+        cached = cache.lookup(document["id"], hash)
+        return false unless cached && cached["embedding"]
+
+        document[field] = cached["embedding"]
+        true
+      end
+
+      def embedding_text(document, document_prefix)
         text = [document["title"], document["excerpt"], document["content"]].compact.join(" ")
-        "#{configuration.embedding_document_prefix}#{text}"
+        "#{document_prefix}#{text}"
       end
 
       def collection_documents(site, configuration, builder)

data/lib/jekyll/client_search/index_cache.rb

@@ -12,11 +12,12 @@ module Jekyll
     # should be git-ignored.
     class IndexCache
       CACHE_FILE = ".jekyll-client-search-cache.json"
+      RELATED_CACHE_FILE = ".jekyll-client-search-related-cache.json"
 
       attr_reader :path
 
-      def initialize(site_source, embedding_identity: nil)
-        @path = File.join(site_source, CACHE_FILE)
+      def initialize(site_source, embedding_identity: nil, file_name: CACHE_FILE)
+        @path = File.join(site_source, file_name)
         @embedding_identity = embedding_identity
         @entries = load
       end

data/lib/jekyll/client_search/ollama_embedding_adapter.rb

@@ -11,6 +11,11 @@ module Jekyll
     #     enabled: true
     #     model: all-minilm          # or nomic-embed-text, bge-m3, etc.
     #     base_url: http://localhost:11434
+    #
+    # A +localhost+ base_url is resolved once to the loopback literal
+    # (127.0.0.1 or ::1) that accepts a TCP connection, because Excon
+    # does not fall back across address families when the DNS name maps
+    # to a family the server is not listening on.
     class OllamaEmbeddingAdapter
       attr_reader :model, :base_url, :connect_timeout, :read_timeout
 
@@ -48,12 +53,53 @@ module Jekyll
         @client ||= begin
           require "ollama"
           Ollama::Client.new(
-            base_url: @base_url,
+            base_url: resolved_base_url,
             connect_timeout: @connect_timeout,
             read_timeout: @read_timeout
           )
         end
       end
+
+      # "localhost" may resolve to ::1 while the server only listens on
+      # 127.0.0.1, or the reverse. Excon does not fall back across
+      # address families, so probe both loopback literals once and use
+      # the one that accepts a TCP connection. Any other host name is
+      # used exactly as configured.
+      def resolved_base_url
+        @resolved_base_url ||= resolve_localhost(@base_url)
+      end
+
+      def resolve_localhost(base_url)
+        require "uri"
+        uri = URI.parse(base_url)
+        return base_url unless uri.host.to_s.chomp(".").casecmp("localhost").zero?
+
+        resolved = loopback_base_url(uri)
+        return base_url unless resolved
+
+        Jekyll.logger.info "ClientSearch:", "resolved localhost to #{resolved}"
+        resolved
+      rescue URI::InvalidURIError
+        base_url
+      end
+
+      def loopback_base_url(uri)
+        %w[127.0.0.1 ::1].each do |address|
+          next unless tcp_reachable?(address, uri.port)
+
+          resolved = uri.dup
+          resolved.host = address.include?(":") ? "[#{address}]" : address
+          return resolved.to_s
+        end
+        nil
+      end
+
+      def tcp_reachable?(address, port)
+        require "socket"
+        Socket.tcp(address, port, connect_timeout: @connect_timeout) { true }
+      rescue SystemCallError, SocketError
+        false
+      end
     end
   end
 end

data/lib/jekyll/client_search/query_embedder_configuration.rb

@@ -8,6 +8,9 @@ module Jekyll
 
       MODEL_MAP = {
         "embeddinggemma:300m" => "onnx-community/embeddinggemma-300m-ONNX",
+        "embeddinggemma-2" => "onnx-community/embeddinggemma-2-ONNX",
+        "embeddinggemma-2:270m" => "onnx-community/embeddinggemma-2-ONNX",
+        "embeddinggemma-2:570m" => "onnx-community/embeddinggemma-2-ONNX",
         "all-minilm" => "Xenova/all-MiniLM-L6-v2"
       }.freeze
 

data/lib/jekyll/client_search/related_analyzer.rb

@@ -29,7 +29,10 @@ module Jekyll
 
       def build_relation(source, target)
         metadata = metadata_relation(source, target)
-        semantic_similarity = similarity(source["embedding"], target["embedding"])
+        semantic_similarity = similarity(
+          source["related_embedding"] || source["embedding"],
+          target["related_embedding"] || target["embedding"]
+        )
         return unless metadata || semantic_match?(semantic_similarity)
 
         relation = base_relation(target, metadata, semantic_similarity)

data/lib/jekyll/client_search/related_configuration.rb

@@ -62,12 +62,27 @@ module Jekyll
         @values.fetch("max_items")
       end
 
+      # Ollama model used for related-article similarity analysis. nil means
+      # the site uses the general embedding.model.
+      def index_model
+        value = @values["index_model"]
+        value&.to_s
+      end
+
       private
 
       def validate!
         validate_booleans!
         validate_similarity!
         validate_max_items!
+        validate_index_model!
+      end
+
+      def validate_index_model!
+        return if index_model.nil? || !index_model.empty?
+
+        raise Jekyll::Errors::FatalException,
+              "client_search related index_model must not be empty"
       end
 
       def validate_booleans!

data/lib/jekyll/client_search/related_tag.rb

@@ -18,11 +18,34 @@ module Jekyll
 
       def initialize(tag_name, markup, tokens)
         super
+        # No validation here: `{% comment %}` still parses nested tags, so
+        # `initialize` runs on commented-out tags. Validate in `render` —
+        # a bad tag inside a comment must not break the build.
         @markup = markup.to_s.strip
+      end
+
+      def render(context)
         parse_tokens(@markup)
+        site = context.registers[:site]
+        return "" if site.nil?
+
+        config = site.config.fetch("client_search", {})
+        return "" if config == false
+        return "" unless related_enabled?(config)
+
+        asset_prefix = asset_prefix(site)
+        sort_attr = @sort ? " data-related-sort=\"#{@sort}\"" : ""
+        max_attr = resolve_max_attr(config)
+        scripts = build_scripts(asset_prefix)
+        build_html(sort_attr, max_attr, scripts)
       end
 
+      private
+
       def parse_tokens(markup)
+        return if @parsed
+
+        @parsed = true
         @sort = nil
         @max_items = nil
         @include_scripts = true
@@ -49,23 +72,6 @@ module Jekyll
           "or {% related_articles no_scripts %}"
       end
 
-      def render(context)
-        site = context.registers[:site]
-        return "" if site.nil?
-
-        config = site.config.fetch("client_search", {})
-        return "" if config == false
-        return "" unless related_enabled?(config)
-
-        asset_prefix = asset_prefix(site)
-        sort_attr = @sort ? " data-related-sort=\"#{@sort}\"" : ""
-        max_attr = resolve_max_attr(config)
-        scripts = build_scripts(asset_prefix)
-        build_html(sort_attr, max_attr, scripts)
-      end
-
-      private
-
       def related_enabled?(config)
         related = config.fetch("related", {})
         related["enabled"] == true

data/lib/jekyll/client_search/script_tags.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require "cgi"
+
+module Jekyll
+  module ClientSearch
+    # Shared <script> tag assembly for the client-search Liquid tags so each
+    # tag only declares its own asset file.
+    module ScriptTags
+      private
+
+      def script_tags(configuration, prefix, tag_asset, extra: [])
+        scripts = []
+        engine = engine_script(configuration)
+        scripts << engine if engine
+        scripts << "<script src=\"#{prefix}/assets/search-runtime-config.js\"></script>"
+        scripts.concat(extra)
+        scripts << "<script src=\"#{prefix}/assets/client-search-shared.js\"></script>"
+        scripts << "<script src=\"#{prefix}/assets/#{tag_asset}\"></script>"
+        scripts << "<script src=\"#{prefix}/assets/adapters/#{configuration.engine}.js\"></script>"
+        scripts.map { |script| "  #{script}" }.join("\n")
+      end
+
+      def engine_script(configuration)
+        url = configuration.engine_url
+        return nil unless url
+
+        attrs = ["src=\"#{CGI.escapeHTML(url)}\""]
+        if configuration.engine_crossorigin
+          crossorigin = CGI.escapeHTML(configuration.engine_crossorigin)
+          attrs << "crossorigin=\"#{crossorigin}\""
+        end
+        if configuration.engine_sri
+          integrity = CGI.escapeHTML(configuration.engine_sri)
+          attrs << "integrity=\"#{integrity}\""
+        end
+        "<script #{attrs.join(' ')}></script>"
+      end
+    end
+  end
+end

data/lib/jekyll/client_search/search_tag.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require "cgi"
-
 module Jekyll
   module ClientSearch
     # Liquid tag that renders the search form, status/results containers,
@@ -14,21 +12,20 @@ module Jekyll
     #
     # When client_search is disabled the tag renders nothing.
     class SearchTag < Liquid::Tag
+      include ScriptTags
+
       SYNTAX = /\A(scripts_only|no_scripts)?\z/
 
       def initialize(tag_name, markup, tokens)
         super
+        # No validation here: `{% comment %}` still parses nested tags, so
+        # `initialize` runs on commented-out tags. Validate in `render` —
+        # a bad tag inside a comment must not break the build.
         @markup = markup.to_s.strip
-        unless (match = @markup.match(SYNTAX))
-          raise Liquid::SyntaxError,
-                "search_form: invalid syntax. Use {% search_form %}, " \
-                "{% search_form scripts_only %}, or {% search_form no_scripts %}"
-        end
-
-        @mode = match[1] || "full"
       end
 
       def render(context)
+        validate_markup!
         site = context.registers[:site]
         return "" if site.nil?
 
@@ -51,6 +48,18 @@ module Jekyll
 
       private
 
+      def validate_markup!
+        return if @mode
+
+        unless (match = @markup.match(SYNTAX))
+          raise Liquid::SyntaxError,
+                "search_form: invalid syntax. Use {% search_form %}, " \
+                "{% search_form scripts_only %}, or {% search_form no_scripts %}"
+        end
+
+        @mode = match[1] || "full"
+      end
+
       def build_form
         <<~HTML
           <form id="search-form" role="search">
@@ -64,31 +73,8 @@ module Jekyll
       end
 
       def build_scripts(configuration, prefix)
-        scripts = []
-        engine = engine_script(configuration)
-        scripts << engine if engine
-        scripts << "<script src=\"#{prefix}/assets/search-runtime-config.js\"></script>"
-        scripts.concat(embedder_scripts(configuration, prefix))
-        scripts << "<script src=\"#{prefix}/assets/client-search-shared.js\"></script>"
-        scripts << "<script src=\"#{prefix}/assets/client-search-base.js\"></script>"
-        scripts << "<script src=\"#{prefix}/assets/adapters/#{configuration.engine}.js\"></script>"
-        scripts.map { |script| "  #{script}" }.join("\n")
-      end
-
-      def engine_script(configuration)
-        url = configuration.engine_url
-        return nil unless url
-
-        attrs = ["src=\"#{CGI.escapeHTML(url)}\""]
-        if configuration.engine_crossorigin
-          crossorigin = CGI.escapeHTML(configuration.engine_crossorigin)
-          attrs << "crossorigin=\"#{crossorigin}\""
-        end
-        if configuration.engine_sri
-          integrity = CGI.escapeHTML(configuration.engine_sri)
-          attrs << "integrity=\"#{integrity}\""
-        end
-        "<script #{attrs.join(' ')}></script>"
+        script_tags(configuration, prefix, "client-search-base.js",
+                    extra: embedder_scripts(configuration, prefix))
       end
 
       def embedder_scripts(configuration, prefix)