legion-llm 0.3.11 → 0.3.13

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 61c5173e4490643fbecb7977697159ffdeb082b63ec4140289128c69efd14806
-  data.tar.gz: c42e9f24e2ecc387c1076fe32f05b4636e17e9fe92b16bf7ed438198caaa3187
+  metadata.gz: f6dc45bc6e985a3a6399ba3ed860bfb1ac9d3d9a0f31dda55a2f812d3c46e7cb
+  data.tar.gz: c3db21154b0b43de08e3e23b24416d9a7dc26a58eb10beb19835845b6ad83500
 SHA512:
-  metadata.gz: b05c1c69d88184ef4ceea383523c0b6538fd363a1cee9d12bf849ab2885bfdfe7fd59170fe059458c89378f66b93851ec69803ae03af6df1a3bbb55ab1aa432c
-  data.tar.gz: 57eab8217bdbc614a8602b45836f4b38bf099d9fc2e6b85cfbd92813856b837387e0901ac06af43085cfe0cd034146d160b05cd358afeb45c03ac628280ce9d6
+  metadata.gz: 6bd0700aee69aab3d7dad4e3266855d6ddf28de1574a9b1e48e972b653f4af509720e53b2d8c34e84ac9599a325b539c5fc6c7ac765e6c62a846a40e2b6b9519
+  data.tar.gz: c2ffe0842728637165668508a68a690eb0a00596710108b4685f47e4fa8b78f24e634ec652e11d7f86ace856f0166299c6827e7bb7a4f1e9ed6e491ed97ca559

data/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Legion LLM Changelog
 
+## [0.3.13] - 2026-03-21
+
+### Added
+- `Legion::LLM::Hooks::RagGuard` module with `check_rag_faithfulness` for post-generation RAG faithfulness evaluation via lex-eval
+- `Legion::LLM::Hooks::ResponseGuard` module with `guard_response` as the central dispatch point for post-generation safety checks
+- Response guard wired into `_dispatch_chat`: fires when `Legion::Settings[:llm][:response_guards][:enabled]` is true, attaches `_guard_result` metadata to the response hash without blocking
+- RAG guard skips gracefully when lex-eval is unavailable (returns `reason: :eval_unavailable`) or context is not provided (returns `reason: :no_context`)
+- Settings keys: `llm.rag_guard.enabled`, `llm.rag_guard.threshold` (default 0.7), `llm.rag_guard.evaluators` (default `[:faithfulness, :rag_relevancy]`)
+- 19 new specs in `spec/legion/llm/hooks/rag_guard_spec.rb` and `spec/legion/llm/hooks/response_guard_spec.rb`
+
+## [0.3.12] - 2026-03-19
+
+### Added
+- `Legion::LLM::Cache` module with deterministic SHA256 key generation, guarded `get`/`set`, and `enabled?` check
+- Application-level response caching in `chat_direct` via `legion-cache` (Legion::Cache guard required)
+- Cache skip conditions: `cache: false` option, `temperature > 0`, nil message, or cache disabled
+- Cache hits return `{ cached: true }` merged into response metadata
+- Anthropic prompt caching support: injects `cache_control: { type: "ephemeral" }` into system messages longer than `min_tokens` when provider is anthropic
+- `prompt_caching` settings section with `enabled`, `min_tokens`, `response_cache.enabled`, `response_cache.ttl_seconds` defaults
+- 25 new specs in `spec/legion/llm/cache_spec.rb` covering key determinism, hit/miss flows, skip conditions, and Legion::Cache unavailability guard
+
 ## [0.3.11] - 2026-03-20
 
 ### Added

data/lib/legion/llm/cache.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require 'digest'
+
+module Legion
+  module LLM
+    module Cache
+      DEFAULT_TTL = 300
+
+      module_function
+
+      # Generates a deterministic SHA256 cache key from request parameters.
+      def key(model:, provider:, messages:, temperature: nil, tools: nil, schema: nil)
+        payload = ::JSON.dump({
+                                model:       model.to_s,
+                                provider:    provider.to_s,
+                                messages:    messages,
+                                temperature: temperature,
+                                tools:       tools,
+                                schema:      schema
+                              })
+        Digest::SHA256.hexdigest(payload)
+      end
+
+      # Returns the cached response hash, or nil on miss / cache unavailable.
+      def get(cache_key)
+        return nil unless available?
+
+        raw = Legion::Cache.get(cache_key)
+        return nil if raw.nil?
+
+        ::JSON.parse(raw, symbolize_names: true)
+      rescue StandardError
+        nil
+      end
+
+      # Stores a response in the cache with the given TTL.
+      def set(cache_key, response, ttl: DEFAULT_TTL)
+        return false unless available?
+
+        Legion::Cache.set(cache_key, ::JSON.dump(response), ttl)
+        true
+      rescue StandardError
+        false
+      end
+
+      # Returns true if response caching is enabled in settings and Legion::Cache is loaded.
+      def enabled?
+        return false unless available?
+
+        settings = llm_settings
+        settings.dig(:prompt_caching, :response_cache, :enabled) != false
+      end
+
+      private_class_method def self.available?
+        defined?(Legion::Cache) && Legion::Cache.respond_to?(:get)
+      end
+
+      private_class_method def self.llm_settings
+        if Legion.const_defined?('Settings')
+          Legion::Settings[:llm]
+        else
+          Legion::LLM::Settings.default
+        end
+      rescue StandardError
+        {}
+      end
+    end
+  end
+end

data/lib/legion/llm/hooks/rag_guard.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Legion
+  module LLM
+    module Hooks
+      module RagGuard
+        class << self
+          def check_rag_faithfulness(response:, context:, threshold: nil, evaluators: nil, **)
+            return { faithful: true, reason: :eval_unavailable } unless eval_available?
+
+            resolved_threshold = threshold || settings_threshold
+            resolved_evaluators = evaluators || settings_evaluators
+
+            scores = {}
+            flagged = []
+
+            resolved_evaluators.each do |evaluator_name|
+              score = run_evaluator(evaluator_name, response: response, context: context)
+              scores[evaluator_name] = score
+              flagged << evaluator_name if score < resolved_threshold
+            end
+
+            faithful = flagged.empty?
+            details = build_details(scores, resolved_threshold, faithful)
+
+            { faithful: faithful, scores: scores, flagged_evaluators: flagged, details: details }
+          rescue StandardError => e
+            Legion::Logging.warn "RagGuard evaluation error: #{e.message}" if logging_available?
+            { faithful: true, reason: :eval_error }
+          end
+
+          private
+
+          def eval_available?
+            defined?(Legion::Extensions::Eval::Client)
+          end
+
+          def logging_available?
+            Legion.const_defined?('Logging')
+          end
+
+          def settings_threshold
+            val = Legion::Settings.dig(:llm, :rag_guard, :threshold) if Legion.const_defined?('Settings')
+            val || 0.7
+          end
+
+          def settings_evaluators
+            val = Legion::Settings.dig(:llm, :rag_guard, :evaluators) if Legion.const_defined?('Settings')
+            val || %i[faithfulness rag_relevancy]
+          end
+
+          def run_evaluator(evaluator_name, response:, context:)
+            client = Legion::Extensions::Eval::Client.new
+            result = client.run_evaluation(
+              evaluator_name: evaluator_name,
+              inputs:         [{ input: context.to_s, output: response.to_s, expected: nil }]
+            )
+            result.dig(:summary, :avg_score) || 0.0
+          rescue StandardError
+            0.0
+          end
+
+          def build_details(scores, threshold, faithful)
+            score_parts = scores.map { |k, v| "#{k}=#{v.round(3)}" }.join(', ')
+            status = faithful ? 'passed' : 'failed'
+            "RAG faithfulness check #{status} (threshold=#{threshold}): #{score_parts}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/llm/hooks/response_guard.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Legion
+  module LLM
+    module Hooks
+      module ResponseGuard
+        GUARD_REGISTRY = {
+          rag: RagGuard
+        }.freeze
+
+        class << self
+          def guard_response(response:, context: nil, guards: [:rag], **)
+            guard_results = {}
+
+            guards.each do |guard_name|
+              guard_mod = GUARD_REGISTRY[guard_name.to_sym]
+              next unless guard_mod
+
+              guard_results[guard_name] = dispatch_guard(guard_mod, guard_name,
+                                                         response: response, context: context)
+            end
+
+            passed = guard_results.values.all? { |r| r[:faithful] != false }
+
+            { passed: passed, guards: guard_results }
+          rescue StandardError => e
+            Legion::Logging.warn "ResponseGuard error: #{e.message}" if Legion.const_defined?('Logging')
+            { passed: true, guards: {} }
+          end
+
+          private
+
+          def dispatch_guard(guard_mod, guard_name, response:, context:)
+            case guard_name.to_sym
+            when :rag
+              return { faithful: true, reason: :no_context } if context.nil?
+
+              guard_mod.check_rag_faithfulness(response: response, context: context)
+            else
+              guard_mod.check(response: response, context: context)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/llm/hooks.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+require 'legion/llm/hooks/rag_guard'
+require 'legion/llm/hooks/response_guard'
+
 module Legion
   module LLM
     module Hooks

data/lib/legion/llm/settings.rb

@@ -14,7 +14,8 @@ module Legion
           routing:          routing_defaults,
           discovery:        discovery_defaults,
           gateway:          gateway_defaults,
-          daemon:           daemon_defaults
+          daemon:           daemon_defaults,
+          prompt_caching:   prompt_caching_defaults
         }
       end
 
@@ -25,6 +26,17 @@ module Legion
         }
       end
 
+      def self.prompt_caching_defaults
+        {
+          enabled:        true,
+          min_tokens:     1024,
+          response_cache: {
+            enabled:     true,
+            ttl_seconds: 300
+          }
+        }
+      end
+
       def self.discovery_defaults
         {
           enabled:         true,

data/lib/legion/llm/version.rb

@@ -2,6 +2,6 @@
 
 module Legion
   module LLM
-    VERSION = '0.3.11'
+    VERSION = '0.3.13'
   end
 end

data/lib/legion/llm.rb

@@ -9,6 +9,7 @@ require 'legion/llm/compressor'
 require 'legion/llm/quality_checker'
 require 'legion/llm/escalation_history'
 require 'legion/llm/hooks'
+require 'legion/llm/cache'
 require_relative 'llm/response_cache'
 require_relative 'llm/daemon_client'
 
@@ -95,18 +96,40 @@ module Legion
 
       # Direct chat bypassing gateway — used by gateway runners to avoid recursion
       def chat_direct(model: nil, provider: nil, intent: nil, tier: nil, escalate: nil,
-                      max_escalations: nil, quality_check: nil, message: nil, **)
+                      max_escalations: nil, quality_check: nil, message: nil, **kwargs)
+        cache_opt   = kwargs.delete(:cache) { true }
+        temperature = kwargs.delete(:temperature)
+
         escalate = escalation_enabled? if escalate.nil?
+        cache_key = build_cache_key(model, provider, message, temperature) if cacheable?(cache_opt, temperature, message)
+
+        if cache_key
+          cached = Cache.get(cache_key)
+          if cached
+            Legion::Logging.debug 'Legion::LLM cache hit'
+            cached_response = cached.dup
+            cached_response[:meta] = (cached_response[:meta] || {}).merge(cached: true)
+            return cached_response
+          end
+        end
 
-        if escalate && message
-          chat_with_escalation(
-            model: model, provider: provider, intent: intent, tier: tier,
-            max_escalations: max_escalations, quality_check: quality_check,
-            message: message, **
-          )
-        else
-          chat_single(model: model, provider: provider, intent: intent, tier: tier, **)
+        result = if escalate && message
+                   chat_with_escalation(
+                     model: model, provider: provider, intent: intent, tier: tier,
+                     max_escalations: max_escalations, quality_check: quality_check,
+                     message: message, temperature: temperature, **kwargs
+                   )
+                 else
+                   chat_single(model: model, provider: provider, intent: intent, tier: tier,
+                               temperature: temperature, **kwargs)
+                 end
+
+        if cache_key && result.is_a?(Hash)
+          ttl = settings.dig(:prompt_caching, :response_cache, :ttl_seconds) || Cache::DEFAULT_TTL
+          Cache.set(cache_key, result, ttl: ttl)
         end
+
+        result
       end
 
       # Generate embeddings — delegates to gateway when available
@@ -161,7 +184,7 @@ module Legion
 
       private
 
-      def _dispatch_chat(model:, provider:, intent:, tier:, escalate:, max_escalations:, quality_check:, message:, **)
+      def _dispatch_chat(model:, provider:, intent:, tier:, escalate:, max_escalations:, quality_check:, message:, **kwargs)
         messages = message.is_a?(Array) ? message : [{ role: 'user', content: message.to_s }]
         resolved_model = model || settings[:default_model]
 
@@ -173,11 +196,11 @@ module Legion
         result = if gateway_loaded? && message
                    gateway_chat(model: model, provider: provider, intent: intent,
                                 tier: tier, message: message, escalate: escalate,
-                                max_escalations: max_escalations, quality_check: quality_check, **)
+                                max_escalations: max_escalations, quality_check: quality_check, **kwargs)
                  else
                    chat_direct(model: model, provider: provider, intent: intent, tier: tier,
                                escalate: escalate, max_escalations: max_escalations,
-                               quality_check: quality_check, message: message, **)
+                               quality_check: quality_check, message: message, **kwargs)
                  end
 
         if defined?(Legion::LLM::Hooks)
@@ -185,6 +208,8 @@ module Legion
           return blocked[:response] if blocked
         end
 
+        result = apply_response_guards(result, kwargs) if response_guards_enabled? && result.is_a?(Hash)
+
         result
       end
 
@@ -268,6 +293,9 @@ module Legion
         opts[:model]    = model    if model
         opts[:provider] = provider if provider
         opts.merge!(kwargs)
+        opts.delete(:temperature) if opts[:temperature].nil?
+
+        inject_anthropic_cache_control!(opts, provider)
 
         RubyLLM.chat(**opts)
       end
@@ -344,6 +372,55 @@ module Legion
         nil
       end
 
+      def response_guards_enabled?
+        settings.dig(:response_guards, :enabled) == true
+      end
+
+      def apply_response_guards(result, kwargs)
+        context = kwargs[:context]
+        response_text = result[:response] || result[:content]
+        guard_result = Hooks::ResponseGuard.guard_response(
+          response: response_text, context: context
+        )
+
+        Legion::Logging.warn "Response guard failed: #{guard_result.inspect}" if !guard_result[:passed] && Legion.const_defined?('Logging')
+
+        result.merge(_guard_result: guard_result)
+      rescue StandardError
+        result
+      end
+
+      def cacheable?(cache_opt, temperature, message)
+        cache_opt != false && temperature.to_f.zero? && message && Cache.enabled?
+      end
+
+      def build_cache_key(model, provider, message, temperature)
+        messages_arr = message.is_a?(Array) ? message : [{ role: 'user', content: message.to_s }]
+        Cache.key(
+          model:       model || settings[:default_model],
+          provider:    provider || settings[:default_provider],
+          messages:    messages_arr,
+          temperature: temperature
+        )
+      end
+
+      def inject_anthropic_cache_control!(opts, provider)
+        resolved_provider = (provider || settings[:default_provider])&.to_sym
+        return unless resolved_provider == :anthropic
+
+        caching_settings = settings[:prompt_caching] || {}
+        return unless caching_settings[:enabled] != false
+
+        min_tokens = caching_settings[:min_tokens] || 1024
+        instructions = opts[:instructions]
+        return unless instructions.is_a?(String) && instructions.length > min_tokens
+
+        opts[:instructions] = {
+          content:       instructions,
+          cache_control: { type: 'ephemeral' }
+        }
+      end
+
       def escalation_enabled?
         routing = settings[:routing]
         return false unless routing.is_a?(Hash)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: legion-llm
 version: !ruby/object:Gem::Version
-  version: 0.3.11
+  version: 0.3.13
 platform: ruby
 authors:
 - Esity
@@ -131,6 +131,7 @@ files:
 - legion-llm.gemspec
 - lib/legion/llm.rb
 - lib/legion/llm/bedrock_bearer_auth.rb
+- lib/legion/llm/cache.rb
 - lib/legion/llm/claude_config_loader.rb
 - lib/legion/llm/compressor.rb
 - lib/legion/llm/daemon_client.rb
@@ -140,6 +141,8 @@ files:
 - lib/legion/llm/escalation_history.rb
 - lib/legion/llm/helpers/llm.rb
 - lib/legion/llm/hooks.rb
+- lib/legion/llm/hooks/rag_guard.rb
+- lib/legion/llm/hooks/response_guard.rb
 - lib/legion/llm/providers.rb
 - lib/legion/llm/quality_checker.rb
 - lib/legion/llm/response_cache.rb