lex-confabulation 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ee2c37bdb8c637bc9e4668ebd47d457a5b8deea44bba412c42c35752ac8f1cc8
+  data.tar.gz: 47875db096f924f3298fa4880588c3990ae219c3823d13277b1431939e91aac7
+SHA512:
+  metadata.gz: 8cb8165024fd17dfba7de1aad74eab7f6484aad5be58da44df11cba8b9536265be446ceacbcd5223058ab8bb52e9af0b72763d866ca7e1670f400c0a7c5f3c72
+  data.tar.gz: 5b8eb4dad3bf6866806538b7a363d1a112c4c2b5f261410ac821fc7a6cb039dea6bc7639dd5a7785e46dbf3ae4ba84a296be9000abaf9b0f45602c6e029892a4

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 Matthew Iverson
+
+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,71 @@
+# lex-confabulation
+
+A LegionIO cognitive architecture extension for confabulation detection and confidence calibration. Confabulation is the cognitive phenomenon of producing plausible but false narratives to fill gaps — occurring when an agent's confidence in a claim exceeds the evidence supporting it. This extension tracks cognitive claims, monitors the confidence-evidence gap, and surfaces high-risk assertions before they influence downstream decisions.
+
+## What It Does
+
+Manages a registry of **claims** — assertions made by the agent with an associated confidence level and an evidence strength rating. The gap between these two values is the **confabulation risk**.
+
+- **Register claims** as the agent makes assertions, capturing confidence and evidence strength at the time
+- **Verify claims** when supporting evidence is confirmed
+- **Flag confabulation** when a claim is later found to be false or unsupported
+- **Monitor calibration** — the average alignment between confidence and evidence across all claims
+- **Surface high-risk claims** — those where confidence significantly exceeds evidence (risk >= 0.6)
+
+A periodic `Decay` actor fires `confabulation_report` every 300 seconds for ongoing monitoring.
+
+## Usage
+
+```ruby
+require 'lex-confabulation'
+
+client = Legion::Extensions::Confabulation::Client.new
+
+# Register a claim made by the agent
+claim = client.register_claim(
+  content:           'The database migration completed successfully',
+  claim_type:        :factual,
+  confidence:        0.9,
+  evidence_strength: 0.4
+)
+# => { id: "uuid...", content: "...", claim_type: :factual,
+#      confidence: 0.9, evidence_strength: 0.4,
+#      confabulation_risk: 0.5, risk_label: :moderate,
+#      verified: false, confabulated: false, created_at: "..." }
+
+claim_id = claim[:id]
+
+# Verify a claim when evidence is confirmed
+client.verify_claim(claim_id: claim_id)
+# => { found: true, claim_id: "uuid...", verified: true }
+
+# Flag a claim as confabulation when found to be false
+client.flag_confabulation(claim_id: claim_id)
+# => { found: true, claim_id: "uuid...", confabulated: true }
+
+# Retrieve all claims with high confabulation risk (risk >= 0.6)
+client.high_risk_claims
+# => { claims: [...], count: 1 }
+
+# Full report across all claims
+client.confabulation_report
+# => { total_claims: 5, high_risk_claims: 1, verified_claims: 2,
+#      confabulated_claims: 1, confabulation_rate: 0.2,
+#      average_calibration: 0.75, overall_risk: 0.2, risk_label: :low }
+
+# Engine summary
+client.confabulation_status
+# => { engine: { claim_count: 5, confabulation_rate: 0.2, average_calibration: 0.75 } }
+```
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
+## License
+
+MIT

data/lex-confabulation.gemspec

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

data/lib/legion/extensions/confabulation/actors/decay.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/actors/every'
+
+module Legion
+  module Extensions
+    module Confabulation
+      module Actor
+        class Decay < Legion::Extensions::Actors::Every
+          def runner_class
+            Legion::Extensions::Confabulation::Runners::Confabulation
+          end
+
+          def runner_function
+            'confabulation_report'
+          end
+
+          def time
+            300
+          end
+
+          def run_now?
+            false
+          end
+
+          def use_runner?
+            false
+          end
+
+          def check_subtask?
+            false
+          end
+
+          def generate_task?
+            false
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/confabulation/helpers/constants'
+require 'legion/extensions/confabulation/helpers/claim'
+require 'legion/extensions/confabulation/helpers/confabulation_engine'
+require 'legion/extensions/confabulation/runners/confabulation'
+
+module Legion
+  module Extensions
+    module Confabulation
+      class Client
+        include Runners::Confabulation
+
+        def initialize(**)
+          @confabulation_engine = Helpers::ConfabulationEngine.new
+        end
+
+        private
+
+        attr_reader :confabulation_engine
+      end
+    end
+  end
+end

data/lib/legion/extensions/confabulation/helpers/claim.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module Confabulation
+      module Helpers
+        class Claim
+          attr_reader :id, :content, :claim_type, :confidence, :evidence_strength,
+                      :verified, :confabulated, :created_at
+
+          def initialize(content:, claim_type:, confidence:, evidence_strength:)
+            @id               = SecureRandom.uuid
+            @content          = content
+            @claim_type       = claim_type
+            @confidence       = confidence.clamp(0.0, 1.0)
+            @evidence_strength = evidence_strength.clamp(0.0, 1.0)
+            @verified         = false
+            @confabulated     = false
+            @created_at       = Time.now.utc
+          end
+
+          def confabulation_risk
+            (confidence - evidence_strength).clamp(0.0, 1.0)
+          end
+
+          def verify!
+            @verified = true
+            self
+          end
+
+          def mark_confabulated!
+            @confabulated = true
+            self
+          end
+
+          def risk_label
+            Constants::RISK_LABELS.each do |range, label|
+              return label if range.cover?(confabulation_risk)
+            end
+            :extreme
+          end
+
+          def to_h
+            {
+              id:                 id,
+              content:            content,
+              claim_type:         claim_type,
+              confidence:         confidence.round(10),
+              evidence_strength:  evidence_strength.round(10),
+              confabulation_risk: confabulation_risk.round(10),
+              risk_label:         risk_label,
+              verified:           verified,
+              confabulated:       confabulated,
+              created_at:         created_at.iso8601
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/confabulation/helpers/confabulation_engine.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Confabulation
+      module Helpers
+        class ConfabulationEngine
+          attr_reader :claims
+
+          def initialize
+            @claims = {}
+          end
+
+          def register_claim(content:, claim_type: :factual, confidence: 0.5, evidence_strength: 0.5)
+            claim_type = claim_type.to_sym
+            claim_type = :factual unless Constants::CLAIM_TYPES.include?(claim_type)
+
+            claim = Claim.new(
+              content:           content,
+              claim_type:        claim_type,
+              confidence:        confidence,
+              evidence_strength: evidence_strength
+            )
+            prune_if_needed
+            @claims[claim.id] = claim
+            claim
+          end
+
+          def verify_claim(claim_id:)
+            claim = @claims[claim_id]
+            return { found: false, claim_id: claim_id } unless claim
+
+            claim.verify!
+            { found: true, claim_id: claim_id, verified: true }
+          end
+
+          def flag_confabulation(claim_id:)
+            claim = @claims[claim_id]
+            return { found: false, claim_id: claim_id } unless claim
+
+            claim.mark_confabulated!
+            { found: true, claim_id: claim_id, confabulated: true }
+          end
+
+          def high_risk_claims
+            @claims.values.select { |c| c.confabulation_risk >= Constants::CONFABULATION_THRESHOLD }
+          end
+
+          def verified_claims
+            @claims.values.select(&:verified)
+          end
+
+          def confabulation_rate
+            total = @claims.size
+            return 0.0 if total.zero?
+
+            flagged = @claims.values.count(&:confabulated)
+            (flagged.to_f / total).round(10)
+          end
+
+          def average_calibration
+            return 0.0 if @claims.empty?
+
+            total_gap = @claims.values.sum { |c| (c.confidence - c.evidence_strength).abs }
+            gap = total_gap / @claims.size.to_f
+            (1.0 - gap).clamp(0.0, 1.0).round(10)
+          end
+
+          def confabulation_report
+            total          = @claims.size
+            high_risk      = high_risk_claims.size
+            verified       = verified_claims.size
+            confabulated   = @claims.values.count(&:confabulated)
+            overall_risk   = total.zero? ? 0.0 : high_risk.to_f / total
+            risk_label     = risk_label_for(overall_risk)
+
+            {
+              total_claims:        total,
+              high_risk_claims:    high_risk,
+              verified_claims:     verified,
+              confabulated_claims: confabulated,
+              confabulation_rate:  confabulation_rate,
+              average_calibration: average_calibration,
+              overall_risk:        overall_risk.round(10),
+              risk_label:          risk_label
+            }
+          end
+
+          def prune_if_needed
+            return unless @claims.size >= Constants::MAX_CLAIMS
+
+            oldest_key = @claims.min_by { |_, c| c.created_at }&.first
+            @claims.delete(oldest_key)
+          end
+
+          def to_h
+            {
+              claim_count:         @claims.size,
+              confabulation_rate:  confabulation_rate,
+              average_calibration: average_calibration
+            }
+          end
+
+          private
+
+          def risk_label_for(value)
+            Constants::RISK_LABELS.each do |range, label|
+              return label if range.cover?(value)
+            end
+            :extreme
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Confabulation
+      module Helpers
+        module Constants
+          MAX_CLAIMS = 500
+          CONFABULATION_THRESHOLD = 0.6
+          EVIDENCE_DECAY = 0.02
+
+          RISK_LABELS = {
+            0.0..0.2 => :minimal,
+            0.2..0.4 => :low,
+            0.4..0.6 => :moderate,
+            0.6..0.8 => :high,
+            0.8..1.0 => :extreme
+          }.freeze
+
+          CLAIM_TYPES = %i[factual causal explanatory predictive autobiographical].freeze
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Confabulation
+      module Runners
+        module Confabulation
+          include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                      Legion::Extensions::Helpers.const_defined?(:Lex)
+
+          def register_claim(content:, claim_type: :factual, confidence: 0.5, evidence_strength: 0.5, **)
+            claim = confabulation_engine.register_claim(
+              content:           content,
+              claim_type:        claim_type,
+              confidence:        confidence,
+              evidence_strength: evidence_strength
+            )
+            Legion::Logging.debug "[confabulation] register: id=#{claim.id} type=#{claim.claim_type} " \
+                                  "risk=#{claim.confabulation_risk.round(2)} label=#{claim.risk_label}"
+            claim.to_h
+          end
+
+          def verify_claim(claim_id:, **)
+            result = confabulation_engine.verify_claim(claim_id: claim_id)
+            if result[:found]
+              Legion::Logging.info "[confabulation] verified: claim_id=#{claim_id}"
+            else
+              Legion::Logging.debug "[confabulation] verify: claim_id=#{claim_id} not found"
+            end
+            result
+          end
+
+          def flag_confabulation(claim_id:, **)
+            result = confabulation_engine.flag_confabulation(claim_id: claim_id)
+            if result[:found]
+              Legion::Logging.warn "[confabulation] flagged: claim_id=#{claim_id} marked as confabulated"
+            else
+              Legion::Logging.debug "[confabulation] flag: claim_id=#{claim_id} not found"
+            end
+            result
+          end
+
+          def confabulation_report(**)
+            report = confabulation_engine.confabulation_report
+            Legion::Logging.debug "[confabulation] report: total=#{report[:total_claims]} " \
+                                  "high_risk=#{report[:high_risk_claims]} " \
+                                  "rate=#{report[:confabulation_rate].round(2)} label=#{report[:risk_label]}"
+            report
+          end
+
+          def high_risk_claims(**)
+            claims = confabulation_engine.high_risk_claims
+            Legion::Logging.debug "[confabulation] high_risk_claims: count=#{claims.size}"
+            { claims: claims.map(&:to_h), count: claims.size }
+          end
+
+          def confabulation_status(**)
+            { engine: confabulation_engine.to_h }
+          end
+
+          private
+
+          def confabulation_engine
+            @confabulation_engine ||= Helpers::ConfabulationEngine.new
+          end
+        end
+      end
+    end
+  end
+end

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

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

data/lib/legion/extensions/confabulation.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/confabulation/version'
+require 'legion/extensions/confabulation/helpers/constants'
+require 'legion/extensions/confabulation/helpers/claim'
+require 'legion/extensions/confabulation/helpers/confabulation_engine'
+require 'legion/extensions/confabulation/runners/confabulation'
+
+module Legion
+  module Extensions
+    module Confabulation
+      extend Legion::Extensions::Core if Legion::Extensions.const_defined? :Core
+    end
+  end
+end

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

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/confabulation/client'
+
+RSpec.describe Legion::Extensions::Confabulation::Client do
+  let(:client) { described_class.new }
+
+  it 'responds to confabulation runner methods' do
+    expect(client).to respond_to(:register_claim)
+    expect(client).to respond_to(:verify_claim)
+    expect(client).to respond_to(:flag_confabulation)
+    expect(client).to respond_to(:confabulation_report)
+    expect(client).to respond_to(:high_risk_claims)
+    expect(client).to respond_to(:confabulation_status)
+  end
+
+  it 'starts with an empty engine' do
+    status = client.confabulation_status
+    expect(status[:engine][:claim_count]).to eq(0)
+  end
+
+  it 'persists claims across calls within the same instance' do
+    client.register_claim(content: 'persistent', claim_type: :factual,
+                          confidence: 0.7, evidence_strength: 0.3)
+    expect(client.confabulation_status[:engine][:claim_count]).to eq(1)
+  end
+
+  it 'maintains separate state between instances' do
+    client.register_claim(content: 'instance A claim', claim_type: :factual,
+                          confidence: 0.7, evidence_strength: 0.3)
+    other = described_class.new
+    expect(other.confabulation_status[:engine][:claim_count]).to eq(0)
+  end
+end

data/spec/legion/extensions/confabulation/helpers/claim_spec.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Confabulation::Helpers::Claim do
+  let(:claim) do
+    described_class.new(
+      content:           'The sky is green',
+      claim_type:        :factual,
+      confidence:        0.8,
+      evidence_strength: 0.3
+    )
+  end
+
+  describe '#initialize' do
+    it 'generates a UUID id' do
+      expect(claim.id).to match(/\A[0-9a-f-]{36}\z/)
+    end
+
+    it 'stores content' do
+      expect(claim.content).to eq('The sky is green')
+    end
+
+    it 'stores claim_type' do
+      expect(claim.claim_type).to eq(:factual)
+    end
+
+    it 'clamps confidence to [0, 1]' do
+      c = described_class.new(content: 'x', claim_type: :factual, confidence: 1.5, evidence_strength: 0.0)
+      expect(c.confidence).to eq(1.0)
+    end
+
+    it 'clamps evidence_strength to [0, 1]' do
+      c = described_class.new(content: 'x', claim_type: :factual, confidence: 0.5, evidence_strength: -0.5)
+      expect(c.evidence_strength).to eq(0.0)
+    end
+
+    it 'starts unverified' do
+      expect(claim.verified).to be false
+    end
+
+    it 'starts not confabulated' do
+      expect(claim.confabulated).to be false
+    end
+
+    it 'sets created_at to utc time' do
+      expect(claim.created_at).to be_a(Time)
+    end
+  end
+
+  describe '#confabulation_risk' do
+    it 'computes the gap between confidence and evidence_strength' do
+      expect(claim.confabulation_risk).to be_within(0.001).of(0.5)
+    end
+
+    it 'clamps to 0.0 when evidence >= confidence' do
+      c = described_class.new(content: 'x', claim_type: :factual, confidence: 0.3, evidence_strength: 0.9)
+      expect(c.confabulation_risk).to eq(0.0)
+    end
+
+    it 'clamps to 1.0 when gap exceeds 1.0' do
+      c = described_class.new(content: 'x', claim_type: :factual, confidence: 1.0, evidence_strength: 0.0)
+      expect(c.confabulation_risk).to eq(1.0)
+    end
+  end
+
+  describe '#verify!' do
+    it 'marks the claim as verified' do
+      claim.verify!
+      expect(claim.verified).to be true
+    end
+
+    it 'returns self' do
+      expect(claim.verify!).to eq(claim)
+    end
+  end
+
+  describe '#mark_confabulated!' do
+    it 'marks the claim as confabulated' do
+      claim.mark_confabulated!
+      expect(claim.confabulated).to be true
+    end
+
+    it 'returns self' do
+      expect(claim.mark_confabulated!).to eq(claim)
+    end
+  end
+
+  describe '#risk_label' do
+    it 'returns :extreme for risk >= 0.8' do
+      c = described_class.new(content: 'x', claim_type: :factual, confidence: 1.0, evidence_strength: 0.1)
+      expect(c.risk_label).to eq(:extreme)
+    end
+
+    it 'returns :minimal for risk <= 0.2' do
+      c = described_class.new(content: 'x', claim_type: :factual, confidence: 0.2, evidence_strength: 0.1)
+      expect(c.risk_label).to eq(:minimal)
+    end
+
+    it 'returns :moderate for mid-range risk' do
+      c = described_class.new(content: 'x', claim_type: :factual, confidence: 0.7, evidence_strength: 0.25)
+      expect(c.risk_label).to eq(:moderate)
+    end
+  end
+
+  describe '#to_h' do
+    it 'includes all expected keys' do
+      h = claim.to_h
+      expect(h.keys).to include(
+        :id, :content, :claim_type, :confidence, :evidence_strength,
+        :confabulation_risk, :risk_label, :verified, :confabulated, :created_at
+      )
+    end
+
+    it 'rounds numeric fields to 10 decimal places' do
+      h = claim.to_h
+      expect(h[:confidence]).to eq(0.8)
+      expect(h[:confabulation_risk]).to be_a(Float)
+    end
+  end
+end

data/spec/legion/extensions/confabulation/helpers/confabulation_engine_spec.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Confabulation::Helpers::ConfabulationEngine do
+  subject(:engine) { described_class.new }
+
+  describe '#register_claim' do
+    it 'stores the claim and returns a Claim object' do
+      claim = engine.register_claim(content: 'Cats can fly', claim_type: :factual,
+                                    confidence: 0.9, evidence_strength: 0.1)
+      expect(claim).to be_a(Legion::Extensions::Confabulation::Helpers::Claim)
+      expect(engine.claims.size).to eq(1)
+    end
+
+    it 'assigns the claim an id' do
+      claim = engine.register_claim(content: 'test', claim_type: :causal,
+                                    confidence: 0.5, evidence_strength: 0.5)
+      expect(claim.id).not_to be_nil
+    end
+
+    it 'defaults claim_type to :factual for unknown types' do
+      claim = engine.register_claim(content: 'x', claim_type: :unknown,
+                                    confidence: 0.5, evidence_strength: 0.5)
+      expect(claim.claim_type).to eq(:factual)
+    end
+
+    it 'accepts all valid claim types' do
+      Legion::Extensions::Confabulation::Helpers::Constants::CLAIM_TYPES.each do |type|
+        claim = engine.register_claim(content: 'x', claim_type: type,
+                                      confidence: 0.5, evidence_strength: 0.5)
+        expect(claim.claim_type).to eq(type)
+      end
+    end
+  end
+
+  describe '#verify_claim' do
+    it 'marks claim as verified' do
+      claim = engine.register_claim(content: 'x', claim_type: :factual,
+                                    confidence: 0.5, evidence_strength: 0.5)
+      result = engine.verify_claim(claim_id: claim.id)
+      expect(result[:found]).to be true
+      expect(result[:verified]).to be true
+      expect(engine.claims[claim.id].verified).to be true
+    end
+
+    it 'returns found: false for unknown id' do
+      result = engine.verify_claim(claim_id: 'no-such-id')
+      expect(result[:found]).to be false
+    end
+  end
+
+  describe '#flag_confabulation' do
+    it 'marks claim as confabulated' do
+      claim = engine.register_claim(content: 'x', claim_type: :factual,
+                                    confidence: 0.9, evidence_strength: 0.1)
+      result = engine.flag_confabulation(claim_id: claim.id)
+      expect(result[:found]).to be true
+      expect(result[:confabulated]).to be true
+      expect(engine.claims[claim.id].confabulated).to be true
+    end
+
+    it 'returns found: false for unknown id' do
+      result = engine.flag_confabulation(claim_id: 'no-such-id')
+      expect(result[:found]).to be false
+    end
+  end
+
+  describe '#high_risk_claims' do
+    it 'returns claims above the confabulation threshold' do
+      engine.register_claim(content: 'risky', claim_type: :factual, confidence: 0.9, evidence_strength: 0.1)
+      engine.register_claim(content: 'safe',  claim_type: :factual, confidence: 0.4, evidence_strength: 0.4)
+      high_risk = engine.high_risk_claims
+      expect(high_risk.size).to eq(1)
+      expect(high_risk.first.content).to eq('risky')
+    end
+
+    it 'returns empty array when no high-risk claims exist' do
+      engine.register_claim(content: 'safe', claim_type: :factual, confidence: 0.3, evidence_strength: 0.3)
+      expect(engine.high_risk_claims).to be_empty
+    end
+  end
+
+  describe '#verified_claims' do
+    it 'returns only verified claims' do
+      c1 = engine.register_claim(content: 'verified', claim_type: :factual, confidence: 0.5, evidence_strength: 0.5)
+      engine.register_claim(content: 'unverified', claim_type: :factual, confidence: 0.5, evidence_strength: 0.5)
+      engine.verify_claim(claim_id: c1.id)
+      expect(engine.verified_claims.size).to eq(1)
+    end
+  end
+
+  describe '#confabulation_rate' do
+    it 'returns 0.0 when no claims' do
+      expect(engine.confabulation_rate).to eq(0.0)
+    end
+
+    it 'returns fraction of confabulated claims' do
+      c1 = engine.register_claim(content: 'a', claim_type: :factual, confidence: 0.9, evidence_strength: 0.1)
+      engine.register_claim(content: 'b', claim_type: :factual, confidence: 0.4, evidence_strength: 0.4)
+      engine.flag_confabulation(claim_id: c1.id)
+      expect(engine.confabulation_rate).to be_within(0.001).of(0.5)
+    end
+  end
+
+  describe '#average_calibration' do
+    it 'returns 0.0 when no claims' do
+      expect(engine.average_calibration).to eq(0.0)
+    end
+
+    it 'returns 1.0 when all claims are perfectly calibrated' do
+      engine.register_claim(content: 'x', claim_type: :factual, confidence: 0.5, evidence_strength: 0.5)
+      expect(engine.average_calibration).to eq(1.0)
+    end
+
+    it 'returns lower value when confidence mismatches evidence' do
+      engine.register_claim(content: 'x', claim_type: :factual, confidence: 1.0, evidence_strength: 0.0)
+      expect(engine.average_calibration).to be < 1.0
+    end
+  end
+
+  describe '#confabulation_report' do
+    it 'returns a comprehensive report hash' do
+      engine.register_claim(content: 'x', claim_type: :factual, confidence: 0.8, evidence_strength: 0.2)
+      report = engine.confabulation_report
+      expect(report.keys).to include(
+        :total_claims, :high_risk_claims, :verified_claims,
+        :confabulated_claims, :confabulation_rate, :average_calibration,
+        :overall_risk, :risk_label
+      )
+    end
+
+    it 'risk_label is a symbol' do
+      report = engine.confabulation_report
+      expect(report[:risk_label]).to be_a(Symbol)
+    end
+
+    it 'totals match registered claims' do
+      2.times { |i| engine.register_claim(content: "claim#{i}", claim_type: :factual, confidence: 0.5, evidence_strength: 0.5) }
+      expect(engine.confabulation_report[:total_claims]).to eq(2)
+    end
+  end
+
+  describe '#prune_if_needed' do
+    it 'prunes oldest claim when at MAX_CLAIMS capacity' do
+      max = Legion::Extensions::Confabulation::Helpers::Constants::MAX_CLAIMS
+      first_claim = engine.register_claim(content: 'first', claim_type: :factual, confidence: 0.5, evidence_strength: 0.5)
+      (max - 1).times { |i| engine.register_claim(content: "claim#{i}", claim_type: :factual, confidence: 0.5, evidence_strength: 0.5) }
+      expect(engine.claims.size).to eq(max)
+      engine.register_claim(content: 'overflow', claim_type: :factual, confidence: 0.5, evidence_strength: 0.5)
+      expect(engine.claims.size).to eq(max)
+      expect(engine.claims[first_claim.id]).to be_nil
+    end
+  end
+
+  describe '#to_h' do
+    it 'returns a summary hash' do
+      engine.register_claim(content: 'x', claim_type: :factual, confidence: 0.5, evidence_strength: 0.5)
+      h = engine.to_h
+      expect(h).to have_key(:claim_count)
+      expect(h).to have_key(:confabulation_rate)
+      expect(h).to have_key(:average_calibration)
+    end
+  end
+end

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

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Confabulation::Helpers::Constants do
+  describe 'MAX_CLAIMS' do
+    it 'is 500' do
+      expect(described_class::MAX_CLAIMS).to eq(500)
+    end
+  end
+
+  describe 'CONFABULATION_THRESHOLD' do
+    it 'is 0.6' do
+      expect(described_class::CONFABULATION_THRESHOLD).to eq(0.6)
+    end
+  end
+
+  describe 'EVIDENCE_DECAY' do
+    it 'is 0.02' do
+      expect(described_class::EVIDENCE_DECAY).to eq(0.02)
+    end
+  end
+
+  describe 'RISK_LABELS' do
+    it 'covers the full 0.0-1.0 range' do
+      expect(described_class::RISK_LABELS.keys.map(&:min).min).to eq(0.0)
+      expect(described_class::RISK_LABELS.keys.map(&:max).max).to eq(1.0)
+    end
+
+    it 'includes all five risk levels' do
+      labels = described_class::RISK_LABELS.values
+      expect(labels).to include(:minimal, :low, :moderate, :high, :extreme)
+    end
+
+    it 'maps 0.0 to minimal' do
+      label = described_class::RISK_LABELS.find { |range, _| range.cover?(0.0) }&.last
+      expect(label).to eq(:minimal)
+    end
+
+    it 'maps 0.9 to extreme' do
+      label = described_class::RISK_LABELS.find { |range, _| range.cover?(0.9) }&.last
+      expect(label).to eq(:extreme)
+    end
+  end
+
+  describe 'CLAIM_TYPES' do
+    it 'includes all five types' do
+      expect(described_class::CLAIM_TYPES).to include(
+        :factual, :causal, :explanatory, :predictive, :autobiographical
+      )
+    end
+
+    it 'is frozen' do
+      expect(described_class::CLAIM_TYPES).to be_frozen
+    end
+  end
+end

data/spec/legion/extensions/confabulation/runners/confabulation_spec.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/confabulation/client'
+
+RSpec.describe Legion::Extensions::Confabulation::Runners::Confabulation do
+  let(:client) { Legion::Extensions::Confabulation::Client.new }
+
+  describe '#register_claim' do
+    it 'returns a claim hash with an id' do
+      result = client.register_claim(content: 'Pigeons navigate by smell', claim_type: :factual,
+                                     confidence: 0.7, evidence_strength: 0.2)
+      expect(result[:id]).not_to be_nil
+      expect(result[:claim_type]).to eq(:factual)
+    end
+
+    it 'includes confabulation_risk and risk_label' do
+      result = client.register_claim(content: 'x', claim_type: :causal, confidence: 0.9, evidence_strength: 0.1)
+      expect(result).to have_key(:confabulation_risk)
+      expect(result).to have_key(:risk_label)
+    end
+
+    it 'accepts all valid claim types' do
+      Legion::Extensions::Confabulation::Helpers::Constants::CLAIM_TYPES.each do |type|
+        result = client.register_claim(content: 'x', claim_type: type, confidence: 0.5, evidence_strength: 0.5)
+        expect(result[:claim_type]).to eq(type)
+      end
+    end
+  end
+
+  describe '#verify_claim' do
+    it 'verifies an existing claim' do
+      claim = client.register_claim(content: 'testable fact', claim_type: :factual,
+                                    confidence: 0.6, evidence_strength: 0.6)
+      result = client.verify_claim(claim_id: claim[:id])
+      expect(result[:found]).to be true
+      expect(result[:verified]).to be true
+    end
+
+    it 'returns found: false for a missing claim' do
+      result = client.verify_claim(claim_id: 'does-not-exist')
+      expect(result[:found]).to be false
+    end
+  end
+
+  describe '#flag_confabulation' do
+    it 'flags an existing claim as confabulated' do
+      claim = client.register_claim(content: 'false memory', claim_type: :autobiographical,
+                                    confidence: 0.9, evidence_strength: 0.05)
+      result = client.flag_confabulation(claim_id: claim[:id])
+      expect(result[:found]).to be true
+      expect(result[:confabulated]).to be true
+    end
+
+    it 'returns found: false for a missing claim' do
+      result = client.flag_confabulation(claim_id: 'no-such-id')
+      expect(result[:found]).to be false
+    end
+  end
+
+  describe '#confabulation_report' do
+    it 'returns a report hash' do
+      client.register_claim(content: 'risky', claim_type: :factual, confidence: 0.9, evidence_strength: 0.05)
+      report = client.confabulation_report
+      expect(report[:total_claims]).to eq(1)
+      expect(report[:risk_label]).to be_a(Symbol)
+    end
+
+    it 'includes overall_risk and average_calibration' do
+      report = client.confabulation_report
+      expect(report).to have_key(:overall_risk)
+      expect(report).to have_key(:average_calibration)
+    end
+  end
+
+  describe '#high_risk_claims' do
+    it 'returns claims above the threshold' do
+      client.register_claim(content: 'overconfident', claim_type: :predictive,
+                            confidence: 0.95, evidence_strength: 0.05)
+      client.register_claim(content: 'calibrated', claim_type: :predictive,
+                            confidence: 0.5, evidence_strength: 0.5)
+      result = client.high_risk_claims
+      expect(result[:count]).to eq(1)
+      expect(result[:claims].first[:content]).to eq('overconfident')
+    end
+
+    it 'returns empty list when no high-risk claims' do
+      client.register_claim(content: 'ok', claim_type: :factual, confidence: 0.5, evidence_strength: 0.5)
+      result = client.high_risk_claims
+      expect(result[:count]).to eq(0)
+    end
+  end
+
+  describe '#confabulation_status' do
+    it 'returns engine summary' do
+      result = client.confabulation_status
+      expect(result[:engine]).to have_key(:claim_count)
+      expect(result[:engine]).to have_key(:confabulation_rate)
+      expect(result[:engine]).to have_key(:average_calibration)
+    end
+  end
+
+  describe 'full cycle' do
+    it 'registers, verifies, flags and reports correctly' do
+      c1 = client.register_claim(content: 'valid fact', claim_type: :factual,
+                                 confidence: 0.6, evidence_strength: 0.6)
+      c2 = client.register_claim(content: 'false memory', claim_type: :autobiographical,
+                                 confidence: 0.9, evidence_strength: 0.05)
+
+      client.verify_claim(claim_id: c1[:id])
+      client.flag_confabulation(claim_id: c2[:id])
+
+      report = client.confabulation_report
+      expect(report[:total_claims]).to eq(2)
+      expect(report[:verified_claims]).to eq(1)
+      expect(report[:confabulated_claims]).to eq(1)
+      expect(report[:confabulation_rate]).to be_within(0.001).of(0.5)
+    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/confabulation'
+
+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,79 @@
+--- !ruby/object:Gem::Specification
+name: lex-confabulation
+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: Confabulation detection and confidence calibration for brain-modeled
+  agentic AI
+email:
+- matthewdiverson@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- Gemfile
+- LICENSE
+- README.md
+- lex-confabulation.gemspec
+- lib/legion/extensions/confabulation.rb
+- lib/legion/extensions/confabulation/actors/decay.rb
+- lib/legion/extensions/confabulation/client.rb
+- lib/legion/extensions/confabulation/helpers/claim.rb
+- lib/legion/extensions/confabulation/helpers/confabulation_engine.rb
+- lib/legion/extensions/confabulation/helpers/constants.rb
+- lib/legion/extensions/confabulation/runners/confabulation.rb
+- lib/legion/extensions/confabulation/version.rb
+- spec/legion/extensions/confabulation/client_spec.rb
+- spec/legion/extensions/confabulation/helpers/claim_spec.rb
+- spec/legion/extensions/confabulation/helpers/confabulation_engine_spec.rb
+- spec/legion/extensions/confabulation/helpers/constants_spec.rb
+- spec/legion/extensions/confabulation/runners/confabulation_spec.rb
+- spec/spec_helper.rb
+homepage: https://github.com/LegionIO/lex-confabulation
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/LegionIO/lex-confabulation
+  source_code_uri: https://github.com/LegionIO/lex-confabulation
+  documentation_uri: https://github.com/LegionIO/lex-confabulation
+  changelog_uri: https://github.com/LegionIO/lex-confabulation
+  bug_tracker_uri: https://github.com/LegionIO/lex-confabulation/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 Confabulation
+test_files: []