legion-mcp 0.1.0

data/lib/legion/mcp/context_compiler.rb

@@ -0,0 +1,173 @@
+# frozen_string_literal: true
+
+require_relative 'embedding_index'
+
+module Legion
+  module MCP
+    module ContextCompiler
+      CATEGORIES = {
+        tasks:         {
+          tools:   %w[legion.run_task legion.list_tasks legion.get_task legion.delete_task legion.get_task_logs],
+          summary: 'Create, list, query, and delete tasks. Run functions via dot-notation task identifiers.'
+        },
+        chains:        {
+          tools:   %w[legion.list_chains legion.create_chain legion.update_chain legion.delete_chain],
+          summary: 'Manage task chains - ordered sequences of tasks that execute in series.'
+        },
+        relationships: {
+          tools:   %w[legion.list_relationships legion.create_relationship legion.update_relationship
+                      legion.delete_relationship],
+          summary: 'Manage trigger-action relationships between functions.'
+        },
+        extensions:    {
+          tools:   %w[legion.list_extensions legion.get_extension legion.enable_extension
+                      legion.disable_extension],
+          summary: 'Manage LEX extensions - list installed, inspect details, enable/disable.'
+        },
+        schedules:     {
+          tools:   %w[legion.list_schedules legion.create_schedule legion.update_schedule legion.delete_schedule],
+          summary: 'Manage scheduled tasks - cron-style recurring task execution.'
+        },
+        workers:       {
+          tools:   %w[legion.list_workers legion.show_worker legion.worker_lifecycle legion.worker_costs],
+          summary: 'Manage digital workers - list, inspect, lifecycle transitions, cost tracking.'
+        },
+        rbac:          {
+          tools:   %w[legion.rbac_check legion.rbac_assignments legion.rbac_grants],
+          summary: 'Role-based access control - check permissions, view assignments and grants.'
+        },
+        status:        {
+          tools:   %w[legion.get_status legion.get_config legion.team_summary legion.routing_stats],
+          summary: 'System status, configuration, team overview, and routing statistics.'
+        },
+        describe:      {
+          tools:   %w[legion.describe_runner],
+          summary: 'Inspect a specific runner function - parameters, return type, metadata.'
+        }
+      }.freeze
+
+      module_function
+
+      # Returns a compressed summary of all categories with tool counts and tool name lists.
+      # @return [Array<Hash>] array of { category:, summary:, tool_count:, tools: }
+      def compressed_catalog
+        CATEGORIES.map do |category, config|
+          tool_names = config[:tools]
+          {
+            category:   category,
+            summary:    config[:summary],
+            tool_count: tool_names.length,
+            tools:      tool_names
+          }
+        end
+      end
+
+      # Returns tools for a specific category, filtered to only those present in TOOL_CLASSES.
+      # @param category_sym [Symbol] one of the CATEGORIES keys
+      # @return [Hash, nil] { category:, summary:, tools: [{ name:, description:, params: }] } or nil
+      def category_tools(category_sym)
+        config = CATEGORIES[category_sym]
+        return nil unless config
+
+        index = tool_index
+        tools = config[:tools].filter_map { |name| index[name] }
+        return nil if tools.empty?
+
+        {
+          category: category_sym,
+          summary:  config[:summary],
+          tools:    tools
+        }
+      end
+
+      # Keyword-match intent against tool names and descriptions.
+      # @param intent_string [String] natural language intent
+      # @return [Class, nil] best matching tool CLASS from Server::TOOL_CLASSES or nil
+      def match_tool(intent_string)
+        scored = scored_tools(intent_string)
+        return nil if scored.empty?
+
+        best = scored.max_by { |entry| entry[:score] }
+        return nil if best[:score].zero?
+
+        Server::TOOL_CLASSES.find { |klass| klass.tool_name == best[:name] }
+      end
+
+      # Returns top N keyword-matched tools ranked by score.
+      # @param intent_string [String] natural language intent
+      # @param limit [Integer] max results (default 5)
+      # @return [Array<Hash>] array of { name:, description:, score: }
+      def match_tools(intent_string, limit: 5)
+        scored = scored_tools(intent_string)
+                 .select { |entry| entry[:score].positive? }
+                 .sort_by { |entry| -entry[:score] }
+        scored.first(limit)
+      end
+
+      # Returns a hash keyed by tool_name with compressed param info.
+      # Memoized — call reset! to clear.
+      # @return [Hash<String, Hash>] { name:, description:, params: [String] }
+      def tool_index
+        @tool_index ||= build_tool_index
+      end
+
+      # Clears the memoized tool_index.
+      def reset!
+        @tool_index = nil
+        Legion::MCP::EmbeddingIndex.reset! if defined?(Legion::MCP::EmbeddingIndex)
+      end
+
+      def build_tool_index
+        Server::TOOL_CLASSES.each_with_object({}) do |klass, idx|
+          raw_schema = klass.input_schema
+          schema = raw_schema.is_a?(Hash) ? raw_schema : raw_schema.to_h
+          properties = schema[:properties] || {}
+          idx[klass.tool_name] = {
+            name:        klass.tool_name,
+            description: klass.description,
+            params:      properties.keys.map(&:to_s)
+          }
+        end
+      end
+
+      def scored_tools(intent_string)
+        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) }
+          [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
+  end
+end

data/lib/legion/mcp/context_guard.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module Legion
+  module MCP
+    module ContextGuard
+      DEFAULT_MAX_STALE_SECONDS      = 3600
+      DEFAULT_RAPID_FIRE_THRESHOLD   = 5
+      DEFAULT_RAPID_FIRE_WINDOW_SECS = 600
+      DEFAULT_ANOMALY_MISS_THRESHOLD = 2
+
+      module_function
+
+      def check(pattern, _params, _context)
+        return staleness_failure(pattern) if stale?(pattern)
+        return anomaly_failure(pattern) if anomalous?(pattern)
+        return rapid_fire_failure(pattern) if rapid_fire?(pattern[:intent_hash])
+
+        { passed: true }
+      end
+
+      def record_request(intent_hash)
+        mutex.synchronize do
+          requests[intent_hash] ||= []
+          requests[intent_hash] << Time.now
+        end
+      end
+
+      def reset!
+        mutex.synchronize { requests.clear }
+      end
+
+      def stale?(pattern)
+        last_hit = pattern[:last_hit_at]
+        return false unless last_hit
+
+        (Time.now - last_hit) > max_stale_seconds
+      end
+
+      def anomalous?(pattern)
+        (pattern[:miss_count] || 0) >= anomaly_miss_threshold
+      end
+
+      def rapid_fire?(intent_hash)
+        return false unless intent_hash
+
+        window = Time.now - rapid_fire_window_seconds
+        count = mutex.synchronize do
+          entries = requests[intent_hash]
+          return false unless entries
+
+          entries.reject! { |t| t < window }
+          entries.size
+        end
+
+        count > rapid_fire_threshold
+      end
+
+      def max_stale_seconds
+        setting(:max_stale_seconds) || DEFAULT_MAX_STALE_SECONDS
+      end
+
+      def rapid_fire_threshold
+        setting(:rapid_fire_threshold) || DEFAULT_RAPID_FIRE_THRESHOLD
+      end
+
+      def rapid_fire_window_seconds
+        setting(:rapid_fire_window_seconds) || DEFAULT_RAPID_FIRE_WINDOW_SECS
+      end
+
+      def anomaly_miss_threshold
+        DEFAULT_ANOMALY_MISS_THRESHOLD
+      end
+
+      def setting(key)
+        return nil unless defined?(Legion::Settings)
+
+        Legion::Settings.dig(:mcp, :tier0, :guards, key)
+      rescue StandardError
+        nil
+      end
+
+      def staleness_failure(pattern)
+        age = pattern[:last_hit_at] ? (Time.now - pattern[:last_hit_at]).round(0) : 0
+        { passed: false, guard: :staleness, reason: "pattern stale (#{age}s since last hit)" }
+      end
+
+      def anomaly_failure(pattern)
+        { passed: false, guard: :anomaly, reason: "#{pattern[:miss_count]} consecutive misses" }
+      end
+
+      def rapid_fire_failure(_pattern)
+        { passed: false, guard: :rapid_fire,
+          reason: "exceeded #{rapid_fire_threshold} requests in #{rapid_fire_window_seconds}s" }
+      end
+
+      def requests
+        @requests ||= {}
+      end
+
+      def mutex
+        @mutex ||= Mutex.new
+      end
+    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/observer.rb

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+require 'concurrent-ruby'
+require 'digest'
+
+module Legion
+  module MCP
+    module Observer
+      RING_BUFFER_MAX   = 500
+      INTENT_BUFFER_MAX = 200
+
+      module_function
+
+      def record(tool_name:, duration_ms:, success:, params_keys: [], error: nil)
+        now = Time.now
+
+        counters_mutex.synchronize do
+          entry = counters[tool_name] || { call_count: 0, total_latency_ms: 0.0, failure_count: 0,
+                                           last_used: nil, last_error: nil }
+          counters[tool_name] = {
+            call_count:       entry[:call_count] + 1,
+            total_latency_ms: entry[:total_latency_ms] + duration_ms.to_f,
+            failure_count:    entry[:failure_count] + (success ? 0 : 1),
+            last_used:        now,
+            last_error:       success ? entry[:last_error] : error
+          }
+        end
+
+        buffer_mutex.synchronize do
+          ring_buffer << {
+            tool_name:   tool_name,
+            duration_ms: duration_ms,
+            success:     success,
+            params_keys: params_keys,
+            error:       error,
+            recorded_at: now
+          }
+          ring_buffer.shift if ring_buffer.size > RING_BUFFER_MAX
+        end
+      end
+
+      def record_intent(intent, matched_tool_name)
+        intent_mutex.synchronize do
+          intent_buffer << { intent: intent, matched_tool: matched_tool_name, recorded_at: Time.now }
+          intent_buffer.shift if intent_buffer.size > INTENT_BUFFER_MAX
+        end
+      end
+
+      def record_intent_with_result(intent:, tool_name:, success:)
+        record_intent(intent, tool_name)
+        return unless success
+        return unless defined?(Legion::MCP::PatternStore)
+
+        normalized  = intent.to_s.strip.downcase.gsub(/\s+/, ' ')
+        intent_hash = Digest::SHA256.hexdigest(normalized)
+
+        promotion = Legion::MCP::PatternStore.record_candidate(
+          intent_hash: intent_hash,
+          tool_chain:  [tool_name],
+          intent_text: intent
+        )
+
+        return unless promotion&.dig(:promote)
+
+        Legion::MCP::PatternStore.promote_candidate(
+          intent_hash:   promotion[:intent_hash],
+          tool_chain:    promotion[:tool_chain],
+          intent_text:   promotion[:intent_text],
+          intent_vector: try_embed(normalized)
+        )
+      end
+
+      def tool_stats(tool_name)
+        entry = counters_mutex.synchronize { counters[tool_name] }
+        return nil unless entry
+
+        count = entry[:call_count]
+        avg   = count.positive? ? (entry[:total_latency_ms] / count).round(2) : 0.0
+
+        {
+          name:           tool_name,
+          call_count:     count,
+          avg_latency_ms: avg,
+          failure_count:  entry[:failure_count],
+          last_used:      entry[:last_used],
+          last_error:     entry[:last_error]
+        }
+      end
+
+      def all_tool_stats
+        names = counters_mutex.synchronize { counters.keys.dup }
+        names.to_h { |name| [name, tool_stats(name)] }
+      end
+
+      def stats
+        all_names = counters_mutex.synchronize { counters.keys.dup }
+        total     = all_names.sum { |n| counters_mutex.synchronize { counters[n][:call_count] } }
+        failures  = all_names.sum { |n| counters_mutex.synchronize { counters[n][:failure_count] } }
+        rate      = total.positive? ? (failures.to_f / total).round(4) : 0.0
+
+        top = all_names
+              .map { |n| tool_stats(n) }
+              .sort_by { |s| -s[:call_count] }
+              .first(10)
+
+        {
+          total_calls:  total,
+          tool_count:   all_names.size,
+          failure_rate: rate,
+          top_tools:    top,
+          since:        started_at
+        }
+      end
+
+      def recent(limit = 10)
+        buffer_mutex.synchronize { ring_buffer.last(limit) }
+      end
+
+      def recent_intents(limit = 10)
+        intent_mutex.synchronize { intent_buffer.last(limit) }
+      end
+
+      def reset!
+        counters_mutex.synchronize { counters.clear }
+        buffer_mutex.synchronize { ring_buffer.clear }
+        intent_mutex.synchronize { intent_buffer.clear }
+        @started_at = Time.now
+      end
+
+      # Internal state accessors
+      def counters
+        @counters ||= {}
+      end
+
+      def counters_mutex
+        @counters_mutex ||= Mutex.new
+      end
+
+      def ring_buffer
+        @ring_buffer ||= []
+      end
+
+      def buffer_mutex
+        @buffer_mutex ||= Mutex.new
+      end
+
+      def intent_buffer
+        @intent_buffer ||= []
+      end
+
+      def intent_mutex
+        @intent_mutex ||= Mutex.new
+      end
+
+      def started_at
+        @started_at ||= Time.now
+      end
+
+      def try_embed(text)
+        return nil unless defined?(Legion::MCP::EmbeddingIndex)
+
+        embedder = Legion::MCP::EmbeddingIndex.instance_variable_get(:@embedder)
+        return nil unless embedder
+
+        embedder.call(text)
+      rescue StandardError
+        nil
+      end
+    end
+  end
+end