legion-llm 0.5.18 → 0.5.19

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9e522e0d580a9f76eb134b4bec7e360aba72d831c4a997da2a56e3fbf5e4af2f
-  data.tar.gz: a27d63184aab2c0f65739a153d3a0943612787c723d2ab3305ac4649b050b75a
+  metadata.gz: ac3514ef943a51cc0f3d2457cc4fa976b63cb2999896626ade1d76dc7c4f7804
+  data.tar.gz: f71220f0ad03f65436d0e0f6ce0f34a3ecbbb5fc0bda3add29f9dcaa1713b07d
 SHA512:
-  metadata.gz: '09fd95274c21c1963a3249ab8a0ad312702a545a493448ccca89fab82314b8148a3c0ef5530f01d82e01eb893d4ad5cee5ea461dc0c01a7a977f71d336fdcfd1'
-  data.tar.gz: 23f322666410c4a603c05b35f077f4fbe80a9266942a8d7483a658351cdb6e678c3aec69acad4eac14b2ca0e87619fbf0eed73ae1a19c8bcf85dd51656dd687d
+  metadata.gz: 7112f4a875c4a49f01d2bf30249c44f85e9427722009c7474a3bb303f4f082010e117650bcacddd1ee2a0cd930d45ad043b6374f8050b31046d195975dcdf222
+  data.tar.gz: f01fd5cfc55684040cc9c312154811a117fb568576f136c9e87fb83c178c89f9ea6eceaf025e7c4f678e182be5d0a76eb7f656ce6b8b552eeb577f3fbe1e737a

data/AGENTS.md

@@ -0,0 +1,37 @@
+# legion-llm Agent Notes
+
+## Scope
+
+`legion-llm` provides provider configuration, chat/embed/structured interfaces, dynamic routing, escalation, quality checks, and pipeline execution for Legion.
+
+## Fast Start
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
+## Primary Entry Points
+
+- `lib/legion/llm.rb`
+- `lib/legion/llm/providers.rb`
+- `lib/legion/llm/router/`
+- `lib/legion/llm/pipeline/`
+- `lib/legion/llm/structured_output.rb`
+- `lib/legion/llm/embeddings.rb`
+- `lib/legion/llm/fleet/`
+
+## Guardrails
+
+- Keep typed error behavior and retry semantics stable (`ProviderDown`, `RateLimitError`, `EscalationExhausted`, etc.).
+- Routing and escalation must remain deterministic given the same inputs/settings.
+- Preserve pipeline feature-flag behavior; avoid forcing pipeline-only code paths.
+- Keep provider credentials resolved through settings secret resolution flow; never hardcode secrets.
+- Maintain compatibility with direct methods (`chat_direct`, `embed_direct`, `structured_direct`) and daemon-aware flows.
+- Health tracker and rule scoring are contract-sensitive; changes require spec updates.
+
+## Validation
+
+- Run targeted specs for modified router/pipeline/provider code.
+- Before handoff, run full `bundle exec rspec` and `bundle exec rubocop`.

data/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Legion LLM Changelog
 
+## [Unreleased]
+
+### Added
+- `Legion::LLM::Helper` module at `lib/legion/llm/helper.rb` — canonical helper following cache/transport pattern
+- Layered defaults: `llm_default_model`, `llm_default_provider`, `llm_default_intent` (LEX-overridable)
+- `llm_embed_batch` — batch embedding convenience
+- `llm_structured` — structured JSON output convenience
+- `llm_ask` — daemon-first single-shot convenience
+- `llm_connected?` / `llm_can_embed?` / `llm_routing_enabled?` — status helpers
+- `llm_cost_estimate` / `llm_cost_summary` / `llm_budget_remaining` — cost and budget helpers
+- Layered model/provider/intent defaults applied to `llm_chat` and `llm_session`
+
+### Changed
+- `lib/legion/llm/helpers/llm.rb` is now a backward-compat shim that includes `Legion::LLM::Helper`
+
 ## [0.5.18] - 2026-03-29
 
 ### Fixed

data/lib/legion/llm/helper.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+module Legion
+  module LLM
+    module Helper
+      # --- Layered Defaults ---
+      # Override in your LEX to set extension-specific defaults.
+      # Resolution chain: per-call kwarg -> LEX override -> Settings -> nil (auto-detect)
+
+      def llm_default_model
+        return nil unless defined?(Legion::Settings)
+
+        Legion::Settings.dig(:llm, :default_model)
+      rescue StandardError
+        nil
+      end
+
+      def llm_default_provider
+        return nil unless defined?(Legion::Settings)
+
+        Legion::Settings.dig(:llm, :default_provider)
+      rescue StandardError
+        nil
+      end
+
+      def llm_default_intent
+        return nil unless defined?(Legion::Settings)
+
+        Legion::Settings.dig(:llm, :routing, :default_intent)
+      rescue StandardError
+        nil
+      end
+
+      # --- Core Operations ---
+
+      def llm_chat(message, model: nil, provider: nil, intent: nil, tier: nil, tools: [], # rubocop:disable Metrics/ParameterLists
+                   instructions: nil, compress: 0, escalate: nil, max_escalations: nil,
+                   quality_check: nil, caller: nil, use_default_intent: false)
+        effective_model = model || llm_default_model
+        effective_provider = provider || llm_default_provider
+        effective_intent = intent || (use_default_intent ? llm_default_intent : nil)
+
+        if compress.positive?
+          message = Legion::LLM::Compressor.compress(message, level: compress)
+          instructions = Legion::LLM::Compressor.compress(instructions, level: compress) if instructions
+        end
+
+        if escalate
+          return Legion::LLM.chat(model: effective_model, provider: effective_provider,
+                                  intent: effective_intent, tier: tier,
+                                  escalate: true, max_escalations: max_escalations,
+                                  quality_check: quality_check, message: message, caller: caller)
+        end
+
+        chat = Legion::LLM.chat(model: effective_model, provider: effective_provider,
+                                intent: effective_intent, tier: tier,
+                                escalate: false, caller: caller)
+        chat.with_instructions(instructions) if instructions
+        chat.with_tools(*tools) unless tools.empty?
+        chat.ask(message)
+      end
+
+      def llm_embed(text, **)
+        Legion::LLM.embed(text, **)
+      end
+
+      def llm_embed_batch(texts, **)
+        Legion::LLM.embed_batch(texts, **)
+      end
+
+      def llm_session(model: nil, provider: nil, intent: nil, tier: nil, caller: nil, use_default_intent: false)
+        effective_model = model || llm_default_model
+        effective_provider = provider || llm_default_provider
+        effective_intent = intent || (use_default_intent ? llm_default_intent : nil)
+
+        Legion::LLM.chat(model: effective_model, provider: effective_provider,
+                         intent: effective_intent, tier: tier,
+                         escalate: false, caller: caller)
+      end
+
+      def llm_structured(messages:, schema:, **)
+        Legion::LLM.structured(messages: messages, schema: schema, **)
+      end
+
+      def llm_ask(message:, **)
+        Legion::LLM.ask(message: message, **)
+      end
+
+      # --- Status ---
+
+      def llm_connected?
+        defined?(Legion::LLM) && Legion::LLM.started?
+      rescue StandardError
+        false
+      end
+
+      def llm_can_embed?
+        llm_connected? && Legion::LLM.can_embed?
+      rescue StandardError
+        false
+      end
+
+      def llm_routing_enabled?
+        llm_connected? && Legion::LLM::Router.routing_enabled?
+      rescue StandardError
+        false
+      end
+
+      # --- Cost / Budget ---
+
+      def llm_cost_estimate(model: nil, input_tokens: 0, output_tokens: 0)
+        model ||= llm_default_model
+        Legion::LLM::CostEstimator.estimate(model_id: model, input_tokens: input_tokens,
+                                            output_tokens: output_tokens)
+      rescue StandardError
+        0.0
+      end
+
+      def llm_cost_summary(since: nil)
+        Legion::LLM::CostTracker.summary(since: since)
+      rescue StandardError
+        { total_cost_usd: 0.0, total_requests: 0, total_input_tokens: 0, total_output_tokens: 0, by_model: {} }
+      end
+
+      def llm_budget_remaining
+        Legion::LLM::Hooks::BudgetGuard.remaining
+      rescue StandardError
+        Float::INFINITY
+      end
+    end
+  end
+end

data/lib/legion/llm/helpers/llm.rb

@@ -1,59 +1,12 @@
 # frozen_string_literal: true
 
+require 'legion/llm/helper'
+
 module Legion
   module Extensions
     module Helpers
       module LLM
-        # Quick chat from any extension runner
-        # @param message [String] the prompt
-        # @param model [String] optional model override
-        # @param provider [Symbol] optional provider override
-        # @param intent [Hash, nil] routing intent (capability, privacy, etc.)
-        # @param tier [Symbol, nil] explicit tier override
-        # @param tools [Array<Class>] optional RubyLLM::Tool subclasses
-        # @param instructions [String] optional system instructions
-        # @param escalate [Boolean, nil] enable model escalation on low-quality responses
-        # @param max_escalations [Integer, nil] max escalation attempts
-        # @param quality_check [Proc, nil] callable that returns true if response is acceptable
-        # @return [RubyLLM::Message] the assistant response
-        def llm_chat(message, model: nil, provider: nil, intent: nil, tier: nil, tools: [], instructions: nil, # rubocop:disable Metrics/ParameterLists
-                     compress: 0, escalate: nil, max_escalations: nil, quality_check: nil, caller: nil)
-          if compress.positive?
-            message = Legion::LLM::Compressor.compress(message, level: compress)
-            instructions = Legion::LLM::Compressor.compress(instructions, level: compress) if instructions
-          end
-
-          # When escalation is active, chat() handles ask() internally via message: kwarg
-          if escalate
-            return Legion::LLM.chat(model: model, provider: provider, intent: intent, tier: tier,
-                                    escalate: true, max_escalations: max_escalations,
-                                    quality_check: quality_check, message: message, caller: caller)
-          end
-
-          chat = Legion::LLM.chat(model: model, provider: provider, intent: intent, tier: tier,
-                                  escalate: false, caller: caller)
-          chat.with_instructions(instructions) if instructions
-          chat.with_tools(*tools) unless tools.empty?
-          chat.ask(message)
-        end
-
-        # Quick embed from any extension runner
-        # @param text [String, Array<String>] text to embed
-        # @param model [String] optional model override
-        # @return [RubyLLM::Embedding]
-        def llm_embed(text, model: nil)
-          Legion::LLM.embed(text, model: model)
-        end
-
-        # Get a raw chat object for multi-turn conversations
-        # @param model [String] optional model override
-        # @param provider [Symbol] optional provider override
-        # @param intent [Hash, nil] routing intent (capability, privacy, etc.)
-        # @param tier [Symbol, nil] explicit tier override
-        # @return [RubyLLM::Chat]
-        def llm_session(model: nil, provider: nil, intent: nil, tier: nil, caller: nil)
-          Legion::LLM.chat(model: model, provider: provider, intent: intent, tier: tier, escalate: false, caller: caller)
-        end
+        include Legion::LLM::Helper
       end
     end
   end

data/lib/legion/llm/version.rb

@@ -2,6 +2,6 @@
 
 module Legion
   module LLM
-    VERSION = '0.5.18'
+    VERSION = '0.5.19'
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: legion-llm
 version: !ruby/object:Gem::Version
-  version: 0.5.18
+  version: 0.5.19
 platform: ruby
 authors:
 - Esity
@@ -179,6 +179,7 @@ files:
 - ".github/workflows/ci.yml"
 - ".gitignore"
 - ".rubocop.yml"
+- AGENTS.md
 - CHANGELOG.md
 - CLAUDE.md
 - CODEOWNERS
@@ -230,6 +231,7 @@ files:
 - lib/legion/llm/fleet/dispatcher.rb
 - lib/legion/llm/fleet/handler.rb
 - lib/legion/llm/fleet/reply_dispatcher.rb
+- lib/legion/llm/helper.rb
 - lib/legion/llm/helpers/llm.rb
 - lib/legion/llm/hooks.rb
 - lib/legion/llm/hooks/budget_guard.rb