lex-agentic-language 0.1.8 → 0.1.10

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b04c9da9a6fcda5c086ee1e27fd8c2a2007faa556737be3d88219a2e505663ba
-  data.tar.gz: fa94cc1d6fda5c3b9fe38a2e6aa9254ee238a9af4f2f3802aeeb94813e98f352
+  metadata.gz: 2e44972f87bca2dccf617db64c48e8e3b99d2174bb45f1d21cd71a72a2489a59
+  data.tar.gz: 1e9fb62235879f874ef6c2ca07b6f58dc104fcc5fcb3d64591dcdf5d6477484f
 SHA512:
-  metadata.gz: 0b08cdd7dc45ec57422597aa41d7a75a6c375b4f5f70cacc8a6abfcb14e6326528dda67ec4c6392596cfcd19b05fdd0bf244cb8a48b3be3d7d84921e5e38b453
-  data.tar.gz: 59f6320175d8e48918b8d45ff9e3b8ea25796205f5d23703d12a978bd722441f48d1f91253178f237b9cde97aad458478eb06de288f1913489775a9934ea7089
+  metadata.gz: aed85b23f9a856e2a26ac20bfdacd601c0ad09c8394f38bedb8195d28852fab393ee170b29d176109c83d6ab7cc426883270621c0bc629a7cab6244f94d38cc5
+  data.tar.gz: e57dbce2e2254462c9940b57b7dcac4b349e8edb3dad723e4c4d3c06bcc0dc6882cf6a4e52dfdb75bed12fdde5bd755f18c6e447c242fbd5d3fe4dcc42b5917b

data/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## [0.1.10] - 2026-04-27
+### Fixed
+- Narrator LLM enhancement now skips empty idle narration and rate-limits provider failure warnings without warning-level backtrace floods. Fixes #7
+
+## [0.1.9] - 2026-04-22
+### Added
+- InnerSpeech::Actor::DecayInnerSpeech (60s) — first actor in the extension, enables autonomous salience decay
+### Fixed
+- LlmEnhancer `available?` now logs errors at debug level instead of swallowing silently
+- Documented PragmaticInference::Utterance vs InnerSpeech::Utterance schema distinctions
+
 ## [0.1.8] - 2026-04-15
 ### Changed
 - Set `mcp_tools?`, `mcp_tools_deferred?`, and `transport_required?` to `false` — internal cognitive pipeline extension

data/README.md

@@ -1,26 +1,50 @@
 # lex-agentic-language
 
-Domain consolidation gem for language processing and communication. Bundles 9 source extensions into one loadable unit under `Legion::Extensions::Agentic::Language`.
+Domain consolidation gem for language processing and communication. Bundles 9 sub-modules into one loadable unit under `Legion::Extensions::Agentic::Language`.
 
 ## Overview
 
 **Gem**: `lex-agentic-language`
-**Version**: 0.1.8
+**Version**: 0.1.9
 **Namespace**: `Legion::Extensions::Agentic::Language`
 
 ## Sub-Modules
 
-| Sub-Module | Source Gem | Purpose |
-|---|---|---|
-| `Language::Language` | `lex-language` | Core language processing — token parsing, semantic framing, pragmatic intent |
-| `Language::Grammar` | `lex-cognitive-grammar` | Grammatical structure processing |
-| `Language::InnerSpeech` | `lex-inner-speech` | Vygotsky inner speech — private verbal thought for problem solving |
-| `Language::Narrator` | `lex-narrator` | Real-time narrative stream of internal state (optional LLM enhancement) |
-| `Language::NarrativeReasoning` | `lex-narrative-reasoning` | Narrative as a reasoning mode — story-schema activation |
-| `Language::FrameSemantics` | `lex-frame-semantics` | Fillmore frame semantics — conceptual frames, slots, fillers |
-| `Language::PragmaticInference` | `lex-pragmatic-inference` | Gricean maxims and conversational implicature |
-| `Language::ConceptualBlending` | `lex-conceptual-blending` | Fauconnier & Turner — emergent blended structure from two input spaces |
-| `Language::ConceptualMetaphor` | `lex-conceptual-metaphor` | Lakoff & Johnson — structural mappings between conceptual domains |
+| Sub-Module | Purpose |
+|---|---|
+| `Language::Language` | Core language processing — token parsing, semantic framing, pragmatic intent |
+| `Language::Grammar` | Grammatical construction processing (construal, construction, grammar engine) |
+| `Language::InnerSpeech` | Vygotsky inner speech — private verbal thought for problem solving |
+| `Language::Narrator` | Real-time narrative stream of internal state (optional LLM enhancement) |
+| `Language::NarrativeReasoning` | Narrative as a reasoning mode — story-schema activation |
+| `Language::FrameSemantics` | Fillmore frame semantics — conceptual frames, slots, fillers |
+| `Language::PragmaticInference` | Gricean maxims and conversational implicature |
+| `Language::ConceptualBlending` | Fauconnier & Turner — emergent blended structure from two input spaces |
+| `Language::ConceptualMetaphor` | Lakoff & Johnson — structural mappings between conceptual domains |
+
+## Actors
+
+- `Language::InnerSpeech::Actor::DecayInnerSpeech` — every 60s, decays utterance salience in the inner voice stream via `update_inner_speech`
+
+This is the first actor added to this gem. Without it the inner speech stream grows indefinitely.
+
+## Quick Usage
+
+```ruby
+require 'legion/extensions/agentic/language'
+
+# Use the InnerSpeech runner
+include Legion::Extensions::Agentic::Language::InnerSpeech::Runners::InnerSpeech
+
+inner_speak(content: "Should I accept this task?", mode: :questioning, topic: :task_eval)
+# => { success: true, utterance_id: "...", mode: :questioning }
+
+inner_plan(content: "First verify the input, then transform")
+# => { success: true, utterance_id: "..." }
+
+recent_inner_speech(count: 3)
+# => { success: true, utterances: [...], count: 3 }
+```
 
 ## Installation
 
@@ -32,8 +56,8 @@ gem 'lex-agentic-language'
 
 ```bash
 bundle install
-bundle exec rspec        # 735 examples, 0 failures
-bundle exec rubocop      # 0 offenses
+bundle exec rspec
+bundle exec rubocop
 ```
 
 ## License

data/lib/legion/extensions/agentic/language/inner_speech/actors/decay_inner_speech.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/actors/every'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Language
+        module InnerSpeech
+          module Actor
+            # DecayInnerSpeech runs every 60 seconds and ticks the inner voice stream,
+            # decaying the salience of all queued utterances.  Without this actor the
+            # stream would grow indefinitely and old utterances would remain at full
+            # salience, distorting urgency calculations.
+            #
+            # Delegates to Runners::InnerSpeech#update_inner_speech, which calls
+            # InnerVoice#tick → SpeechStream#decay_all.
+            class DecayInnerSpeech < Legion::Extensions::Actors::Every
+              time 60
+
+              def runner_class
+                Legion::Extensions::Agentic::Language::InnerSpeech::Runners::InnerSpeech
+              end
+
+              def runner_function
+                'update_inner_speech'
+              end
+
+              def run_now?
+                false
+              end
+
+              def use_runner?
+                false
+              end
+
+              def check_subtask?
+                false
+              end
+
+              def generate_task?
+                false
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/language/inner_speech/helpers/utterance.rb

@@ -1,5 +1,16 @@
 # frozen_string_literal: true
 
+# InnerSpeech::Helpers::Utterance — represents a single token of inner-voice activity.
+#
+# Key fields: mode (narrating/planning/questioning/…), voice (rational/bold/cautious/…),
+# urgency (0–1), salience (0–1, subject to temporal decay via #decay_salience!).
+# Salience decays over time via the InnerSpeech decay actor (every 60 s), which calls
+# Runners::InnerSpeech#update_inner_speech → InnerVoice#tick → SpeechStream#decay_all.
+#
+# Compare with PragmaticInference::Helpers::Utterance, which models an external
+# communicative act scored against Gricean maxims with implicature accumulation.
+# That class carries NO urgency, salience, or decay logic.
+
 module Legion
   module Extensions
     module Agentic

data/lib/legion/extensions/agentic/language/narrator/helpers/llm_enhancer.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'concurrent/atomic/atomic_reference'
+
 module Legion
   module Extensions
     module Agentic
@@ -13,12 +15,20 @@ module Legion
                 Write 3-5 sentences that feel like genuine introspection, not a report.
                 Vary your sentence structure. Use present tense. Be concise and vivid.
               PROMPT
+              FAILURE_LOG_INTERVAL = 60
+              FAILURE_LOGGED_AT = Concurrent::AtomicReference.new
 
               module_function
 
+              def log
+                Legion::Logging
+              end
+              private_class_method :log
+
               def available?
                 !!(defined?(Legion::LLM) && Legion::LLM.respond_to?(:started?) && Legion::LLM.started?)
-              rescue StandardError => _e
+              rescue StandardError => e
+                log.debug("[narrator:llm] available? check failed: #{e.class}: #{e.message}")
                 false
               end
 
@@ -27,8 +37,7 @@ module Legion
                 response = llm_ask(prompt)
                 parse_narrate_response(response)
               rescue StandardError => e
-                Legion::Logging.warn("[narrator:llm] narrate failed: #{e.message}") # rubocop:disable Legion/HelperMigration/DirectLogging
-                Legion::Logging.warn(e.backtrace) # rubocop:disable Legion/HelperMigration/DirectLogging
+                log_failure(e)
                 nil
               end
 
@@ -57,12 +66,31 @@ module Legion
                   Legion::LLM.respond_to?(:pipeline_enabled?) &&
                   Legion::LLM.pipeline_enabled?)
               rescue StandardError => e
-                Legion::Logging.warn("pipeline_available? #{e.class}: #{e.message}") # rubocop:disable Legion/HelperMigration/DirectLogging
+                log.warn("[narrator:llm] pipeline_available? #{e.class}: #{e.message}")
                 false
               end
 
               private_class_method :pipeline_available?
 
+              def log_failure(error)
+                if log_failure_now?
+                  log.warn("[narrator:llm] narrate failed: #{error.class}: #{error.message}")
+                  FAILURE_LOGGED_AT.set(Time.now.utc)
+                end
+                log.debug(error.backtrace)
+              end
+
+              private_class_method :log_failure
+
+              def log_failure_now?
+                last_logged_at = FAILURE_LOGGED_AT.get
+                return true unless last_logged_at
+
+                (Time.now.utc - last_logged_at) >= FAILURE_LOG_INTERVAL
+              end
+
+              private_class_method :log_failure_now?
+
               def build_narrate_prompt(sections_data)
                 parts = [
                   'Generate a first-person internal monologue based on the following cognitive state:',

data/lib/legion/extensions/agentic/language/narrator/runners/narrator.rb

@@ -13,7 +13,7 @@ module Legion
               def narrate(tick_results: {}, cognitive_state: {}, **)
                 entry = Helpers::Synthesizer.narrate(tick_results: tick_results, cognitive_state: cognitive_state)
 
-                if Helpers::LlmEnhancer.available?
+                if Helpers::LlmEnhancer.available? && meaningful_for_llm?(tick_results, cognitive_state)
                   sections_data = build_llm_sections_data(tick_results, cognitive_state, entry)
                   llm_result = Helpers::LlmEnhancer.narrate(sections_data: sections_data)
                   if llm_result
@@ -103,6 +103,25 @@ module Legion
                 @journal ||= Helpers::Journal.new
               end
 
+              def meaningful_for_llm?(tick_results, cognitive_state)
+                meaningful_hash?(tick_results) || meaningful_hash?(cognitive_state)
+              end
+
+              def meaningful_hash?(value)
+                return false unless value.is_a?(Hash)
+
+                value.any? do |_, nested|
+                  case nested
+                  when Hash
+                    meaningful_hash?(nested)
+                  when Array
+                    nested.any?
+                  else
+                    !nested.nil?
+                  end
+                end
+              end
+
               def build_llm_sections_data(tick_results, cognitive_state, entry)
                 {
                   emotion:    llm_emotion_data(tick_results, cognitive_state),

data/lib/legion/extensions/agentic/language/pragmatic_inference/helpers/utterance.rb

@@ -1,5 +1,15 @@
 # frozen_string_literal: true
 
+# PragmaticInference::Helpers::Utterance — represents a single communicative act
+# evaluated through Gricean maxims (quantity, quality, relation, manner).
+#
+# Key fields: speaker, speech_act, literal_meaning, maxim_scores, implicatures, confidence.
+# Maxim compliance is scored per-maxim and aggregated via #overall_compliance.
+# Violations and implicatures are accumulated after construction via mutation methods.
+#
+# Compare with InnerSpeech::Helpers::Utterance, which models inner-voice tokens
+# (mode, urgency, salience, decay) and carries NO maxim or implicature logic.
+
 require 'securerandom'
 
 module Legion

data/lib/legion/extensions/agentic/language/version.rb

@@ -4,7 +4,7 @@ module Legion
   module Extensions
     module Agentic
       module Language
-        VERSION = '0.1.8'
+        VERSION = '0.1.10'
       end
     end
   end

data/spec/legion/extensions/agentic/language/inner_speech/actors/decay_inner_speech_spec.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+# Stub the base class before loading the actor so the spec can run in isolation
+# without requiring the full Legion framework.
+#
+# The stub must support the `time` DSL accessor used by Every actors: a class-level
+# setter (time 60) and an instance-level reader that delegates to the class method.
+module Legion
+  module Extensions
+    module Actors
+      class Every
+        def self.time(val = :_unset)
+          if val == :_unset
+            @time || 1
+          else
+            @time = val
+          end
+        end
+
+        def time
+          self.class.time
+        end
+      end
+    end
+  end
+end
+
+$LOADED_FEATURES << 'legion/extensions/actors/every'
+
+require_relative '../../../../../../../lib/legion/extensions/agentic/language/inner_speech/actors/decay_inner_speech'
+
+RSpec.describe Legion::Extensions::Agentic::Language::InnerSpeech::Actor::DecayInnerSpeech do
+  subject(:actor) { described_class.new }
+
+  describe '#runner_class' do
+    it do
+      expect(actor.runner_class).to eq(
+        Legion::Extensions::Agentic::Language::InnerSpeech::Runners::InnerSpeech
+      )
+    end
+  end
+
+  describe '#runner_function' do
+    it { expect(actor.runner_function).to eq 'update_inner_speech' }
+  end
+
+  describe '#time' do
+    it { expect(actor.time).to eq 60 }
+  end
+
+  describe '#run_now?' do
+    it { expect(actor.run_now?).to be false }
+  end
+
+  describe '#use_runner?' do
+    it { expect(actor.use_runner?).to be false }
+  end
+
+  describe '#check_subtask?' do
+    it { expect(actor.check_subtask?).to be false }
+  end
+
+  describe '#generate_task?' do
+    it { expect(actor.generate_task?).to be false }
+  end
+end

data/spec/legion/extensions/agentic/language/narrator/helpers/llm_enhancer_spec.rb

@@ -78,16 +78,28 @@ RSpec.describe Legion::Extensions::Agentic::Language::Narrator::Helpers::LlmEnha
     end
 
     context 'when an error occurs' do
-      it 'returns nil and logs a warning' do
+      before { described_class::FAILURE_LOGGED_AT.set(nil) }
+
+      it 'returns nil and logs a concise warning with debug backtrace' do
         llm_double = double('Legion::LLM', started?: true)
         allow(llm_double).to receive(:chat).and_raise(StandardError, 'connection failed')
         stub_const('Legion::LLM', llm_double)
 
-        expect(Legion::Logging).to receive(:warn).with(/narrator:llm.*narrate failed/)
-        expect(Legion::Logging).to receive(:warn).with(instance_of(Array))
+        expect(Legion::Logging).to receive(:warn).with(/narrator:llm.*StandardError: connection failed/)
+        expect(Legion::Logging).to receive(:debug).with(instance_of(Array))
         result = described_class.narrate(sections_data: sections_data)
         expect(result).to be_nil
       end
+
+      it 'throttles repeated failure warnings' do
+        llm_double = double('Legion::LLM', started?: true)
+        allow(llm_double).to receive(:chat).and_raise(StandardError, 'connection failed')
+        stub_const('Legion::LLM', llm_double)
+        allow(Legion::Logging).to receive(:debug)
+
+        expect(Legion::Logging).to receive(:warn).once
+        2.times { described_class.narrate(sections_data: sections_data) }
+      end
     end
 
     context 'with empty sections_data' do

data/spec/legion/extensions/agentic/language/narrator/runners/narrator_llm_spec.rb

@@ -4,9 +4,10 @@ RSpec.describe Legion::Extensions::Agentic::Language::Narrator::Runners::Narrato
   let(:client) { Legion::Extensions::Agentic::Language::Narrator::Client.new }
 
   describe '#narrate with LLM available' do
+    let(:chat_double) { double('chat') }
+
     before do
       response_double = double('response', content: 'I feel a deep sense of focus and possibility.')
-      chat_double = double('chat')
       allow(chat_double).to receive(:with_instructions)
       allow(chat_double).to receive(:ask).and_return(response_double)
       llm_double = double('Legion::LLM', started?: true)
@@ -22,8 +23,8 @@ RSpec.describe Legion::Extensions::Agentic::Language::Narrator::Runners::Narrato
       expect(result[:source]).to eq(:llm)
     end
 
-    it 'returns the LLM narrative string' do
-      result = client.narrate(tick_results: {}, cognitive_state: {})
+    it 'returns the LLM narrative string when there is meaningful cognitive data' do
+      result = client.narrate(tick_results: { emotional_evaluation: { valence: 0.6 } }, cognitive_state: {})
       expect(result[:narrative]).to eq('I feel a deep sense of focus and possibility.')
     end
 
@@ -34,9 +35,18 @@ RSpec.describe Legion::Extensions::Agentic::Language::Narrator::Runners::Narrato
     end
 
     it 'appends to journal' do
-      client.narrate(tick_results: {}, cognitive_state: {})
+      client.narrate(tick_results: { emotional_evaluation: { valence: 0.6 } }, cognitive_state: {})
       expect(client.journal.size).to eq(1)
     end
+
+    it 'uses the mechanical pipeline for empty idle narration' do
+      expect(chat_double).not_to receive(:ask)
+
+      result = client.narrate(tick_results: {}, cognitive_state: {})
+
+      expect(result).not_to have_key(:source)
+      expect(result[:narrative]).to be_a(String)
+    end
   end
 
   describe '#narrate with LLM available but narrate returns nil' do
@@ -50,7 +60,7 @@ RSpec.describe Legion::Extensions::Agentic::Language::Narrator::Runners::Narrato
     end
 
     it 'falls back to mechanical pipeline' do
-      result = client.narrate(tick_results: {}, cognitive_state: {})
+      result = client.narrate(tick_results: { emotional_evaluation: { valence: 0.6 } }, cognitive_state: {})
       expect(result).not_to have_key(:source)
       expect(result[:narrative]).to be_a(String)
     end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lex-agentic-language
 version: !ruby/object:Gem::Version
-  version: 0.1.8
+  version: 0.1.10
 platform: ruby
 authors:
 - Esity
@@ -208,6 +208,7 @@ files:
 - lib/legion/extensions/agentic/language/grammar/runners/cognitive_grammar.rb
 - lib/legion/extensions/agentic/language/grammar/version.rb
 - lib/legion/extensions/agentic/language/inner_speech.rb
+- lib/legion/extensions/agentic/language/inner_speech/actors/decay_inner_speech.rb
 - lib/legion/extensions/agentic/language/inner_speech/client.rb
 - lib/legion/extensions/agentic/language/inner_speech/helpers/constants.rb
 - lib/legion/extensions/agentic/language/inner_speech/helpers/inner_voice.rb
@@ -266,6 +267,7 @@ files:
 - spec/legion/extensions/agentic/language/grammar/helpers/construction_spec.rb
 - spec/legion/extensions/agentic/language/grammar/helpers/grammar_engine_spec.rb
 - spec/legion/extensions/agentic/language/grammar/runners/cognitive_grammar_spec.rb
+- spec/legion/extensions/agentic/language/inner_speech/actors/decay_inner_speech_spec.rb
 - spec/legion/extensions/agentic/language/inner_speech/client_spec.rb
 - spec/legion/extensions/agentic/language/inner_speech/helpers/inner_voice_spec.rb
 - spec/legion/extensions/agentic/language/inner_speech/helpers/speech_stream_spec.rb