lex-language 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 38927cf1b9e51ee052d7d3760a10e7030ba57e08658776dc955669fb7efcbc87
+  data.tar.gz: 615a29cdd55c75591edc3b3ce62ee3cb9bacefbed3a2c064ddbcdb5413e75914
+SHA512:
+  metadata.gz: de1666f187f15312b478e0df40edfdbe916810abfb75bd5c1af8e96c6512910a1ca70ee47dfc1a128e52cccffcc8c9e1ad4ac4024c3fc6c73e7db13816e32312
+  data.tar.gz: 14182d7c1c7d1a615bf88cb1394e2a018c18d0f9b2cfa8e176f506c04798a3ac634f74668f0a4391cf133f4b81f51f6a948037a4067cbb7660d82977191603c5

data/Gemfile

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gemspec
+
+group :development, :test do
+  gem 'rake', '~> 13.0'
+  gem 'rspec', '~> 3.0'
+  gem 'rubocop', '~> 1.21'
+  gem 'rubocop-rspec', require: false
+  gem 'simplecov', require: false
+end
+
+gem 'legion-gaia', path: '../../legion-gaia'

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 LegionIO
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,74 @@
+# lex-language
+
+Symbolic-to-linguistic grounding for LegionIO agents. Part of the LegionIO cognitive architecture extension ecosystem (LEX).
+
+## What It Does
+
+`lex-language` bridges raw memory traces and meaningful knowledge expression. Given a set of memory traces for a domain, it aggregates them by type priority, extracts key facts at configurable depth, assesses knowledge level, and returns a structured summary or prose narrative. A TTL-based lexicon cache avoids reprocessing unchanged trace sets. Also determines whether the agent's knowledge is sufficient to answer specific queries.
+
+Key capabilities:
+
+- **Domain summarization**: brief (3 facts), standard (7 facts), detailed (all traces above minimum strength)
+- **Knowledge assessment**: rich (>=10 traces), moderate (>=5), sparse (<5)
+- **Wonder resolution**: checks if a query domain has enough traces to answer
+- **Lexicon cache**: 5-minute TTL per domain to avoid repeated processing
+- **Knowledge map**: snapshot of all cached domain summaries
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem 'lex-language'
+```
+
+Or install directly:
+
+```
+gem install lex-language
+```
+
+## Usage
+
+```ruby
+require 'legion/extensions/language'
+
+# Fetch traces from lex-memory first, then summarize
+client = Legion::Extensions::Language::Client.new
+
+summary = client.summarize(domain: :networking, traces: traces, depth: :standard)
+# => { domain: :networking, trace_count: 12, knowledge_level: :rich,
+#      key_facts: ['...', '...', ...], strength_stats: { min: 0.3, max: 0.9, avg: 0.65 } }
+
+# Assess knowledge in a domain
+knowledge = client.what_do_i_know(domain: :networking, traces: traces)
+
+# Check if a wonder can be answered
+result = client.can_answer_wonder?(wonder: { domain: :networking }, traces: traces)
+# => { can_answer: true, trace_count: 12, threshold: 3 }
+
+# View all cached knowledge
+map = client.knowledge_map
+```
+
+## Runner Methods
+
+| Method | Description |
+|---|---|
+| `summarize` | Summarize domain traces at specified depth (brief/standard/detailed) |
+| `what_do_i_know` | Detailed knowledge assessment for a domain |
+| `can_answer_wonder?` | Check if trace count meets the resolution threshold |
+| `knowledge_map` | All cached domain summaries |
+| `language_stats` | Cached domain count, total traces processed |
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
+## License
+
+MIT

data/lex-language.gemspec

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative 'lib/legion/extensions/language/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'lex-language'
+  spec.version       = Legion::Extensions::Language::VERSION
+  spec.authors       = ['Esity']
+  spec.email         = ['matthewdiverson@gmail.com']
+
+  spec.summary       = 'LEX Language'
+  spec.description   = 'Symbolic-to-linguistic grounding layer for brain-modeled agentic AI'
+  spec.homepage      = 'https://github.com/LegionIO/lex-language'
+  spec.license       = 'MIT'
+  spec.required_ruby_version = '>= 3.4'
+
+  spec.metadata['homepage_uri'] = spec.homepage
+  spec.metadata['source_code_uri'] = 'https://github.com/LegionIO/lex-language'
+  spec.metadata['documentation_uri'] = 'https://github.com/LegionIO/lex-language'
+  spec.metadata['changelog_uri'] = 'https://github.com/LegionIO/lex-language'
+  spec.metadata['bug_tracker_uri'] = 'https://github.com/LegionIO/lex-language/issues'
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    Dir.glob('{lib,spec}/**/*') + %w[lex-language.gemspec Gemfile LICENSE README.md]
+  end
+  spec.require_paths = ['lib']
+  spec.add_development_dependency 'legion-gaia'
+end

data/lib/legion/extensions/language/client.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/language/helpers/constants'
+require 'legion/extensions/language/helpers/summarizer'
+require 'legion/extensions/language/helpers/lexicon'
+require 'legion/extensions/language/runners/language'
+
+module Legion
+  module Extensions
+    module Language
+      class Client
+        include Runners::Language
+
+        attr_reader :lexicon
+
+        def initialize(lexicon: nil, **)
+          @lexicon = lexicon || Helpers::Lexicon.new
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/language/helpers/constants.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Language
+      module Helpers
+        module Constants
+          # Maximum traces to consider in a single summarization
+          MAX_TRACES_PER_SUMMARY = 50
+
+          # Minimum strength threshold for including a trace in a summary
+          MIN_SUMMARY_STRENGTH = 0.1
+
+          # Summary depth levels
+          DEPTHS = %i[brief standard detailed].freeze
+
+          # Trace type priority for summary ordering
+          TYPE_PRIORITY = {
+            firmware:   0,
+            identity:   1,
+            procedural: 2,
+            semantic:   3,
+            trust:      4,
+            episodic:   5,
+            sensory:    6
+          }.freeze
+
+          # Knowledge quality thresholds
+          KNOWLEDGE_RICH     = 10  # traces for "rich knowledge"
+          KNOWLEDGE_MODERATE = 5   # traces for "moderate knowledge"
+          KNOWLEDGE_SPARSE   = 1   # traces for "sparse knowledge"
+
+          # Wonder resolution: minimum traces to consider a domain "known"
+          RESOLUTION_THRESHOLD = 3
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/language/helpers/lexicon.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Language
+      module Helpers
+        class Lexicon
+          attr_reader :domain_summaries
+
+          def initialize
+            @domain_summaries = {}
+          end
+
+          def store_summary(domain, summary)
+            domain = domain.to_sym
+            @domain_summaries[domain] = summary.merge(cached_at: Time.now.utc)
+          end
+
+          def get_summary(domain)
+            @domain_summaries[domain.to_sym]
+          end
+
+          def known_domains
+            @domain_summaries.keys
+          end
+
+          def knowledge_map
+            @domain_summaries.transform_values do |summary|
+              {
+                knowledge_level: summary[:knowledge_level],
+                trace_count:     summary[:trace_count],
+                cached_at:       summary[:cached_at]
+              }
+            end
+          end
+
+          def stale?(domain, max_age: 300)
+            summary = get_summary(domain)
+            return true unless summary
+
+            (Time.now.utc - summary[:cached_at]) > max_age
+          end
+
+          def clear(domain = nil)
+            if domain
+              @domain_summaries.delete(domain.to_sym)
+            else
+              @domain_summaries.clear
+            end
+          end
+
+          def size
+            @domain_summaries.size
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/language/helpers/summarizer.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Language
+      module Helpers
+        module Summarizer
+          module_function
+
+          def summarize_domain(traces, domain:, depth: :standard)
+            return empty_summary(domain) if traces.empty?
+
+            grouped = group_by_type(traces)
+            knowledge_level = classify_knowledge(traces.size)
+
+            {
+              domain:          domain,
+              knowledge_level: knowledge_level,
+              trace_count:     traces.size,
+              type_breakdown:  type_breakdown(grouped),
+              key_facts:       extract_key_facts(grouped, depth: depth),
+              strength_stats:  strength_stats(traces),
+              emotional_tone:  emotional_tone(traces),
+              freshness:       freshness_assessment(traces)
+            }
+          end
+
+          def group_by_type(traces)
+            grouped = traces.group_by { |t| t[:trace_type] || :unknown }
+            grouped.sort_by { |type, _| Constants::TYPE_PRIORITY[type] || 99 }.to_h
+          end
+
+          def type_breakdown(grouped)
+            grouped.transform_values(&:size)
+          end
+
+          def extract_key_facts(grouped, depth: :standard)
+            limit = case depth
+                    when :brief    then 3
+                    when :detailed then 15
+                    else 7
+                    end
+
+            facts = []
+            grouped.each do |type, traces|
+              sorted = traces.sort_by { |t| -(t[:strength] || 0) }
+              count = [sorted.size, limit_per_type(type, limit)].min
+              sorted.first(count).each do |trace|
+                facts << format_fact(trace, type)
+              end
+            end
+
+            facts.first(limit)
+          end
+
+          def format_fact(trace, type)
+            content = extract_content_text(trace[:content_payload])
+            {
+              trace_id:    trace[:trace_id],
+              type:        type,
+              content:     content,
+              strength:    (trace[:strength] || 0).round(3),
+              confidence:  (trace[:confidence] || 0.5).round(3),
+              domain_tags: trace[:domain_tags] || []
+            }
+          end
+
+          def extract_content_text(payload)
+            case payload
+            when String then payload
+            when Hash   then payload[:text] || payload[:content] || payload[:summary] || payload.to_s
+            when Array  then payload.first.to_s
+            else payload.to_s
+            end
+          end
+
+          def classify_knowledge(count)
+            if count >= Constants::KNOWLEDGE_RICH then :rich
+            elsif count >= Constants::KNOWLEDGE_MODERATE then :moderate
+            elsif count >= Constants::KNOWLEDGE_SPARSE   then :sparse
+            else :none
+            end
+          end
+
+          def strength_stats(traces)
+            strengths = traces.map { |t| t[:strength] || 0 }
+            {
+              mean:   (strengths.sum / strengths.size).round(3),
+              max:    strengths.max.round(3),
+              min:    strengths.min.round(3),
+              strong: strengths.count { |s| s >= 0.5 },
+              weak:   strengths.count { |s| s < 0.3 }
+            }
+          end
+
+          def emotional_tone(traces)
+            valences = traces.map { |t| t[:emotional_valence] || 0.0 }
+            intensities = traces.map { |t| t[:emotional_intensity] || 0.0 }
+
+            avg_valence = valences.sum / valences.size
+            avg_intensity = intensities.sum / intensities.size
+
+            {
+              avg_valence:   avg_valence.round(3),
+              avg_intensity: avg_intensity.round(3),
+              tone:          tone_label(avg_valence, avg_intensity)
+            }
+          end
+
+          def tone_label(valence, intensity)
+            if intensity < 0.2      then :neutral
+            elsif valence > 0.3     then :positive
+            elsif valence < -0.3    then :negative
+            else :mixed
+            end
+          end
+
+          def freshness_assessment(traces)
+            now = Time.now.utc
+            ages = traces.map { |t| now - (t[:last_reinforced] || t[:created_at] || now) }
+            avg_age = ages.sum / ages.size
+
+            {
+              avg_age_seconds: avg_age.round(1),
+              freshest:        ages.min.round(1),
+              stalest:         ages.max.round(1),
+              label:           freshness_label(avg_age)
+            }
+          end
+
+          def freshness_label(avg_age)
+            if avg_age < 60       then :very_fresh
+            elsif avg_age < 3600  then :fresh
+            elsif avg_age < 86_400 then :aging
+            else :stale
+            end
+          end
+
+          def empty_summary(domain)
+            {
+              domain:          domain,
+              knowledge_level: :none,
+              trace_count:     0,
+              type_breakdown:  {},
+              key_facts:       [],
+              strength_stats:  { mean: 0.0, max: 0.0, min: 0.0, strong: 0, weak: 0 },
+              emotional_tone:  { avg_valence: 0.0, avg_intensity: 0.0, tone: :neutral },
+              freshness:       { avg_age_seconds: 0.0, freshest: 0.0, stalest: 0.0, label: :stale }
+            }
+          end
+
+          def limit_per_type(type, total_limit)
+            case type
+            when :firmware, :identity then [total_limit, 3].min
+            when :procedural          then [total_limit, 2].min
+            else [total_limit, 5].min
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Language
+      module Runners
+        module Language
+          include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                      Legion::Extensions::Helpers.const_defined?(:Lex)
+
+          def summarize(domain:, depth: :standard, traces: [], **)
+            traces = filter_traces(traces, domain)
+            summary = Helpers::Summarizer.summarize_domain(traces, domain: domain.to_sym, depth: depth.to_sym)
+            lexicon.store_summary(domain, summary)
+
+            Legion::Logging.debug "[language] summarize domain=#{domain} traces=#{traces.size} " \
+                                  "knowledge=#{summary[:knowledge_level]}"
+            summary
+          end
+
+          def what_do_i_know(domain:, depth: :standard, traces: [], **)
+            summary = if lexicon.stale?(domain)
+                        summarize(domain: domain, depth: depth, traces: traces)
+                      else
+                        lexicon.get_summary(domain)
+                      end
+
+            prose = generate_knowledge_prose(summary)
+
+            {
+              domain:          domain.to_sym,
+              knowledge_level: summary[:knowledge_level],
+              prose:           prose,
+              fact_count:      summary[:key_facts]&.size || 0,
+              summary:         summary
+            }
+          end
+
+          def can_answer_wonder?(wonder:, traces: [], **)
+            domain = wonder.is_a?(Hash) ? wonder[:domain] : :general
+            relevant = filter_traces(traces, domain)
+
+            answerable = relevant.size >= Helpers::Constants::RESOLUTION_THRESHOLD
+            confidence = answerable ? compute_answer_confidence(relevant) : 0.0
+
+            {
+              answerable:  answerable,
+              confidence:  confidence.round(3),
+              domain:      domain,
+              trace_count: relevant.size,
+              threshold:   Helpers::Constants::RESOLUTION_THRESHOLD
+            }
+          end
+
+          def knowledge_map(**)
+            {
+              domains:       lexicon.knowledge_map,
+              known_domains: lexicon.known_domains,
+              total_domains: lexicon.size
+            }
+          end
+
+          def language_stats(**)
+            {
+              cached_domains: lexicon.size,
+              known_domains:  lexicon.known_domains,
+              knowledge_map:  lexicon.knowledge_map
+            }
+          end
+
+          private
+
+          def lexicon
+            @lexicon ||= Helpers::Lexicon.new
+          end
+
+          def filter_traces(traces, domain)
+            return [] unless traces.is_a?(Array)
+
+            domain_sym = domain.to_sym
+            domain_str = domain.to_s
+
+            matching = traces.select do |t|
+              tags = t[:domain_tags] || []
+              tags.any? { |tag| tag.to_s == domain_str || tag.to_sym == domain_sym }
+            end
+
+            matching
+              .select { |t| (t[:strength] || 0) >= Helpers::Constants::MIN_SUMMARY_STRENGTH }
+              .sort_by { |t| -(t[:strength] || 0) }
+              .first(Helpers::Constants::MAX_TRACES_PER_SUMMARY)
+          end
+
+          def generate_knowledge_prose(summary)
+            domain = summary[:domain]
+            level = summary[:knowledge_level]
+            count = summary[:trace_count]
+            facts = summary[:key_facts] || []
+
+            base = "About #{domain}: I have #{level} knowledge (#{count} traces)."
+
+            if facts.empty?
+              "#{base} No specific facts available."
+            else
+              fact_lines = facts.first(5).map { |f| "- #{truncate(f[:content], 120)}" }
+              "#{base}\nKey facts:\n#{fact_lines.join("\n")}"
+            end
+          end
+
+          def compute_answer_confidence(traces)
+            return 0.0 if traces.empty?
+
+            strengths = traces.map { |t| t[:strength] || 0.0 }
+            confidences = traces.map { |t| t[:confidence] || 0.5 }
+
+            avg_strength = strengths.sum / strengths.size
+            avg_confidence = confidences.sum / confidences.size
+
+            ((avg_strength * 0.5) + (avg_confidence * 0.5)).clamp(0.0, 1.0)
+          end
+
+          def truncate(text, max_length)
+            text = text.to_s
+            text.length > max_length ? "#{text[0...max_length]}..." : text
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Language
+      VERSION = '0.1.0'
+    end
+  end
+end

data/lib/legion/extensions/language.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/language/version'
+require 'legion/extensions/language/helpers/constants'
+require 'legion/extensions/language/helpers/summarizer'
+require 'legion/extensions/language/helpers/lexicon'
+require 'legion/extensions/language/runners/language'
+require 'legion/extensions/language/client'
+
+module Legion
+  module Extensions
+    module Language
+      extend Legion::Extensions::Core if Legion::Extensions.const_defined? :Core
+    end
+  end
+end

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

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Language::Client do
+  describe '#initialize' do
+    it 'creates a default lexicon' do
+      client = described_class.new
+      expect(client.lexicon).to be_a(Legion::Extensions::Language::Helpers::Lexicon)
+    end
+
+    it 'accepts an injected lexicon' do
+      lexicon = Legion::Extensions::Language::Helpers::Lexicon.new
+      client = described_class.new(lexicon: lexicon)
+      expect(client.lexicon).to equal(lexicon)
+    end
+  end
+
+  it 'includes Runners::Language' do
+    expect(described_class.ancestors).to include(Legion::Extensions::Language::Runners::Language)
+  end
+end

data/spec/legion/extensions/language/helpers/constants_spec.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Language::Helpers::Constants do
+  it 'defines MAX_TRACES_PER_SUMMARY' do
+    expect(described_class::MAX_TRACES_PER_SUMMARY).to eq(50)
+  end
+
+  it 'defines MIN_SUMMARY_STRENGTH' do
+    expect(described_class::MIN_SUMMARY_STRENGTH).to eq(0.1)
+  end
+
+  it 'defines DEPTHS as frozen array of symbols' do
+    expect(described_class::DEPTHS).to eq(%i[brief standard detailed])
+    expect(described_class::DEPTHS).to be_frozen
+  end
+
+  it 'defines TYPE_PRIORITY as frozen hash' do
+    expect(described_class::TYPE_PRIORITY).to include(firmware: 0, sensory: 6)
+    expect(described_class::TYPE_PRIORITY).to be_frozen
+  end
+
+  it 'defines knowledge thresholds' do
+    expect(described_class::KNOWLEDGE_RICH).to eq(10)
+    expect(described_class::KNOWLEDGE_MODERATE).to eq(5)
+    expect(described_class::KNOWLEDGE_SPARSE).to eq(1)
+  end
+
+  it 'defines RESOLUTION_THRESHOLD' do
+    expect(described_class::RESOLUTION_THRESHOLD).to eq(3)
+  end
+end

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

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::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/language/helpers/summarizer_spec.rb

@@ -0,0 +1,224 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::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/language/runners/language_spec.rb

@@ -0,0 +1,169 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Language::Runners::Language do
+  let(:lexicon) { Legion::Extensions::Language::Helpers::Lexicon.new }
+  let(:client) { Legion::Extensions::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/spec_helper.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require 'bundler/setup'
+
+module Legion
+  module Logging
+    def self.debug(_msg); end
+    def self.info(_msg); end
+    def self.warn(_msg); end
+    def self.error(_msg); end
+  end
+end
+
+require 'legion/extensions/language'
+
+RSpec.configure do |config|
+  config.example_status_persistence_file_path = '.rspec_status'
+  config.disable_monkey_patching!
+  config.expect_with(:rspec) { |c| c.syntax = :expect }
+end

metadata

@@ -0,0 +1,77 @@
+--- !ruby/object:Gem::Specification
+name: lex-language
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Esity
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: legion-gaia
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Symbolic-to-linguistic grounding layer for brain-modeled agentic AI
+email:
+- matthewdiverson@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- Gemfile
+- LICENSE
+- README.md
+- lex-language.gemspec
+- lib/legion/extensions/language.rb
+- lib/legion/extensions/language/client.rb
+- lib/legion/extensions/language/helpers/constants.rb
+- lib/legion/extensions/language/helpers/lexicon.rb
+- lib/legion/extensions/language/helpers/summarizer.rb
+- lib/legion/extensions/language/runners/language.rb
+- lib/legion/extensions/language/version.rb
+- spec/legion/extensions/language/client_spec.rb
+- spec/legion/extensions/language/helpers/constants_spec.rb
+- spec/legion/extensions/language/helpers/lexicon_spec.rb
+- spec/legion/extensions/language/helpers/summarizer_spec.rb
+- spec/legion/extensions/language/runners/language_spec.rb
+- spec/spec_helper.rb
+homepage: https://github.com/LegionIO/lex-language
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/LegionIO/lex-language
+  source_code_uri: https://github.com/LegionIO/lex-language
+  documentation_uri: https://github.com/LegionIO/lex-language
+  changelog_uri: https://github.com/LegionIO/lex-language
+  bug_tracker_uri: https://github.com/LegionIO/lex-language/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.4'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: LEX Language
+test_files: []