legionio 1.4.72 → 1.4.73

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d9c2f9048a25ea9cff5f0b8db43aaaf49ab40bb6c388b2f892c3f952fb7233f4
-  data.tar.gz: 02225b7029518b45f1d78f632cce4fdbaee631efb9c03cade5e575ac3c96e3cf
+  metadata.gz: 7693068b5190222c508dd07a248424e8f9e1eff77e80059cbd8a4fc81e9e6325
+  data.tar.gz: 43cc0da2efe7d604101ab87426c21b5f8ce677a8c023aeec38e5b91018b515ae
 SHA512:
-  metadata.gz: 758ee671a15875e26a60fe87b10b3499c5ef47f766d5cd3d43498b7c362be4a791defe79b99bda56ccbf263558fa7a4e8450b307f3bc29734c3c3d279bba4dd4
-  data.tar.gz: 2c04803613fe2a2ba39ef4aa29865f66b96b237ba7c3f74920cd784bedfebc9bc90df91042714a016f06587a6d234ed722cf29a5727c039e8f09fbddfb322184
+  metadata.gz: a2d75a86b1646113be917a9f8ed17f8f7aa8ffb48ff371db78ee62fbfdba1929d85e675f2bf7d6a5469b077f10370f3d044eb6f5049db353d471f5be1c3cbab5
+  data.tar.gz: 2f00a29a6ddf7be18ee71839b97e1a8aeeb74f2cecd820932447bc574fcfeb595a6adce0d757909bf3e3d68909235fcbb32ad95182192b5471dea0a2f3d39a0e

data/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Legion Changelog
 
+## [1.4.73] - 2026-03-19
+
+### Added
+- TBI Phase 3: semantic tool retrieval via embedding vectors
+- `Legion::MCP::EmbeddingIndex` module: in-memory embedding cache with pure-Ruby cosine similarity
+- `ContextCompiler` semantic score blending: 60% semantic + 40% keyword when embeddings available, keyword-only fallback
+- `Server.populate_embedding_index`: auto-populates tool embeddings on MCP server build (no-op if LLM unavailable)
+- `legion observe embeddings` subcommand: index size, coverage, and populated status
+- 61 new specs (1666 total): EmbeddingIndex unit, ContextCompiler semantic blending, integration wiring, CLI
+
 ## [1.4.72] - 2026-03-19
 
 ### Added

data/lib/legion/cli/observe_command.rb

@@ -72,6 +72,27 @@ module Legion
         puts 'Observation data cleared.'
       end
 
+      desc 'embeddings', 'Show MCP tool embedding index status'
+      def embeddings
+        require 'legion/mcp/embedding_index'
+        data = {
+          index_size: Legion::MCP::EmbeddingIndex.size,
+          coverage:   Legion::MCP::EmbeddingIndex.coverage,
+          populated:  Legion::MCP::EmbeddingIndex.populated?
+        }
+
+        if options['json']
+          puts ::JSON.pretty_generate(data.transform_keys(&:to_s))
+          return
+        end
+
+        puts 'MCP Embedding Index'
+        puts '=' * 40
+        puts "Index Size: #{data[:index_size]}"
+        puts "Coverage:   #{(data[:coverage] * 100).round(1)}%"
+        puts "Populated:  #{data[:populated]}"
+      end
+
       private
 
       def serialize_stats(data)

data/lib/legion/mcp/context_compiler.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative 'embedding_index'
+
 module Legion
   module MCP
     module ContextCompiler
@@ -112,6 +114,7 @@ module Legion
       # Clears the memoized tool_index.
       def reset!
         @tool_index = nil
+        Legion::MCP::EmbeddingIndex.reset! if defined?(Legion::MCP::EmbeddingIndex)
       end
 
       def build_tool_index
@@ -131,10 +134,38 @@ module Legion
         keywords = intent_string.downcase.split
         return [] if keywords.empty?
 
+        kw_scores = keyword_score_map(keywords)
+        sem_scores = semantic_score_map(intent_string)
+        use_semantic = !sem_scores.empty?
+
         tool_index.values.map do |entry|
+          kw_raw = kw_scores[entry[:name]] || 0
+          if use_semantic
+            max_kw = kw_scores.values.max || 1
+            normalized_kw = max_kw.positive? ? kw_raw.to_f / max_kw : 0.0
+            sem = sem_scores[entry[:name]] || 0.0
+            blended = (normalized_kw * 0.4) + (sem * 0.6)
+          else
+            blended = kw_raw.to_f
+          end
+
+          { name: entry[:name], description: entry[:description], score: blended }
+        end
+      end
+
+      def keyword_score_map(keywords)
+        tool_index.values.to_h do |entry|
           haystack = "#{entry[:name].downcase} #{entry[:description].downcase}"
-          score    = keywords.count { |kw| haystack.include?(kw) }
-          { name: entry[:name], description: entry[:description], score: score }
+          score = keywords.count { |kw| haystack.include?(kw) }
+          [entry[:name], score]
+        end
+      end
+
+      def semantic_score_map(intent_string)
+        return {} unless defined?(Legion::MCP::EmbeddingIndex) && Legion::MCP::EmbeddingIndex.populated?
+
+        Legion::MCP::EmbeddingIndex.semantic_match(intent_string, limit: tool_index.size).to_h do |result|
+          [result[:name], result[:score]]
         end
       end
     end

data/lib/legion/mcp/embedding_index.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module Legion
+  module MCP
+    module EmbeddingIndex
+      module_function
+
+      def build_from_tool_data(tool_data, embedder: default_embedder)
+        @embedder = embedder
+        mutex.synchronize do
+          tool_data.each do |tool|
+            composite = build_composite(tool[:name], tool[:description], tool[:params])
+            vector = safe_embed(composite, embedder)
+            next unless vector
+
+            index[tool[:name]] = {
+              name:           tool[:name],
+              composite_text: composite,
+              vector:         vector,
+              built_at:       Time.now
+            }
+          end
+        end
+      end
+
+      def semantic_match(intent, embedder: @embedder || default_embedder, limit: 5)
+        return [] if index.empty?
+
+        intent_vec = safe_embed(intent, embedder)
+        return [] unless intent_vec
+
+        scores = mutex.synchronize do
+          index.values.filter_map do |entry|
+            next unless entry[:vector]
+
+            score = cosine_similarity(intent_vec, entry[:vector])
+            { name: entry[:name], score: score }
+          end
+        end
+
+        scores.sort_by { |s| -s[:score] }.first(limit)
+      end
+
+      def cosine_similarity(vec_a, vec_b)
+        dot = vec_a.zip(vec_b).sum { |a, b| a * b }
+        mag_a = Math.sqrt(vec_a.sum { |x| x**2 })
+        mag_b = Math.sqrt(vec_b.sum { |x| x**2 })
+        return 0.0 if mag_a.zero? || mag_b.zero?
+
+        dot / (mag_a * mag_b)
+      end
+
+      def entry(tool_name)
+        mutex.synchronize { index[tool_name] }
+      end
+
+      def size
+        mutex.synchronize { index.size }
+      end
+
+      def populated?
+        mutex.synchronize { !index.empty? }
+      end
+
+      def coverage
+        mutex.synchronize do
+          return 0.0 if index.empty?
+
+          with_vectors = index.values.count { |e| e[:vector] }
+          with_vectors.to_f / index.size
+        end
+      end
+
+      def reset!
+        @embedder = nil
+        mutex.synchronize { index.clear }
+      end
+
+      def index
+        @index ||= {}
+      end
+
+      def mutex
+        @mutex ||= Mutex.new
+      end
+
+      def build_composite(name, description, params)
+        parts = [name, '--', description]
+        parts << "Params: #{params.join(', ')}" unless params.empty?
+        parts.join(' ')
+      end
+
+      def safe_embed(text, embedder)
+        return nil unless embedder
+
+        result = embedder.call(text)
+        return nil unless result.is_a?(Array) && !result.empty?
+
+        result
+      rescue StandardError
+        nil
+      end
+
+      def default_embedder
+        return nil unless defined?(Legion::LLM) && Legion::LLM.respond_to?(:started?) && Legion::LLM.started?
+
+        ->(text) { Legion::LLM.embed(text)[:vector] }
+      rescue StandardError
+        nil
+      end
+    end
+  end
+end

data/lib/legion/mcp/server.rb

@@ -36,6 +36,7 @@ require_relative 'tools/rbac_check'
 require_relative 'tools/rbac_assignments'
 require_relative 'tools/rbac_grants'
 require_relative 'context_compiler'
+require_relative 'embedding_index'
 require_relative 'tools/do_action'
 require_relative 'tools/discover_tools'
 require_relative 'resources/runner_catalog'
@@ -109,12 +110,22 @@ module Legion
             build_filtered_tool_list.map(&:to_h)
           end
 
+          # Populate embedding index for semantic tool matching (lazy — no-op if LLM unavailable)
+          populate_embedding_index
+
           Resources::RunnerCatalog.register(server)
           Resources::ExtensionInfo.register_read_handler(server)
 
           server
         end
 
+        def populate_embedding_index(embedder: EmbeddingIndex.default_embedder)
+          return unless embedder
+
+          tool_data = ContextCompiler.tool_index.values
+          EmbeddingIndex.build_from_tool_data(tool_data, embedder: embedder)
+        end
+
         def wire_observer(data)
           return unless data[:method] == 'tools/call' && data[:tool_name]
 

data/lib/legion/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Legion
-  VERSION = '1.4.72'
+  VERSION = '1.4.73'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: legionio
 version: !ruby/object:Gem::Version
-  version: 1.4.72
+  version: 1.4.73
 platform: ruby
 authors:
 - Esity
@@ -560,6 +560,7 @@ files:
 - lib/legion/mcp.rb
 - lib/legion/mcp/auth.rb
 - lib/legion/mcp/context_compiler.rb
+- lib/legion/mcp/embedding_index.rb
 - lib/legion/mcp/observer.rb
 - lib/legion/mcp/resources/extension_info.rb
 - lib/legion/mcp/resources/runner_catalog.rb