lex-agentic-language 0.1.0

data/spec/legion/extensions/agentic/language/language/helpers/lexicon_spec.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Language::Language::Helpers::Lexicon do
+  subject(:lexicon) { described_class.new }
+
+  let(:summary) do
+    {
+      domain:          :networking,
+      knowledge_level: :moderate,
+      trace_count:     7,
+      key_facts:       [{ content: 'fact 1' }]
+    }
+  end
+
+  describe '#store_summary' do
+    it 'stores a summary keyed by domain symbol' do
+      lexicon.store_summary(:networking, summary)
+      expect(lexicon.get_summary(:networking)).to include(domain: :networking)
+    end
+
+    it 'adds a cached_at timestamp' do
+      lexicon.store_summary('networking', summary)
+      stored = lexicon.get_summary(:networking)
+      expect(stored[:cached_at]).to be_a(Time)
+    end
+
+    it 'converts string domain to symbol' do
+      lexicon.store_summary('security', summary)
+      expect(lexicon.get_summary(:security)).not_to be_nil
+    end
+  end
+
+  describe '#get_summary' do
+    it 'returns nil for unknown domain' do
+      expect(lexicon.get_summary(:unknown)).to be_nil
+    end
+
+    it 'returns stored summary' do
+      lexicon.store_summary(:networking, summary)
+      result = lexicon.get_summary(:networking)
+      expect(result[:knowledge_level]).to eq(:moderate)
+    end
+  end
+
+  describe '#known_domains' do
+    it 'returns empty array initially' do
+      expect(lexicon.known_domains).to eq([])
+    end
+
+    it 'returns stored domain keys' do
+      lexicon.store_summary(:networking, summary)
+      lexicon.store_summary(:security, summary)
+      expect(lexicon.known_domains).to contain_exactly(:networking, :security)
+    end
+  end
+
+  describe '#knowledge_map' do
+    it 'returns empty hash initially' do
+      expect(lexicon.knowledge_map).to eq({})
+    end
+
+    it 'returns condensed view of all summaries' do
+      lexicon.store_summary(:networking, summary)
+      map = lexicon.knowledge_map
+      expect(map[:networking]).to include(knowledge_level: :moderate, trace_count: 7)
+      expect(map[:networking]).to have_key(:cached_at)
+    end
+  end
+
+  describe '#stale?' do
+    it 'returns true for unknown domain' do
+      expect(lexicon.stale?(:unknown)).to be true
+    end
+
+    it 'returns false for recently stored summary' do
+      lexicon.store_summary(:networking, summary)
+      expect(lexicon.stale?(:networking)).to be false
+    end
+
+    it 'returns true when max_age exceeded' do
+      lexicon.store_summary(:networking, summary)
+      stored = lexicon.get_summary(:networking)
+      stored[:cached_at] = Time.now.utc - 600
+      expect(lexicon.stale?(:networking, max_age: 300)).to be true
+    end
+  end
+
+  describe '#clear' do
+    before do
+      lexicon.store_summary(:networking, summary)
+      lexicon.store_summary(:security, summary)
+    end
+
+    it 'clears a specific domain' do
+      lexicon.clear(:networking)
+      expect(lexicon.get_summary(:networking)).to be_nil
+      expect(lexicon.get_summary(:security)).not_to be_nil
+    end
+
+    it 'clears all domains when called without argument' do
+      lexicon.clear
+      expect(lexicon.size).to eq(0)
+    end
+  end
+
+  describe '#size' do
+    it 'returns 0 initially' do
+      expect(lexicon.size).to eq(0)
+    end
+
+    it 'reflects stored summary count' do
+      lexicon.store_summary(:networking, summary)
+      expect(lexicon.size).to eq(1)
+    end
+  end
+end

data/spec/legion/extensions/agentic/language/language/helpers/summarizer_spec.rb

@@ -0,0 +1,224 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Language::Language::Helpers::Summarizer do
+  let(:now) { Time.now.utc }
+
+  let(:base_trace) do
+    {
+      trace_id:            'trace-1',
+      trace_type:          :semantic,
+      content_payload:     'Networking uses TCP/IP',
+      strength:            0.7,
+      confidence:          0.8,
+      domain_tags:         [:networking],
+      emotional_valence:   0.2,
+      emotional_intensity: 0.3,
+      last_reinforced:     now,
+      created_at:          now
+    }
+  end
+
+  def make_traces(count, overrides = {})
+    count.times.map do |i|
+      base_trace.merge(trace_id: "trace-#{i}").merge(overrides)
+    end
+  end
+
+  describe '.summarize_domain' do
+    it 'returns empty summary for no traces' do
+      result = described_class.summarize_domain([], domain: :networking)
+      expect(result[:knowledge_level]).to eq(:none)
+      expect(result[:trace_count]).to eq(0)
+      expect(result[:key_facts]).to eq([])
+    end
+
+    it 'summarizes traces into structured result' do
+      traces = make_traces(3)
+      result = described_class.summarize_domain(traces, domain: :networking)
+
+      expect(result[:domain]).to eq(:networking)
+      expect(result[:knowledge_level]).to eq(:sparse)
+      expect(result[:trace_count]).to eq(3)
+      expect(result).to have_key(:type_breakdown)
+      expect(result).to have_key(:key_facts)
+      expect(result).to have_key(:strength_stats)
+      expect(result).to have_key(:emotional_tone)
+      expect(result).to have_key(:freshness)
+    end
+
+    it 'classifies rich knowledge at 10+ traces' do
+      traces = make_traces(12)
+      result = described_class.summarize_domain(traces, domain: :networking)
+      expect(result[:knowledge_level]).to eq(:rich)
+    end
+
+    it 'classifies moderate knowledge at 5-9 traces' do
+      traces = make_traces(7)
+      result = described_class.summarize_domain(traces, domain: :networking)
+      expect(result[:knowledge_level]).to eq(:moderate)
+    end
+
+    it 'classifies sparse knowledge at 1-4 traces' do
+      traces = make_traces(2)
+      result = described_class.summarize_domain(traces, domain: :networking)
+      expect(result[:knowledge_level]).to eq(:sparse)
+    end
+  end
+
+  describe '.group_by_type' do
+    it 'groups traces by trace_type' do
+      traces = [
+        base_trace.merge(trace_type: :firmware),
+        base_trace.merge(trace_type: :semantic),
+        base_trace.merge(trace_type: :firmware)
+      ]
+      grouped = described_class.group_by_type(traces)
+      expect(grouped[:firmware].size).to eq(2)
+      expect(grouped[:semantic].size).to eq(1)
+    end
+
+    it 'orders by TYPE_PRIORITY' do
+      traces = [
+        base_trace.merge(trace_type: :sensory),
+        base_trace.merge(trace_type: :firmware)
+      ]
+      grouped = described_class.group_by_type(traces)
+      expect(grouped.keys.first).to eq(:firmware)
+    end
+  end
+
+  describe '.extract_key_facts' do
+    let(:grouped) do
+      { semantic: make_traces(10) }
+    end
+
+    it 'limits facts by depth :brief' do
+      facts = described_class.extract_key_facts(grouped, depth: :brief)
+      expect(facts.size).to be <= 3
+    end
+
+    it 'limits facts by depth :standard' do
+      facts = described_class.extract_key_facts(grouped, depth: :standard)
+      expect(facts.size).to be <= 7
+    end
+
+    it 'limits facts by depth :detailed' do
+      facts = described_class.extract_key_facts(grouped, depth: :detailed)
+      expect(facts.size).to be <= 15
+    end
+
+    it 'returns structured fact hashes' do
+      facts = described_class.extract_key_facts(grouped)
+      fact = facts.first
+      expect(fact).to include(:trace_id, :type, :content, :strength, :confidence, :domain_tags)
+    end
+  end
+
+  describe '.extract_content_text' do
+    it 'handles String payload' do
+      expect(described_class.extract_content_text('hello')).to eq('hello')
+    end
+
+    it 'handles Hash with :text key' do
+      expect(described_class.extract_content_text({ text: 'hello' })).to eq('hello')
+    end
+
+    it 'handles Hash with :content key' do
+      expect(described_class.extract_content_text({ content: 'world' })).to eq('world')
+    end
+
+    it 'handles Hash with :summary key' do
+      expect(described_class.extract_content_text({ summary: 'sum' })).to eq('sum')
+    end
+
+    it 'handles Array payload' do
+      expect(described_class.extract_content_text(%w[first second])).to eq('first')
+    end
+
+    it 'converts other types to string' do
+      expect(described_class.extract_content_text(42)).to eq('42')
+    end
+  end
+
+  describe '.strength_stats' do
+    it 'computes mean, max, min, strong, weak counts' do
+      traces = [
+        base_trace.merge(strength: 0.8),
+        base_trace.merge(strength: 0.2),
+        base_trace.merge(strength: 0.5)
+      ]
+      stats = described_class.strength_stats(traces)
+      expect(stats[:mean]).to eq(0.5)
+      expect(stats[:max]).to eq(0.8)
+      expect(stats[:min]).to eq(0.2)
+      expect(stats[:strong]).to eq(2) # 0.8 and 0.5
+      expect(stats[:weak]).to eq(1)   # 0.2
+    end
+  end
+
+  describe '.emotional_tone' do
+    it 'computes average valence and intensity' do
+      traces = [
+        base_trace.merge(emotional_valence: 0.5, emotional_intensity: 0.6),
+        base_trace.merge(emotional_valence: 0.3, emotional_intensity: 0.4)
+      ]
+      tone = described_class.emotional_tone(traces)
+      expect(tone[:avg_valence]).to eq(0.4)
+      expect(tone[:avg_intensity]).to eq(0.5)
+    end
+
+    it 'classifies neutral tone for low intensity' do
+      traces = [base_trace.merge(emotional_valence: 0.5, emotional_intensity: 0.1)]
+      tone = described_class.emotional_tone(traces)
+      expect(tone[:tone]).to eq(:neutral)
+    end
+
+    it 'classifies positive tone for high valence' do
+      traces = [base_trace.merge(emotional_valence: 0.5, emotional_intensity: 0.5)]
+      tone = described_class.emotional_tone(traces)
+      expect(tone[:tone]).to eq(:positive)
+    end
+
+    it 'classifies negative tone for low valence' do
+      traces = [base_trace.merge(emotional_valence: -0.5, emotional_intensity: 0.5)]
+      tone = described_class.emotional_tone(traces)
+      expect(tone[:tone]).to eq(:negative)
+    end
+
+    it 'classifies mixed tone for moderate valence' do
+      traces = [base_trace.merge(emotional_valence: 0.0, emotional_intensity: 0.5)]
+      tone = described_class.emotional_tone(traces)
+      expect(tone[:tone]).to eq(:mixed)
+    end
+  end
+
+  describe '.freshness_assessment' do
+    it 'classifies very_fresh traces' do
+      traces = [base_trace.merge(last_reinforced: Time.now.utc)]
+      result = described_class.freshness_assessment(traces)
+      expect(result[:label]).to eq(:very_fresh)
+    end
+
+    it 'classifies stale traces' do
+      traces = [base_trace.merge(last_reinforced: Time.now.utc - 100_000)]
+      result = described_class.freshness_assessment(traces)
+      expect(result[:label]).to eq(:stale)
+    end
+
+    it 'returns avg_age_seconds, freshest, stalest' do
+      result = described_class.freshness_assessment([base_trace])
+      expect(result).to have_key(:avg_age_seconds)
+      expect(result).to have_key(:freshest)
+      expect(result).to have_key(:stalest)
+    end
+  end
+
+  describe '.empty_summary' do
+    it 'returns zeroed-out summary for domain' do
+      result = described_class.empty_summary(:networking)
+      expect(result[:domain]).to eq(:networking)
+      expect(result[:knowledge_level]).to eq(:none)
+      expect(result[:trace_count]).to eq(0)
+    end
+  end
+end

data/spec/legion/extensions/agentic/language/language/runners/language_spec.rb

@@ -0,0 +1,169 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Language::Language::Runners::Language do
+  let(:lexicon) { Legion::Extensions::Agentic::Language::Language::Helpers::Lexicon.new }
+  let(:client) { Legion::Extensions::Agentic::Language::Language::Client.new(lexicon: lexicon) }
+
+  let(:now) { Time.now.utc }
+  let(:base_trace) do
+    {
+      trace_id:            'trace-1',
+      trace_type:          :semantic,
+      content_payload:     'Networking uses TCP/IP',
+      strength:            0.7,
+      confidence:          0.8,
+      domain_tags:         [:networking],
+      emotional_valence:   0.2,
+      emotional_intensity: 0.3,
+      last_reinforced:     now,
+      created_at:          now
+    }
+  end
+
+  def make_traces(count, domain: :networking)
+    count.times.map do |i|
+      base_trace.merge(
+        trace_id:    "trace-#{i}",
+        domain_tags: [domain],
+        strength:    0.3 + (rand * 0.5)
+      )
+    end
+  end
+
+  describe '#summarize' do
+    it 'returns a summary hash for the domain' do
+      traces = make_traces(5)
+      result = client.summarize(domain: :networking, traces: traces)
+      expect(result[:domain]).to eq(:networking)
+      expect(result[:knowledge_level]).to eq(:moderate)
+    end
+
+    it 'stores the summary in the lexicon' do
+      traces = make_traces(5)
+      client.summarize(domain: :networking, traces: traces)
+      expect(lexicon.get_summary(:networking)).not_to be_nil
+    end
+
+    it 'filters traces by domain' do
+      traces = make_traces(5, domain: :networking) + make_traces(3, domain: :security)
+      result = client.summarize(domain: :networking, traces: traces)
+      expect(result[:trace_count]).to eq(5)
+    end
+
+    it 'respects minimum strength threshold' do
+      weak_traces = make_traces(3).map { |t| t.merge(strength: 0.05) }
+      strong_traces = make_traces(2)
+      result = client.summarize(domain: :networking, traces: weak_traces + strong_traces)
+      expect(result[:trace_count]).to eq(2)
+    end
+
+    it 'accepts string domain and converts to symbol' do
+      traces = make_traces(3)
+      result = client.summarize(domain: 'networking', traces: traces)
+      expect(result[:domain]).to eq(:networking)
+    end
+  end
+
+  describe '#what_do_i_know' do
+    it 'returns structured knowledge with prose' do
+      traces = make_traces(5)
+      result = client.what_do_i_know(domain: :networking, traces: traces)
+      expect(result[:domain]).to eq(:networking)
+      expect(result[:knowledge_level]).to be_a(Symbol)
+      expect(result[:prose]).to be_a(String)
+      expect(result[:fact_count]).to be >= 0
+      expect(result).to have_key(:summary)
+    end
+
+    it 'uses cached summary when not stale' do
+      traces = make_traces(5)
+      client.summarize(domain: :networking, traces: traces)
+
+      result = client.what_do_i_know(domain: :networking, traces: [])
+      expect(result[:knowledge_level]).to eq(:moderate)
+    end
+
+    it 're-summarizes when cache is stale' do
+      traces = make_traces(5)
+      client.summarize(domain: :networking, traces: traces)
+
+      stored = lexicon.get_summary(:networking)
+      stored[:cached_at] = Time.now.utc - 600
+
+      new_traces = make_traces(12)
+      result = client.what_do_i_know(domain: :networking, traces: new_traces)
+      expect(result[:knowledge_level]).to eq(:rich)
+    end
+
+    it 'includes key facts in prose when available' do
+      traces = make_traces(5)
+      result = client.what_do_i_know(domain: :networking, traces: traces)
+      expect(result[:prose]).to include('Key facts')
+    end
+
+    it 'handles no-facts prose' do
+      result = client.what_do_i_know(domain: :empty, traces: [])
+      expect(result[:prose]).to include('No specific facts')
+    end
+  end
+
+  describe '#can_answer_wonder?' do
+    it 'returns answerable when enough traces exist' do
+      traces = make_traces(5)
+      result = client.can_answer_wonder?(wonder: { domain: :networking }, traces: traces)
+      expect(result[:answerable]).to be true
+      expect(result[:confidence]).to be > 0.0
+    end
+
+    it 'returns not answerable when traces below threshold' do
+      traces = make_traces(2)
+      result = client.can_answer_wonder?(wonder: { domain: :networking }, traces: traces)
+      expect(result[:answerable]).to be false
+      expect(result[:confidence]).to eq(0.0)
+    end
+
+    it 'extracts domain from wonder hash' do
+      traces = make_traces(5, domain: :security)
+      result = client.can_answer_wonder?(wonder: { domain: :security }, traces: traces)
+      expect(result[:domain]).to eq(:security)
+    end
+
+    it 'defaults to :general when wonder is not a hash' do
+      result = client.can_answer_wonder?(wonder: 'what is life?', traces: [])
+      expect(result[:domain]).to eq(:general)
+    end
+
+    it 'includes trace_count and threshold' do
+      traces = make_traces(4)
+      result = client.can_answer_wonder?(wonder: { domain: :networking }, traces: traces)
+      expect(result[:trace_count]).to eq(4)
+      expect(result[:threshold]).to eq(3)
+    end
+  end
+
+  describe '#knowledge_map' do
+    it 'returns domains, known_domains, and total_domains' do
+      traces = make_traces(5)
+      client.summarize(domain: :networking, traces: traces)
+      result = client.knowledge_map
+      expect(result[:known_domains]).to include(:networking)
+      expect(result[:total_domains]).to eq(1)
+      expect(result[:domains]).to have_key(:networking)
+    end
+
+    it 'returns empty map with no summaries' do
+      result = client.knowledge_map
+      expect(result[:total_domains]).to eq(0)
+      expect(result[:known_domains]).to eq([])
+    end
+  end
+
+  describe '#language_stats' do
+    it 'returns cached_domains, known_domains, knowledge_map' do
+      result = client.language_stats
+      expect(result).to have_key(:cached_domains)
+      expect(result).to have_key(:known_domains)
+      expect(result).to have_key(:knowledge_map)
+    end
+  end
+end

data/spec/legion/extensions/agentic/language/narrative_reasoning/client_spec.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/agentic/language/narrative_reasoning/client'
+
+RSpec.describe Legion::Extensions::Agentic::Language::NarrativeReasoning::Client do
+  it 'responds to all runner methods' do
+    client = described_class.new
+    expect(client).to respond_to(:create_narrative)
+    expect(client).to respond_to(:add_narrative_event)
+    expect(client).to respond_to(:add_narrative_theme)
+    expect(client).to respond_to(:advance_narrative_arc)
+    expect(client).to respond_to(:trace_narrative_causes)
+    expect(client).to respond_to(:complete_narratives)
+    expect(client).to respond_to(:domain_narratives)
+    expect(client).to respond_to(:most_coherent_narratives)
+    expect(client).to respond_to(:update_narrative_reasoning)
+    expect(client).to respond_to(:narrative_reasoning_stats)
+  end
+end