lex-schema 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 610c292616da34f0d31990db52cd23f1f6144003742f28c5fa10482fbbe8f490
+  data.tar.gz: d0d06626d42e4b37bf60ffb78284c4a8cbd04fb5f59bfe1ea2e3835de2b203d9
+SHA512:
+  metadata.gz: c4f0d6677c40e2ef05393c4c122bf5072d20115a442275ebd145f857165cf43099383697c942205662bed81afa110e4bbbf02f8ad6441fb3cf0e6b51d623f1e9
+  data.tar.gz: ce3fa23aa8352a05e629c9bd045ca24e859e40c62c8a952f522dae0439b985575ebd85980e39823a77acd2643c76342bcf521b7327c4044999a42b4c694e9f1f

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

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/schema/helpers/constants'
+require 'legion/extensions/schema/helpers/causal_relation'
+require 'legion/extensions/schema/helpers/world_model'
+require 'legion/extensions/schema/runners/schema'
+
+module Legion
+  module Extensions
+    module Schema
+      class Client
+        include Runners::Schema
+
+        attr_reader :world_model
+
+        def initialize(world_model: nil, **)
+          @world_model = world_model || Helpers::WorldModel.new
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/schema/helpers/causal_relation.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module Schema
+      module Helpers
+        class CausalRelation
+          attr_reader :id, :cause, :effect, :relation_type, :confidence,
+                      :evidence_count, :created_at, :updated_at
+
+          def initialize(cause:, effect:, relation_type:, confidence: 0.5)
+            @id             = SecureRandom.uuid
+            @cause          = cause
+            @effect         = effect
+            @relation_type  = relation_type
+            @confidence     = confidence.clamp(0.0, 1.0)
+            @evidence_count = 1
+            @created_at     = Time.now.utc
+            @updated_at     = Time.now.utc
+          end
+
+          def reinforce(amount = Constants::REINFORCEMENT_BONUS)
+            @confidence = [@confidence + amount, 1.0].min
+            @evidence_count += 1
+            @updated_at = Time.now.utc
+          end
+
+          def weaken(amount = Constants::CONTRADICTION_PENALTY)
+            @confidence = [@confidence - amount, 0.0].max
+            @updated_at = Time.now.utc
+          end
+
+          def decay
+            @confidence = [@confidence - Constants::DECAY_RATE, 0.0].max
+          end
+
+          def established?
+            @confidence >= Constants::CONFIDENCE_LEVELS[:established]
+          end
+
+          def speculative?
+            @confidence <= Constants::CONFIDENCE_LEVELS[:speculative]
+          end
+
+          def prunable?
+            @confidence < Constants::PRUNE_THRESHOLD
+          end
+
+          def to_h
+            {
+              id:             @id,
+              cause:          @cause,
+              effect:         @effect,
+              relation_type:  @relation_type,
+              confidence:     @confidence.round(4),
+              evidence_count: @evidence_count,
+              established:    established?
+            }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Schema
+      module Helpers
+        module Constants
+          RELATION_TYPES = %i[
+            causes
+            prevents
+            enables
+            requires
+            correlates
+            contradicts
+          ].freeze
+
+          CONFIDENCE_LEVELS = {
+            established: 0.9,
+            strong:      0.7,
+            moderate:    0.5,
+            weak:        0.3,
+            speculative: 0.1
+          }.freeze
+
+          SCHEMA_ALPHA = 0.12
+
+          MAX_SCHEMAS = 500
+
+          MAX_RELATIONS_PER_SCHEMA = 50
+
+          REINFORCEMENT_BONUS = 0.05
+
+          CONTRADICTION_PENALTY = 0.15
+
+          DECAY_RATE = 0.005
+
+          PRUNE_THRESHOLD = 0.1
+
+          MAX_COUNTERFACTUAL_DEPTH = 5
+
+          MAX_EXPLANATION_CHAIN = 10
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/schema/helpers/world_model.rb

@@ -0,0 +1,169 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Schema
+      module Helpers
+        class WorldModel
+          attr_reader :relations, :domains
+
+          def initialize
+            @relations = {}
+            @domains   = Hash.new { |h, k| h[k] = [] }
+          end
+
+          def add_relation(cause:, effect:, relation_type:, confidence: 0.5)
+            return nil unless Constants::RELATION_TYPES.include?(relation_type)
+
+            key = relation_key(cause, effect, relation_type)
+            if @relations.key?(key)
+              @relations[key].reinforce
+            else
+              @relations[key] = CausalRelation.new(cause: cause, effect: effect, relation_type: relation_type, confidence: confidence)
+              index_domains(cause, effect, key)
+              trim_relations
+            end
+            @relations[key]
+          end
+
+          def weaken_relation(cause:, effect:, relation_type:)
+            key = relation_key(cause, effect, relation_type)
+            relation = @relations[key]
+            return nil unless relation
+
+            relation.weaken
+            prune_if_needed(key)
+            relation
+          end
+
+          def find_effects(cause)
+            keys = @domains[cause] || []
+            keys.filter_map { |k| @relations[k] }.select { |r| r.cause == cause }
+          end
+
+          def find_causes(effect)
+            keys = @domains[effect] || []
+            keys.filter_map { |k| @relations[k] }.select { |r| r.effect == effect }
+          end
+
+          def explain(outcome, max_depth: Constants::MAX_EXPLANATION_CHAIN)
+            chain = []
+            visited = Set.new
+            build_explanation_chain(outcome, chain, visited, max_depth)
+            chain
+          end
+
+          def counterfactual(cause, max_depth: Constants::MAX_COUNTERFACTUAL_DEPTH)
+            affected = []
+            visited  = Set.new
+            propagate_counterfactual(cause, affected, visited, max_depth)
+            affected
+          end
+
+          def contradictions
+            @relations.values.each_with_object([]) do |rel, result|
+              next unless rel.relation_type == :causes
+
+              opposite = @relations[relation_key(rel.cause, rel.effect, :prevents)]
+              next unless opposite
+
+              result << {
+                cause:               rel.cause,
+                effect:              rel.effect,
+                causes_confidence:   rel.confidence.round(4),
+                prevents_confidence: opposite.confidence.round(4)
+              }
+            end
+          end
+
+          def decay_all
+            @relations.each_value(&:decay)
+            prune_weak
+          end
+
+          def relation_count
+            @relations.size
+          end
+
+          def domain_count
+            all_entities = @relations.values.flat_map { |r| [r.cause, r.effect] }
+            all_entities.uniq.size
+          end
+
+          def established_relations
+            @relations.values.select(&:established?)
+          end
+
+          def to_h
+            {
+              relation_count:      relation_count,
+              domain_count:        domain_count,
+              established_count:   established_relations.size,
+              contradiction_count: contradictions.size
+            }
+          end
+
+          private
+
+          def relation_key(cause, effect, relation_type)
+            "#{cause}->#{relation_type}->#{effect}"
+          end
+
+          def index_domains(cause, effect, key)
+            @domains[cause] << key
+            @domains[effect] << key
+          end
+
+          def build_explanation_chain(outcome, chain, visited, depth)
+            return if depth <= 0 || visited.include?(outcome)
+
+            visited.add(outcome)
+            causes = find_causes(outcome).sort_by { |r| -r.confidence }
+            causes.first(3).each do |rel|
+              chain << rel.to_h
+              build_explanation_chain(rel.cause, chain, visited, depth - 1)
+            end
+          end
+
+          def propagate_counterfactual(cause, affected, visited, depth)
+            return if depth <= 0 || visited.include?(cause)
+
+            visited.add(cause)
+            effects = find_effects(cause).sort_by { |r| -r.confidence }
+            effects.each do |rel|
+              affected << { effect: rel.effect, relation: rel.relation_type, confidence: rel.confidence.round(4) }
+              propagate_counterfactual(rel.effect, affected, visited, depth - 1)
+            end
+          end
+
+          def prune_if_needed(key)
+            relation = @relations[key]
+            return unless relation&.prunable?
+
+            remove_relation(key)
+          end
+
+          def prune_weak
+            prunable = @relations.select { |_, r| r.prunable? }.keys
+            prunable.each { |key| remove_relation(key) }
+          end
+
+          def remove_relation(key)
+            rel = @relations.delete(key)
+            return unless rel
+
+            @domains[rel.cause]&.delete(key)
+            @domains[rel.effect]&.delete(key)
+          end
+
+          def trim_relations
+            return if @relations.size <= Constants::MAX_SCHEMAS
+
+            weakest = @relations.sort_by { |_, r| r.confidence }
+            weakest.first(@relations.size - Constants::MAX_SCHEMAS).each { |k, _| remove_relation(k) } # rubocop:disable Style/HashEachMethods
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Schema
+      module Runners
+        module Schema
+          include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                      Legion::Extensions::Helpers.const_defined?(:Lex)
+
+          def update_schema(tick_results: {}, **)
+            extract_prediction_outcomes(tick_results)
+            world_model.decay_all
+
+            Legion::Logging.debug "[schema] relations=#{world_model.relation_count} " \
+                                  "domains=#{world_model.domain_count} established=#{world_model.established_relations.size}"
+
+            world_model.to_h
+          end
+
+          def learn_relation(cause:, effect:, relation_type:, confidence: 0.5, **)
+            relation_sym = relation_type.to_sym
+            result = world_model.add_relation(cause: cause, effect: effect, relation_type: relation_sym, confidence: confidence)
+            return { success: false, error: 'invalid relation type' } unless result
+
+            Legion::Logging.info "[schema] learned: #{cause} #{relation_sym} #{effect} (#{result.confidence.round(2)})"
+            { success: true, relation: result.to_h }
+          end
+
+          def weaken_relation(cause:, effect:, relation_type:, **)
+            result = world_model.weaken_relation(cause: cause, effect: effect, relation_type: relation_type.to_sym)
+            return { success: false, error: 'relation not found' } unless result
+
+            Legion::Logging.debug "[schema] weakened: #{cause} #{relation_type} #{effect}"
+            { success: true, relation: result.to_h }
+          end
+
+          def explain(outcome:, **)
+            chain = world_model.explain(outcome)
+            Legion::Logging.debug "[schema] explanation for #{outcome}: #{chain.size} links"
+            { outcome: outcome, chain: chain, depth: chain.size }
+          end
+
+          def counterfactual(cause:, **)
+            affected = world_model.counterfactual(cause)
+            Legion::Logging.debug "[schema] counterfactual for #{cause}: #{affected.size} effects"
+            { cause: cause, affected: affected, impact: affected.size }
+          end
+
+          def find_effects(cause:, **)
+            effects = world_model.find_effects(cause).map(&:to_h)
+            { cause: cause, effects: effects, count: effects.size }
+          end
+
+          def find_causes(effect:, **)
+            causes = world_model.find_causes(effect).map(&:to_h)
+            { effect: effect, causes: causes, count: causes.size }
+          end
+
+          def contradictions(**)
+            result = world_model.contradictions
+            Legion::Logging.debug "[schema] contradictions: #{result.size}"
+            { contradictions: result, count: result.size }
+          end
+
+          def schema_stats(**)
+            Legion::Logging.debug '[schema] stats'
+            world_model.to_h.merge(
+              top_relations: world_model.established_relations.first(10).map(&:to_h)
+            )
+          end
+
+          private
+
+          def world_model
+            @world_model ||= Helpers::WorldModel.new
+          end
+
+          def extract_prediction_outcomes(tick_results)
+            predictions = tick_results.dig(:prediction_engine, :resolved)
+            return unless predictions.is_a?(Array)
+
+            predictions.each do |pred|
+              next unless pred[:domain] && pred[:outcome_domain]
+
+              if pred[:accurate]
+                world_model.add_relation(cause: pred[:domain], effect: pred[:outcome_domain], relation_type: :causes, confidence: 0.6)
+              else
+                world_model.weaken_relation(cause: pred[:domain], effect: pred[:outcome_domain], relation_type: :causes)
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

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

data/lib/legion/extensions/schema.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/schema/version'
+require 'legion/extensions/schema/helpers/constants'
+require 'legion/extensions/schema/helpers/causal_relation'
+require 'legion/extensions/schema/helpers/world_model'
+require 'legion/extensions/schema/runners/schema'
+require 'legion/extensions/schema/client'
+
+module Legion
+  module Extensions
+    module Schema
+      extend Legion::Extensions::Core if Legion::Extensions.const_defined?(:Core)
+    end
+  end
+end

metadata

@@ -0,0 +1,63 @@
+--- !ruby/object:Gem::Specification
+name: lex-schema
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Matthew Iverson
+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: Builds and maintains causal schemas — structured models of how things
+  work, enabling explanation and counterfactual reasoning
+email:
+- matt@legionIO.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/legion/extensions/schema.rb
+- lib/legion/extensions/schema/client.rb
+- lib/legion/extensions/schema/helpers/causal_relation.rb
+- lib/legion/extensions/schema/helpers/constants.rb
+- lib/legion/extensions/schema/helpers/world_model.rb
+- lib/legion/extensions/schema/runners/schema.rb
+- lib/legion/extensions/schema/version.rb
+homepage: https://github.com/LegionIO/lex-schema
+licenses:
+- MIT
+metadata:
+  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: Internal world model and causal reasoning for LegionIO cognitive agents
+test_files: []