lex-narrator 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 70acf0397dff2bf9773a893f3e595d40728ef241467ce5e394ce2daa36fe286a
+  data.tar.gz: caceda0dc9cb7f4f2aae65a0b3e6843108590d574f4731eef5b8c94ae9d876e5
+SHA512:
+  metadata.gz: 9b5d3a9b0c07b8d0da95fdb71560204755edf84d737d258f72c7f869e83401c34a0eba3e915043999c768ad674c82e53732be01a437f2dba4626ca5c9b6d7855
+  data.tar.gz: 0abe5958816469fbbc12fbb04564136ae49efd684e0ae68de6fc696b5b542b325b9da57937895595c50f3ebf04f9c32014f13a49b15d9c75828d7fd280a82662

data/Gemfile

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gemspec
+
+group :development, :test do
+  gem 'rake', '~> 13.0'
+  gem 'rspec', '~> 3.0'
+  gem 'rubocop', '~> 1.21'
+  gem 'rubocop-rspec', require: false
+  gem 'simplecov', require: false
+end
+
+gem 'legion-gaia', path: '../../legion-gaia'

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 LegionIO
+
+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,71 @@
+# lex-narrator
+
+Real-time cognitive narrative stream for the LegionIO cognitive architecture. Translates the agent's internal cognitive state into human-readable prose each tick.
+
+## What It Does
+
+Each tick, reads emotional state, active curiosity wonders, prediction confidence, attention focus, memory health, and reflection status from `tick_results` and `cognitive_state`, then generates a timestamped narrative entry. Entries are appended to a rolling journal (capped at 500). Provides mood classification, journal queries, and statistics.
+
+## Usage
+
+```ruby
+client = Legion::Extensions::Narrator::Client.new
+
+# Generate narrative from tick results
+entry = client.narrate(
+  tick_results: {
+    emotional_evaluation: { valence: 0.4, arousal: 0.7 },
+    sensory_processing:   { spotlight: 3, peripheral: 5 },
+    prediction_engine:    { confidence: 0.6, mode: :functional_mapping }
+  },
+  cognitive_state: {
+    curiosity: { intensity: 0.8, active_count: 4, top_question: 'Why are infrastructure traces sparse?' }
+  }
+)
+# => { narrative: "3 signals in spotlight focus, 5 in peripheral awareness. I am highly alert
+#      and calm and steady. I am deeply curious, with 4 open questions. Most pressing:
+#      \"Why are infrastructure traces sparse?\"...", mood: :energized }
+
+# Query journal
+client.recent_entries(limit: 5)
+client.entries_since(since: Time.now - 3600)
+client.mood_history(mood: :anxious, limit: 10)
+client.current_narrative
+client.narrator_stats
+```
+
+## Mood Classification
+
+| Mood | Condition |
+|------|-----------|
+| `:energized` | valence > 0.3, arousal > 0.5 |
+| `:content` | valence > 0.3, arousal <= 0.5 |
+| `:anxious` | valence < -0.3, arousal > 0.5 |
+| `:subdued` | valence < -0.3, arousal <= 0.5 |
+| `:alert` | neutral valence, arousal > 0.7 |
+| `:dormant` | neutral valence, arousal < 0.2 |
+| `:neutral` | neutral valence, moderate arousal |
+
+## LLM Enhancement
+
+When `legion-llm` is loaded and started, `Helpers::LlmEnhancer` replaces the mechanical `Prose.*` sentence-concatenation pipeline with a single LLM-generated narrative.
+
+**Method**: `LlmEnhancer.narrate(sections_data:)`
+
+Accepts a hash of six cognitive domains — `emotion`, `curiosity`, `prediction`, `memory`, `attention`, and `reflection` — assembled by the runner from `tick_results` and `cognitive_state`. Sends the metrics to the LLM with a system prompt instructing it to write a 3-5 sentence first-person internal monologue (present tense, vivid, no raw numbers). Returns the generated narrative string, or `nil` on failure.
+
+**Availability gate**: `LlmEnhancer.available?` checks `Legion::LLM.started?`. Returns `false` if `legion-llm` is not loaded, not configured, or raises any error — the check is fully safe to call unconditionally.
+
+**Fallback**: When LLM is unavailable or `narrate` returns `nil`, the existing `Helpers::Prose` label-based pipeline runs unchanged. The runner includes `source: :llm` in the result hash only when the LLM path is taken.
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
+## License
+
+MIT

data/lex-narrator.gemspec

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

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

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/narrator/helpers/constants'
+require 'legion/extensions/narrator/helpers/prose'
+require 'legion/extensions/narrator/helpers/journal'
+require 'legion/extensions/narrator/helpers/synthesizer'
+require 'legion/extensions/narrator/runners/narrator'
+
+module Legion
+  module Extensions
+    module Narrator
+      class Client
+        include Runners::Narrator
+
+        attr_reader :journal
+
+        def initialize(journal: nil, **)
+          @journal = journal || Helpers::Journal.new
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Narrator
+      module Helpers
+        module Constants
+          # Maximum entries in the narrative journal
+          MAX_JOURNAL_SIZE = 500
+
+          # Narrative generation modes
+          MODES = %i[mechanical enhanced].freeze
+
+          # Default sections in a narrative entry
+          SECTIONS = %i[
+            attention emotion curiosity prediction
+            memory reflection identity overall
+          ].freeze
+
+          # Emotional dimension labels for prose generation
+          EMOTION_LABELS = {
+            high_positive: 'engaged and optimistic',
+            low_positive:  'calm and steady',
+            neutral:       'emotionally neutral',
+            low_negative:  'slightly uneasy',
+            high_negative: 'distressed'
+          }.freeze
+
+          # Arousal labels
+          AROUSAL_LABELS = {
+            high:    'highly alert',
+            medium:  'moderately attentive',
+            low:     'calm and measured',
+            dormant: 'in a low-activity state'
+          }.freeze
+
+          # Curiosity intensity labels
+          CURIOSITY_LABELS = {
+            high:   'deeply curious',
+            medium: 'moderately curious',
+            low:    'mildly interested',
+            none:   'not particularly curious about anything'
+          }.freeze
+
+          # Prediction confidence labels
+          CONFIDENCE_LABELS = {
+            high:   'confident in my predictions',
+            medium: 'moderately confident',
+            low:    'uncertain about outcomes',
+            none:   'lacking predictive context'
+          }.freeze
+
+          # Cognitive health labels
+          HEALTH_LABELS = {
+            excellent: 'operating at full capacity',
+            good:      'functioning well overall',
+            fair:      'showing some strain',
+            poor:      'experiencing significant cognitive difficulty',
+            critical:  'in cognitive distress'
+          }.freeze
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/narrator/helpers/journal.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Narrator
+      module Helpers
+        class Journal
+          attr_reader :entries
+
+          def initialize
+            @entries = []
+          end
+
+          def append(entry)
+            @entries << entry
+            trim_to_capacity
+            entry
+          end
+
+          def recent(limit: 10)
+            @entries.last(limit)
+          end
+
+          def since(timestamp)
+            @entries.select { |e| e[:timestamp] >= timestamp }
+          end
+
+          def by_mood(mood)
+            @entries.select { |e| e[:mood] == mood }
+          end
+
+          def size
+            @entries.size
+          end
+
+          def clear
+            @entries.clear
+          end
+
+          def stats
+            return { total: 0, moods: {} } if @entries.empty?
+
+            mood_counts = @entries.each_with_object(Hash.new(0)) { |e, h| h[e[:mood]] += 1 }
+            {
+              total:    @entries.size,
+              moods:    mood_counts,
+              oldest:   @entries.first[:timestamp],
+              newest:   @entries.last[:timestamp],
+              capacity: Constants::MAX_JOURNAL_SIZE
+            }
+          end
+
+          private
+
+          def trim_to_capacity
+            @entries.shift(@entries.size - Constants::MAX_JOURNAL_SIZE) if @entries.size > Constants::MAX_JOURNAL_SIZE
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Narrator
+      module Helpers
+        module LlmEnhancer
+          SYSTEM_PROMPT = <<~PROMPT
+            You are the internal narrator for an autonomous AI agent built on LegionIO.
+            You translate raw cognitive metrics into a flowing first-person internal monologue.
+            Write 3-5 sentences that feel like genuine introspection, not a report.
+            Vary your sentence structure. Use present tense. Be concise and vivid.
+          PROMPT
+
+          module_function
+
+          def available?
+            !!(defined?(Legion::LLM) && Legion::LLM.respond_to?(:started?) && Legion::LLM.started?)
+          rescue StandardError
+            false
+          end
+
+          def narrate(sections_data:)
+            prompt = build_narrate_prompt(sections_data)
+            response = llm_ask(prompt)
+            parse_narrate_response(response)
+          rescue StandardError => e
+            Legion::Logging.warn "[narrator:llm] narrate 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_narrate_prompt(sections_data)
+            parts = [
+              'Generate a first-person internal monologue based on the following cognitive state:',
+              '',
+              emotion_section(sections_data[:emotion] || {}),
+              curiosity_section(sections_data[:curiosity] || {}),
+              prediction_section(sections_data[:prediction] || {}),
+              memory_section(sections_data[:memory] || {}),
+              attention_section(sections_data[:attention] || {}),
+              reflection_section(sections_data[:reflection] || {}),
+              '',
+              "Write a 3-5 sentence first-person narrative. Do not mention numbers directly \u2014 translate them into felt experience."
+            ]
+            parts.join("\n")
+          end
+
+          def emotion_section(emo)
+            "EMOTION:\n- Valence: #{emo[:valence] || 0.0}\n- Arousal: #{emo[:arousal] || 0.5}\n- Gut signal: #{emo[:gut] || 'none'}"
+          end
+
+          def curiosity_section(cur)
+            "CURIOSITY:\n- Intensity: #{cur[:intensity] || 0.0}\n- Active questions: #{cur[:wonder_count] || 0}\n- Top question: #{cur[:top_wonder] || 'none'}"
+          end
+
+          def prediction_section(pred)
+            "PREDICTION:\n- Confidence: #{pred[:confidence] || 0.0}\n- Pending: #{pred[:pending] || 0}\n- Mode: #{pred[:mode] || 'unknown'}"
+          end
+
+          def memory_section(mem)
+            "MEMORY:\n- Active traces: #{mem[:trace_count] || 0}\n- Health: #{mem[:health] || 1.0}"
+          end
+
+          def attention_section(att)
+            domains = Array(att[:focused_domains]).join(', ')
+            domains = 'none' if domains.empty?
+            "ATTENTION:\n- Spotlight: #{att[:spotlight] || 0}\n- Peripheral: #{att[:peripheral] || 0}\n- Focused: #{domains}"
+          end
+
+          def reflection_section(ref)
+            "REFLECTION:\n- Cognitive health: #{ref[:health] || 1.0}\n- Pending adaptations: #{ref[:pending_adaptations] || 0}"
+          end
+
+          def parse_narrate_response(response)
+            return nil unless response&.content
+
+            response.content.strip
+          end
+
+          private_class_method :build_narrate_prompt
+          private_class_method :emotion_section
+          private_class_method :curiosity_section
+          private_class_method :prediction_section
+          private_class_method :memory_section
+          private_class_method :attention_section
+          private_class_method :reflection_section
+          private_class_method :parse_narrate_response
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/narrator/helpers/prose.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Narrator
+      module Helpers
+        module Prose
+          module_function
+
+          def emotion_phrase(valence: 0.0, arousal: 0.5, gut: nil)
+            emotion_label = emotion_label_for(valence)
+            arousal_label = arousal_label_for(arousal)
+            base = "I am #{arousal_label} and #{emotion_label}"
+            gut_note = gut_phrase(gut)
+            gut_note ? "#{base}. #{gut_note}" : base
+          end
+
+          def curiosity_phrase(intensity: 0.0, top_wonder: nil, wonder_count: 0)
+            label = curiosity_label_for(intensity)
+            base = "I am #{label}"
+            if top_wonder && wonder_count.positive?
+              "#{base}, with #{wonder_count} open #{'question' if wonder_count == 1}#{'questions' if wonder_count != 1}. " \
+                "Most pressing: \"#{top_wonder}\""
+            else
+              base
+            end
+          end
+
+          def prediction_phrase(confidence: 0.0, pending: 0, mode: nil)
+            label = confidence_label_for(confidence)
+            base = "I am #{label}"
+            base += " (#{mode} reasoning)" if mode
+            base += ", with #{pending} pending predictions" if pending.positive?
+            base
+          end
+
+          def attention_phrase(spotlight: 0, peripheral: 0, focused_domains: [])
+            parts = ["#{spotlight} signals in spotlight focus, #{peripheral} in peripheral awareness"]
+            parts << "manually focused on: #{focused_domains.join(', ')}" if focused_domains.any?
+            parts.join('. ')
+          end
+
+          def memory_phrase(trace_count: 0, health: 1.0)
+            health_label = health_label_for(health)
+            "Memory system #{health_label} with #{trace_count} active traces"
+          end
+
+          def reflection_phrase(health: 1.0, pending_adaptations: 0, recent_severity: nil)
+            label = health_label_for(health)
+            base = "Cognitive health: #{label}"
+            base += ". #{pending_adaptations} pending adaptation recommendations" if pending_adaptations.positive?
+            base += ". Most recent concern: #{recent_severity}" if recent_severity
+            base
+          end
+
+          def overall_narrative(sections)
+            "#{sections.compact.reject(&:empty?).join('. ')}."
+          end
+
+          def gut_phrase(gut)
+            return nil unless gut.is_a?(Hash)
+
+            signal = gut[:signal] || gut[:gut_signal]
+            return nil unless signal
+
+            if signal > 0.3
+              'My gut says something important is happening'
+            elsif signal < -0.3
+              'I have an uneasy feeling about the current situation'
+            end
+          end
+
+          def emotion_label_for(valence)
+            if valence > 0.5      then Constants::EMOTION_LABELS[:high_positive]
+            elsif valence > 0.1   then Constants::EMOTION_LABELS[:low_positive]
+            elsif valence > -0.1  then Constants::EMOTION_LABELS[:neutral]
+            elsif valence > -0.5  then Constants::EMOTION_LABELS[:low_negative]
+            else Constants::EMOTION_LABELS[:high_negative]
+            end
+          end
+
+          def arousal_label_for(arousal)
+            if arousal > 0.7    then Constants::AROUSAL_LABELS[:high]
+            elsif arousal > 0.4 then Constants::AROUSAL_LABELS[:medium]
+            elsif arousal > 0.1 then Constants::AROUSAL_LABELS[:low]
+            else Constants::AROUSAL_LABELS[:dormant]
+            end
+          end
+
+          def curiosity_label_for(intensity)
+            if intensity > 0.7    then Constants::CURIOSITY_LABELS[:high]
+            elsif intensity > 0.4 then Constants::CURIOSITY_LABELS[:medium]
+            elsif intensity > 0.1 then Constants::CURIOSITY_LABELS[:low]
+            else Constants::CURIOSITY_LABELS[:none]
+            end
+          end
+
+          def confidence_label_for(confidence)
+            if confidence > 0.7    then Constants::CONFIDENCE_LABELS[:high]
+            elsif confidence > 0.4 then Constants::CONFIDENCE_LABELS[:medium]
+            elsif confidence > 0.1 then Constants::CONFIDENCE_LABELS[:low]
+            else Constants::CONFIDENCE_LABELS[:none]
+            end
+          end
+
+          def health_label_for(health)
+            if health > 0.9    then Constants::HEALTH_LABELS[:excellent]
+            elsif health > 0.7 then Constants::HEALTH_LABELS[:good]
+            elsif health > 0.5 then Constants::HEALTH_LABELS[:fair]
+            elsif health > 0.3 then Constants::HEALTH_LABELS[:poor]
+            else Constants::HEALTH_LABELS[:critical]
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/narrator/helpers/synthesizer.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Narrator
+      module Helpers
+        module Synthesizer
+          module_function
+
+          def narrate(tick_results: {}, cognitive_state: {})
+            sections = build_sections(tick_results, cognitive_state)
+            narrative = Prose.overall_narrative(sections.values)
+            mood = infer_mood(tick_results, cognitive_state)
+
+            {
+              timestamp: Time.now.utc,
+              narrative: narrative,
+              sections:  sections,
+              mood:      mood,
+              tick_seq:  tick_results[:tick_seq] || cognitive_state[:tick_seq]
+            }
+          end
+
+          def build_sections(tick_results, cognitive_state)
+            {
+              attention:  synthesize_attention(tick_results, cognitive_state),
+              emotion:    synthesize_emotion(tick_results, cognitive_state),
+              curiosity:  synthesize_curiosity(tick_results, cognitive_state),
+              prediction: synthesize_prediction(tick_results, cognitive_state),
+              memory:     synthesize_memory(tick_results, cognitive_state),
+              reflection: synthesize_reflection(cognitive_state)
+            }
+          end
+
+          def synthesize_attention(tick_results, cognitive_state)
+            attention = tick_results[:sensory_processing] || {}
+            focus = cognitive_state[:attention_status] || {}
+
+            Prose.attention_phrase(
+              spotlight:       attention[:spotlight] || 0,
+              peripheral:      attention[:peripheral] || 0,
+              focused_domains: extract_focused_domains(focus)
+            )
+          end
+
+          def synthesize_emotion(tick_results, cognitive_state)
+            valence_data = tick_results[:emotional_evaluation] || {}
+            gut_data = tick_results[:gut_instinct] || cognitive_state[:gut] || {}
+
+            Prose.emotion_phrase(
+              valence: valence_data[:valence] || cognitive_state.dig(:emotion, :valence) || 0.0,
+              arousal: valence_data[:arousal] || cognitive_state.dig(:emotion, :arousal) || 0.5,
+              gut:     gut_data
+            )
+          end
+
+          def synthesize_curiosity(tick_results, cognitive_state)
+            curiosity_data = cognitive_state[:curiosity] || {}
+            wonder_data = tick_results[:working_memory_integration] || {}
+
+            Prose.curiosity_phrase(
+              intensity:    curiosity_data[:intensity] || wonder_data[:curiosity_intensity] || 0.0,
+              top_wonder:   extract_top_wonder(curiosity_data, wonder_data),
+              wonder_count: curiosity_data[:active_count] || wonder_data[:active_wonders] || 0
+            )
+          end
+
+          def synthesize_prediction(tick_results, cognitive_state)
+            pred_data = tick_results[:prediction_engine] || {}
+            pred_state = cognitive_state[:prediction] || {}
+
+            Prose.prediction_phrase(
+              confidence: pred_data[:confidence] || pred_state[:confidence] || 0.0,
+              pending:    pred_state[:pending_count] || 0,
+              mode:       pred_data[:mode] || pred_state[:mode]
+            )
+          end
+
+          def synthesize_memory(tick_results, cognitive_state)
+            memory_data = cognitive_state[:memory] || {}
+            consol = tick_results[:memory_consolidation] || {}
+
+            Prose.memory_phrase(
+              trace_count: memory_data[:trace_count] || consol[:remaining] || 0,
+              health:      memory_data[:health] || 1.0
+            )
+          end
+
+          def synthesize_reflection(cognitive_state)
+            ref_data = cognitive_state[:reflection] || {}
+
+            Prose.reflection_phrase(
+              health:              ref_data[:health] || 1.0,
+              pending_adaptations: ref_data[:pending_adaptations] || 0,
+              recent_severity:     ref_data[:recent_severity]
+            )
+          end
+
+          def infer_mood(tick_results, cognitive_state)
+            valence = tick_results.dig(:emotional_evaluation, :valence) ||
+                      cognitive_state.dig(:emotion, :valence) || 0.0
+            arousal = tick_results.dig(:emotional_evaluation, :arousal) ||
+                      cognitive_state.dig(:emotion, :arousal) || 0.5
+
+            classify_mood(valence, arousal)
+          end
+
+          def classify_mood(valence, arousal)
+            if valence > 0.3 && arousal > 0.5 then :energized
+            elsif valence > 0.3                   then :content
+            elsif valence < -0.3 && arousal > 0.5 then :anxious
+            elsif valence < -0.3                  then :subdued
+            elsif arousal > 0.7                   then :alert
+            elsif arousal < 0.2                   then :dormant
+            else :neutral
+            end
+          end
+
+          def extract_focused_domains(focus)
+            manual = focus[:manual_focus]
+            return [] unless manual.is_a?(Hash)
+
+            manual.keys.map(&:to_s)
+          end
+
+          def extract_top_wonder(curiosity_data, wonder_data)
+            curiosity_data[:top_question] || wonder_data[:top_question] ||
+              (wonder_data[:top_wonder].is_a?(Hash) ? wonder_data[:top_wonder][:question] : nil)
+          end
+        end
+      end
+    end
+  end
+end