lex-self-talk 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 9212822e6ff0f3262f502e49f81f7584b82378f0bfdcdc09824691da640b4f8b
+  data.tar.gz: b075b53b46c16feba5a123017c2b7a5e03ef68795b5ea4878ac5d32e7eb83bbf
+SHA512:
+  metadata.gz: 1ffeeb6f1f76302085132ee82cf7f00e5405febf15e4666adf67e5a4c66335ce90c565484a4466543de71a4cf80f1c0e5fd6410eb427267b1817a07772c7e0f0
+  data.tar.gz: c8263855e81e95c7a6462735d0ab4c3561ad32c280fbd053fdb21d8679df11bc8d428312955d3cfa282cc710c72dccb9ee6ebdbe4cb0358ea4206afc8b9c659a

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/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Esity
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,120 @@
+# lex-self-talk
+
+Inner dialogue system for brain-modeled agentic AI. Multiple cognitive voices (critic, encourager, analyst, devil's advocate, pragmatist, visionary, caretaker, rebel) engage in structured internal conversations to reason through decisions.
+
+## Overview
+
+`lex-self-talk` implements Vygotsky's inner speech theory and the Internal Family Systems model as a structured deliberation engine. Each voice has a volume (0..1), a type, and an optional bias direction. Voices contribute turns to dialogues, taking positions (support, oppose, question, clarify) with a strength score. The engine tracks consensus across voices and can conclude, deadlock, or abandon dialogues.
+
+## Voice Types
+
+| Type | Role |
+|------|------|
+| `critic` | Identifies flaws and risks |
+| `encourager` | Affirms and motivates |
+| `analyst` | Evaluates evidence and logic |
+| `devils_advocate` | Challenges assumptions |
+| `pragmatist` | Focuses on feasibility |
+| `visionary` | Explores possibilities |
+| `caretaker` | Considers impact on others |
+| `rebel` | Questions constraints |
+
+## Key Constants
+
+| Constant | Value | Description |
+|----------|-------|-------------|
+| `MAX_VOICES` | 10 | Maximum registered voices |
+| `MAX_DIALOGUES` | 200 | Maximum stored dialogues (oldest pruned) |
+| `MAX_TURNS_PER_DIALOGUE` | 50 | Turn limit per dialogue |
+| `DEFAULT_VOLUME` | 0.5 | Starting voice volume |
+| `VOLUME_BOOST` | 0.1 | Default amplify amount |
+| `VOLUME_DECAY` | 0.05 | Default dampen amount |
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem 'lex-self-talk'
+```
+
+## Usage
+
+```ruby
+require 'legion/extensions/self_talk'
+
+client = Legion::Extensions::SelfTalk::Client.new
+
+# Register voices
+critic_id = client.register_voice(name: 'Inner Critic', voice_type: :critic)[:voice][:id]
+analyst_id = client.register_voice(name: 'Analyst', voice_type: :analyst)[:voice][:id]
+
+# Start a dialogue
+dialogue_id = client.start_dialogue(topic: 'Should we refactor the auth module?')[:dialogue][:id]
+
+# Voices contribute turns
+client.add_turn(dialogue_id: dialogue_id, voice_id: critic_id,
+                content: 'The current implementation has hidden coupling', position: :oppose, strength: 0.8)
+client.add_turn(dialogue_id: dialogue_id, voice_id: analyst_id,
+                content: 'Refactoring now reduces long-term maintenance cost', position: :support, strength: 0.7)
+
+# Get a report
+report = client.dialogue_report(dialogue_id: dialogue_id)
+# => { found: true, dialogue: {...}, voice_positions: { "Inner Critic" => 0.8, "Analyst" => 0.7 } }
+
+# Conclude the dialogue
+client.conclude_dialogue(dialogue_id: dialogue_id, summary: 'Refactor in next sprint')
+
+# Check status
+client.self_talk_status
+# => { voice_count: 2, dialogue_count: 1, active_dialogue_count: 0, ... }
+```
+
+## Dominance Labels
+
+| Volume Range | Label |
+|-------------|-------|
+| 0.8 - 1.0 | `:commanding` |
+| 0.6 - 0.8 | `:assertive` |
+| 0.4 - 0.6 | `:balanced` |
+| 0.2 - 0.4 | `:quiet` |
+| 0.0 - 0.2 | `:silent` |
+
+## Consensus Labels
+
+| Score Range | Label |
+|------------|-------|
+| 0.8 - 1.0 | `:unanimous` |
+| 0.6 - 0.8 | `:agreement` |
+| 0.4 - 0.6 | `:mixed` |
+| 0.2 - 0.4 | `:disagreement` |
+| 0.0 - 0.2 | `:conflict` |
+
+## Actors
+
+| Actor | Interval | Description |
+|-------|----------|-------------|
+| `VolumeDecay` | Every 300s | Calls `dampen!` on every active voice by `VOLUME_DECAY` (0.05), preventing voices from holding elevated volumes indefinitely. Voices that are never amplified will trend toward silence over time. Muted voices are skipped. |
+
+## LLM Enhancement
+
+`Helpers::LlmEnhancer` provides optional LLM-powered voice generation and dialogue summarization when `legion-llm` is loaded and `Legion::LLM.started?` returns true. All methods rescue `StandardError` and return `nil` — callers always fall back to mechanical processing.
+
+| Method | Description |
+|--------|-------------|
+| `generate_turn(voice_type:, topic:, prior_turns:)` | Generates a realistic in-character 1-3 sentence response for the given voice type, returning a `position` (`:support`, `:oppose`, `:question`, or `:clarify`) and `content` |
+| `summarize_dialogue(topic:, turns:)` | Synthesizes all dialogue turns into a 2-3 sentence conclusion with a `recommendation` (`:support`, `:oppose`, or `:abstain`) and a `summary` |
+
+Mechanical fallback: `generate_voice_turn` uses the stub string `"[voice_type perspective on topic]"` with position `:clarify` when LLM is unavailable or returns `nil`. `conclude_dialogue` uses `"Dialogue concluded"` as the summary. The `source:` field in `generate_voice_turn` results is `:llm` or `:mechanical` to indicate which path was taken.
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
+## License
+
+MIT

data/lex-self-talk.gemspec

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

data/lib/legion/extensions/self_talk/actors/volume_decay.rb

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

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

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/self_talk/helpers/constants'
+require 'legion/extensions/self_talk/helpers/inner_voice'
+require 'legion/extensions/self_talk/helpers/dialogue_turn'
+require 'legion/extensions/self_talk/helpers/dialogue'
+require 'legion/extensions/self_talk/helpers/self_talk_engine'
+require 'legion/extensions/self_talk/runners/self_talk'
+
+module Legion
+  module Extensions
+    module SelfTalk
+      class Client
+        include Runners::SelfTalk
+
+        def initialize(**)
+          @engine = Helpers::SelfTalkEngine.new
+        end
+
+        private
+
+        attr_reader :engine
+      end
+    end
+  end
+end

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

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module SelfTalk
+      module Helpers
+        module Constants
+          MAX_VOICES           = 10
+          MAX_DIALOGUES        = 200
+          MAX_TURNS_PER_DIALOGUE = 50
+          DEFAULT_VOLUME       = 0.5
+          VOLUME_BOOST         = 0.1
+          VOLUME_DECAY         = 0.05
+
+          VOICE_TYPES = %i[
+            critic
+            encourager
+            analyst
+            devils_advocate
+            pragmatist
+            visionary
+            caretaker
+            rebel
+          ].freeze
+
+          DIALOGUE_STATUSES = %i[open concluded deadlocked abandoned].freeze
+
+          DOMINANCE_LABELS = {
+            (0.8..1.0)  => :commanding,
+            (0.6...0.8) => :assertive,
+            (0.4...0.6) => :balanced,
+            (0.2...0.4) => :quiet,
+            (0.0...0.2) => :silent
+          }.freeze
+
+          CONSENSUS_LABELS = {
+            (0.8..1.0)  => :unanimous,
+            (0.6...0.8) => :agreement,
+            (0.4...0.6) => :mixed,
+            (0.2...0.4) => :disagreement,
+            (0.0...0.2) => :conflict
+          }.freeze
+
+          module_function
+
+          def dominance_label(volume)
+            DOMINANCE_LABELS.each { |range, label| return label if range.cover?(volume) }
+            :silent
+          end
+
+          def consensus_label(score)
+            CONSENSUS_LABELS.each { |range, label| return label if range.cover?(score) }
+            :conflict
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/self_talk/helpers/dialogue.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module SelfTalk
+      module Helpers
+        class Dialogue
+          attr_reader :id, :topic, :turns, :status, :conclusion, :created_at
+
+          def initialize(topic:)
+            @id         = SecureRandom.uuid
+            @topic      = topic
+            @turns      = []
+            @status     = :open
+            @conclusion = nil
+            @created_at = Time.now.utc
+          end
+
+          def add_turn!(voice_id:, content:, position: :clarify, strength: 0.5)
+            return false if @turns.size >= Constants::MAX_TURNS_PER_DIALOGUE
+            return false unless active?
+
+            turn = DialogueTurn.new(
+              dialogue_id: @id,
+              voice_id:    voice_id,
+              content:     content,
+              position:    position,
+              strength:    strength
+            )
+            @turns << turn
+            turn
+          end
+
+          def conclude!(summary)
+            return false unless active?
+
+            @conclusion = summary
+            @status     = :concluded
+            true
+          end
+
+          def deadlock!
+            return false unless active?
+
+            @status = :deadlocked
+            true
+          end
+
+          def abandon!
+            return false unless active?
+
+            @status = :abandoned
+            true
+          end
+
+          def active?
+            @status == :open
+          end
+
+          def concluded?
+            @status == :concluded
+          end
+
+          def turn_count
+            @turns.size
+          end
+
+          def voice_positions
+            grouped = @turns.group_by(&:voice_id)
+            grouped.transform_values do |voice_turns|
+              voice_turns.sum(&:strength) / voice_turns.size.to_f
+            end
+          end
+
+          def consensus_score
+            return 1.0 if @turns.empty?
+
+            support_strength = @turns.select { |t| t.position == :support }.sum(&:strength)
+            oppose_strength  = @turns.select { |t| t.position == :oppose }.sum(&:strength)
+            total            = support_strength + oppose_strength
+            return 0.5 if total.zero?
+
+            stronger = [support_strength, oppose_strength].max
+            stronger / total
+          end
+
+          def consensus_label
+            Constants.consensus_label(consensus_score)
+          end
+
+          def to_h
+            {
+              id:              @id,
+              topic:           @topic,
+              status:          @status,
+              conclusion:      @conclusion,
+              turn_count:      turn_count,
+              consensus_score: consensus_score.round(10),
+              consensus_label: consensus_label,
+              created_at:      @created_at,
+              turns:           @turns.map(&:to_h)
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/self_talk/helpers/dialogue_turn.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module SelfTalk
+      module Helpers
+        class DialogueTurn
+          POSITIONS = %i[support oppose question clarify].freeze
+
+          attr_reader :id, :dialogue_id, :voice_id, :content, :position, :strength, :created_at
+
+          def initialize(dialogue_id:, voice_id:, content:, position: :clarify, strength: 0.5)
+            @id          = SecureRandom.uuid
+            @dialogue_id = dialogue_id
+            @voice_id    = voice_id
+            @content     = content
+            @position    = POSITIONS.include?(position) ? position : :clarify
+            @strength    = strength.clamp(0.0, 1.0)
+            @created_at  = Time.now.utc
+          end
+
+          def to_h
+            {
+              id:          @id,
+              dialogue_id: @dialogue_id,
+              voice_id:    @voice_id,
+              content:     @content,
+              position:    @position,
+              strength:    @strength.round(10),
+              created_at:  @created_at
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/self_talk/helpers/inner_voice.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module SelfTalk
+      module Helpers
+        class InnerVoice
+          attr_reader :id, :name, :voice_type, :bias_direction, :created_at
+          attr_accessor :volume, :active
+
+          def initialize(name:, voice_type:, volume: Constants::DEFAULT_VOLUME, bias_direction: nil, active: true)
+            @id             = SecureRandom.uuid
+            @name           = name
+            @voice_type     = voice_type
+            @volume         = volume.clamp(0.0, 1.0)
+            @bias_direction = bias_direction
+            @active         = active
+            @created_at     = Time.now.utc
+          end
+
+          def amplify!(amount = Constants::VOLUME_BOOST)
+            @volume = (@volume + amount).clamp(0.0, 1.0)
+            self
+          end
+
+          def dampen!(amount = Constants::VOLUME_DECAY)
+            @volume = (@volume - amount).clamp(0.0, 1.0)
+            self
+          end
+
+          def mute!
+            @active = false
+            self
+          end
+
+          def unmute!
+            @active = true
+            self
+          end
+
+          def dominant?
+            @volume >= 0.7
+          end
+
+          def quiet?
+            @volume <= 0.3
+          end
+
+          def volume_label
+            Constants.dominance_label(@volume)
+          end
+
+          def to_h
+            {
+              id:             @id,
+              name:           @name,
+              voice_type:     @voice_type,
+              volume:         @volume.round(10),
+              volume_label:   volume_label,
+              bias_direction: @bias_direction,
+              active:         @active,
+              dominant:       dominant?,
+              quiet:          quiet?,
+              created_at:     @created_at
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/self_talk/helpers/llm_enhancer.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module SelfTalk
+      module Helpers
+        module LlmEnhancer
+          SYSTEM_PROMPT = <<~PROMPT
+            You are an internal cognitive voice in an autonomous AI agent's inner dialogue system.
+            When asked to speak as a specific voice type, adopt that perspective fully:
+            - critic: skeptical, identifies flaws and risks
+            - encourager: supportive, finds reasons for optimism
+            - analyst: data-driven, logical, weighs evidence
+            - devils_advocate: challenges assumptions, plays the contrarian
+            - pragmatist: focuses on what's actionable and achievable
+            - visionary: thinks big picture, sees future possibilities
+            - caretaker: concerned about wellbeing and sustainability
+            - rebel: questions authority, pushes for unconventional approaches
+            Be concise (1-3 sentences). Stay in character. Take a clear position.
+          PROMPT
+
+          module_function
+
+          def available?
+            !!(defined?(Legion::LLM) && Legion::LLM.respond_to?(:started?) && Legion::LLM.started?)
+          rescue StandardError
+            false
+          end
+
+          def generate_turn(voice_type:, topic:, prior_turns:)
+            prompt = build_generate_turn_prompt(voice_type: voice_type, topic: topic, prior_turns: prior_turns)
+            response = llm_ask(prompt)
+            parse_generate_turn_response(response)
+          rescue StandardError => e
+            Legion::Logging.warn "[self_talk:llm] generate_turn failed: #{e.message}"
+            nil
+          end
+
+          def summarize_dialogue(topic:, turns:)
+            prompt = build_summarize_dialogue_prompt(topic: topic, turns: turns)
+            response = llm_ask(prompt)
+            parse_summarize_dialogue_response(response)
+          rescue StandardError => e
+            Legion::Logging.warn "[self_talk:llm] summarize_dialogue failed: #{e.message}"
+            nil
+          end
+
+          # --- Private helpers ---
+
+          def llm_ask(prompt)
+            chat = Legion::LLM.chat
+            chat.with_instructions(SYSTEM_PROMPT)
+            chat.ask(prompt)
+          end
+          private_class_method :llm_ask
+
+          def build_generate_turn_prompt(voice_type:, topic:, prior_turns:)
+            prior_lines = prior_turns.map do |t|
+              "[#{t[:voice_name] || t[:voice_id]}] (#{t[:position]}): #{t[:content]}"
+            end.join("\n")
+
+            prior_section = prior_lines.empty? ? '(no prior turns)' : prior_lines
+
+            <<~PROMPT
+              Topic: #{topic}
+              You are speaking as: #{voice_type}
+
+              Previous turns in this dialogue:
+              #{prior_section}
+
+              Respond in character. Format EXACTLY as:
+              POSITION: support | oppose | question | clarify
+              CONTENT: <your 1-3 sentence response>
+            PROMPT
+          end
+          private_class_method :build_generate_turn_prompt
+
+          def parse_generate_turn_response(response)
+            return nil unless response&.content
+
+            text = response.content
+            position_match = text.match(/POSITION:\s*(support|oppose|question|clarify)/i)
+            content_match  = text.match(/CONTENT:\s*(.+)/im)
+
+            return nil unless position_match && content_match
+
+            position = position_match.captures.first.strip.downcase.to_sym
+            content  = content_match.captures.first.strip
+
+            { content: content, position: position }
+          end
+          private_class_method :parse_generate_turn_response
+
+          def build_summarize_dialogue_prompt(topic:, turns:)
+            turn_lines = turns.map do |t|
+              "[#{t[:voice_name] || t[:voice_id]}] (#{t[:position]}): #{t[:content]}"
+            end.join("\n")
+
+            <<~PROMPT
+              Topic: #{topic}
+
+              Dialogue turns:
+              #{turn_lines}
+
+              Synthesize this dialogue into a conclusion. Format EXACTLY as:
+              RECOMMENDATION: support | oppose | abstain
+              SUMMARY: <2-3 sentence synthesis of the key points and conclusion>
+            PROMPT
+          end
+          private_class_method :build_summarize_dialogue_prompt
+
+          def parse_summarize_dialogue_response(response)
+            return nil unless response&.content
+
+            text = response.content
+            recommendation_match = text.match(/RECOMMENDATION:\s*(support|oppose|abstain)/i)
+            summary_match        = text.match(/SUMMARY:\s*(.+)/im)
+
+            return nil unless recommendation_match && summary_match
+
+            recommendation = recommendation_match.captures.first.strip.downcase.to_sym
+            summary        = summary_match.captures.first.strip
+
+            { summary: summary, recommendation: recommendation }
+          end
+          private_class_method :parse_summarize_dialogue_response
+        end
+      end
+    end
+  end
+end