legion-llm 0.5.18 → 0.5.20

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9e522e0d580a9f76eb134b4bec7e360aba72d831c4a997da2a56e3fbf5e4af2f
-  data.tar.gz: a27d63184aab2c0f65739a153d3a0943612787c723d2ab3305ac4649b050b75a
+  metadata.gz: f51b096c53558665dbfc074fa203c8624aa79444324cb686759aee35cd568ca6
+  data.tar.gz: 95c6a41fa6839d476cff0d60a6b56a1fbc7ad5be4f914f290fc877e0198e50bc
 SHA512:
-  metadata.gz: '09fd95274c21c1963a3249ab8a0ad312702a545a493448ccca89fab82314b8148a3c0ef5530f01d82e01eb893d4ad5cee5ea461dc0c01a7a977f71d336fdcfd1'
-  data.tar.gz: 23f322666410c4a603c05b35f077f4fbe80a9266942a8d7483a658351cdb6e678c3aec69acad4eac14b2ca0e87619fbf0eed73ae1a19c8bcf85dd51656dd687d
+  metadata.gz: 33a939afde771b78203d7c84f3fdb9ccbe226907037bc97f86a5650324c089e1034e9de3251ea1deb72d634680b3de6e263a48bbb933648621586598d1244f16
+  data.tar.gz: d0f98e6c6dfbee9040953991e8ab3a0de88cd37ed32a352b2d6d0ef52163e120756238d7d5f96c6f00d028b25e778a2076c9012550879fba1b98b06339d5a63e

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,26 @@
 # Legion LLM Changelog
 
+## [Unreleased]
+
+## [0.5.20] - 2026-03-30
+
+### Added
+- `CodexConfigLoader`: auto-imports OpenAI bearer token from `~/.codex/auth.json` when `auth_mode` is `chatgpt` and no existing OpenAI API key is configured (#15)
+- JWT expiry validation — expired codex tokens are skipped with a debug log (#15)
+- Non-JWT tokens (plain API keys) accepted without validation (#15)
+- Falls back to vault/settings/env when codex auth file is absent or token is expired (#15)
+- `Legion::LLM::Helper` module at `lib/legion/llm/helper.rb` — canonical helper following cache/transport pattern (#20)
+- Layered defaults: `llm_default_model`, `llm_default_provider`, `llm_default_intent` (LEX-overridable) (#20)
+- `llm_embed_batch` — batch embedding convenience (#20)
+- `llm_structured` — structured JSON output convenience (#20)
+- `llm_ask` — daemon-first single-shot convenience (#20)
+- `llm_connected?` / `llm_can_embed?` / `llm_routing_enabled?` — status helpers (#20)
+- `llm_cost_estimate` / `llm_cost_summary` / `llm_budget_remaining` — cost and budget helpers (#20)
+- Layered model/provider/intent defaults applied to `llm_chat` and `llm_session` (#20)
+
+### Changed
+- `lib/legion/llm/helpers/llm.rb` is now a backward-compat shim that includes `Legion::LLM::Helper` (#20)
+
 ## [0.5.18] - 2026-03-29
 
 ### Fixed
@@ -43,6 +64,10 @@
 ## [0.5.14] - 2026-03-27
 
 ### Added
+- `CodexConfigLoader`: auto-imports OpenAI bearer token from `~/.codex/auth.json` when `auth_mode` is `chatgpt` and no existing OpenAI API key is configured
+- JWT expiry validation — expired codex tokens are skipped with a debug log
+- Non-JWT tokens (plain API keys) accepted without validation
+- Falls back to vault/settings/env when codex auth file is absent or token is expired
 - `DaemonClient.inference` method for conversation-level routing — accepts a full `messages:` array and optional `tools:`, `model:`, `provider:`, and `timeout:` keyword args, posts to `POST /api/llm/inference`, and returns a structured `{ status: :ok, data: { content:, tool_calls:, stop_reason:, model:, input_tokens:, output_tokens: } }` hash on success
 - `http_post` now accepts an optional `timeout:` keyword argument (default `DEFAULT_TIMEOUT = 60`) so callers like `inference` can pass a longer timeout (120s) without affecting existing `chat` calls
 - `interpret_inference_response` private helper that maps the `/api/llm/inference` HTTP response — 200 returns `:ok` with structured fields, 4xx/5xx follow the same error handling as `interpret_response`

data/lib/legion/llm/codex_config_loader.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require 'base64'
+require 'json'
+
+module Legion
+  module LLM
+    module CodexConfigLoader
+      CODEX_AUTH = File.expand_path('~/.codex/auth.json')
+
+      module_function
+
+      def load
+        return unless File.exist?(CODEX_AUTH)
+
+        config = read_json(CODEX_AUTH)
+        return if config.empty?
+
+        apply_codex_config(config)
+      end
+
+      def read_json(path)
+        ::JSON.parse(File.read(path), symbolize_names: true)
+      rescue StandardError => e
+        Legion::Logging.debug("CodexConfigLoader could not read #{path}: #{e.message}") if defined?(Legion::Logging)
+        {}
+      end
+
+      def apply_codex_config(config)
+        return unless config[:auth_mode] == 'chatgpt'
+
+        token = config.dig(:tokens, :access_token)
+        return unless token.is_a?(String) && !token.empty?
+
+        unless token_valid?(token)
+          Legion::Logging.debug 'CodexConfigLoader: access token is expired, skipping' if defined?(Legion::Logging)
+          return
+        end
+
+        providers = Legion::LLM.settings[:providers]
+        existing_raw = providers.dig(:openai, :api_key)
+        resolved_existing = resolve_env_api_key(existing_raw)
+        return unless resolved_existing.nil? || (resolved_existing.respond_to?(:empty?) && resolved_existing.empty?)
+
+        providers[:openai][:api_key] = token
+        Legion::Logging.debug 'Imported OpenAI API key from Codex auth config' if defined?(Legion::Logging)
+      end
+
+      def resolve_env_api_key(value)
+        return nil if value.nil?
+
+        if value.is_a?(String)
+          return nil if value.empty?
+
+          if value.start_with?('env://')
+            env_name = value.sub('env://', '')
+            env_value = ENV.fetch(env_name, nil)
+            return nil if env_value.nil? || env_value.empty?
+
+            return env_value
+          end
+
+          return value
+        end
+
+        if value.is_a?(Array)
+          resolved = value.map { |v| resolve_env_api_key(v) }.compact
+          return nil if resolved.empty?
+          return resolved.first if resolved.length == 1
+
+          return resolved
+        end
+
+        value
+      end
+
+      def token_valid?(token)
+        parts = token.split('.')
+        return true unless parts.length == 3
+
+        padded = parts[1] + ('=' * ((4 - (parts[1].length % 4)) % 4))
+        payload = ::JSON.parse(Base64.urlsafe_decode64(padded), symbolize_names: true)
+        exp = payload[:exp]
+        return true unless exp.is_a?(Integer)
+
+        exp > Time.now.to_i
+      rescue StandardError => e
+        Legion::Logging.debug("CodexConfigLoader: failed to parse access token for exp validation: #{e.class}: #{e.message}") if defined?(Legion::Logging)
+        true
+      end
+    end
+  end
+end

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.20'
   end
 end

data/lib/legion/llm.rb

@@ -45,6 +45,9 @@ module Legion
         require 'legion/llm/claude_config_loader'
         ClaudeConfigLoader.load
 
+        require 'legion/llm/codex_config_loader'
+        CodexConfigLoader.load
+
         configure_providers
         run_discovery
         detect_embedding_capability

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: legion-llm
 version: !ruby/object:Gem::Version
-  version: 0.5.18
+  version: 0.5.20
 platform: ruby
 authors:
 - Esity
@@ -179,6 +179,7 @@ files:
 - ".github/workflows/ci.yml"
 - ".gitignore"
 - ".rubocop.yml"
+- AGENTS.md
 - CHANGELOG.md
 - CLAUDE.md
 - CODEOWNERS
@@ -213,6 +214,7 @@ files:
 - lib/legion/llm/bedrock_bearer_auth.rb
 - lib/legion/llm/cache.rb
 - lib/legion/llm/claude_config_loader.rb
+- lib/legion/llm/codex_config_loader.rb
 - lib/legion/llm/compressor.rb
 - lib/legion/llm/confidence_score.rb
 - lib/legion/llm/confidence_scorer.rb
@@ -230,6 +232,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