lex-coldstart 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 0fb6a1e08b7bb5ba42d3ef2c62f2e4c4d90f8f9d3c2cf4891fdffda7f55af3cd
+  data.tar.gz: cb3d573d7657a27333bbed0b5850b429b20c9f8f8a62a64318f585e311a2917a
+SHA512:
+  metadata.gz: cb3d44fa4365e62518583c7e0ac42848d999e7ea40419a378b3372029da2835bfae7a048c0925b3363f16941488163d21ad736815362e9b6ed46239acbaca2ff
+  data.tar.gz: 9ff4f0933b47c8111502cf0c7450cdf25b9ca91c69dd4da2fd6a997e79e662d49ef502202e8a0c243bcb8223ce86b611ee36ef5c296cc56fbddb7195f786babb

data/Gemfile

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

data/lex-coldstart.gemspec

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require_relative 'lib/legion/extensions/coldstart/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'lex-coldstart'
+  spec.version       = Legion::Extensions::Coldstart::VERSION
+  spec.authors       = ['Esity']
+  spec.email         = ['matthewdiverson@gmail.com']
+
+  spec.summary       = 'LEX Coldstart'
+  spec.description   = 'Imprint window and bootstrap calibration for brain-modeled agentic AI'
+  spec.homepage      = 'https://github.com/LegionIO/lex-coldstart'
+  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-coldstart'
+  spec.metadata['documentation_uri'] = 'https://github.com/LegionIO/lex-coldstart'
+  spec.metadata['changelog_uri'] = 'https://github.com/LegionIO/lex-coldstart'
+  spec.metadata['bug_tracker_uri'] = 'https://github.com/LegionIO/lex-coldstart/issues'
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    Dir.glob('{lib,spec}/**/*') + %w[lex-coldstart.gemspec Gemfile]
+  end
+  spec.require_paths = ['lib']
+  spec.add_development_dependency 'sequel', '~> 5.70'
+  spec.add_development_dependency 'sqlite3', '~> 2.0'
+end

data/lib/legion/extensions/coldstart/actors/imprint.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/actors/once'
+
+module Legion
+  module Extensions
+    module Coldstart
+      module Actor
+        class Imprint < Legion::Extensions::Actors::Once
+          def runner_class
+            Legion::Extensions::Coldstart::Runners::Coldstart
+          end
+
+          def runner_function
+            'begin_imprint'
+          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/coldstart/client.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/coldstart/helpers/imprint'
+require 'legion/extensions/coldstart/helpers/bootstrap'
+require 'legion/extensions/coldstart/runners/coldstart'
+
+module Legion
+  module Extensions
+    module Coldstart
+      class Client
+        include Runners::Coldstart
+
+        def initialize(**)
+          @bootstrap = Helpers::Bootstrap.new
+        end
+
+        private
+
+        attr_reader :bootstrap
+      end
+    end
+  end
+end

data/lib/legion/extensions/coldstart/helpers/bootstrap.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Coldstart
+      module Helpers
+        class Bootstrap
+          attr_reader :started_at, :observation_count, :firmware_loaded, :calibration_state
+
+          def initialize
+            @started_at = nil
+            @observation_count = 0
+            @firmware_loaded = false
+            @calibration_state = :not_started
+            load_from_local
+          end
+
+          def begin_imprint
+            @started_at = Time.now.utc
+            @calibration_state = :imprinting
+            save_to_local
+          end
+
+          def load_firmware
+            @firmware_loaded = true
+            save_to_local
+          end
+
+          def record_observation
+            @observation_count += 1
+            check_calibration_progress
+            save_to_local
+          end
+
+          def imprint_active?
+            Imprint.imprint_active?(@started_at)
+          end
+
+          def current_layer
+            return :firmware unless @firmware_loaded
+
+            Imprint.current_layer(@started_at, observations: @observation_count)
+          end
+
+          def progress
+            {
+              firmware_loaded:   @firmware_loaded,
+              imprint_active:    imprint_active?,
+              imprint_progress:  Imprint.imprint_progress(@started_at),
+              observation_count: @observation_count,
+              calibration_state: @calibration_state,
+              current_layer:     current_layer
+            }
+          end
+
+          private
+
+          def check_calibration_progress
+            if @observation_count >= Imprint::IMPRINT_ENTROPY_BASELINE && !imprint_active?
+              @calibration_state = :calibrated
+            elsif @observation_count >= Imprint::IMPRINT_ENTROPY_BASELINE
+              @calibration_state = :baseline_established
+            end
+          end
+
+          def save_to_local
+            return unless defined?(Legion::Data::Local) && Legion::Data::Local.connected?
+
+            ds = Legion::Data::Local.connection[:bootstrap_state]
+            row = {
+              started_at_i:      @started_at&.to_i,
+              observation_count: @observation_count,
+              firmware_loaded:   @firmware_loaded,
+              calibration_state: @calibration_state.to_s
+            }
+            if ds.where(id: 1).any?
+              ds.where(id: 1).update(row)
+            else
+              ds.insert(row.merge(id: 1))
+            end
+          rescue StandardError => e
+            Legion::Logging.warn "lex-coldstart: save_to_local failed: #{e.message}"
+          end
+
+          def load_from_local
+            return unless defined?(Legion::Data::Local) && Legion::Data::Local.connected?
+
+            row = Legion::Data::Local.connection[:bootstrap_state].where(id: 1).first
+            return unless row
+
+            @started_at        = row[:started_at_i] ? Time.at(row[:started_at_i]).utc : nil
+            @observation_count = row[:observation_count].to_i
+            @firmware_loaded   = [true, 1].include?(row[:firmware_loaded])
+            @calibration_state = row[:calibration_state].to_sym
+          rescue StandardError => e
+            Legion::Logging.warn "lex-coldstart: load_from_local failed: #{e.message}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/coldstart/helpers/claude_parser.rb

@@ -0,0 +1,231 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Coldstart
+      module Helpers
+        module ClaudeParser
+          module_function
+
+          SECTION_TYPE_MAP = {
+            /\bhard rules\b/i                        => :firmware,
+            /\bidentity auth\b/i                     => :identity,
+            /\barchitecture\b/i                      => :semantic,
+            /\bkey concepts?\b|terminology/i         => :semantic,
+            /\bproject structure\b/i                 => :semantic,
+            /\bdigital worker\b/i                    => :semantic,
+            /\bgotcha|caveat|pitfall|known issue/i   => :procedural,
+            /\bcli\b|command|usage/i                 => :procedural,
+            /\bapi\b|routes?\b|endpoint/i            => :procedural,
+            /\bmcp\b/i                               => :procedural,
+            /\bconfig|settings?\b|scaffold/i         => :procedural,
+            /\bskills?\b/i                           => :procedural,
+            /\bdevelopment|conventions?\b|workflow/i => :procedural,
+            /\brubocop|lint/i                        => :procedural,
+            /\bdependenc/i                           => :semantic,
+            /\bfile (map|structure)\b/i              => :semantic,
+            /\bwhat is\b/i                           => :semantic,
+            /\bpurpose\b/i                           => :semantic,
+            /\bstatus|stub|todo\b/i                  => :semantic,
+            /\bagentic\b/i                           => :semantic,
+            /\bjwt\b|auth|crypt|secur/i              => :procedural,
+            /\bsinatra\b|rest\b/i                    => :procedural,
+            /\btransport|rabbitmq|amqp/i             => :semantic
+          }.freeze
+
+          DEFAULT_TRACE_TYPE = :semantic
+
+          SECTION_VALENCE_MAP = {
+            /\bgotcha|caveat|pitfall|known issue|error|stub|todo\b/i => { valence: -0.4, intensity: 0.5 },
+            /\bhard rules?\b/i                                       => { valence: 0.0,  intensity: 0.8 },
+            /\barchitecture\b|design|key concepts?\b/i               => { valence: 0.3,  intensity: 0.4 },
+            /\bdependenc|integration|requirements?\b/i               => { valence: 0.1, intensity: 0.3 }
+          }.freeze
+
+          DEFAULT_VALENCE = { valence: 0.1, intensity: 0.3 }.freeze
+
+          # Parse a markdown file into an array of trace candidates.
+          # Each candidate is a Hash ready for lex-memory's store_trace.
+          #
+          # Returns Array<Hash> with keys:
+          #   :trace_type, :content_payload, :domain_tags, :origin, :confidence, :source_file
+          def parse_file(file_path)
+            content = File.read(file_path)
+            file_type = detect_file_type(file_path)
+            sections = split_sections(content)
+            source_name = File.basename(file_path)
+            dir_context = extract_dir_context(file_path)
+
+            traces = []
+            sections.each do |section|
+              trace_type = classify_section(section[:heading])
+              base_tags = [file_type.to_s, source_name, dir_context].compact
+              base_tags << section[:heading_slug] if section[:heading_slug]
+
+              items = extract_items(section[:body])
+              items.each do |item|
+                inline_tags = extract_inline_tags(item)
+                section_valence = classify_valence(section[:heading])
+                traces << {
+                  trace_type:          trace_type,
+                  content_payload:     item.strip,
+                  domain_tags:         (base_tags + inline_tags).uniq,
+                  origin:              file_type == :memory ? :firmware : :direct_experience,
+                  confidence:          trace_type == :firmware ? 1.0 : 0.7,
+                  emotional_valence:   trace_type == :firmware ? 0.0 : section_valence[:valence],
+                  emotional_intensity: section_valence[:intensity],
+                  source_file:         file_path
+                }
+              end
+            end
+
+            traces.reject { |t| t[:content_payload].empty? }
+          end
+
+          # Parse all matching markdown files under a directory.
+          # Returns Array<Hash> of trace candidates.
+          def parse_directory(dir_path, pattern: '**/{CLAUDE,MEMORY}.md')
+            Dir.glob(File.join(dir_path, pattern)).flat_map do |path|
+              next [] if skip_path?(path)
+
+              parse_file(path)
+            end
+          end
+
+          # Detect whether a file is a MEMORY.md or CLAUDE.md
+          def detect_file_type(file_path)
+            basename = File.basename(file_path).downcase
+            if basename.include?('memory') && basename.end_with?('.md')
+              :memory
+            elsif basename.include?('claude') && basename.end_with?('.md')
+              :claude_md
+            else
+              :markdown
+            end
+          end
+
+          # Split markdown content into sections by ## headers.
+          # Returns Array<Hash{ heading:, heading_slug:, body: }>
+          def split_sections(content)
+            sections = []
+            current = { heading: 'preamble', heading_slug: 'preamble', body: String.new }
+
+            content.each_line do |line|
+              if line.match?(/\A##\s+/)
+                sections << current unless current[:body].strip.empty?
+                heading = line.sub(/\A##\s+/, '').strip
+                current = {
+                  heading:      heading,
+                  heading_slug: slugify(heading),
+                  body:         String.new
+                }
+              else
+                current[:body] << line
+              end
+            end
+            sections << current unless current[:body].strip.empty?
+            sections
+          end
+
+          # Extract individual items from a section body.
+          # Bullets become individual items; paragraphs become single items;
+          # code blocks are kept as single items.
+          def extract_items(body) # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+            items = []
+            current_item = nil
+            in_code_block = false
+
+            body.each_line do |line|
+              if line.match?(/\A```/)
+                if in_code_block
+                  current_item << line
+                  items << current_item
+                  current_item = nil
+                  in_code_block = false
+                else
+                  items << current_item if current_item && !current_item.strip.empty?
+                  current_item = line
+                  in_code_block = true
+                end
+                next
+              end
+
+              if in_code_block
+                current_item << line
+                next
+              end
+
+              if line.match?(/\A\s*[-*]\s+/)
+                items << current_item if current_item && !current_item.strip.empty?
+                current_item = line.sub(/\A\s*[-*]\s+/, '').strip
+              elsif line.match?(/\A\s{2,}[-*]\s+/) || (current_item && line.match?(/\A\s{2,}\S/))
+                # Sub-bullet or continuation of current bullet
+                current_item = "#{current_item || ''} #{line.strip}"
+              elsif line.strip.empty?
+                items << current_item if current_item && !current_item.strip.empty?
+                current_item = nil
+              elsif current_item
+                current_item += " #{line.strip}"
+              else
+                current_item = line.strip
+              end
+            end
+            items << current_item if current_item && !current_item.strip.empty?
+
+            items.compact.map(&:strip).reject(&:empty?)
+          end
+
+          # Extract backtick-quoted terms and bold terms as domain tags.
+          def extract_inline_tags(text)
+            tags = []
+            text.scan(/`([^`]+)`/) { |m| tags << m[0] }
+            text.scan(/\*\*([^*]+)\*\*/) { |m| tags << m[0] }
+            tags.map { |t| t.gsub(/[^a-zA-Z0-9_\-.]/, '_').downcase }
+                .reject { |t| t.length > 60 || t.length < 2 }
+                .uniq
+          end
+
+          # Classify a section heading into a trace type.
+          def classify_section(heading)
+            SECTION_TYPE_MAP.each do |pattern, type|
+              return type if heading.match?(pattern)
+            end
+            DEFAULT_TRACE_TYPE
+          end
+
+          # Classify a section heading into an emotional valence hash.
+          def classify_valence(heading)
+            SECTION_VALENCE_MAP.each do |pattern, vals|
+              return vals if heading.match?(pattern)
+            end
+            DEFAULT_VALENCE
+          end
+
+          # Extract directory context for domain tagging (e.g., "lex-coldstart", "LegionIO").
+          def extract_dir_context(file_path)
+            parts = file_path.split('/')
+            # Find the most meaningful directory name
+            meaningful = parts.reverse.find do |p|
+              p.match?(/\A(lex-|legion-|Legion|extensions)/) && p != File.basename(file_path)
+            end
+            meaningful || parts[-2]
+          end
+
+          def slugify(text)
+            text.downcase.gsub(/[^a-z0-9]+/, '-').gsub(/\A-|-\z/, '')
+          end
+
+          def skip_path?(path)
+            path.include?('/_deprecated/') ||
+              path.include?('/_ignored/') ||
+              path.include?('/z_other/') ||
+              path.include?('_working/') ||
+              path.include?('/test/') ||
+              path.include?('/.terraform/') ||
+              path.include?('/references/')
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/coldstart/helpers/imprint.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Coldstart
+      module Helpers
+        module Imprint
+          # Three learning layers (spec: cold-start-spec.md)
+          LAYERS = %i[firmware imprint_window continuous_learning].freeze
+
+          # Imprint window parameters
+          IMPRINT_DURATION        = 7 * 86_400 # 7 days
+          IMPRINT_MULTIPLIER      = 3.0        # consolidation rate multiplier during imprint
+          IMPRINT_CONSENT_TIER    = :consult # conservative consent during imprint
+          IMPRINT_ENTROPY_BASELINE = 50 # minimum observations before entropy is meaningful
+
+          # Self-play bootstrap parameters
+          SELF_PLAY_ITERATIONS    = 100
+          BOOTSTRAP_TRACE_TYPES   = %i[identity semantic procedural].freeze
+
+          module_function
+
+          def imprint_active?(started_at)
+            return false unless started_at
+
+            (Time.now.utc - started_at) < IMPRINT_DURATION
+          end
+
+          def imprint_progress(started_at)
+            return 1.0 unless started_at
+
+            elapsed = Time.now.utc - started_at
+            [elapsed / IMPRINT_DURATION.to_f, 1.0].min
+          end
+
+          def current_layer(started_at, observations:)
+            if (observations < IMPRINT_ENTROPY_BASELINE && imprint_active?(started_at)) ||
+               imprint_active?(started_at)
+              :imprint_window
+            else
+              :continuous_learning
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/coldstart/local_migrations/20260316000050_create_bootstrap_state.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+Sequel.migration do
+  change do
+    create_table(:bootstrap_state) do
+      primary_key :id
+      Integer :started_at_i
+      Integer :observation_count, default: 0
+      TrueClass :firmware_loaded, default: false
+      String :calibration_state, default: 'not_started'
+    end
+  end
+end

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

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Coldstart
+      module Runners
+        module Coldstart
+          include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                      Legion::Extensions::Helpers.const_defined?(:Lex)
+
+          def begin_imprint(**)
+            bootstrap.load_firmware
+            bootstrap.begin_imprint
+            dur = Helpers::Imprint::IMPRINT_DURATION
+            mul = Helpers::Imprint::IMPRINT_MULTIPLIER
+            tier = Helpers::Imprint::IMPRINT_CONSENT_TIER
+            Legion::Logging.info "[coldstart] imprint begun: duration=#{dur}s multiplier=#{mul}x consent=#{tier}"
+            {
+              started:          true,
+              imprint_duration: Helpers::Imprint::IMPRINT_DURATION,
+              multiplier:       Helpers::Imprint::IMPRINT_MULTIPLIER,
+              consent_tier:     Helpers::Imprint::IMPRINT_CONSENT_TIER
+            }
+          end
+
+          def record_observation(**)
+            bootstrap.record_observation
+            Legion::Logging.debug "[coldstart] observation: count=#{bootstrap.observation_count} " \
+                                  "calibration=#{bootstrap.calibration_state} layer=#{bootstrap.current_layer}"
+            {
+              observation_count: bootstrap.observation_count,
+              calibration_state: bootstrap.calibration_state,
+              current_layer:     bootstrap.current_layer
+            }
+          end
+
+          def coldstart_progress(**)
+            progress = bootstrap.progress
+            Legion::Logging.debug "[coldstart] progress: #{progress.inspect}"
+            progress
+          end
+
+          def imprint_active?(**) # rubocop:disable Naming/PredicateMethod
+            active = bootstrap.imprint_active?
+            Legion::Logging.debug "[coldstart] imprint_active?=#{active}"
+            { active: active }
+          end
+
+          def current_multiplier(**)
+            active = bootstrap.imprint_active?
+            multiplier = active ? Helpers::Imprint::IMPRINT_MULTIPLIER : 1.0
+            Legion::Logging.debug "[coldstart] multiplier=#{multiplier} imprint_active=#{active}"
+            { multiplier: multiplier, imprint_active: active }
+          end
+
+          private
+
+          def bootstrap
+            @bootstrap ||= Helpers::Bootstrap.new
+          end
+        end
+      end
+    end
+  end
+end