lex-context 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a471dc0eb03821a6242b22bf9d1355d2aca38b6152498dd473c56ee96b3c0013
+  data.tar.gz: 83023441c865a754e6a3397750a7e95f050181d9f0fe8650f0c0a7830ed9d094
+SHA512:
+  metadata.gz: 87c59f574c3683a53f7b3e9018a9a2205fe916099dde07cc984155bd6ed2270cd1448f6ed87db6868ddfbf35525219044516df260f73312d0bdbeb0428cba944
+  data.tar.gz: aae221c9aee738367fd76f7c4052cbb81dcfed652052ec6cf53fe1f736dbec0cf5c4962587d1916237f697d23fa5ea00d4e081325d261f6d08c35401e4bb51db

data/README.md

@@ -0,0 +1,80 @@
+# lex-context
+
+A LegionIO cognitive architecture extension for contextual framing and situation modeling. Maintains context frames that shape perception, memory retrieval, and action selection. Tracks context switches with measurable switch costs and familiarity-based discounts — switching to a familiar frame costs less than switching to an unfamiliar one.
+
+## What It Does
+
+Manages a registry of **frames** — each representing a situated context with a domain, a set of cues (tokens that activate the frame), and a strength score. An active frame stack (up to 10 deep) tracks the current cognitive situation.
+
+- **Create frames** representing different operational contexts (coding, reviewing, planning)
+- **Activate frames** explicitly or let `auto_switch` select the best match from input cues
+- **Measure switch costs** — base 0.15 cost reduced by familiarity and same-domain bonuses, increased by rapid successive switches
+- **Decay frames** over time — unused frames weaken and are eventually pruned from the registry
+
+## Usage
+
+```ruby
+require 'lex-context'
+
+client = Legion::Extensions::Context::Client.new
+
+# Create context frames
+coding = client.create_context(
+  name:   'software_development',
+  domain: :technical,
+  cues:   [:code, :function, :test, :deploy, :bug]
+)
+# => { success: true, frame: { id: "uuid...", name: "software_development",
+#      domain: :technical, strength: 1.0, familiarity: 0.3, label: :dominant, ... } }
+
+review = client.create_context(
+  name:   'code_review',
+  domain: :technical,
+  cues:   [:review, :pr, :feedback, :approve, :merge]
+)
+
+frame_id = coding[:frame][:id]
+
+# Activate a frame explicitly
+client.activate_context(frame_id: frame_id)
+# => { success: true, frame: { ... }, switch_cost: 0.0 }
+
+# Detect matching frames from input cues
+client.detect_context(input_cues: [:review, :pr, :feedback])
+# => { success: true, candidates: [{ frame: {...}, relevance: 0.6 }],
+#      count: 1, best: { name: "code_review", relevance: 0.6 } }
+
+# Automatically switch to the best-matching frame
+client.auto_switch(input_cues: [:review, :pr])
+# => { success: true, switched: true, frame: { ... }, switch_cost: 0.12 }
+
+# Current active frame
+client.current_context
+# => { success: true, frame: { name: "code_review", ... } }
+
+# Add a cue to an existing frame
+client.add_cue(frame_id: frame_id, cue: :refactor)
+# => { success: true, frame: { ... } }
+
+# Periodic maintenance: decay all frames, remove stale ones
+client.update_context
+# => { success: true, frame_count: 2, active: "code_review" }
+
+# Stats
+client.context_stats
+# => { success: true, stats: { frame_count: 2, active_frame: "code_review",
+#      stack_depth: 1, switch_count: 1, avg_switch_cost: 0.12,
+#      by_domain: { technical: 2 } } }
+```
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
+## License
+
+MIT

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

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/context/helpers/constants'
+require 'legion/extensions/context/helpers/frame'
+require 'legion/extensions/context/helpers/context_manager'
+require 'legion/extensions/context/runners/context'
+
+module Legion
+  module Extensions
+    module Context
+      class Client
+        include Runners::Context
+
+        attr_reader :context_manager
+
+        def initialize(context_manager: nil, **)
+          @context_manager = context_manager || Helpers::ContextManager.new
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Context
+      module Helpers
+        module Constants
+          MAX_FRAMES           = 50
+          MAX_FRAME_STACK      = 10
+          FRAME_DECAY          = 0.02
+          FRAME_STRENGTH_FLOOR = 0.05
+          SWITCH_COST          = 0.15
+          SWITCH_COOLDOWN      = 5
+          FAMILIARITY_ALPHA    = 0.12
+          DEFAULT_FAMILIARITY  = 0.3
+          RELEVANCE_THRESHOLD  = 0.2
+          MAX_CUES_PER_FRAME   = 30
+          MAX_HISTORY          = 200
+
+          FRAME_LABELS = {
+            (0.8..)     => :dominant,
+            (0.5...0.8) => :active,
+            (0.2...0.5) => :background,
+            (..0.2)     => :fading
+          }.freeze
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/context/helpers/context_manager.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Context
+      module Helpers
+        class ContextManager
+          include Constants
+
+          attr_reader :frames, :active_stack, :switch_history
+
+          def initialize
+            @frames         = []
+            @active_stack   = []
+            @switch_history = []
+            @last_switch_at = nil
+          end
+
+          def create_frame(name:, domain: :general, cues: [])
+            frame = Frame.new(name: name, domain: domain, cues: cues)
+            @frames << frame
+            trim_frames
+            frame
+          end
+
+          def activate(frame_id)
+            frame = find(frame_id)
+            return nil unless frame
+
+            previous = current_frame
+            cost = 0.0
+
+            if previous && previous.id != frame_id
+              cost = compute_switch_cost(previous, frame)
+              previous.deactivate
+              record_switch(from: previous, to: frame, cost: cost)
+            end
+
+            @active_stack.reject! { |f| f.id == frame_id }
+            @active_stack.push(frame)
+            @active_stack.shift while @active_stack.size > MAX_FRAME_STACK
+            frame.activate
+            { frame: frame, switch_cost: cost }
+          end
+
+          def current_frame
+            @active_stack.last
+          end
+
+          def detect_context(input_cues)
+            scored = @frames.map { |f| [f, f.match_score(input_cues)] }
+            scored.select! { |_, score| score >= RELEVANCE_THRESHOLD }
+            scored.sort_by! { |_, score| -score }
+            scored.map { |f, score| { frame: f, relevance: score } }
+          end
+
+          def auto_switch(input_cues)
+            candidates = detect_context(input_cues)
+            return nil if candidates.empty?
+
+            best = candidates.first
+            current = current_frame
+
+            return nil if current && current.id == best[:frame].id
+
+            activate(best[:frame].id)
+          end
+
+          def find(frame_id)
+            @frames.find { |f| f.id == frame_id }
+          end
+
+          def find_by_name(name)
+            @frames.select { |f| f.name == name }
+          end
+
+          def in_domain(domain)
+            @frames.select { |f| f.domain == domain }
+          end
+
+          def decay_all
+            @frames.each(&:decay)
+            @frames.reject!(&:stale?)
+            @active_stack.reject!(&:stale?)
+          end
+
+          def remove(frame_id)
+            @frames.reject! { |f| f.id == frame_id }
+            @active_stack.reject! { |f| f.id == frame_id }
+          end
+
+          def switch_cost_average
+            return 0.0 if @switch_history.empty?
+
+            @switch_history.sum { |s| s[:cost] }.to_f / @switch_history.size
+          end
+
+          def to_h
+            {
+              frame_count:     @frames.size,
+              active_frame:    current_frame&.name,
+              stack_depth:     @active_stack.size,
+              switch_count:    @switch_history.size,
+              avg_switch_cost: switch_cost_average.round(4),
+              by_domain:       @frames.group_by(&:domain).transform_values(&:size)
+            }
+          end
+
+          private
+
+          def compute_switch_cost(from_frame, to_frame)
+            base = SWITCH_COST
+            familiarity_discount = to_frame.familiarity * 0.2
+            domain_bonus = from_frame.domain == to_frame.domain ? 0.02 : 0.0
+            cooldown_penalty = in_cooldown? ? 0.1 : 0.0
+            (base - familiarity_discount - domain_bonus + cooldown_penalty).clamp(0.0, 1.0)
+          end
+
+          def in_cooldown?
+            return false unless @last_switch_at
+
+            (Time.now.utc - @last_switch_at) < SWITCH_COOLDOWN
+          end
+
+          def record_switch(from:, to:, cost:)
+            @last_switch_at = Time.now.utc
+            @switch_history << {
+              from: from.name,
+              to:   to.name,
+              cost: cost,
+              at:   @last_switch_at
+            }
+            @switch_history.shift while @switch_history.size > MAX_HISTORY
+          end
+
+          def trim_frames
+            return unless @frames.size > MAX_FRAMES
+
+            @frames.sort_by!(&:strength)
+            @frames.shift(@frames.size - MAX_FRAMES)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/context/helpers/frame.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module Context
+      module Helpers
+        class Frame
+          include Constants
+
+          attr_reader :id, :name, :domain, :cues, :strength, :familiarity,
+                      :created_at, :last_activated, :activation_count
+
+          def initialize(name:, domain: :general, cues: [])
+            @id               = SecureRandom.uuid
+            @name             = name
+            @domain           = domain
+            @cues             = cues.first(MAX_CUES_PER_FRAME)
+            @strength         = 1.0
+            @familiarity      = DEFAULT_FAMILIARITY
+            @created_at       = Time.now.utc
+            @last_activated   = @created_at
+            @activation_count = 0
+          end
+
+          def activate
+            @last_activated = Time.now.utc
+            @activation_count += 1
+            @strength = [@strength + 0.1, 1.0].min
+            update_familiarity(1.0)
+          end
+
+          def deactivate
+            update_familiarity(0.0)
+          end
+
+          def decay
+            @strength = [(@strength - FRAME_DECAY), 0.0].max
+          end
+
+          def match_score(input_cues)
+            return 0.0 if @cues.empty? || input_cues.empty?
+
+            overlap = (@cues & input_cues).size
+            overlap.to_f / @cues.size
+          end
+
+          def add_cue(cue)
+            return if @cues.include?(cue)
+
+            @cues << cue
+            @cues.shift if @cues.size > MAX_CUES_PER_FRAME
+          end
+
+          def remove_cue(cue)
+            @cues.delete(cue)
+          end
+
+          def label
+            FRAME_LABELS.each do |range, lbl|
+              return lbl if range.cover?(@strength)
+            end
+            :fading
+          end
+
+          def stale?
+            @strength < FRAME_STRENGTH_FLOOR
+          end
+
+          def to_h
+            {
+              id:               @id,
+              name:             @name,
+              domain:           @domain,
+              strength:         @strength,
+              familiarity:      @familiarity,
+              label:            label,
+              cues:             @cues.dup,
+              activation_count: @activation_count,
+              created_at:       @created_at,
+              last_activated:   @last_activated
+            }
+          end
+
+          private
+
+          def update_familiarity(signal)
+            @familiarity = ((FAMILIARITY_ALPHA * signal) + ((1.0 - FAMILIARITY_ALPHA) * @familiarity)).clamp(0.0, 1.0)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Context
+      module Runners
+        module Context
+          include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                      Legion::Extensions::Helpers.const_defined?(:Lex)
+
+          def create_context(name:, domain: :general, cues: [], **)
+            frame = context_manager.create_frame(name: name, domain: domain, cues: cues)
+            Legion::Logging.debug "[context] created frame=#{name} domain=#{domain} cues=#{cues.size}"
+            { success: true, frame: frame.to_h }
+          end
+
+          def activate_context(frame_id:, **)
+            result = context_manager.activate(frame_id)
+            return { success: false, reason: :not_found } unless result
+
+            frame = result[:frame]
+            Legion::Logging.debug "[context] activated frame=#{frame.name} cost=#{result[:switch_cost].round(3)}"
+            { success: true, frame: frame.to_h, switch_cost: result[:switch_cost] }
+          end
+
+          def detect_context(input_cues:, **)
+            matches = context_manager.detect_context(input_cues)
+            Legion::Logging.debug "[context] detect: #{matches.size} candidates for #{input_cues.size} cues"
+            {
+              success:    true,
+              candidates: matches.map { |m| { frame: m[:frame].to_h, relevance: m[:relevance] } },
+              count:      matches.size,
+              best:       matches.first && { name: matches.first[:frame].name, relevance: matches.first[:relevance] }
+            }
+          end
+
+          def auto_switch(input_cues:, **)
+            result = context_manager.auto_switch(input_cues)
+            return { success: true, switched: false, reason: :no_better_match } unless result
+
+            frame = result[:frame]
+            Legion::Logging.debug "[context] auto-switched to frame=#{frame.name} cost=#{result[:switch_cost].round(3)}"
+            { success: true, switched: true, frame: frame.to_h, switch_cost: result[:switch_cost] }
+          end
+
+          def current_context(**)
+            frame = context_manager.current_frame
+            return { success: true, frame: nil } unless frame
+
+            { success: true, frame: frame.to_h }
+          end
+
+          def update_context(**)
+            context_manager.decay_all
+            Legion::Logging.debug "[context] tick: frames=#{context_manager.frames.size} active=#{context_manager.current_frame&.name}"
+            { success: true, frame_count: context_manager.frames.size, active: context_manager.current_frame&.name }
+          end
+
+          def add_cue(frame_id:, cue:, **)
+            frame = context_manager.find(frame_id)
+            return { success: false, reason: :not_found } unless frame
+
+            frame.add_cue(cue)
+            { success: true, frame: frame.to_h }
+          end
+
+          def frames_in_domain(domain:, **)
+            frames = context_manager.in_domain(domain)
+            { success: true, frames: frames.map(&:to_h), count: frames.size }
+          end
+
+          def remove_context(frame_id:, **)
+            context_manager.remove(frame_id)
+            { success: true }
+          end
+
+          def context_stats(**)
+            { success: true, stats: context_manager.to_h }
+          end
+
+          private
+
+          def context_manager
+            @context_manager ||= Helpers::ContextManager.new
+          end
+        end
+      end
+    end
+  end
+end

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

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

data/lib/legion/extensions/context.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/context/version'
+require 'legion/extensions/context/helpers/constants'
+require 'legion/extensions/context/helpers/frame'
+require 'legion/extensions/context/helpers/context_manager'
+require 'legion/extensions/context/runners/context'
+require 'legion/extensions/context/client'
+
+module Legion
+  module Extensions
+    module Context
+      extend Legion::Extensions::Core if Legion::Extensions.const_defined? :Core
+    end
+  end
+end

metadata

@@ -0,0 +1,65 @@
+--- !ruby/object:Gem::Specification
+name: lex-context
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Matthew Iverson
+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 situated conceptualization — maintains context frames that shape
+  perception, memory retrieval, and action selection. Tracks context switches with
+  measurable switch costs and familiarity-based discount.
+email:
+- matt@iverson.io
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/legion/extensions/context.rb
+- lib/legion/extensions/context/client.rb
+- lib/legion/extensions/context/helpers/constants.rb
+- lib/legion/extensions/context/helpers/context_manager.rb
+- lib/legion/extensions/context/helpers/frame.rb
+- lib/legion/extensions/context/runners/context.rb
+- lib/legion/extensions/context/version.rb
+homepage: https://github.com/LegionIO/lex-context
+licenses:
+- MIT
+metadata:
+  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: Contextual framing and situation model for LegionIO
+test_files: []