lex-curiosity 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 623f3def5e2ab5884f76c5ec7c2b4b07e64b24c7b689d4e53bb1f3f08dff70f1
+  data.tar.gz: 4b13a988bf90bbee281996ccf907684d75f171a4efc2457e72aef519df6078d2
+SHA512:
+  metadata.gz: fa60920e8f1415c0983b9630b0f7ce6b8839666ace8dcf03cf12eecacaed9ffeb8aa6dcdc6e8d353c9af08327ac9e5c41e4d9867d12d84725071c8f0ea570e91
+  data.tar.gz: 409581811ece58563bd7253c0c9aa341034f9557563d4256b7db4885db8a2565b3ff770daca46cfe69dc658c55420aa63cf9275c872db9461ef1f8da931562aa

data/Gemfile

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

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Esity
+
+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,75 @@
+# lex-curiosity
+
+Intrinsic curiosity engine for the LegionIO brain-modeled cognitive architecture.
+
+## What It Does
+
+Models the dopaminergic curiosity/reward system — the intrinsic motivation to explore knowledge gaps. The agent doesn't just process information when presented; it actively wonders about what it doesn't know and seeks to learn.
+
+Two forms of curiosity:
+- **Diversive curiosity**: general scanning for novelty (high-novelty, low-familiarity signals)
+- **Specific curiosity**: focused pursuit of a particular knowledge gap (low-confidence predictions, contradictions)
+
+## Core Concept: The Wonder
+
+A "wonder" is a structured curiosity item — a question the agent has generated about a gap in its knowledge.
+
+```ruby
+client = Legion::Extensions::Curiosity::Client.new
+
+# Detect gaps from tick phase results
+result = client.detect_gaps(prior_results: {
+  memory_retrieval: { traces: [], domain: :kubernetes },
+  prediction_engine: { confidence: 0.3, domain: :vault }
+})
+# => { gaps_detected: 2, wonders_created: 2, curiosity_intensity: 0.15, ... }
+
+# Manually generate a wonder
+wonder = client.generate_wonder(
+  question: 'How does Consul ACL token inheritance work?',
+  domain: :consul,
+  gap_type: :incomplete
+)
+
+# Explore and resolve
+client.explore_wonder(wonder_id: wonder[:wonder_id])
+client.resolve_wonder(
+  wonder_id: wonder[:wonder_id],
+  resolution: 'Child tokens inherit parent policy',
+  actual_gain: 0.8
+)
+
+# Get the curiosity-driven agenda
+client.form_agenda
+# => { agenda_items: [{ type: :curious, summary: "...", weight: 0.7 }], source: :curiosity }
+
+# Decay salience over time
+client.decay_wonders(hours_elapsed: 1.0)
+```
+
+## Gap Types
+
+| Type | Trigger |
+|------|---------|
+| `:unknown` | Domain with no memory traces |
+| `:uncertain` | Low-confidence predictions |
+| `:contradictory` | Conflicting memory traces |
+| `:incomplete` | Partial pattern matches or weak traces |
+
+## Integration
+
+Wires into lex-tick phases:
+- `working_memory_integration` → `detect_gaps`
+- `agenda_formation` → `form_agenda`
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
+## License
+
+MIT

data/lex-curiosity.gemspec

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative 'lib/legion/extensions/curiosity/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'lex-curiosity'
+  spec.version       = Legion::Extensions::Curiosity::VERSION
+  spec.authors       = ['Esity']
+  spec.email         = ['matthewdiverson@gmail.com']
+
+  spec.summary       = 'LEX Curiosity'
+  spec.description   = 'Intrinsic curiosity engine for brain-modeled agentic AI'
+  spec.homepage      = 'https://github.com/LegionIO/lex-curiosity'
+  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-curiosity'
+  spec.metadata['documentation_uri'] = 'https://github.com/LegionIO/lex-curiosity'
+  spec.metadata['changelog_uri'] = 'https://github.com/LegionIO/lex-curiosity'
+  spec.metadata['bug_tracker_uri'] = 'https://github.com/LegionIO/lex-curiosity/issues'
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    Dir.glob('{lib,spec}/**/*') + %w[lex-curiosity.gemspec Gemfile LICENSE README.md]
+  end
+  spec.require_paths = ['lib']
+  spec.add_development_dependency 'legion-gaia'
+end

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

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/curiosity/helpers/constants'
+require 'legion/extensions/curiosity/helpers/wonder'
+require 'legion/extensions/curiosity/helpers/wonder_store'
+require 'legion/extensions/curiosity/helpers/gap_detector'
+require 'legion/extensions/curiosity/runners/curiosity'
+
+module Legion
+  module Extensions
+    module Curiosity
+      # Standalone client for curiosity operations without the full framework.
+      class Client
+        include Runners::Curiosity
+
+        attr_reader :wonder_store
+
+        def initialize(store: nil, **)
+          @wonder_store = store || Helpers::WonderStore.new
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Curiosity
+      module Helpers
+        module Constants
+          GAP_TYPES = %i[unknown uncertain contradictory incomplete].freeze
+
+          MAX_WONDERS                  = 20
+          WONDER_DECAY_RATE            = 0.02    # salience decay per hour
+          WONDER_STALE_THRESHOLD       = 259_200 # 3 days in seconds
+          MAX_EXPLORATION_ATTEMPTS     = 5
+          INFORMATION_GAIN_THRESHOLD   = 0.3     # minimum expected gain to create wonder
+          CURIOSITY_REWARD_MULTIPLIER  = 1.5     # emotional reward on resolution
+          DOMAIN_BALANCE_FACTOR        = 0.7     # penalize overrepresented domains
+          DIVERSIVE_NOVELTY_THRESHOLD  = 0.6     # novelty above which diversive curiosity triggers
+          SPECIFIC_GAP_THRESHOLD       = 0.5     # gap score above which specific curiosity triggers
+          EXPLORATION_COOLDOWN         = 300     # seconds between re-exploration of same wonder
+          LOW_CONFIDENCE_THRESHOLD     = 0.5     # prediction confidence below this triggers wonder
+          EMPTY_RETRIEVAL_THRESHOLD    = 2       # fewer traces than this = unknown domain
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/curiosity/helpers/gap_detector.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Curiosity
+      module Helpers
+        # Analyzes tick phase results for knowledge gaps that drive curiosity.
+        module GapDetector
+          module_function
+
+          def detect(prior_results)
+            detectors = %i[memory_retrieval prediction_engine emotional_evaluation contradiction_resolution]
+            methods   = %i[detect_memory_gaps detect_prediction_gaps detect_emotional_gaps detect_contradiction_gaps]
+
+            gaps = detectors.zip(methods).flat_map { |key, method| send(method, prior_results[key]) }
+
+            gaps
+              .select { |g| g[:information_gain] >= Constants::INFORMATION_GAIN_THRESHOLD }
+              .sort_by { |g| -((g[:salience] * 0.6) + (g[:information_gain] * 0.4)) }
+          end
+
+          def detect_memory_gaps(result)
+            return [] unless result.is_a?(Hash)
+
+            gaps = []
+            traces = result[:traces]
+            domain = result[:domain] || :general
+
+            gaps << unknown_domain_gap(traces, domain) if sparse_traces?(traces)
+            gaps << incomplete_knowledge_gap(traces, domain) if weak_traces?(traces)
+            gaps.compact
+          end
+
+          def detect_prediction_gaps(result)
+            return [] unless result.is_a?(Hash)
+
+            gaps = []
+            gaps << low_confidence_gap(result) if low_confidence?(result)
+            gaps << failed_prediction_gap(result) if failed_prediction?(result)
+            gaps
+          end
+
+          def detect_emotional_gaps(result)
+            return [] unless result.is_a?(Hash)
+
+            valence = result[:valence]
+            return [] unless valence.is_a?(Hash) && novel_unfamiliar?(valence)
+
+            [novel_unfamiliar_gap(result, valence)]
+          end
+
+          def detect_contradiction_gaps(result)
+            return [] unless result.is_a?(Hash)
+
+            conflicts = result[:active_conflicts] || result[:conflicts]
+            return [] unless conflicts.is_a?(Array) && !conflicts.empty?
+
+            conflicts.first(3).map { |c| contradiction_gap(c) }
+          end
+
+          # -- private helpers below --
+
+          def sparse_traces?(traces)
+            traces.is_a?(Array) && traces.size < Constants::EMPTY_RETRIEVAL_THRESHOLD
+          end
+
+          def weak_traces?(traces)
+            return false unless traces.is_a?(Array)
+
+            traces.any? { |t| t.is_a?(Hash) && (t[:strength] || 1.0) < 0.3 }
+          end
+
+          def low_confidence?(result)
+            c = result[:confidence]
+            c.is_a?(Numeric) && c < Constants::LOW_CONFIDENCE_THRESHOLD
+          end
+
+          def failed_prediction?(result)
+            result[:status] == :failed || result[:error]
+          end
+
+          def novel_unfamiliar?(valence)
+            (valence[:novelty] || 0.0) > Constants::DIVERSIVE_NOVELTY_THRESHOLD &&
+              (valence[:familiarity] || 1.0) < 0.3
+          end
+
+          def unknown_domain_gap(traces, domain)
+            {
+              gap_type:         :unknown,
+              domain:           domain,
+              question:         "What do I know about #{domain}?",
+              salience:         0.6,
+              information_gain: 0.7,
+              source_trace_ids: traces&.filter_map { |t| t[:trace_id] } || []
+            }
+          end
+
+          def incomplete_knowledge_gap(traces, domain)
+            weak = traces.select { |t| t.is_a?(Hash) && (t[:strength] || 1.0) < 0.3 }
+            return nil if weak.empty?
+
+            {
+              gap_type:         :incomplete,
+              domain:           domain,
+              question:         'Why are my memories about this topic weak?',
+              salience:         0.4,
+              information_gain: 0.5,
+              source_trace_ids: weak.filter_map { |t| t[:trace_id] }
+            }
+          end
+
+          def low_confidence_gap(result)
+            confidence = result[:confidence]
+            {
+              gap_type:         :uncertain,
+              domain:           result[:domain] || :general,
+              question:         "Why is my prediction confidence low (#{(confidence * 100).round}%)?",
+              salience:         0.7,
+              information_gain: 0.6,
+              source_trace_ids: []
+            }
+          end
+
+          def failed_prediction_gap(result)
+            {
+              gap_type:         :uncertain,
+              domain:           result[:domain] || :general,
+              question:         'What caused this prediction failure?',
+              salience:         0.8,
+              information_gain: 0.7,
+              source_trace_ids: []
+            }
+          end
+
+          def novel_unfamiliar_gap(result, valence)
+            novelty = valence[:novelty] || 0.0
+            familiarity = valence[:familiarity] || 1.0
+            {
+              gap_type:         :unknown,
+              domain:           result[:domain] || :general,
+              question:         'This is novel and unfamiliar — what is it?',
+              salience:         novelty,
+              information_gain: (1.0 - familiarity) * 0.8,
+              source_trace_ids: []
+            }
+          end
+
+          def contradiction_gap(conflict)
+            domain = conflict.is_a?(Hash) ? (conflict[:domain] || :general) : :general
+            {
+              gap_type:         :contradictory,
+              domain:           domain,
+              question:         "Why do I have contradictory knowledge about #{domain}?",
+              salience:         0.8,
+              information_gain: 0.7,
+              source_trace_ids: conflict.is_a?(Hash) ? Array(conflict[:trace_ids]) : []
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/curiosity/helpers/wonder.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module Curiosity
+      module Helpers
+        module Wonder
+          module_function
+
+          def new_wonder(question:, domain: :general, gap_type: :unknown,
+                         salience: 0.5, information_gain: 0.5,
+                         source_trace_ids: [], emotional_valence: {})
+            raise ArgumentError, "invalid gap_type: #{gap_type}" unless Constants::GAP_TYPES.include?(gap_type)
+
+            {
+              wonder_id:         SecureRandom.uuid,
+              question:          question,
+              domain:            domain.to_sym,
+              gap_type:          gap_type,
+              salience:          salience.clamp(0.0, 1.0),
+              information_gain:  information_gain.clamp(0.0, 1.0),
+              attempts:          0,
+              created_at:        Time.now.utc,
+              last_explored_at:  nil,
+              resolved:          false,
+              resolution:        nil,
+              source_trace_ids:  Array(source_trace_ids),
+              emotional_valence: emotional_valence
+            }
+          end
+
+          def score(wonder)
+            return 0.0 if wonder[:resolved]
+
+            base = (wonder[:salience] * 0.6) + (wonder[:information_gain] * 0.4)
+            attempt_penalty = [wonder[:attempts] * 0.1, 0.5].min
+            base - attempt_penalty
+          end
+
+          def stale?(wonder)
+            age = Time.now.utc - wonder[:created_at]
+            age > Constants::WONDER_STALE_THRESHOLD
+          end
+
+          def explorable?(wonder)
+            return false if wonder[:resolved]
+            return false if wonder[:attempts] >= Constants::MAX_EXPLORATION_ATTEMPTS
+
+            if wonder[:last_explored_at]
+              cooldown = Constants::EXPLORATION_COOLDOWN * (2**[wonder[:attempts] - 1, 0].max)
+              return false if (Time.now.utc - wonder[:last_explored_at]) < cooldown
+            end
+
+            true
+          end
+
+          def decay_salience(wonder, hours_elapsed: 1.0)
+            return wonder if wonder[:resolved]
+
+            decayed = wonder[:salience] - (Constants::WONDER_DECAY_RATE * hours_elapsed)
+            wonder.merge(salience: [decayed, 0.0].max)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/curiosity/helpers/wonder_store.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Curiosity
+      module Helpers
+        # In-memory priority queue for wonder items with domain balancing and decay.
+        class WonderStore
+          attr_reader :resolved_count, :total_generated
+
+          def initialize
+            @wonders = {}
+            @resolved_count = 0
+            @total_generated = 0
+            @domain_resolution_rates = Hash.new { |h, k| h[k] = { resolved: 0, total: 0 } }
+          end
+
+          def store(wonder)
+            prune_if_full
+            @wonders[wonder[:wonder_id]] = wonder
+            @total_generated += 1
+            @domain_resolution_rates[wonder[:domain]][:total] += 1
+            wonder
+          end
+
+          def get(wonder_id)
+            @wonders[wonder_id]
+          end
+
+          def update(wonder_id, attrs)
+            wonder = @wonders[wonder_id]
+            return nil unless wonder
+
+            @wonders[wonder_id] = wonder.merge(attrs)
+          end
+
+          def delete(wonder_id)
+            @wonders.delete(wonder_id)
+          end
+
+          def active_wonders
+            @wonders.values.reject { |w| w[:resolved] }
+          end
+
+          def resolved_wonders
+            @wonders.values.select { |w| w[:resolved] }
+          end
+
+          def top(limit: 5, exclude_domains: [])
+            active_wonders
+              .reject { |w| exclude_domains.include?(w[:domain]) }
+              .sort_by { |w| -Wonder.score(w) }
+              .first(limit)
+          end
+
+          def top_balanced(limit: 5)
+            domain_counts = active_wonders.group_by { |w| w[:domain] }
+                                          .transform_values(&:size)
+            max_domain = domain_counts.values.max || 1
+
+            active_wonders
+              .sort_by do |w|
+                domain_penalty = (domain_counts[w[:domain]].to_f / max_domain) * Constants::DOMAIN_BALANCE_FACTOR
+                -(Wonder.score(w) - domain_penalty)
+              end
+              .first(limit)
+          end
+
+          def by_domain(domain)
+            active_wonders.select { |w| w[:domain] == domain.to_sym }
+          end
+
+          def mark_resolved(wonder_id, resolution:, actual_gain: 0.5)
+            wonder = @wonders[wonder_id]
+            return nil unless wonder
+
+            @wonders[wonder_id] = wonder.merge(
+              resolved:    true,
+              resolution:  resolution,
+              actual_gain: actual_gain
+            )
+            @resolved_count += 1
+            @domain_resolution_rates[wonder[:domain]][:resolved] += 1
+            @wonders[wonder_id]
+          end
+
+          def decay_all(hours_elapsed: 1.0)
+            pruned = 0
+            @wonders.each do |id, wonder|
+              next if wonder[:resolved]
+
+              decayed = Wonder.decay_salience(wonder, hours_elapsed: hours_elapsed)
+              if decayed[:salience] <= 0.0 || Wonder.stale?(decayed)
+                @wonders.delete(id)
+                pruned += 1
+              else
+                @wonders[id] = decayed
+              end
+            end
+            pruned
+          end
+
+          def count
+            @wonders.size
+          end
+
+          def active_count
+            active_wonders.size
+          end
+
+          def domain_stats
+            stats = Hash.new { |h, k| h[k] = { active: 0, resolved: 0 } }
+            @wonders.each_value do |w|
+              key = w[:resolved] ? :resolved : :active
+              stats[w[:domain]][key] += 1
+            end
+            stats
+          end
+
+          def resolution_rate
+            return 0.0 if @total_generated.zero?
+
+            @resolved_count.to_f / @total_generated
+          end
+
+          def domain_resolution_rate(domain)
+            rates = @domain_resolution_rates[domain.to_sym]
+            return 0.0 if rates[:total].zero?
+
+            rates[:resolved].to_f / rates[:total]
+          end
+
+          private
+
+          def prune_if_full
+            return unless active_count >= Constants::MAX_WONDERS
+
+            lowest = active_wonders.min_by { |w| Wonder.score(w) }
+            @wonders.delete(lowest[:wonder_id]) if lowest
+          end
+        end
+      end
+    end
+  end
+end