lex-cognitive-narrative-arc 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 2274e2972537f554c592cd9128575d6bc006b3a2d8675cb4eb74b6ed9759d6f4
+  data.tar.gz: cb53f27b356b02768b53e099f646e07bea79d6a367456f14e1f756b9014a4e7d
+SHA512:
+  metadata.gz: f9e0d5b050adae938413b2dad6bd836f6d78e80189599ecf7ce08a38d192f77ecf8ab85515476af2e770d68a15afd06a09f63e9d7ed788f8501c02069be48a29
+  data.tar.gz: 6ff13f7dee6c859469bef93ac99d85bfd8bc91a1434ae056d607c1fdd3eab3758cc50a119b9747655f4a141c96eaca5e318d0c24eaac357e4a4f6df7afe42f97

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,11 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+*.gem
+.rspec_status
+Gemfile.lock

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,64 @@
+AllCops:
+  TargetRubyVersion: 3.4
+  NewCops: enable
+  SuggestExtensions: false
+
+Layout/LineLength:
+  Max: 160
+
+Layout/SpaceAroundEqualsInParameterDefault:
+  EnforcedStyle: space
+
+Layout/HashAlignment:
+  EnforcedHashRocketStyle: table
+  EnforcedColonStyle: table
+
+Metrics/MethodLength:
+  Max: 25
+
+Metrics/ClassLength:
+  Max: 150
+
+Metrics/ModuleLength:
+  Max: 1500
+
+Metrics/BlockLength:
+  Max: 40
+  Exclude:
+    - 'spec/**/*'
+
+Metrics/AbcSize:
+  Max: 25
+
+Metrics/ParameterLists:
+  Max: 8
+  MaxOptionalParameters: 8
+
+Metrics/CyclomaticComplexity:
+  Max: 15
+
+Metrics/PerceivedComplexity:
+  Max: 17
+
+Style/Documentation:
+  Enabled: false
+
+Style/OneClassPerFile:
+  Exclude:
+    - 'spec/spec_helper.rb'
+
+Style/SymbolArray:
+  Enabled: true
+
+Style/FrozenStringLiteralComment:
+  Enabled: true
+  EnforcedStyle: always
+
+Naming/FileName:
+  Enabled: false
+
+Naming/PredicateMethod:
+  Enabled: false
+
+Naming/PredicatePrefix:
+  Enabled: false

data/CLAUDE.md

@@ -0,0 +1,100 @@
+# lex-cognitive-narrative-arc
+
+**Level 3 Leaf Documentation**
+- **Parent**: `/Users/miverso2/rubymine/legion/extensions-agentic/CLAUDE.md`
+
+## Purpose
+
+Narrative arc tracking engine for cognitive processing. Models ongoing cognitive situations as narrative arcs with beats that drive tension through phases. Beat events (exposition, rising_action, complication, crisis, climax, falling_action, resolution, denouement) each carry intensity and emotional_charge and adjust the arc's tension level. Phases (building, peak, resolving, complete) transition automatically based on tension thresholds. A dramatic score synthesizes tension, beat count, and average intensity.
+
+## Gem Info
+
+- **Gem name**: `lex-cognitive-narrative-arc`
+- **Module**: `Legion::Extensions::CognitiveNarrativeArc`
+- **Version**: `0.1.0`
+- **Ruby**: `>= 3.4`
+- **License**: MIT
+
+## File Structure
+
+```
+lib/legion/extensions/cognitive_narrative_arc/
+  version.rb
+  client.rb
+  helpers/
+    constants.rb
+    arc.rb
+    beat_event.rb
+  runners/
+    narrative.rb
+```
+
+## Key Constants
+
+| Constant | Value | Purpose |
+|---|---|---|
+| `MAX_ARCS` | `100` | Per-engine arc capacity |
+| `MAX_BEATS_PER_ARC` | `50` | Max beats per arc |
+| `DEFAULT_TENSION` | `0.3` | Starting tension for new arcs |
+| `TENSION_RISE` | `0.1` | Tension increase for escalating beats |
+| `TENSION_FALL` | `0.08` | Tension decrease for resolving beats |
+| `CLIMAX_THRESHOLD` | `0.8` | Tension above which arc enters peak phase |
+| `RESOLUTION_THRESHOLD` | `0.2` | Tension below which arc enters resolved phase |
+| `BEAT_TYPES` | `%i[exposition rising_action complication crisis climax falling_action resolution denouement]` | Valid beat types |
+| `ARC_PHASES` | `%i[building peak resolving complete]` | Arc lifecycle phases |
+| `TENSION_LABELS` | range hash | From `:calm` to `:explosive` |
+| `DRAMA_LABELS` | range hash | From `:mundane` to `:epic` |
+| `PHASE_LABELS` | hash | Human-readable phase names |
+
+## Helpers
+
+### `Helpers::BeatEvent`
+Immutable (frozen) record of a single narrative beat. Has `id`, `beat_type`, `content`, `intensity` (0.0–1.0), `emotional_charge` (-1.0 to 1.0), and `occurred_at`.
+
+- `climactic?` — `beat_type == :climax`
+- `resolving?` — `beat_type` is `:resolution` or `:denouement`
+- `emotional_charge` — pre-computed from beat type: crisis/climax are negative, resolution/denouement are positive
+
+### `Helpers::Arc`
+Active narrative arc. Has `id`, `title`, `domain`, `genre`, `tension`, `phase`, `beats` (array of `BeatEvent`), and `created_at`.
+
+- `add_beat!(beat_type:, content:, intensity:)` — creates `BeatEvent`, adjusts tension (escalating beats raise tension, resolving beats lower it), appends to beats array
+- `advance_phase!` — checks tension vs thresholds and transitions phase
+- `tension_rise!(amount)` — direct tension increase
+- `tension_fall!(amount)` — direct tension decrease
+- `climaxed?` — phase is `:peak` or later
+- `resolved?` — phase is `:resolving` or `:complete`
+- `complete?` — phase is `:complete`
+- `dramatic_score` — composite: `tension * 0.4 + (beat_count / MAX_BEATS) * 0.3 + avg_intensity * 0.3`
+
+## Runners
+
+Module: `Runners::Narrative`
+
+| Runner Method | Description |
+|---|---|
+| `create_arc(title:, domain:, genre:)` | Start a new narrative arc |
+| `add_beat(arc_id:, beat_type:, content:, intensity:)` | Add a beat to an arc |
+| `get_arc(arc_id:)` | Retrieve arc details |
+| `active_arcs` | All arcs not yet complete |
+| `completed_arcs` | All resolved/complete arcs |
+| `most_dramatic_arc` | Arc with highest dramatic score |
+| `arc_report` | Aggregate stats across all arcs |
+
+All runners return `{success: true/false, ...}` hashes.
+
+## Integration Points
+
+- `lex-emotion`: beat emotional_charge directly feeds into `lex-emotion` valence evaluation
+- `lex-tick` `action_selection`: high-tension arcs (peak phase) should trigger cautious behavior; resolved arcs can close open actions
+- `lex-conflict`: rising_action/complication/crisis beats parallel conflict escalation in `lex-conflict`
+- `lex-memory`: arcs serve as episodic containers — complete arcs can be consolidated as episodic memory traces
+
+## Development Notes
+
+- `Client` instantiates `@narrative_engine = Helpers::NarrativeEngine.new`
+- `add_beat!` drives both the events log and phase transitions atomically
+- `TENSION_RISE` is applied for: `rising_action`, `complication`, `crisis`, `climax` beats
+- `TENSION_FALL` is applied for: `falling_action`, `resolution`, `denouement` beats
+- `exposition` beats are neutral (no tension change)
+- `dramatic_score` normalizes beat_count to `MAX_BEATS_PER_ARC` so all three components are [0.0, 1.0]

data/Gemfile

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

data/README.md

@@ -0,0 +1,50 @@
+# lex-cognitive-narrative-arc
+
+Narrative arc tracking for LegionIO cognitive agents. Models ongoing situations as story arcs with beats that drive tension through building, peak, resolving, and complete phases. Dramatic score synthesizes tension, event count, and intensity.
+
+## What It Does
+
+- Eight beat types: exposition, rising_action, complication, crisis, climax, falling_action, resolution, denouement
+- Tension adjusts automatically per beat type (crisis/climax raise; resolution/denouement lower)
+- Four arc phases: building → peak (tension >= 0.8) → resolving (tension <= 0.2) → complete
+- Each beat has intensity (0.0–1.0) and emotional_charge (-1.0 to 1.0)
+- Dramatic score: composite of tension (40%), beat count ratio (30%), average intensity (30%)
+- Track active, completed, and most-dramatic arcs
+
+## Usage
+
+```ruby
+# Create an arc
+result = runner.create_arc(title: 'deployment_incident', domain: :operations, genre: :crisis)
+arc_id = result[:arc][:id]
+
+# Add beats
+runner.add_beat(arc_id: arc_id, beat_type: :rising_action,
+                 content: 'error rate climbing', intensity: 0.6)
+runner.add_beat(arc_id: arc_id, beat_type: :crisis,
+                 content: 'service unavailable', intensity: 0.9)
+# => { success: true, arc: { tension: 0.5, phase: :building, ... } }
+
+runner.add_beat(arc_id: arc_id, beat_type: :climax,
+                 content: 'root cause identified', intensity: 1.0)
+# tension reaches peak phase
+
+runner.add_beat(arc_id: arc_id, beat_type: :resolution,
+                 content: 'hotfix deployed', intensity: 0.7)
+
+# Check most dramatic
+runner.most_dramatic_arc
+# => { success: true, arc: { title: 'deployment_incident', dramatic_score: 0.73, ... } }
+```
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
+## License
+
+MIT

data/lex-cognitive-narrative-arc.gemspec

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative 'lib/legion/extensions/cognitive_narrative_arc/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'lex-cognitive-narrative-arc'
+  spec.version       = Legion::Extensions::CognitiveNarrativeArc::VERSION
+  spec.authors       = ['Esity']
+  spec.email         = ['matthewdiverson@gmail.com']
+
+  spec.summary       = 'LEX Cognitive Narrative Arc'
+  spec.description   = 'Narrative arc detection in cognitive experience for LegionIO'
+  spec.homepage      = 'https://github.com/LegionIO/lex-cognitive-narrative-arc'
+  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-cognitive-narrative-arc'
+  spec.metadata['documentation_uri'] = 'https://github.com/LegionIO/lex-cognitive-narrative-arc'
+  spec.metadata['changelog_uri']     = 'https://github.com/LegionIO/lex-cognitive-narrative-arc'
+  spec.metadata['bug_tracker_uri']   = 'https://github.com/LegionIO/lex-cognitive-narrative-arc/issues'
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  spec.files = `git ls-files -z`.split("\x0").reject do |f|
+    f.match(%r{\A(?:test|spec|features)/})
+  end
+  spec.require_paths = ['lib']
+  spec.add_development_dependency 'legion-gaia'
+end

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

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/cognitive_narrative_arc/helpers/constants'
+require 'legion/extensions/cognitive_narrative_arc/helpers/beat_event'
+require 'legion/extensions/cognitive_narrative_arc/helpers/arc'
+require 'legion/extensions/cognitive_narrative_arc/helpers/arc_engine'
+require 'legion/extensions/cognitive_narrative_arc/runners/narrative'
+
+module Legion
+  module Extensions
+    module CognitiveNarrativeArc
+      class Client
+        include Runners::Narrative
+
+        def initialize(**)
+          @arc_engine = Helpers::ArcEngine.new
+        end
+
+        private
+
+        attr_reader :arc_engine
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_narrative_arc/helpers/arc.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module CognitiveNarrativeArc
+      module Helpers
+        class Arc
+          attr_reader :arc_id, :title, :domain, :beats, :arc_phase, :tension_level,
+                      :created_at, :resolved_at
+
+          def initialize(title:, domain: :general, initial_tension: Constants::DEFAULT_TENSION)
+            @arc_id       = SecureRandom.uuid
+            @title        = title
+            @domain       = domain
+            @beats        = []
+            @arc_phase    = :building
+            @tension_level = initial_tension.clamp(0.0, 1.0)
+            @created_at   = Time.now.utc
+            @resolved_at  = nil
+          end
+
+          def add_beat!(beat)
+            return false if @beats.size >= Constants::MAX_BEATS_PER_ARC
+            return false if complete?
+
+            @beats << beat
+            adjust_tension_for_beat(beat)
+            advance_phase!
+            true
+          end
+
+          def advance_phase!
+            new_phase = detect_phase
+            @arc_phase = new_phase if new_phase != @arc_phase
+            @resolved_at = Time.now.utc if @arc_phase == :complete
+            @arc_phase
+          end
+
+          def tension_rise!(amount = Constants::TENSION_RISE)
+            @tension_level = (@tension_level + amount).round(10).clamp(0.0, 1.0)
+          end
+
+          def tension_fall!(amount = Constants::TENSION_FALL)
+            @tension_level = (@tension_level - amount).round(10).clamp(0.0, 1.0)
+          end
+
+          def climaxed?
+            @tension_level >= Constants::CLIMAX_THRESHOLD || @arc_phase == :peak
+          end
+
+          def resolved?
+            @arc_phase == :complete
+          end
+
+          def complete?
+            @arc_phase == :complete
+          end
+
+          def dramatic_score
+            return 0.0 if @beats.empty?
+
+            tension_contrib = @tension_level * 0.4
+            beat_count_contrib = [@beats.size.to_f / Constants::MAX_BEATS_PER_ARC, 1.0].min * 0.3
+            intensity_contrib = average_beat_intensity * 0.3
+            (tension_contrib + beat_count_contrib + intensity_contrib).round(10)
+          end
+
+          def tension_label
+            Constants.label_for(Constants::TENSION_LABELS, @tension_level)
+          end
+
+          def drama_label
+            Constants.label_for(Constants::DRAMA_LABELS, dramatic_score)
+          end
+
+          def to_h
+            {
+              arc_id:         @arc_id,
+              title:          @title,
+              domain:         @domain,
+              arc_phase:      @arc_phase,
+              tension_level:  @tension_level,
+              beat_count:     @beats.size,
+              dramatic_score: dramatic_score,
+              tension_label:  tension_label,
+              drama_label:    drama_label,
+              created_at:     @created_at,
+              resolved_at:    @resolved_at
+            }
+          end
+
+          private
+
+          def average_beat_intensity
+            return 0.0 if @beats.empty?
+
+            @beats.sum(&:intensity) / @beats.size.to_f
+          end
+
+          def adjust_tension_for_beat(beat)
+            case beat.beat_type
+            when :rising_action, :complication, :crisis
+              tension_rise!(beat.intensity * Constants::TENSION_RISE)
+            when :climax
+              @tension_level = [@tension_level, Constants::CLIMAX_THRESHOLD].max.clamp(0.0, 1.0)
+            when :falling_action, :resolution, :denouement
+              tension_fall!(beat.intensity * Constants::TENSION_FALL)
+            end
+          end
+
+          def detect_phase
+            return :complete if has_resolution_beat?
+            return :resolving if has_climax_beat? && @tension_level < Constants::CLIMAX_THRESHOLD
+            return :peak if @tension_level >= Constants::CLIMAX_THRESHOLD
+            return :building if @tension_level < Constants::CLIMAX_THRESHOLD
+
+            @arc_phase
+          end
+
+          def has_climax_beat?
+            @beats.any?(&:climactic?)
+          end
+
+          def has_resolution_beat?
+            @beats.any? { |b| %i[resolution denouement].include?(b.beat_type) }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_narrative_arc/helpers/arc_engine.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveNarrativeArc
+      module Helpers
+        class ArcEngine
+          attr_reader :arcs
+
+          def initialize
+            @arcs = {}
+          end
+
+          def create_arc(title:, domain: :general, initial_tension: Constants::DEFAULT_TENSION)
+            return nil if @arcs.size >= Constants::MAX_ARCS
+
+            arc = Arc.new(title: title, domain: domain, initial_tension: initial_tension)
+            @arcs[arc.arc_id] = arc
+            arc
+          end
+
+          def add_beat(arc_id:, content:, intensity: 0.5, beat_type: :rising_action,
+                       domain: :general, emotional_charge: 0.0)
+            arc = @arcs[arc_id]
+            return { success: false, reason: :arc_not_found } unless arc
+
+            beat = BeatEvent.new(
+              content:          content,
+              intensity:        intensity,
+              beat_type:        beat_type,
+              domain:           domain,
+              emotional_charge: emotional_charge
+            )
+
+            added = arc.add_beat!(beat)
+            return { success: false, reason: :arc_full_or_complete } unless added
+
+            { success: true, beat_id: beat.beat_id, arc_phase: arc.arc_phase,
+              tension_level: arc.tension_level }
+          end
+
+          def get_arc(arc_id)
+            @arcs[arc_id]
+          end
+
+          def active_arcs
+            @arcs.values.reject(&:complete?)
+          end
+
+          def completed_arcs
+            @arcs.values.select(&:complete?)
+          end
+
+          def most_dramatic_arc
+            return nil if @arcs.empty?
+
+            @arcs.values.max_by(&:dramatic_score)
+          end
+
+          def tension_distribution
+            return {} if @arcs.empty?
+
+            counts = Hash.new(0)
+            @arcs.each_value do |arc|
+              label = arc.tension_label
+              counts[label] += 1
+            end
+            counts
+          end
+
+          def detect_narrative_patterns
+            return [] if @arcs.size < 2
+
+            patterns = []
+            patterns << :recurring_crisis if recurring_beat_pattern?(:crisis)
+            patterns << :recurring_climax if recurring_beat_pattern?(:climax)
+            patterns << :unresolved_tension if unresolved_high_tension?
+            patterns << :rapid_resolution if rapid_resolution_pattern?
+            patterns
+          end
+
+          def arc_report
+            {
+              total_arcs:    @arcs.size,
+              active:        active_arcs.size,
+              completed:     completed_arcs.size,
+              patterns:      detect_narrative_patterns,
+              tension_dist:  tension_distribution,
+              most_dramatic: most_dramatic_arc&.to_h
+            }
+          end
+
+          private
+
+          def recurring_beat_pattern?(beat_type)
+            arc_with_beat_type_count = @arcs.values.count do |arc|
+              arc.beats.any? { |b| b.beat_type == beat_type }
+            end
+            arc_with_beat_type_count >= 2
+          end
+
+          def unresolved_high_tension?
+            active_arcs.any? { |arc| arc.tension_level >= Constants::CLIMAX_THRESHOLD }
+          end
+
+          def rapid_resolution_pattern?
+            @arcs.values.any? do |arc|
+              arc.complete? && arc.beats.size <= 3
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_narrative_arc/helpers/beat_event.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module CognitiveNarrativeArc
+      module Helpers
+        class BeatEvent
+          attr_reader :beat_id, :content, :intensity, :beat_type, :domain,
+                      :emotional_charge, :created_at
+
+          def initialize(content:, intensity: 0.5, beat_type: :rising_action,
+                         domain: :general, emotional_charge: 0.0)
+            @beat_id        = SecureRandom.uuid
+            @content        = content
+            @intensity      = intensity.clamp(0.0, 1.0)
+            @beat_type      = validate_beat_type(beat_type)
+            @domain         = domain
+            @emotional_charge = emotional_charge.clamp(-1.0, 1.0)
+            @created_at = Time.now.utc
+          end
+
+          def to_h
+            {
+              beat_id:          @beat_id,
+              content:          @content,
+              intensity:        @intensity,
+              beat_type:        @beat_type,
+              domain:           @domain,
+              emotional_charge: @emotional_charge,
+              created_at:       @created_at
+            }
+          end
+
+          def climactic?
+            @beat_type == :climax || @intensity >= Constants::CLIMAX_THRESHOLD
+          end
+
+          def resolving?
+            %i[falling_action resolution denouement].include?(@beat_type)
+          end
+
+          private
+
+          def validate_beat_type(type)
+            return type if Constants::BEAT_TYPES.include?(type)
+
+            Constants::BEAT_TYPES.first
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveNarrativeArc
+      module Helpers
+        module Constants
+          MAX_ARCS           = 100
+          MAX_BEATS_PER_ARC  = 50
+          DEFAULT_TENSION    = 0.3
+          TENSION_RISE       = 0.1
+          TENSION_FALL       = 0.08
+          CLIMAX_THRESHOLD   = 0.8
+          RESOLUTION_THRESHOLD = 0.2
+
+          BEAT_TYPES = %i[
+            exposition
+            rising_action
+            complication
+            crisis
+            climax
+            falling_action
+            resolution
+            denouement
+          ].freeze
+
+          ARC_PHASES = %i[building peak resolving complete].freeze
+
+          TENSION_LABELS = {
+            (0.0..0.2) => :calm,
+            (0.2..0.5) => :developing,
+            (0.5..0.8) => :tense,
+            (0.8..1.0) => :critical
+          }.freeze
+
+          DRAMA_LABELS = {
+            (0.0..0.25) => :mundane,
+            (0.25..0.5) => :engaging,
+            (0.5..0.75) => :compelling,
+            (0.75..1.0) => :gripping
+          }.freeze
+
+          PHASE_LABELS = {
+            building:  'Rising action building toward climax',
+            peak:      'At or near peak tension — climax active',
+            resolving: 'Falling action moving toward resolution',
+            complete:  'Arc resolved and closed'
+          }.freeze
+
+          module_function
+
+          def label_for(labels_hash, value)
+            labels_hash.each do |range, label|
+              return label if range.cover?(value)
+            end
+            labels_hash.values.last
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_narrative_arc/runners/narrative.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveNarrativeArc
+      module Runners
+        module Narrative
+          include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                      Legion::Extensions::Helpers.const_defined?(:Lex)
+
+          def create_arc(title:, domain: :general, initial_tension: Helpers::Constants::DEFAULT_TENSION,
+                         engine: nil, **)
+            eng = engine || arc_engine
+            arc = eng.create_arc(title: title, domain: domain, initial_tension: initial_tension)
+
+            unless arc
+              Legion::Logging.warn "[narrative_arc] create_arc failed: engine at capacity (#{Helpers::Constants::MAX_ARCS})"
+              return { success: false, reason: :engine_at_capacity }
+            end
+
+            Legion::Logging.debug "[narrative_arc] arc created: #{arc.arc_id[0..7]} title=#{title} domain=#{domain}"
+            { success: true, arc_id: arc.arc_id, title: arc.title, arc_phase: arc.arc_phase,
+              tension_level: arc.tension_level }
+          end
+
+          def add_beat(arc_id:, content:, intensity: 0.5, beat_type: :rising_action,
+                       domain: :general, emotional_charge: 0.0, engine: nil, **)
+            eng = engine || arc_engine
+            result = eng.add_beat(
+              arc_id:           arc_id,
+              content:          content,
+              intensity:        intensity,
+              beat_type:        beat_type,
+              domain:           domain,
+              emotional_charge: emotional_charge
+            )
+
+            if result[:success]
+              arc = eng.get_arc(arc_id)
+              Legion::Logging.debug "[narrative_arc] beat added: arc=#{arc_id[0..7]} type=#{beat_type} " \
+                                    "phase=#{result[:arc_phase]} tension=#{result[:tension_level].round(2)}"
+              result[:dramatic_score] = arc.dramatic_score if arc
+            else
+              Legion::Logging.debug "[narrative_arc] add_beat failed: #{result[:reason]} arc=#{arc_id[0..7]}"
+            end
+
+            result
+          end
+
+          def get_arc(arc_id:, engine: nil, **)
+            eng = engine || arc_engine
+            arc = eng.get_arc(arc_id)
+            return { found: false, arc_id: arc_id } unless arc
+
+            { found: true, arc: arc.to_h, beats: arc.beats.map(&:to_h) }
+          end
+
+          def active_arcs(engine: nil, **)
+            eng = engine || arc_engine
+            arcs = eng.active_arcs
+            Legion::Logging.debug "[narrative_arc] active arcs count=#{arcs.size}"
+            { arcs: arcs.map(&:to_h), count: arcs.size }
+          end
+
+          def completed_arcs(engine: nil, **)
+            eng = engine || arc_engine
+            arcs = eng.completed_arcs
+            Legion::Logging.debug "[narrative_arc] completed arcs count=#{arcs.size}"
+            { arcs: arcs.map(&:to_h), count: arcs.size }
+          end
+
+          def most_dramatic_arc(engine: nil, **)
+            eng = engine || arc_engine
+            arc = eng.most_dramatic_arc
+            return { found: false } unless arc
+
+            Legion::Logging.debug "[narrative_arc] most dramatic: #{arc.arc_id[0..7]} score=#{arc.dramatic_score.round(2)}"
+            { found: true, arc: arc.to_h }
+          end
+
+          def arc_report(engine: nil, **)
+            eng = engine || arc_engine
+            report = eng.arc_report
+            Legion::Logging.debug "[narrative_arc] arc_report total=#{report[:total_arcs]} patterns=#{report[:patterns].inspect}"
+            { success: true, report: report }
+          end
+
+          private
+
+          def arc_engine
+            @arc_engine ||= Helpers::ArcEngine.new
+          end
+        end
+      end
+    end
+  end
+end

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

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

data/lib/legion/extensions/cognitive_narrative_arc.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/cognitive_narrative_arc/version'
+require 'legion/extensions/cognitive_narrative_arc/helpers/constants'
+require 'legion/extensions/cognitive_narrative_arc/helpers/beat_event'
+require 'legion/extensions/cognitive_narrative_arc/helpers/arc'
+require 'legion/extensions/cognitive_narrative_arc/helpers/arc_engine'
+require 'legion/extensions/cognitive_narrative_arc/runners/narrative'
+
+module Legion
+  module Extensions
+    module CognitiveNarrativeArc
+      extend Legion::Extensions::Core if Legion::Extensions.const_defined? :Core
+    end
+  end
+end

metadata

@@ -0,0 +1,76 @@
+--- !ruby/object:Gem::Specification
+name: lex-cognitive-narrative-arc
+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: Narrative arc detection in cognitive experience for LegionIO
+email:
+- matthewdiverson@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".github/workflows/ci.yml"
+- ".gitignore"
+- ".rspec"
+- ".rubocop.yml"
+- CLAUDE.md
+- Gemfile
+- README.md
+- lex-cognitive-narrative-arc.gemspec
+- lib/legion/extensions/cognitive_narrative_arc.rb
+- lib/legion/extensions/cognitive_narrative_arc/client.rb
+- lib/legion/extensions/cognitive_narrative_arc/helpers/arc.rb
+- lib/legion/extensions/cognitive_narrative_arc/helpers/arc_engine.rb
+- lib/legion/extensions/cognitive_narrative_arc/helpers/beat_event.rb
+- lib/legion/extensions/cognitive_narrative_arc/helpers/constants.rb
+- lib/legion/extensions/cognitive_narrative_arc/runners/narrative.rb
+- lib/legion/extensions/cognitive_narrative_arc/version.rb
+homepage: https://github.com/LegionIO/lex-cognitive-narrative-arc
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/LegionIO/lex-cognitive-narrative-arc
+  source_code_uri: https://github.com/LegionIO/lex-cognitive-narrative-arc
+  documentation_uri: https://github.com/LegionIO/lex-cognitive-narrative-arc
+  changelog_uri: https://github.com/LegionIO/lex-cognitive-narrative-arc
+  bug_tracker_uri: https://github.com/LegionIO/lex-cognitive-narrative-arc/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 Cognitive Narrative Arc
+test_files: []