lex-qualia 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 90d75ec1c119d5845728a944d020abb717b6db31563bb414137c699e59e30359
+  data.tar.gz: ce574fbede579585641bd4849e55ea43a82511226c1df03daeb3924bcf6fe618
+SHA512:
+  metadata.gz: '03910f6dd5f0234a0a99b232c8b8217caaee6f0fb2d1f5bcc5fb50ddfe797f9b16f4226c3382a59004e61ba1cf0d77727b5a466d7b4c34ceee6cd212d53242c7'
+  data.tar.gz: ddeea4d67e15449bca97dac7125799859ea663045146544d6ac4f1b4fb3b3921c38f86e573961e7f31b6ee028768e845494973870d3de5518bd592472c4e1eb3

data/.github/workflows/ci.yml

@@ -0,0 +1,16 @@
+name: CI
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  ci:
+    uses: LegionIO/.github/.github/workflows/ci.yml@main
+
+  release:
+    needs: ci
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    uses: LegionIO/.github/.github/workflows/release.yml@main
+    secrets:
+      rubygems-api-key: ${{ secrets.RUBYGEMS_API_KEY }}

data/.gitignore

@@ -0,0 +1,10 @@
+*.gem
+*.rbc
+.bundle
+.config
+coverage
+pkg
+spec/reports
+tmp
+Gemfile.lock
+.rspec_status

data/.rspec

@@ -0,0 +1,3 @@
+--require spec_helper
+--format documentation
+--order random

data/.rubocop.yml

@@ -0,0 +1,37 @@
+AllCops:
+  NewCops: enable
+  TargetRubyVersion: 3.4
+
+Style/Documentation:
+  Enabled: false
+
+Naming/PredicateMethod:
+  Enabled: false
+
+Naming/PredicatePrefix:
+  Enabled: false
+
+Metrics/ClassLength:
+  Max: 150
+
+Metrics/MethodLength:
+  Max: 25
+
+Metrics/AbcSize:
+  Max: 25
+
+Metrics/ParameterLists:
+  Max: 8
+  MaxOptionalParameters: 8
+
+Layout/HashAlignment:
+  EnforcedColonStyle: table
+  EnforcedHashRocketStyle: table
+
+Metrics/BlockLength:
+  Exclude:
+    - spec/**/*
+
+Style/OneClassPerFile:
+  Exclude:
+    - spec/spec_helper.rb

data/CLAUDE.md

@@ -0,0 +1,87 @@
+# lex-qualia
+
+**Level 3 Leaf Documentation**
+- **Parent**: `/Users/miverso2/rubymine/legion/extensions-agentic/CLAUDE.md`
+- **Gem**: `lex-qualia`
+- **Version**: 0.1.0
+- **Namespace**: `Legion::Extensions::Qualia`
+
+## Purpose
+
+Phenomenal experience registry. Represents the subjective "what it is like" quality of the agent's processing. Each quale is defined by modality, quality, texture, vividness, and valence. Vividness decays; intense experiences are retained longer. Provides phenomenal richness scoring, experiential diversity, and qualitative classification of the agent's experience palette.
+
+## Gem Info
+
+- **Homepage**: https://github.com/LegionIO/lex-qualia
+- **License**: MIT
+- **Ruby**: >= 3.4
+
+## File Structure
+
+```
+lib/legion/extensions/qualia/
+  version.rb
+  client.rb
+  helpers/
+    constants.rb       # MODALITIES, PHENOMENAL_QUALITIES, TEXTURE_TYPES, thresholds, labels
+    quale.rb           # Quale class — single phenomenal experience
+    qualia_engine.rb   # QualiaEngine — experience registry and analysis
+  runners/
+    qualia.rb          # Runner module
+spec/
+  helpers/quale_spec.rb
+  helpers/qualia_engine_spec.rb
+  runners/qualia_spec.rb (runners_spec.rb)
+  client_spec.rb
+```
+
+## Key Constants
+
+From `Helpers::Constants`:
+- `MAX_EXPERIENCES = 500`, `MAX_PALETTE_SIZE = 100`
+- `DEFAULT_VIVIDNESS = 0.5`, `DEFAULT_VALENCE = 0.0`, `DEFAULT_TEXTURE = 0.5`
+- `VIVIDNESS_DECAY = 0.03`, `VIVIDNESS_BOOST = 0.1`
+- `VIVID_THRESHOLD = 0.7`, `FAINT_THRESHOLD = 0.2`, `INTENSE_THRESHOLD = 0.8`
+- `MODALITIES = %i[visual auditory tactile gustatory olfactory kinesthetic emotional abstract]`
+- `PHENOMENAL_QUALITIES = %i[sharp smooth warm cool heavy light bright dark flowing rigid pulsing still]`
+- `TEXTURE_TYPES = %i[crystalline fluid granular electric velvet metallic organic ethereal]`
+- `VIVIDNESS_LABELS`: `:overwhelming` (0.8+), `:vivid`, `:moderate`, `:faint`, `:ghost`
+- `VALENCE_LABELS`: `:pleasant` (>= 0.5), `:mildly_pleasant`, `:neutral`, `:mildly_unpleasant`, `:unpleasant`
+- `RICHNESS_LABELS`: `:synesthetic` (0.8+), `:rich`, `:moderate`, `:sparse`, `:flat`
+- `Constants.label_for(labels_hash, value)` module-level lookup method
+
+## Runners
+
+| Method | Key Parameters | Returns |
+|---|---|---|
+| `create_quale` | `content:`, `modality:`, `quality:`, `texture:`, `vividness:`, `valence:` | `{ success:, quale: }` |
+| `intensify_quale` | `quale_id:`, `amount:` | `{ success:, quale: }` |
+| `fade_all` | — | `{ success:, remaining: }` (decay + prune faint) |
+| `vivid_experiences` | — | `{ success:, count:, qualia: }` |
+| `by_modality` | `modality:` | `{ success:, count:, qualia: }` |
+| `phenomenal_richness` | — | `{ success:, richness:, label: }` |
+| `qualia_status` | — | full report: totals, vivid/faint/pleasant/unpleasant counts, avg vividness/valence, richness, most vivid |
+
+## Helpers
+
+### `Helpers::Quale`
+Single experience: `id`, `content`, `modality`, `quality`, `texture`, `vividness` (clamped 0–1), `valence` (clamped -1–1). `vivid?` = vividness >= 0.7. `faint?` = vividness <= 0.2. `intense?` = vividness >= 0.8. `pleasant?` = valence > 0.2. `unpleasant?` = valence < -0.2. `intensify!(amount:)` adds to vividness. `fade!` subtracts `VIVIDNESS_DECAY`. `phenomenal_richness` = vividness*0.5 + quality_bonus + texture_bonus.
+
+### `Helpers::QualiaEngine`
+Manages `@experiences` hash. `create_quale` prunes faint/weakest when at `MAX_EXPERIENCES`. `intensify(quale_id:, amount:)` delegates to quale. `fade_all!` decays all and prunes faint. `vivid_experiences`, `faint_experiences`, `intense_experiences`, `pleasant_experiences`, `unpleasant_experiences` filter by thresholds. `most_vivid(limit:)` sorts by vividness desc. `average_vividness`, `average_valence` mean over all. `phenomenal_richness` mean richness score. `modality_distribution` counts per modality. `quality_palette`, `texture_palette` tally by attribute. `experiential_diversity` = unique modalities / total modalities.
+
+## Integration Points
+
+- `create_quale` can accept perceptual binding output from `lex-phenomenal-binding`
+- Quale `valence` feeds `lex-emotion` as a secondary affective signal
+- `phenomenal_richness` can feed `lex-narrator` for prose richness modulation
+- `vivid_experiences` with negative valence feed `lex-cognitive-reappraisal` as reappraisal candidates
+- `fade_all` called each tick for natural experience fading
+
+## Development Notes
+
+- `phenomenal_richness` per quale = vividness*0.5 + quality_bonus + texture_bonus (texture/quality diversity bonuses)
+- Prune on capacity: first removes entries with vividness <= 0, then removes weakest if still over capacity
+- `qualia_status` uses `QualiaEngine#qualia_report` which calls `Constants.label_for` for richness label
+- `experiential_diversity` = unique modalities used / `MODALITIES.size`
+- All state is in-memory; reset on process restart

data/Gemfile

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gemspec
+
+gem 'rspec', '~> 3.13'
+gem 'rubocop', '~> 1.75'
+gem 'rubocop-rspec'
+
+gem 'legion-gaia', path: '../../legion-gaia'

data/README.md

@@ -0,0 +1,64 @@
+# lex-qualia
+
+Phenomenal experience registry for the LegionIO cognitive architecture. Represents and tracks the qualitative character of the agent's cognitive experiences.
+
+## What It Does
+
+Maintains a registry of qualia — the "what it is like" quality of experiences. Each quale is described by its sensory modality, phenomenal quality, texture, vividness, and emotional valence. Vividness decays naturally, with more intense experiences lasting longer. Provides richness scoring across the experience space and qualitative analysis of the agent's current phenomenal palette.
+
+## Usage
+
+```ruby
+client = Legion::Extensions::Qualia::Client.new
+
+# Register a phenomenal experience
+q = client.create_quale(
+  content:   'processing a novel algorithm',
+  modality:  :abstract,
+  quality:   :sharp,
+  texture:   :crystalline,
+  vividness: 0.8,
+  valence:   0.3
+)
+quale_id = q[:quale][:id]
+
+# Intensify with attention
+client.intensify_quale(quale_id: quale_id, amount: 0.1)
+
+# Query current experiences
+client.vivid_experiences
+client.by_modality(modality: :abstract)
+
+# Phenomenal richness (diversity and vividness score)
+client.phenomenal_richness
+# => { success: true, richness: 0.42, label: :moderate }
+
+# Full status report
+client.qualia_status
+# => { success: true, total_experiences: 1, vivid_count: 1, faint_count: 0,
+#      average_vividness: 0.9, phenomenal_richness: 0.42, richness_label: :moderate,
+#      most_vivid: [...] }
+
+# Periodic fade (vividness decays)
+client.fade_all
+```
+
+## Modalities
+
+`:visual`, `:auditory`, `:tactile`, `:gustatory`, `:olfactory`, `:kinesthetic`, `:emotional`, `:abstract`
+
+## Richness Labels
+
+`:synesthetic` (>= 0.8), `:rich`, `:moderate`, `:sparse`, `:flat`
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
+## License
+
+MIT

data/lex-qualia.gemspec

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative 'lib/legion/extensions/qualia/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'lex-qualia'
+  spec.version       = Legion::Extensions::Qualia::VERSION
+  spec.authors       = ['Esity']
+  spec.email         = ['matthewdiverson@gmail.com']
+  spec.summary       = 'Subjective phenomenal experience simulation for LegionIO agents'
+  spec.description   = 'Models qualia — the subjective phenomenal qualities of experience ' \
+                       'with vividness, valence, texture, and modality for the LegionIO architecture'
+  spec.homepage      = 'https://github.com/LegionIO/lex-qualia'
+  spec.license       = 'MIT'
+  spec.required_ruby_version = '>= 3.4'
+
+  spec.metadata = {
+    'homepage_uri'          => spec.homepage,
+    'source_code_uri'       => spec.homepage,
+    'documentation_uri'     => "#{spec.homepage}/blob/origin/README.md",
+    'changelog_uri'         => "#{spec.homepage}/blob/origin/CHANGELOG.md",
+    'bug_tracker_uri'       => "#{spec.homepage}/issues",
+    'rubygems_mfa_required' => 'true'
+  }
+
+  spec.files = Dir.chdir(__dir__) { `git ls-files -z`.split("\x0") }
+  spec.require_paths = ['lib']
+  spec.add_development_dependency 'legion-gaia'
+end

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

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Qualia
+      class Client
+        include Runners::Qualia
+
+        def initialize
+          @default_engine = Helpers::QualiaEngine.new
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Qualia
+      module Helpers
+        module Constants
+          MAX_EXPERIENCES = 500
+          MAX_PALETTE_SIZE = 100
+
+          # Phenomenal dimensions
+          DEFAULT_VIVIDNESS = 0.5
+          DEFAULT_VALENCE = 0.0
+          DEFAULT_TEXTURE = 0.5
+          VIVIDNESS_DECAY = 0.03
+          VIVIDNESS_BOOST = 0.1
+
+          # Thresholds
+          VIVID_THRESHOLD = 0.7
+          FAINT_THRESHOLD = 0.2
+          INTENSE_THRESHOLD = 0.8
+
+          PHENOMENAL_QUALITIES = %i[
+            sharp smooth warm cool heavy light
+            bright dark flowing rigid pulsing still
+          ].freeze
+
+          TEXTURE_TYPES = %i[
+            crystalline fluid granular electric
+            velvet metallic organic ethereal
+          ].freeze
+
+          MODALITIES = %i[
+            visual auditory tactile gustatory
+            olfactory kinesthetic emotional abstract
+          ].freeze
+
+          VIVIDNESS_LABELS = {
+            (0.8..)     => :overwhelming,
+            (0.6...0.8) => :vivid,
+            (0.4...0.6) => :moderate,
+            (0.2...0.4) => :faint,
+            (..0.2)     => :ghost
+          }.freeze
+
+          VALENCE_LABELS = {
+            (0.5..)       => :pleasant,
+            (0.2...0.5)   => :mildly_pleasant,
+            (-0.2...0.2)  => :neutral,
+            (-0.5...-0.2) => :mildly_unpleasant,
+            (..-0.5)      => :unpleasant
+          }.freeze
+
+          RICHNESS_LABELS = {
+            (0.8..)     => :synesthetic,
+            (0.6...0.8) => :rich,
+            (0.4...0.6) => :moderate,
+            (0.2...0.4) => :sparse,
+            (..0.2)     => :flat
+          }.freeze
+
+          def self.label_for(labels, value)
+            labels.each { |range, label| return label if range.cover?(value) }
+            :unknown
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/qualia/helpers/quale.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module Qualia
+      module Helpers
+        class Quale
+          include Constants
+
+          attr_reader :id, :content, :modality, :quality, :texture,
+                      :valence, :original_vividness, :created_at
+          attr_accessor :vividness
+
+          def initialize(content:, modality: :abstract, quality: :smooth, texture: :fluid,
+                         vividness: DEFAULT_VIVIDNESS, valence: DEFAULT_VALENCE)
+            @id = SecureRandom.uuid
+            @content = content.to_s
+            @modality = valid_modality(modality)
+            @quality = valid_quality(quality)
+            @texture = valid_texture(texture)
+            @vividness = vividness.to_f.clamp(0.0, 1.0).round(10)
+            @original_vividness = @vividness
+            @valence = valence.to_f.clamp(-1.0, 1.0).round(10)
+            @created_at = Time.now
+          end
+
+          def intensify!(amount: VIVIDNESS_BOOST)
+            @vividness = (@vividness + amount).clamp(0.0, 1.0).round(10)
+            self
+          end
+
+          def fade!
+            @vividness = (@vividness - VIVIDNESS_DECAY).clamp(0.0, 1.0).round(10)
+            self
+          end
+
+          def vivid? = @vividness >= VIVID_THRESHOLD
+          def faint? = @vividness <= FAINT_THRESHOLD
+          def intense? = @vividness >= INTENSE_THRESHOLD
+          def pleasant? = @valence > 0.2
+          def unpleasant? = @valence < -0.2
+          def neutral_valence? = @valence.abs <= 0.2
+
+          def phenomenal_richness
+            base = @vividness * 0.5
+            quality_bonus = PHENOMENAL_QUALITIES.index(@quality).to_f / PHENOMENAL_QUALITIES.size * 0.25
+            texture_bonus = TEXTURE_TYPES.index(@texture).to_f / TEXTURE_TYPES.size * 0.25
+            (base + quality_bonus + texture_bonus).clamp(0.0, 1.0).round(10)
+          end
+
+          def persistence = (@vividness / [@original_vividness, 0.01].max).clamp(0.0, 1.0).round(10)
+          def vividness_label = Constants.label_for(VIVIDNESS_LABELS, @vividness)
+          def valence_label = Constants.label_for(VALENCE_LABELS, @valence)
+          def richness_label = Constants.label_for(RICHNESS_LABELS, phenomenal_richness)
+
+          def to_h
+            {
+              id:                  @id,
+              content:             @content,
+              modality:            @modality,
+              quality:             @quality,
+              texture:             @texture,
+              vividness:           @vividness,
+              original_vividness:  @original_vividness,
+              valence:             @valence,
+              phenomenal_richness: phenomenal_richness,
+              vivid:               vivid?,
+              faint:               faint?,
+              intense:             intense?,
+              vividness_label:     vividness_label,
+              valence_label:       valence_label,
+              persistence:         persistence,
+              created_at:          @created_at.iso8601
+            }
+          end
+
+          private
+
+          def valid_modality(mod)
+            sym = mod.to_sym
+            MODALITIES.include?(sym) ? sym : :abstract
+          end
+
+          def valid_quality(qual)
+            sym = qual.to_sym
+            PHENOMENAL_QUALITIES.include?(sym) ? sym : :smooth
+          end
+
+          def valid_texture(tex)
+            sym = tex.to_sym
+            TEXTURE_TYPES.include?(sym) ? sym : :fluid
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/qualia/helpers/qualia_engine.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Qualia
+      module Helpers
+        class QualiaEngine
+          include Constants
+
+          def initialize
+            @experiences = {}
+          end
+
+          def create_quale(content:, modality: :abstract, quality: :smooth, texture: :fluid,
+                           vividness: DEFAULT_VIVIDNESS, valence: DEFAULT_VALENCE)
+            prune_faint
+            quale = Quale.new(content: content, modality: modality, quality: quality,
+                              texture: texture, vividness: vividness, valence: valence)
+            @experiences[quale.id] = quale
+            quale
+          end
+
+          def intensify(quale_id:, amount: VIVIDNESS_BOOST)
+            quale = @experiences[quale_id]
+            return nil unless quale
+
+            quale.intensify!(amount: amount)
+            quale
+          end
+
+          def fade_all!
+            @experiences.each_value(&:fade!)
+            prune_faint
+            { remaining: @experiences.size }
+          end
+
+          def vivid_experiences = @experiences.values.select(&:vivid?)
+          def faint_experiences = @experiences.values.select(&:faint?)
+          def intense_experiences = @experiences.values.select(&:intense?)
+
+          def by_modality(modality:)
+            @experiences.values.select { |q| q.modality == modality.to_sym }
+          end
+
+          def by_quality(quality:)
+            @experiences.values.select { |q| q.quality == quality.to_sym }
+          end
+
+          def by_texture(texture:)
+            @experiences.values.select { |q| q.texture == texture.to_sym }
+          end
+
+          def pleasant_experiences = @experiences.values.select(&:pleasant?)
+          def unpleasant_experiences = @experiences.values.select(&:unpleasant?)
+
+          def most_vivid(limit: 5) = @experiences.values.sort_by { |q| -q.vividness }.first(limit)
+
+          def average_vividness
+            return 0.0 if @experiences.empty?
+
+            (@experiences.values.sum(&:vividness) / @experiences.size).round(10)
+          end
+
+          def average_valence
+            return 0.0 if @experiences.empty?
+
+            (@experiences.values.sum(&:valence) / @experiences.size).round(10)
+          end
+
+          def phenomenal_richness
+            return 0.0 if @experiences.empty?
+
+            (@experiences.values.sum(&:phenomenal_richness) / @experiences.size).round(10)
+          end
+
+          def modality_distribution
+            MODALITIES.to_h do |mod|
+              [mod, @experiences.values.count { |q| q.modality == mod }]
+            end
+          end
+
+          def quality_palette
+            @experiences.values.map(&:quality).tally.sort_by { |_, v| -v }.to_h
+          end
+
+          def texture_palette
+            @experiences.values.map(&:texture).tally.sort_by { |_, v| -v }.to_h
+          end
+
+          def experiential_diversity
+            return 0.0 if @experiences.empty?
+
+            modalities_used = @experiences.values.map(&:modality).uniq.size
+            (modalities_used.to_f / MODALITIES.size).clamp(0.0, 1.0).round(10)
+          end
+
+          def qualia_report
+            {
+              total_experiences:      @experiences.size,
+              vivid_count:            vivid_experiences.size,
+              faint_count:            faint_experiences.size,
+              pleasant_count:         pleasant_experiences.size,
+              unpleasant_count:       unpleasant_experiences.size,
+              average_vividness:      average_vividness,
+              average_valence:        average_valence,
+              phenomenal_richness:    phenomenal_richness,
+              experiential_diversity: experiential_diversity,
+              richness_label:         Constants.label_for(RICHNESS_LABELS, phenomenal_richness),
+              most_vivid:             most_vivid(limit: 3).map(&:to_h)
+            }
+          end
+
+          def to_h
+            {
+              total_experiences: @experiences.size,
+              vivid:             vivid_experiences.size,
+              avg_vividness:     average_vividness,
+              avg_valence:       average_valence,
+              richness:          phenomenal_richness
+            }
+          end
+
+          private
+
+          def prune_faint
+            return if @experiences.size < MAX_EXPERIENCES
+
+            @experiences.reject! { |_, q| q.vividness <= 0.0 }
+            return unless @experiences.size >= MAX_EXPERIENCES
+
+            weakest = @experiences.values.min_by(&:vividness)
+            @experiences.delete(weakest.id) if weakest
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Qualia
+      module Runners
+        module Qualia
+          include Legion::Extensions::Helpers::Lex if defined?(Legion::Extensions::Helpers::Lex)
+
+          def create_quale(content:, modality: :abstract, quality: :smooth, texture: :fluid, vividness: nil,
+                           valence: nil, engine: nil, **)
+            eng = engine || @default_engine
+            quale = eng.create_quale(content: content, modality: modality, quality: quality,
+                                     texture: texture,
+                                     vividness: vividness || Helpers::Constants::DEFAULT_VIVIDNESS,
+                                     valence: valence || Helpers::Constants::DEFAULT_VALENCE)
+            { success: true, quale: quale.to_h }
+          end
+
+          def intensify_quale(quale_id:, amount: nil, engine: nil, **)
+            eng = engine || @default_engine
+            quale = eng.intensify(quale_id: quale_id,
+                                  amount:   amount || Helpers::Constants::VIVIDNESS_BOOST)
+            return { success: false, error: 'quale not found' } unless quale
+
+            { success: true, quale: quale.to_h }
+          end
+
+          def fade_all(engine: nil, **)
+            eng = engine || @default_engine
+            result = eng.fade_all!
+            { success: true, **result }
+          end
+
+          def vivid_experiences(engine: nil, **)
+            eng = engine || @default_engine
+            qualia = eng.vivid_experiences
+            { success: true, count: qualia.size, qualia: qualia.map(&:to_h) }
+          end
+
+          def by_modality(modality:, engine: nil, **)
+            eng = engine || @default_engine
+            qualia = eng.by_modality(modality: modality)
+            { success: true, count: qualia.size, qualia: qualia.map(&:to_h) }
+          end
+
+          def phenomenal_richness(engine: nil, **)
+            eng = engine || @default_engine
+            richness = eng.phenomenal_richness
+            label = Helpers::Constants.label_for(Helpers::Constants::RICHNESS_LABELS, richness)
+            { success: true, richness: richness, label: label }
+          end
+
+          def qualia_status(engine: nil, **)
+            eng = engine || @default_engine
+            report = eng.qualia_report
+            { success: true, **report }
+          end
+        end
+      end
+    end
+  end
+end

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

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

data/lib/legion/extensions/qualia.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require_relative 'qualia/version'
+require_relative 'qualia/helpers/constants'
+require_relative 'qualia/helpers/quale'
+require_relative 'qualia/helpers/qualia_engine'
+require_relative 'qualia/runners/qualia'
+require_relative 'qualia/client'
+
+module Legion
+  module Extensions
+    module Qualia
+    end
+  end
+end

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

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Qualia::Client do
+  subject(:client) { described_class.new }
+
+  it 'responds to runner methods' do
+    expect(client).to respond_to(:create_quale, :fade_all, :qualia_status)
+  end
+
+  it 'runs a full qualia lifecycle' do
+    result = client.create_quale(content: 'sharp insight', modality: :emotional,
+                                 quality: :sharp, texture: :crystalline, vividness: 0.8)
+    quale_id = result[:quale][:id]
+
+    client.intensify_quale(quale_id: quale_id)
+    client.fade_all
+
+    status = client.qualia_status
+    expect(status[:total_experiences]).to eq(1)
+  end
+end

data/spec/legion/extensions/qualia/helpers/quale_spec.rb

@@ -0,0 +1,168 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Qualia::Helpers::Quale do
+  subject(:quale) { described_class.new(content: 'warmth of recognition') }
+
+  describe '#initialize' do
+    it 'assigns a UUID id' do
+      expect(quale.id).to match(/\A[0-9a-f-]{36}\z/)
+    end
+
+    it 'stores content' do
+      expect(quale.content).to eq('warmth of recognition')
+    end
+
+    it 'defaults modality to :abstract' do
+      expect(quale.modality).to eq(:abstract)
+    end
+
+    it 'defaults quality to :smooth' do
+      expect(quale.quality).to eq(:smooth)
+    end
+
+    it 'defaults texture to :fluid' do
+      expect(quale.texture).to eq(:fluid)
+    end
+
+    it 'defaults vividness' do
+      expect(quale.vividness).to eq(0.5)
+    end
+
+    it 'defaults valence to 0.0' do
+      expect(quale.valence).to eq(0.0)
+    end
+
+    it 'clamps vividness' do
+      high = described_class.new(content: 'x', vividness: 5.0)
+      expect(high.vividness).to eq(1.0)
+    end
+
+    it 'clamps valence' do
+      extreme = described_class.new(content: 'x', valence: -5.0)
+      expect(extreme.valence).to eq(-1.0)
+    end
+
+    it 'validates modality' do
+      bad = described_class.new(content: 'x', modality: :nonexistent)
+      expect(bad.modality).to eq(:abstract)
+    end
+
+    it 'validates quality' do
+      bad = described_class.new(content: 'x', quality: :nonexistent)
+      expect(bad.quality).to eq(:smooth)
+    end
+
+    it 'validates texture' do
+      bad = described_class.new(content: 'x', texture: :nonexistent)
+      expect(bad.texture).to eq(:fluid)
+    end
+  end
+
+  describe '#intensify!' do
+    it 'increases vividness' do
+      original = quale.vividness
+      quale.intensify!
+      expect(quale.vividness).to be > original
+    end
+
+    it 'clamps at 1.0' do
+      20.times { quale.intensify! }
+      expect(quale.vividness).to eq(1.0)
+    end
+  end
+
+  describe '#fade!' do
+    it 'decreases vividness' do
+      original = quale.vividness
+      quale.fade!
+      expect(quale.vividness).to be < original
+    end
+
+    it 'clamps at 0.0' do
+      50.times { quale.fade! }
+      expect(quale.vividness).to eq(0.0)
+    end
+  end
+
+  describe '#vivid?' do
+    it 'is false at default vividness' do
+      expect(quale.vivid?).to be false
+    end
+
+    it 'is true when vivid' do
+      vivid = described_class.new(content: 'x', vividness: 0.8)
+      expect(vivid.vivid?).to be true
+    end
+  end
+
+  describe '#faint?' do
+    it 'is false at default vividness' do
+      expect(quale.faint?).to be false
+    end
+
+    it 'is true when faint' do
+      faint = described_class.new(content: 'x', vividness: 0.1)
+      expect(faint.faint?).to be true
+    end
+  end
+
+  describe '#intense?' do
+    it 'is true when very vivid' do
+      intense = described_class.new(content: 'x', vividness: 0.9)
+      expect(intense.intense?).to be true
+    end
+  end
+
+  describe '#pleasant?' do
+    it 'is true for positive valence' do
+      pleasant = described_class.new(content: 'x', valence: 0.5)
+      expect(pleasant.pleasant?).to be true
+    end
+
+    it 'is false for negative valence' do
+      expect(quale.pleasant?).to be false
+    end
+  end
+
+  describe '#unpleasant?' do
+    it 'is true for negative valence' do
+      unpleasant = described_class.new(content: 'x', valence: -0.5)
+      expect(unpleasant.unpleasant?).to be true
+    end
+  end
+
+  describe '#neutral_valence?' do
+    it 'is true at default valence' do
+      expect(quale.neutral_valence?).to be true
+    end
+  end
+
+  describe '#phenomenal_richness' do
+    it 'returns a value between 0 and 1' do
+      expect(quale.phenomenal_richness).to be_between(0.0, 1.0)
+    end
+  end
+
+  describe '#persistence' do
+    it 'is 1.0 initially' do
+      expect(quale.persistence).to eq(1.0)
+    end
+
+    it 'decreases after fading' do
+      quale.fade!
+      expect(quale.persistence).to be < 1.0
+    end
+  end
+
+  describe '#to_h' do
+    it 'includes all fields' do
+      hash = quale.to_h
+      expect(hash).to include(
+        :id, :content, :modality, :quality, :texture, :vividness,
+        :original_vividness, :valence, :phenomenal_richness,
+        :vivid, :faint, :intense, :vividness_label, :valence_label,
+        :persistence, :created_at
+      )
+    end
+  end
+end

data/spec/legion/extensions/qualia/helpers/qualia_engine_spec.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Qualia::Helpers::QualiaEngine do
+  subject(:engine) { described_class.new }
+
+  describe '#create_quale' do
+    it 'creates and stores a quale' do
+      quale = engine.create_quale(content: 'sharpness of insight')
+      expect(quale.content).to eq('sharpness of insight')
+    end
+  end
+
+  describe '#intensify' do
+    it 'increases vividness' do
+      quale = engine.create_quale(content: 'test')
+      original = quale.vividness
+      engine.intensify(quale_id: quale.id)
+      expect(quale.vividness).to be > original
+    end
+
+    it 'returns nil for unknown quale' do
+      expect(engine.intensify(quale_id: 'bad')).to be_nil
+    end
+  end
+
+  describe '#fade_all!' do
+    it 'fades all qualia' do
+      quale = engine.create_quale(content: 'test')
+      original = quale.vividness
+      engine.fade_all!
+      expect(quale.vividness).to be < original
+    end
+  end
+
+  describe '#vivid_experiences' do
+    it 'returns vivid qualia' do
+      engine.create_quale(content: 'vivid', vividness: 0.8)
+      engine.create_quale(content: 'faint', vividness: 0.2)
+      expect(engine.vivid_experiences.size).to eq(1)
+    end
+  end
+
+  describe '#faint_experiences' do
+    it 'returns faint qualia' do
+      engine.create_quale(content: 'faint', vividness: 0.1)
+      expect(engine.faint_experiences.size).to eq(1)
+    end
+  end
+
+  describe '#by_modality' do
+    it 'filters by modality' do
+      engine.create_quale(content: 'a', modality: :visual)
+      engine.create_quale(content: 'b', modality: :auditory)
+      expect(engine.by_modality(modality: :visual).size).to eq(1)
+    end
+  end
+
+  describe '#by_quality' do
+    it 'filters by quality' do
+      engine.create_quale(content: 'a', quality: :sharp)
+      engine.create_quale(content: 'b', quality: :warm)
+      expect(engine.by_quality(quality: :sharp).size).to eq(1)
+    end
+  end
+
+  describe '#by_texture' do
+    it 'filters by texture' do
+      engine.create_quale(content: 'a', texture: :metallic)
+      engine.create_quale(content: 'b', texture: :velvet)
+      expect(engine.by_texture(texture: :metallic).size).to eq(1)
+    end
+  end
+
+  describe '#pleasant_experiences' do
+    it 'returns pleasant qualia' do
+      engine.create_quale(content: 'nice', valence: 0.5)
+      engine.create_quale(content: 'bad', valence: -0.5)
+      expect(engine.pleasant_experiences.size).to eq(1)
+    end
+  end
+
+  describe '#unpleasant_experiences' do
+    it 'returns unpleasant qualia' do
+      engine.create_quale(content: 'bad', valence: -0.5)
+      expect(engine.unpleasant_experiences.size).to eq(1)
+    end
+  end
+
+  describe '#most_vivid' do
+    it 'returns sorted by vividness descending' do
+      engine.create_quale(content: 'dim', vividness: 0.3)
+      bright = engine.create_quale(content: 'bright', vividness: 0.9)
+      expect(engine.most_vivid(limit: 1).first.id).to eq(bright.id)
+    end
+  end
+
+  describe '#average_vividness' do
+    it 'returns 0.0 with no qualia' do
+      expect(engine.average_vividness).to eq(0.0)
+    end
+
+    it 'computes average' do
+      engine.create_quale(content: 'a', vividness: 0.4)
+      engine.create_quale(content: 'b', vividness: 0.6)
+      expect(engine.average_vividness).to eq(0.5)
+    end
+  end
+
+  describe '#average_valence' do
+    it 'returns 0.0 with no qualia' do
+      expect(engine.average_valence).to eq(0.0)
+    end
+  end
+
+  describe '#phenomenal_richness' do
+    it 'returns 0.0 with no qualia' do
+      expect(engine.phenomenal_richness).to eq(0.0)
+    end
+
+    it 'returns positive with qualia' do
+      engine.create_quale(content: 'test', vividness: 0.8)
+      expect(engine.phenomenal_richness).to be > 0.0
+    end
+  end
+
+  describe '#modality_distribution' do
+    it 'returns counts per modality' do
+      engine.create_quale(content: 'a', modality: :visual)
+      dist = engine.modality_distribution
+      expect(dist[:visual]).to eq(1)
+      expect(dist[:auditory]).to eq(0)
+    end
+  end
+
+  describe '#experiential_diversity' do
+    it 'returns 0.0 with no qualia' do
+      expect(engine.experiential_diversity).to eq(0.0)
+    end
+
+    it 'increases with diverse modalities' do
+      engine.create_quale(content: 'a', modality: :visual)
+      engine.create_quale(content: 'b', modality: :auditory)
+      expect(engine.experiential_diversity).to be > 0.0
+    end
+  end
+
+  describe '#quality_palette' do
+    it 'returns quality frequencies' do
+      engine.create_quale(content: 'a', quality: :sharp)
+      engine.create_quale(content: 'b', quality: :sharp)
+      palette = engine.quality_palette
+      expect(palette[:sharp]).to eq(2)
+    end
+  end
+
+  describe '#qualia_report' do
+    it 'includes all report fields' do
+      report = engine.qualia_report
+      expect(report).to include(
+        :total_experiences, :vivid_count, :faint_count,
+        :pleasant_count, :unpleasant_count, :average_vividness,
+        :average_valence, :phenomenal_richness, :experiential_diversity,
+        :richness_label, :most_vivid
+      )
+    end
+  end
+
+  describe '#to_h' do
+    it 'includes summary fields' do
+      hash = engine.to_h
+      expect(hash).to include(:total_experiences, :vivid, :avg_vividness, :avg_valence, :richness)
+    end
+  end
+end

data/spec/legion/extensions/qualia/runners_spec.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Qualia::Runners::Qualia do
+  let(:engine) { Legion::Extensions::Qualia::Helpers::QualiaEngine.new }
+  let(:runner) do
+    obj = Object.new
+    obj.extend(described_class)
+    obj.instance_variable_set(:@default_engine, engine)
+    obj
+  end
+
+  describe '#create_quale' do
+    it 'returns success with quale hash' do
+      result = runner.create_quale(content: 'test', engine: engine)
+      expect(result[:success]).to be true
+      expect(result[:quale][:content]).to eq('test')
+    end
+  end
+
+  describe '#intensify_quale' do
+    it 'returns success for known quale' do
+      quale = engine.create_quale(content: 'test')
+      result = runner.intensify_quale(quale_id: quale.id, engine: engine)
+      expect(result[:success]).to be true
+    end
+
+    it 'returns failure for unknown quale' do
+      result = runner.intensify_quale(quale_id: 'bad', engine: engine)
+      expect(result[:success]).to be false
+    end
+  end
+
+  describe '#fade_all' do
+    it 'returns success' do
+      result = runner.fade_all(engine: engine)
+      expect(result[:success]).to be true
+    end
+  end
+
+  describe '#vivid_experiences' do
+    it 'returns vivid list' do
+      engine.create_quale(content: 'vivid', vividness: 0.8)
+      result = runner.vivid_experiences(engine: engine)
+      expect(result[:count]).to eq(1)
+    end
+  end
+
+  describe '#by_modality' do
+    it 'filters by modality' do
+      engine.create_quale(content: 'a', modality: :visual)
+      result = runner.by_modality(modality: :visual, engine: engine)
+      expect(result[:count]).to eq(1)
+    end
+  end
+
+  describe '#phenomenal_richness' do
+    it 'returns richness level' do
+      result = runner.phenomenal_richness(engine: engine)
+      expect(result[:success]).to be true
+    end
+  end
+
+  describe '#qualia_status' do
+    it 'returns comprehensive status' do
+      result = runner.qualia_status(engine: engine)
+      expect(result[:success]).to be true
+      expect(result).to include(:total_experiences, :phenomenal_richness)
+    end
+  end
+end

data/spec/legion/extensions/qualia_spec.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Qualia do
+  it 'has a version number' do
+    expect(Legion::Extensions::Qualia::VERSION).to eq('0.1.0')
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/qualia'
+
+module Legion
+  module Extensions
+    module Helpers
+      module Lex; end
+    end
+  end
+
+  module Logging
+    def self.method_missing(_, *) = nil
+    def self.respond_to_missing?(_, _ = false) = true
+  end
+end
+
+RSpec.configure do |config|
+  config.expect_with :rspec do |expectations|
+    expectations.include_chain_clauses_in_custom_matcher_descriptions = true
+  end
+  config.mock_with :rspec do |mocks|
+    mocks.verify_partial_doubles = true
+  end
+  config.shared_context_metadata_behavior = :apply_to_host_groups
+  config.order = :random
+  Kernel.srand config.seed
+end

metadata

@@ -0,0 +1,82 @@
+--- !ruby/object:Gem::Specification
+name: lex-qualia
+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: Models qualia — the subjective phenomenal qualities of experience with
+  vividness, valence, texture, and modality for the LegionIO architecture
+email:
+- matthewdiverson@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".github/workflows/ci.yml"
+- ".gitignore"
+- ".rspec"
+- ".rubocop.yml"
+- CLAUDE.md
+- Gemfile
+- README.md
+- lex-qualia.gemspec
+- lib/legion/extensions/qualia.rb
+- lib/legion/extensions/qualia/client.rb
+- lib/legion/extensions/qualia/helpers/constants.rb
+- lib/legion/extensions/qualia/helpers/quale.rb
+- lib/legion/extensions/qualia/helpers/qualia_engine.rb
+- lib/legion/extensions/qualia/runners/qualia.rb
+- lib/legion/extensions/qualia/version.rb
+- spec/legion/extensions/qualia/client_spec.rb
+- spec/legion/extensions/qualia/helpers/quale_spec.rb
+- spec/legion/extensions/qualia/helpers/qualia_engine_spec.rb
+- spec/legion/extensions/qualia/runners_spec.rb
+- spec/legion/extensions/qualia_spec.rb
+- spec/spec_helper.rb
+homepage: https://github.com/LegionIO/lex-qualia
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/LegionIO/lex-qualia
+  source_code_uri: https://github.com/LegionIO/lex-qualia
+  documentation_uri: https://github.com/LegionIO/lex-qualia/blob/origin/README.md
+  changelog_uri: https://github.com/LegionIO/lex-qualia/blob/origin/CHANGELOG.md
+  bug_tracker_uri: https://github.com/LegionIO/lex-qualia/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: Subjective phenomenal experience simulation for LegionIO agents
+test_files: []