lex-cognitive-fermentation 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 4ea50c03dfbb3796b24114e8395d00e9a70bbc9efd2801912528f909f931ea39
+  data.tar.gz: ee361053997fc4d64fdcd522abb6ff406a621d190b8c7002c8b7ac2cdaf11fc5
+SHA512:
+  metadata.gz: e35f786a95a757afb400bc8827ee11fe685f37514a657afe4c05132cb18d6a987bdba670690f5afff19896a6d0b0d5b3d02f87f9aa2dc9fd0ed704eeee9abf1a
+  data.tar.gz: 55444692dc3361b8c1ef6272d59a94767bc69ad603215d0fd1feaf2d6622ad2d7e85ee5894ec01c7aeb6e895ae71744fc4649ccb51900d281187535d4066159f

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,2 @@
+.rspec_status
+Gemfile.lock

data/.rspec

@@ -0,0 +1,2 @@
+--require spec_helper
+--format documentation

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,117 @@
+# lex-cognitive-fermentation
+
+**Level 3 Leaf Documentation**
+- **Parent**: `/Users/miverso2/rubymine/legion/extensions-agentic/CLAUDE.md`
+- **Gem**: `lex-cognitive-fermentation`
+
+## Purpose
+
+Models slow, non-linear cognitive maturation using a fermentation metaphor. Raw, unresolved, or partial cognitive material (substrates) ferments over time, developing potency and maturity through natural processing and catalysis. When substrates reach peak stage, they are ready for use or harvest. Over-fermented substrates decay. Domain-grouped batches track collective fermentation progress.
+
+## Gem Info
+
+| Field | Value |
+|---|---|
+| Gem name | `lex-cognitive-fermentation` |
+| Version | `0.1.0` |
+| Namespace | `Legion::Extensions::CognitiveFermentation` |
+| Ruby | `>= 3.4` |
+| License | MIT |
+| GitHub | https://github.com/LegionIO/lex-cognitive-fermentation |
+
+## File Structure
+
+```
+lib/legion/extensions/cognitive_fermentation/
+  cognitive_fermentation.rb         # Top-level require
+  version.rb                        # VERSION = '0.1.0'
+  client.rb                         # Client class
+  helpers/
+    constants.rb                    # Types, stages, rates, label hashes
+    substrate.rb                    # Substrate value object
+    batch.rb                        # Batch (domain group) value object
+    fermentation_engine.rb          # Engine: substrates + batches
+  runners/
+    cognitive_fermentation.rb       # Runner module
+```
+
+## Key Constants
+
+| Constant | Value | Meaning |
+|---|---|---|
+| `MAX_SUBSTRATES` | 500 | Hard cap; evicts spoiled then lowest-potency |
+| `MAX_BATCHES` | 50 | Batch cap |
+| `MATURATION_RATE` | 0.05 | Default fermentation step size |
+| `CATALYSIS_BOOST` | 0.12 | Potency boost from catalyst application |
+| `SPOILAGE_THRESHOLD` | 0.1 | Potency below this = spoiled |
+| `RIPE_THRESHOLD` | 0.7 | Potency above this = ripe |
+| `PEAK_THRESHOLD` | 0.9 | Potency above this = peak |
+| `OVER_FERMENTED_DECAY` | 0.03 | Post-peak potency loss rate |
+| `SUBSTRATE_TYPES` | array | `raw_idea`, `unresolved_problem`, `partial_pattern`, etc. |
+| `FERMENTATION_STAGES` | array | `inoculation` through `over_fermented` |
+| `CATALYST_TYPES` | array | `analogy`, `contrast`, `emotional_charge`, `dream_residue`, etc. |
+
+## Helpers
+
+### `Substrate`
+
+Tracks the fermentation state of a single cognitive material unit.
+
+- `initialize(substrate_type:, domain:, content:, potency: nil, volatility: nil)`
+- `ferment!(rate)` — advances maturity and potency by rate; transitions stage
+- `catalyze!(catalyst_type)` — boosts potency by `CATALYSIS_BOOST` if valid catalyst
+- `ripe?`, `peak?`, `spoiled?`, `raw?` — state predicates
+- `to_h` — includes stage, potency, maturity, volatility, labels
+
+### `Batch`
+
+Groups substrates by domain.
+
+- `add_substrate(substrate)`
+- `ferment_all!(rate)` — delegates to each substrate
+
+### `FermentationEngine`
+
+Manages substrates and batches.
+
+- `create_substrate(substrate_type:, domain:, content:, potency: nil, volatility: nil)` — auto-assigns to batch; prunes when at cap
+- `ferment(substrate_id:, rate: MATURATION_RATE)` — single substrate advance
+- `catalyze(substrate_id:, catalyst_type:)` — catalyzes single substrate
+- `ferment_all!(rate: MATURATION_RATE)` — advances all batches
+- `substrates_by_domain(domain:)`, `substrates_by_type(type:)`, `substrates_by_stage(stage:)`
+- `ripe_substrates`, `peak_substrates`, `spoiled_substrates`, `raw_substrates`
+- `most_potent(limit: 5)`, `most_mature(limit: 5)`
+- `overall_potency`, `overall_maturity`, `overall_volatility`, `yield_rate`, `stage_distribution`
+- `fermentation_report` — full stats with labels and top substrates
+
+## Runners
+
+**Module**: `Legion::Extensions::CognitiveFermentation::Runners::CognitiveFermentation`
+
+| Method | Key Args | Returns |
+|---|---|---|
+| `create_substrate` | `substrate_type:`, `domain:`, `content:` | `{ success:, substrate: }` |
+| `ferment` | `substrate_id:`, `rate: nil` | `{ success:, substrate: }` |
+| `catalyze` | `substrate_id:`, `catalyst_type:` | `{ success:, substrate: }` |
+| `ferment_all` | `rate: nil` | `{ success: }` |
+| `list_ripe` | — | `{ count:, substrates: }` |
+| `fermentation_status` | — | Full fermentation report |
+
+Private: `@default_engine` — memoized `FermentationEngine`. Runner uses `engine || @default_engine` pattern.
+
+## Integration Points
+
+- **`lex-dream`**: Dream cycle is a natural catalyst source. The `dream_residue` catalyst type in the constants is specifically for materials that surface during the dream cycle and catalyze substrate development.
+- **`lex-memory`**: Ripe substrates could be promoted to memory traces after maturation.
+- **`lex-genesis`**: Fermentation produces potent substrates ready for concept birth.
+
+## Development Notes
+
+- Pruning order on cap: first removes `spoiled?` substrates, then lowest-potency if still over cap.
+- `ferment_all!` works through the batch grouping, not directly over substrates. Batch-level iteration.
+- `CATALYST_TYPES` includes `sleep` and `dream_residue` — these are valid symbols recognized by `catalyze!`.
+- In-memory only. No persistence.
+
+---
+
+**Maintained By**: Matthew Iverson (@Esity)

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/Gemfile.lock

@@ -0,0 +1,78 @@
+PATH
+  remote: .
+  specs:
+    lex-cognitive-fermentation (0.1.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    addressable (2.8.9)
+      public_suffix (>= 2.0.2, < 8.0)
+    ast (2.4.3)
+    bigdecimal (4.0.1)
+    diff-lcs (1.6.2)
+    json (2.19.1)
+    json-schema (6.2.0)
+      addressable (~> 2.8)
+      bigdecimal (>= 3.1, < 5)
+    language_server-protocol (3.17.0.5)
+    lint_roller (1.1.0)
+    mcp (0.8.0)
+      json-schema (>= 4.1)
+    parallel (1.27.0)
+    parser (3.3.10.2)
+      ast (~> 2.4.1)
+      racc
+    prism (1.9.0)
+    public_suffix (7.0.5)
+    racc (1.8.1)
+    rainbow (3.1.1)
+    regexp_parser (2.11.3)
+    rspec (3.13.2)
+      rspec-core (~> 3.13.0)
+      rspec-expectations (~> 3.13.0)
+      rspec-mocks (~> 3.13.0)
+    rspec-core (3.13.6)
+      rspec-support (~> 3.13.0)
+    rspec-expectations (3.13.5)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-mocks (3.13.8)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-support (3.13.7)
+    rubocop (1.85.1)
+      json (~> 2.3)
+      language_server-protocol (~> 3.17.0.2)
+      lint_roller (~> 1.1.0)
+      mcp (~> 0.6)
+      parallel (~> 1.10)
+      parser (>= 3.3.0.2)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 2.9.3, < 3.0)
+      rubocop-ast (>= 1.49.0, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 2.4.0, < 4.0)
+    rubocop-ast (1.49.1)
+      parser (>= 3.3.7.2)
+      prism (~> 1.7)
+    rubocop-rspec (3.9.0)
+      lint_roller (~> 1.1)
+      rubocop (~> 1.81)
+    ruby-progressbar (1.13.0)
+    unicode-display_width (3.2.0)
+      unicode-emoji (~> 4.1)
+    unicode-emoji (4.2.0)
+
+PLATFORMS
+  arm64-darwin-25
+  ruby
+
+DEPENDENCIES
+  lex-cognitive-fermentation!
+  rspec (~> 3.13)
+  rubocop (~> 1.75)
+  rubocop-rspec
+
+BUNDLED WITH
+   2.6.9

data/README.md

@@ -0,0 +1,53 @@
+# lex-cognitive-fermentation
+
+Slow non-linear cognitive maturation model for brain-modeled agentic AI in the LegionIO ecosystem.
+
+## What It Does
+
+Not all cognitive processing is immediate. Raw ideas, unresolved problems, partial patterns, and lingering questions sometimes need time to develop before they yield useful output. This extension models that incubation process using a fermentation metaphor: substrates move through stages from `inoculation` to `peak` maturity, developing potency along the way. Catalysts (analogies, emotional charge, dream residue) accelerate the process. Over-fermented substrates decay.
+
+Substrates are grouped into domain-based batches for collective tracking. The engine surfaces which substrates are ripe or at peak, and provides an overall yield rate.
+
+## Usage
+
+```ruby
+require 'legion/extensions/cognitive_fermentation'
+
+client = Legion::Extensions::CognitiveFermentation::Client.new
+
+# Add a substrate
+result = client.create_substrate(
+  substrate_type: :unresolved_problem,
+  domain:         :analytical,
+  content:        'Why do requests cluster in the morning?'
+)
+id = result[:substrate][:id]
+
+# Advance fermentation naturally
+client.ferment(substrate_id: id)
+
+# Apply a catalyst to boost potency
+client.catalyze(substrate_id: id, catalyst_type: :analogy)
+
+# Run a full fermentation cycle on all substrates
+client.ferment_all
+
+# See what's ready
+client.list_ripe
+# => { count: 0, substrates: [] }
+
+# Full status report
+client.fermentation_status
+```
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
+## License
+
+MIT

data/lex-cognitive-fermentation.gemspec

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative 'lib/legion/extensions/cognitive_fermentation/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'lex-cognitive-fermentation'
+  spec.version       = Legion::Extensions::CognitiveFermentation::VERSION
+  spec.authors       = ['Esity']
+  spec.email         = ['matthewdiverson@gmail.com']
+  spec.summary       = 'Slow unconscious cognitive processing for LegionIO agents'
+  spec.description   = 'Models cognitive fermentation — the slow transformation of raw ideas ' \
+                       'into refined insights through unconscious incubation and catalysis'
+  spec.homepage      = 'https://github.com/LegionIO/lex-cognitive-fermentation'
+  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/master/README.md",
+    'changelog_uri'         => "#{spec.homepage}/blob/master/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/cognitive_fermentation/client.rb

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

data/lib/legion/extensions/cognitive_fermentation/helpers/batch.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveFermentation
+      module Helpers
+        class Batch
+          include Constants
+
+          attr_reader :id, :domain, :substrates, :created_at
+
+          def initialize(domain:)
+            @id         = SecureRandom.uuid
+            @domain     = domain.to_sym
+            @substrates = []
+            @created_at = Time.now.utc
+          end
+
+          def add_substrate(substrate)
+            @substrates << substrate
+            substrate
+          end
+
+          def ferment_all!(rate = MATURATION_RATE)
+            @substrates.each { |s| s.ferment!(rate) }
+          end
+
+          def average_potency
+            return 0.0 if @substrates.empty?
+
+            (@substrates.sum(&:potency) / @substrates.size).round(10)
+          end
+
+          def average_maturity
+            return 0.0 if @substrates.empty?
+
+            (@substrates.sum(&:maturity) / @substrates.size).round(10)
+          end
+
+          def ripe_count = @substrates.count(&:ripe?)
+          def peak_count = @substrates.count(&:peak?)
+          def spoiled_count = @substrates.count(&:spoiled?)
+          def raw_count = @substrates.count(&:raw?)
+
+          def yield_rate
+            return 0.0 if @substrates.empty?
+
+            (ripe_count.to_f / @substrates.size).round(10)
+          end
+
+          def ready_to_harvest? = yield_rate >= 0.5
+
+          def to_h
+            {
+              id:               @id,
+              domain:           @domain,
+              substrate_count:  @substrates.size,
+              average_potency:  average_potency,
+              average_maturity: average_maturity,
+              ripe_count:       ripe_count,
+              peak_count:       peak_count,
+              spoiled_count:    spoiled_count,
+              yield_rate:       yield_rate,
+              ready_to_harvest: ready_to_harvest?
+            }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveFermentation
+      module Helpers
+        module Constants
+          MAX_SUBSTRATES = 500
+          MAX_BATCHES = 50
+
+          DEFAULT_POTENCY = 0.3
+          MATURATION_RATE = 0.05
+          VOLATILITY_DECAY = 0.02
+          CATALYSIS_BOOST = 0.12
+          SPOILAGE_THRESHOLD = 0.1
+          RIPE_THRESHOLD = 0.7
+          PEAK_THRESHOLD = 0.9
+          OVER_FERMENTED_DECAY = 0.03
+
+          SUBSTRATE_TYPES = %i[
+            raw_idea unresolved_problem partial_pattern
+            dormant_association vague_intuition half_formed_belief
+            contradictory_evidence lingering_question
+          ].freeze
+
+          FERMENTATION_STAGES = %i[
+            inoculation primary_fermentation secondary_fermentation
+            conditioning maturation aging peak over_fermented
+          ].freeze
+
+          CATALYST_TYPES = %i[
+            analogy contrast juxtaposition
+            emotional_charge sleep dream_residue
+            environmental_stimulus social_interaction
+          ].freeze
+
+          DOMAINS = %i[
+            cognitive emotional procedural semantic
+            episodic social creative analytical
+          ].freeze
+
+          POTENCY_LABELS = {
+            (0.8..)     => :transcendent,
+            (0.6...0.8) => :potent,
+            (0.4...0.6) => :developing,
+            (0.2...0.4) => :mild,
+            (..0.2)     => :inert
+          }.freeze
+
+          MATURITY_LABELS = {
+            (0.8..)     => :peak,
+            (0.6...0.8) => :mature,
+            (0.4...0.6) => :developing,
+            (0.2...0.4) => :young,
+            (..0.2)     => :raw
+          }.freeze
+
+          VOLATILITY_LABELS = {
+            (0.8..)     => :explosive,
+            (0.6...0.8) => :volatile,
+            (0.4...0.6) => :active,
+            (0.2...0.4) => :stable,
+            (..0.2)     => :dormant
+          }.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/cognitive_fermentation/helpers/fermentation_engine.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveFermentation
+      module Helpers
+        class FermentationEngine
+          include Constants
+
+          def initialize
+            @substrates = {}
+            @batches    = {}
+          end
+
+          def create_substrate(substrate_type:, domain:, content: '', potency: nil, volatility: nil)
+            sub = Substrate.new(substrate_type: substrate_type, domain: domain, content: content,
+                                potency: potency, volatility: volatility)
+            @substrates[sub.id] = sub
+            batch = find_or_create_batch(domain: domain)
+            batch.add_substrate(sub)
+            prune_substrates
+            sub
+          end
+
+          def ferment(substrate_id:, rate: MATURATION_RATE)
+            sub = @substrates[substrate_id]
+            return nil unless sub
+
+            sub.ferment!(rate)
+            sub
+          end
+
+          def catalyze(substrate_id:, catalyst_type:)
+            sub = @substrates[substrate_id]
+            return nil unless sub
+
+            sub.catalyze!(catalyst_type)
+            sub
+          end
+
+          def ferment_all!(rate: MATURATION_RATE)
+            @batches.each_value { |b| b.ferment_all!(rate) }
+          end
+
+          def substrates_by_domain(domain:) = @substrates.values.select { |s| s.domain == domain.to_sym }
+          def substrates_by_type(type:) = @substrates.values.select { |s| s.substrate_type == type.to_sym }
+          def substrates_by_stage(stage:) = @substrates.values.select { |s| s.stage == stage.to_sym }
+          def ripe_substrates = @substrates.values.select(&:ripe?)
+          def peak_substrates = @substrates.values.select(&:peak?)
+          def spoiled_substrates = @substrates.values.select(&:spoiled?)
+          def raw_substrates = @substrates.values.select(&:raw?)
+
+          def most_potent(limit: 5)
+            @substrates.values.sort_by { |s| -s.potency }.first(limit)
+          end
+
+          def most_mature(limit: 5)
+            @substrates.values.sort_by { |s| -s.maturity }.first(limit)
+          end
+
+          def overall_potency
+            return 0.0 if @substrates.empty?
+
+            (@substrates.values.sum(&:potency) / @substrates.size).round(10)
+          end
+
+          def overall_maturity
+            return 0.0 if @substrates.empty?
+
+            (@substrates.values.sum(&:maturity) / @substrates.size).round(10)
+          end
+
+          def overall_volatility
+            return 0.0 if @substrates.empty?
+
+            (@substrates.values.sum(&:volatility) / @substrates.size).round(10)
+          end
+
+          def yield_rate
+            return 0.0 if @substrates.empty?
+
+            (ripe_substrates.size.to_f / @substrates.size).round(10)
+          end
+
+          def stage_distribution
+            dist = Hash.new(0)
+            @substrates.each_value { |s| dist[s.stage] += 1 }
+            dist
+          end
+
+          def fermentation_report
+            {
+              total_substrates:   @substrates.size,
+              total_batches:      @batches.size,
+              overall_potency:    overall_potency,
+              potency_label:      Constants.label_for(POTENCY_LABELS, overall_potency),
+              overall_maturity:   overall_maturity,
+              maturity_label:     Constants.label_for(MATURITY_LABELS, overall_maturity),
+              overall_volatility: overall_volatility,
+              volatility_label:   Constants.label_for(VOLATILITY_LABELS, overall_volatility),
+              yield_rate:         yield_rate,
+              ripe_count:         ripe_substrates.size,
+              peak_count:         peak_substrates.size,
+              spoiled_count:      spoiled_substrates.size,
+              stage_distribution: stage_distribution,
+              batches:            @batches.values.map(&:to_h),
+              most_potent:        most_potent(limit: 3).map(&:to_h)
+            }
+          end
+
+          def to_h
+            {
+              total_substrates: @substrates.size,
+              total_batches:    @batches.size,
+              potency:          overall_potency,
+              maturity:         overall_maturity,
+              volatility:       overall_volatility
+            }
+          end
+
+          private
+
+          def find_or_create_batch(domain:)
+            key = domain.to_sym
+            @batches[key] ||= Batch.new(domain: key)
+          end
+
+          def prune_substrates
+            return if @substrates.size <= MAX_SUBSTRATES
+
+            spoiled = @substrates.values.select(&:spoiled?)
+            spoiled.each { |s| @substrates.delete(s.id) }
+            return if @substrates.size <= MAX_SUBSTRATES
+
+            sorted = @substrates.values.sort_by(&:potency)
+            to_remove = sorted.first(@substrates.size - MAX_SUBSTRATES)
+            to_remove.each { |s| @substrates.delete(s.id) }
+          end
+        end
+      end
+    end
+  end
+end