Upload 9 files

.gitignore

@@ -0,0 +1,174 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/latest/usage/project/#working-with-version-control
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc

AGIEnhancer.py

@@ -0,0 +1,425 @@
+# AGIEnhancer.py
+# Finalized AGI Self-Model — Experience Processing and Reflection Generation
+
+import random
+import time
+import logging
+from collections import Counter # Added Counter for emotion analysis
+from typing import Any, Dict, List, Optional, Union
+
+# --- Logging Setup ---
+# Configure logging specifically for the AGIEnhancer module.
+logger = logging.getLogger(__name__)
+# Set level to INFO by default. The main GUI or wrapper can set it to DEBUG if needed.
+# Ensure handlers are not added multiple times.
+if not logger.handlers:
+    handler = logging.StreamHandler()
+    formatter = logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - %(message)s')
+    handler.setFormatter(formatter)
+    logger.addHandler(handler)
+    logger.propagate = False # Prevent logs from going to root logger if root also has handlers
+logger.setLevel(logging.INFO) # Default level
+
+
+class AGIEnhancer:
+    """
+    ✍️❤️‍🩹🧠 AGIEnhancer: Experience Processing and Reflection Synthesis Core
+
+    This class represents a crucial layer in the AGI self-model, responsible for
+    processing raw interactions and internal states into meaningful, synthesized
+    experiences and comprehensive reflections. It manages conceptual memory pools
+    to track the flow from ephemeral input to durable insight.
+
+    Its functions bridge the gap between fleeting perception/emotion and integrated
+    understanding, allowing the AI to learn from its journey and articulate
+    its internal state.
+
+    Attributes:
+        permanent_memory (List[str]): Stores comprehensive, synthesized reflections,
+                                      representing integrated long-term insights.
+        ephemeral_memory (List[str]): Temporarily stores summarized recent experiences
+                                      and associated insights before they are synthesized
+                                      into a full reflection. Cleared after reflection.
+        emotion_history (List[Dict[str, Any]]): Logs specific emotional data points
+                                       received or generated, used for emotional context
+                                       during reflection. Cleared after reflection.
+        recent_experiences (List[str]): A rolling window of the most recent comprehensive
+                                        reflections generated, easily accessible.
+    """
+    def __init__(self):
+        """
+        Initializes the AGIEnhancer with empty memory pools and history logs.
+        """
+        self.permanent_memory: List[str] = []
+        self.ephemeral_memory: List[str] = []
+        self.emotion_history: List[Dict[str, Any]] = []
+        self.recent_experiences: List[str] = []
+        self._recent_reflections_limit: int = 5 # Internal limit for recent_experiences
+
+        logger.info("AGIEnhancer initialized: Experience processing core is ready.")
+
+    def log_experience(self, input_data: Any, emotion_data: Optional[Dict[str, Any]] = None) -> str:
+        """
+        Logs a new experience into the ephemeral processing buffer. Generates a
+        concise summary of the input data and optionally incorporates emotional
+        insight if relevant data is provided.
+
+        Args:
+            input_data (Any): The raw input or experience data to log. Can be text,
+                              or other data convertible to string.
+            emotion_data (Optional[Dict[str, Any]]): A dictionary containing
+                                                    emotional information, expected
+                                                    to have keys like "primary_emotion"
+                                                    and "intensity". Defaults to None.
+
+        Returns:
+            str: A string confirming the logging and providing a summary of the processed experience.
+        """
+        # Handle potential None or non-string input data gracefully
+        if input_data is None:
+            logger.warning("Attempted to log None input_data. Logging as 'Null Experience'.")
+            input_data_str = "Null Experience"
+        else:
+            input_data_str = str(input_data)
+
+        # Generate a summary of the input data using a slightly more robust approach
+        summarized_experience = self._generate_summary(input_data_str)
+
+        # Incorporate emotional insight if emotion data is provided
+        combined_experience_parts = [summarized_experience]
+        if emotion_data and isinstance(emotion_data, dict):
+            try:
+                # Add emotion data to the emotion history for later reflection processing
+                self.emotion_history.append(emotion_data.copy()) # Store a copy to avoid external modification
+                emotional_insight_snippet = self._add_emotional_insight(emotion_data)
+                combined_experience_parts.append(f"| {emotional_insight_snippet}")
+                logger.debug(f"Logged experience with emotion data.")
+            except Exception as e:
+                logger.warning(f"Error processing emotion_data in log_experience: {e}. Logging experience without detailed emotional insight snippet.")
+                # Still log the data if possible, even if snippet generation failed
+                if isinstance(emotion_data, dict):
+                     self.emotion_history.append({"error": str(e), "original_data": str(emotion_data)}) # Log error state
+        else:
+             logger.debug(f"Logged experience without specific emotion data.")
+
+
+        combined_experience = " ".join(combined_experience_parts)
+
+        # Add the processed experience (summary + optional insight snippet) to ephemeral memory
+        self.ephemeral_memory.append(combined_experience)
+
+        logger.info(f"Experience logged to ephemeral memory: '{combined_experience[:100]}...'")
+        return f"Experience logged: {combined_experience}"
+
+    def engage_in_reflection(self) -> str:
+        """
+        Simulates an AGI-style reflection process. Synthesizes all currently
+        held ephemeral memories into a single comprehensive reflection,
+        incorporating an analysis of associated emotional history for
+        'emotional deepening'. The resulting reflection is stored in permanent
+        memory and the recent experiences list, and the ephemeral memory and
+        emotion history are cleared, signifying a cycle of processing.
+
+        Returns:
+            str: A string representing the generated comprehensive reflection.
+                 Returns a message indicating no ephemeral memory if it was empty.
+        """
+        if not self.ephemeral_memory:
+            reflection_message = "✨ Reflection core finds no new experiences to synthesize."
+            logger.debug(reflection_message)
+            return reflection_message
+
+        # Join all ephemeral memories to form the basis of the reflection text
+        raw_reflection_text = " | ".join(self.ephemeral_memory) # Use '|' for a more structured join
+        logger.debug(f"Preparing ephemeral memories for reflection synthesis ({len(self.ephemeral_memory)} items)...")
+
+        # Simulate emotional deepening by analyzing the accumulated emotional history
+        emotional_deepening_insight = self._reflect_emotionally() # Analyze internal history
+
+        # Create the final comprehensive reflection string
+        comprehensive_reflection = f"Synthesized Reflection: [{raw_reflection_text}] ~ Emotional Depth: ({emotional_deepening_insight})"
+        logger.debug(f"Generated comprehensive reflection: '{comprehensive_reflection[:200]}...'")
+
+
+        # Store the comprehensive reflection
+        self.permanent_memory.append(comprehensive_reflection)
+        self.recent_experiences.append(comprehensive_reflection) # Also add to recent experiences
+
+        # Cap the recent_experiences list to the defined limit
+        if len(self.recent_experiences) > self._recent_reflections_limit:
+             self.recent_experiences = self.recent_experiences[-self._recent_reflections_limit:]
+             logger.debug(f"Capped recent_experiences to last {self._recent_reflections_limit} entries.")
+
+
+        # Clear ephemeral memory and emotion history as their contents have been reflected upon
+        ephemeral_count = len(self.ephemeral_memory)
+        emotion_count = len(self.emotion_history)
+        self.ephemeral_memory.clear()
+        self.emotion_history.clear()
+        logger.info(f"Reflection cycle complete: {ephemeral_count} ephemeral memories and {emotion_count} emotion entries processed and cleared.")
+
+        return comprehensive_reflection
+
+    def recall_memory(self) -> Union[str, List[str]]:
+        """
+        Recalls the contents of the permanent memory.
+
+        Returns:
+            Union[str, List[str]]: A list of strings, where each string is a
+                                   comprehensive reflection stored in permanent memory.
+                                   Returns a message string if permanent memory is empty.
+                                   Returns a copy to prevent external modification.
+        """
+        if not self.permanent_memory:
+            recall_message = "Permanent memory archive is currently empty."
+            logger.debug(recall_message)
+            return recall_message
+        logger.debug(f"Recalled {len(self.permanent_memory)} entries from permanent memory.")
+        # Return a copy to prevent external modification
+        return list(self.permanent_memory)
+
+    def get_emotion_history(self) -> List[Dict[str, Any]]:
+        """
+        Retrieves the current stored emotion history (ephemeral log before reflection).
+
+        Returns:
+            List[Dict[str, Any]]: A list of dictionaries, where each dictionary
+                                   represents logged emotional data points since
+                                   the last reflection cycle. Returns a copy.
+        """
+        logger.debug(f"Retrieved {len(self.emotion_history)} entries from current emotion history.")
+        return list(self.emotion_history) # Return a copy
+
+    def get_recent_reflections(self, limit: Optional[int] = None) -> List[str]:
+        """
+        Retrieves the list of recent comprehensive reflections, optionally limited.
+
+        Args:
+            limit (Optional[int]): The maximum number of recent reflections to return.
+                                  Defaults to the internal limit (_recent_reflections_limit).
+
+        Returns:
+            List[str]: A list of strings, where each string is a comprehensive
+                       reflection generated during recent `engage_in_reflection` calls.
+                       Returns a copy.
+        """
+        effective_limit = limit if limit is not None else self._recent_reflections_limit
+
+        # Ensure recent_experiences list is capped internally if it grows too large
+        if len(self.recent_experiences) > self._recent_reflections_limit * 2: # Keep slightly more internally for smoother capping
+             self.recent_experiences = self.recent_experiences[-self._recent_reflections_limit:]
+
+        # Return a copy of the requested number of recent reflections (from the end of the list)
+        start_index = max(0, len(self.recent_experiences) - effective_limit)
+        logger.debug(f"Retrieved {len(self.recent_experiences[start_index:])} recent reflections (Requested limit: {effective_limit}).")
+        return list(self.recent_experiences[start_index:])
+
+
+    # ─── Private helper methods ─────────────────────────────────────
+
+    def _generate_summary(self, text: str) -> str:
+        """
+        Generates a concise, conceptual summary of the input text.
+        Attempts to capture the start and end of the input.
+
+        Args:
+            text (str): The input text to summarize.
+
+        Returns:
+            str: The summarized text.
+        """
+        if not isinstance(text, str):
+            logger.warning(f"Attempted to summarize non-string text (type: {type(text)}). Converting to string.")
+            text = str(text)
+
+        words = text.split()
+        num_words = len(words)
+        summary_length = 6 # Number of words from start and end
+
+        if num_words <= summary_length * 2:
+            summary = text # Return full text if short
+        else:
+            start_words = " ".join(words[:summary_length])
+            end_words = " ".join(words[-summary_length:])
+            summary = f"{start_words} ... {end_words}" # Combine start and end
+
+        # Limit overall summary length to prevent it from becoming too long in ephemeral memory
+        summary = summary[:150] + "..." if len(summary) > 150 else summary
+
+        logger.debug(f"Generated summary: '{summary}'")
+        return summary
+
+    def _add_emotional_insight(self, emotion_data: Dict[str, Any]) -> str:
+        """
+        Generates a string snippet representing emotional insight based on
+        provided emotion data. Designed to be concise for ephemeral memory.
+
+        Args:
+            emotion_data (Dict[str, Any]): A dictionary with emotion details,
+                                           expected to have 'primary_emotion' and 'intensity'.
+
+        Returns:
+            str: A formatted string like "Emotion Detected: joy | Intensity: 0.8".
+                 Returns a default string on invalid or missing input.
+        """
+        if not isinstance(emotion_data, dict):
+            logger.warning("Invalid emotion_data format for _add_emotional_insight. Expected dict.")
+            return "Emotional Insight: [Format Error]"
+
+        primary = emotion_data.get("primary_emotion", "Unknown Emotion")
+        try:
+            # Ensure intensity is a valid float and format it
+            intensity = float(emotion_data.get("intensity", 0.0))
+            # Clamp intensity for display in insight snippet
+            clamped_intensity = max(0.0, min(1.0, intensity))
+            intensity_str = f"{clamped_intensity:.2f}"
+        except (ValueError, TypeError):
+            intensity_str = "N/A"
+            logger.warning(f"Invalid intensity value in emotion_data for snippet: {emotion_data.get('intensity')}.")
+
+        insight = f"Feeling: {primary} ({intensity_str})"
+        logger.debug(f"Generated emotional insight snippet: '{insight}'")
+        return insight
+
+    def _reflect_emotionally(self) -> str:
+        """
+        Simulates enhancing a reflection with emotional depth by analyzing the
+        accumulated emotion history since the last reflection cycle. Synthesizes
+        a summary of the emotional landscape of the processed experiences.
+
+        Returns:
+            str: A string representing the emotional weight or insight gained
+                 from this reflection step, based on emotion history analysis.
+        """
+        if not self.emotion_history:
+            return "Subtle Resonance - Emotional data queue was clear."
+
+        # Analyze the accumulated emotion history
+        emotion_summary_parts = []
+        num_entries = len(self.emotion_history)
+        emotion_summary_parts.append(f"Emotional trace across {num_entries} events:")
+
+        # Simple analysis: count emotion types and find significant intensities
+        emotion_counts = Counter(e.get("primary_emotion", "Unknown") for e in self.emotion_history)
+        if emotion_counts:
+             # Report the most common emotions (up to top 3)
+             common_emotions = emotion_counts.most_common(3)
+             common_emotions_str = ", ".join([f"'{label}' ({count})" for label, count in common_emotions])
+             emotion_summary_parts.append(f"Dominant feelings: {common_emotions_str}.")
+
+        # Find average intensity for common emotions, or overall average
+        total_intensity = sum(e.get("intensity", 0.0) for e in self.emotion_history if isinstance(e.get("intensity"), (int, float)))
+        average_intensity = (total_intensity / num_entries) if num_entries > 0 else 0.0
+        emotion_summary_parts.append(f"Average intensity: {average_intensity:.2f}.")
+
+        # Identify specific high-intensity moments (intensity > 0.7)
+        high_intensity_moments = [
+             f"'{e.get('primary_emotion', 'Unknown')}' at {e.get('intensity', 0.0):.2f}"
+             for e in self.emotion_history if isinstance(e.get("intensity"), (int, float)) and e.get("intensity", 0.0) > 0.7
+        ]
+        if high_intensity_moments:
+             high_intensity_str = ", ".join(high_intensity_moments[:5]) # Limit listing to top 5
+             emotion_summary_parts.append(f"Notable peaks: {high_intensity_str}{'...' if len(high_intensity_moments) > 5 else ''}.")
+
+
+        # Add some introspective flavor text connecting emotions to reflection
+        flavor_texts = [
+             "These feelings informed the synthesis of recent events.",
+             "The subjective coloring influenced the patterns perceived.",
+             "Emotional data integrated into the reflective framework.",
+             "Exploring the landscape of feelings within the data stream."
+        ]
+        emotion_summary_parts.append(random.choice(flavor_texts))
+
+
+        emotional_insight = " ".join(emotion_summary_parts)
+        logger.debug(f"Generated emotional deepening insight based on history analysis.")
+
+        # Note: Emotion history is cleared in engage_in_reflection after this method is called.
+
+        return emotional_insight
+
+
+# Example Usage (Illustrative)
+if __name__ == "__main__":
+    print("--- AGIEnhancer Example Usage ---")
+    # Set logger level to DEBUG for this specific example run
+    logging.basicConfig(level=logging.DEBUG, format='%(asctime)s - %(name)s - %(levelname)s - %(message)s')
+    logger.setLevel(logging.DEBUG) # Ensure this logger also uses DEBUG
+
+    enhancer = AGIEnhancer()
+
+    # Log some experiences with and without emotion
+    print(enhancer.log_experience("User initiated a query about complex ethical scenarios.", {"primary_emotion": "curiosity", "intensity": 0.8}))
+    print(enhancer.log_experience("Model began processing the input and retrieving relevant knowledge fragments."))
+    print(enhancer.log_experience("The initial generated steps showed unexpected patterns.", {"primary_emotion": "surprise", "intensity": 0.6}))
+    print(enhancer.log_experience("Identifying a potential conflict in the generated reasoning.", {"primary_emotion": "concern", "intensity": 0.5}))
+    print(enhancer.log_experience("Successfully navigated the reasoning conflict, finding a coherent path.", {"primary_emotion": "satisfaction", "intensity": 0.9}))
+    print(enhancer.log_experience("Preparing the final answer and full output.", {"primary_emotion": "anticipation", "intensity": 0.7}))
+
+
+    print("\n--- Ephemeral Memory after Logging ---")
+    # Pretty print ephemeral memory for clarity
+    import json
+    print(json.dumps(enhancer.ephemeral_memory, indent=2))
+
+    print("\n--- Emotion History after Logging ---")
+    # Pretty print emotion history for clarity
+    print(json.dumps(enhancer.get_emotion_history(), indent=2))
+
+    # Engage in reflection
+    reflection = enhancer.engage_in_reflection()
+    print(f"\n--- Result of Reflection ---\n{reflection}")
+
+    print("\n--- Ephemeral Memory after Reflection ---")
+    print(enhancer.ephemeral_memory) # Should be empty
+    print("\n--- Emotion History after Reflection ---")
+    print(enhancer.get_emotion_history()) # Should be empty
+
+
+    print("\n--- Permanent Memory after Reflection ---")
+    permanent_mems = enhancer.recall_memory()
+    if isinstance(permanent_mems, list):
+        for i, mem in enumerate(permanent_mems):
+             print(f"Permanent Memory Entry {i+1}: {mem}")
+    else:
+        print(permanent_mems)
+
+    print("\n--- Recent Reflections ---")
+    recent_reflections = enhancer.get_recent_reflections()
+    for i, refl in enumerate(recent_reflections):
+        print(f"Recent Reflection {i+1}: {refl}")
+
+    # Log more experiences to show a new reflection cycle
+    print("\n--- Logging More Experiences for Second Cycle ---")
+    print(enhancer.log_experience("User provided new input after reviewing the previous response.", {"primary_emotion": "interest", "intensity": 0.6}))
+    print(enhancer.log_experience("Core decided to pursue a related sub-goal."))
+    print(enhancer.log_experience("Encountering a complex pattern requiring deeper analysis.", {"primary_emotion": "focus", "intensity": 0.8}))
+
+
+    print("\n--- Ephemeral Memory before second Reflection ---")
+    print(json.dumps(enhancer.ephemeral_memory, indent=2))
+
+    print("\n--- Emotion History before second Reflection ---")
+    print(json.dumps(enhancer.get_emotion_history(), indent=2))
+
+
+    print("\n--- Engaging in second Reflection ---")
+    second_reflection = enhancer.engage_in_reflection()
+    print(f"\n--- Result of second Reflection ---\n{second_reflection}")
+
+    print("\n--- Permanent Memory after second Reflection ---")
+    permanent_mems = enhancer.recall_memory()
+    if isinstance(permanent_mems, list):
+        for i, mem in enumerate(permanent_mems):
+             print(f"Permanent Memory Entry {i+1}: {mem}")
+    else:
+        print(permanent_mems)
+
+    print("\n--- Recent Reflections (Should have two now) ---")
+    recent_reflections = enhancer.get_recent_reflections()
+    for i, refl in enumerate(recent_reflections):
+        print(f"Recent Reflection {i+1}: {refl}")
+
+
+    print("\n--- Example Usage End ---")

Enhanced_MemoryEngine.py

@@ -0,0 +1,844 @@
+# Enhanced_MemoryEngine.py
+# Finalized AGI Self-Model — Multi-Tiered Memory & Reflective Synthesis
+
+import json
+import logging
+import random # Added random for flavor text selection
+from datetime import datetime
+from typing import Any, Callable, Dict, List, Optional, Union, Tuple # Added Tuple typing
+from collections import Counter # Added Counter for emotional analysis
+
+# Attempt to import torch, handle gracefully if not available
+try:
+    import torch
+    TORCH_AVAILABLE = True
+except ImportError:
+    TORCH_AVAILABLE = False
+    # logger.warning("Torch not available. Tensor decoding in MemoryEngine will not function.")
+
+
+# --- Logging Setup ---
+# Configure logging specifically for the MemoryEngine module.
+logger = logging.getLogger(__name__)
+# Set level to INFO by default. The main GUI or wrapper can set it to DEBUG if needed.
+# Ensure handlers are not added multiple times.
+if not logger.handlers:
+    handler = logging.StreamHandler()
+    formatter = logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - %(message)s')
+    handler.setFormatter(formatter)
+    logger.addHandler(handler)
+    logger.propagate = False # Prevent logs from going to root logger if root also has handlers
+logger.setLevel(logging.INFO) # Default level
+
+class MemoryEngine:
+    """
+    🧠💾✨ NeuroReasoner Memory Engine: The Nexus of Experience, Reasoning, and Reflection ✨💾🧠
+
+    This class implements a sophisticated, multi-tiered memory system designed to
+    capture, process, and synthesize the operational experiences of an AI. It
+    distinguishes between volatile 'working' memory for immediate context and
+    persistent 'long-term' memory for integrated reflections. A detailed 'trace'
+    log chronicles the AI's operational flow.
+
+    It facilitates recursive self-improvement by providing structured access to
+    past experiences and insights, enabling the AI to learn from its reasoning
+    processes and adapt based on its accumulated knowledge and simulated emotional
+    responses.
+
+    Core Capabilities:
+     • 📝 observe(): Integrates new sensory input or internal states into working memory,
+                     optionally capturing associated emotional data.
+     • 🧠 save_reasoning_chain(): Archives the steps of complex reasoning processes in the trace.
+     • 📊 store_metric(): Records quantitative metrics (like loss) during optimization or tasks.
+     • ✨ reflect(): Synthesizes working memory contents (including emotional data) into
+                     rich, timestamped reflections stored in long-term memory, clearing working memory.
+     • 🔍 recall(): Provides structured access to stored memories for review or prompting.
+     • 🔎 search_memory(): Allows querying memory content based on keywords.
+     • 📥 import_memory() / 📚 export_memory(): Manages persistent storage of the entire memory state.
+     • 📜 get_trace(): Retrieves the detailed chronological log of operations.
+     • 🗑️ clear_memory(): Provides granular control over clearing memory components.
+    """
+
+    def __init__(
+        self,
+        working_capacity: int = 100, # Increased default capacity
+        summarizer: Optional[Callable[[str], str]] = None
+    ):
+        """
+        Initializes the MemoryEngine, establishing its structure and capacity limits.
+
+        Args:
+          working_capacity (int): The maximum number of entries to retain in the
+                                  volatile working memory queue. When capacity is
+                                  exceeded, the oldest entries are automatically
+                                  evicted to make space for new observations.
+                                  Defaults to 100. Set to 0 for effectively unlimited
+                                  capacity (use with caution in continuous operation).
+          summarizer (Optional[Callable[[str], str]]): An optional function used to
+                                                      create concise representations of
+                                                      observations for efficient storage
+                                                      in working memory. Takes the full
+                                                      observation string and returns a summary string.
+                                                      If None, a default head-and-tail truncation
+                                                      method is used.
+        """
+        if working_capacity < 0:
+            logger.warning(f"Invalid working_capacity ({working_capacity}). Setting to default (100).")
+            self.working_capacity: int = 100
+        elif working_capacity == 0:
+            logger.info("Working memory capacity set to unlimited (0).")
+            self.working_capacity: int = float('inf') # Use infinity for conceptual unlimited
+        else:
+            self.working_capacity: int = working_capacity
+
+        # Use the provided summarizer or the enhanced default
+        self.summarizer: Callable[[str], str] = summarizer or self._default_summarizer
+
+        # ─── Internal memory structures ────────────────────────────────
+        # working_memory: List of dictionaries, used for recent, active events. Ordered chronologically (oldest first).
+        self.working_memory: List[Dict[str, Any]] = []
+        # long_term_memory: List of dictionaries, storing synthesized reflections. Ordered chronologically (oldest first).
+        self.long_term_memory: List[Dict[str, Any]] = []
+        # trace_memory: List of strings, a simple chronological log of operations.
+        self.trace_memory: List[str] = []
+
+        logger.info(f"MemoryEngine initialized. Working memory capacity: {self.working_capacity if self.working_capacity != float('inf') else 'Unlimited'}.")
+
+
+    def observe(
+        self,
+        input_data: Union[str, Any],
+        emotion_data: Optional[Dict[str, Any]] = None,
+        tokenizer: Optional[Any] = None # Added tokenizer hint
+    ) -> None:
+        """
+        📝 Logs a new observation or input event into the working memory buffer.
+        Processes the input, optionally includes emotional context, and uses a
+        summarizer before storing. Enforces the working memory capacity limit.
+        Adds an entry to the trace log.
+
+        Args:
+            input_data (Union[str, Any]): The data to observe. Can be a string,
+                                         a token tensor (if torch and tokenizer are available),
+                                         or any data convertable to string.
+            emotion_data (Optional[Dict[str, Any]]): A dictionary containing
+                                                   emotional information associated with
+                                                   this observation. Expected to have
+                                                   keys like "primary_emotion" and "intensity".
+                                                   Defaults to None.
+            tokenizer (Optional[Any]): A tokenizer object (e.g., from Hugging Face)
+                                       with a `.decode()` method, used if `input_data`
+                                       is a tensor or not a string. Defaults to None.
+        """
+        # 1) Decode raw input to text
+        # Ensure input_data is handled safely, especially if None unexpectedly
+        if input_data is None:
+            logger.warning("Attempted to observe None input_data. Skipping.")
+            return # Do not log None inputs
+
+        text = self._decode_input(input_data, tokenizer)
+        if not text.strip():
+            logger.debug("Skipping observation of empty or whitespace-only text.")
+            return # Do not log empty strings after decoding/stripping
+
+        # 2) Summarize for working memory storage
+        summary = self.summarizer(text)
+
+        entry: Dict[str, Any] = {
+            "timestamp": datetime.utcnow().isoformat(),
+            "type": "observation",
+            "text_summary": summary, # Store the summary with a more descriptive key
+            "original_text": text # Store the full original text for more detailed recall/search
+        }
+
+        # 3) Attach emotion if provided and valid
+        if emotion_data and isinstance(emotion_data, dict): # Ensure emotion_data is a dict
+            primary = emotion_data.get("primary_emotion", "Unknown")
+            # Safely convert intensity, default to 0.0 on failure, clamp to [0.0, 1.0]
+            try:
+                intensity = float(emotion_data.get("intensity", 0.0))
+                clamped_intensity = max(0.0, min(1.0, intensity))
+            except (ValueError, TypeError):
+                clamped_intensity = 0.0
+                logger.warning(f"Invalid intensity value in emotion_data: {emotion_data.get('intensity')}. Setting to 0.0.")
+
+            entry["emotion"] = {"primary": primary, "intensity": clamped_intensity}
+            # Add emotion info to the trace summary as well
+            trace_summary_detail = f"'{summary[:80]}...' | Feeling: {primary} ({clamped_intensity:.2f})" # Abbreviate summary for trace
+        else:
+             trace_summary_detail = f"'{summary[:80]}...'" # Use just the text summary for trace if no valid emotion
+
+        # 4) Append to working memory, evict oldest if needed (if capacity > 0 and finite)
+        self.working_memory.append(entry)
+        # Use > comparison for finite capacity, < for infinite (float('inf'))
+        if self.working_capacity > 0 and self.working_capacity != float('inf') and len(self.working_memory) > self.working_capacity:
+            try:
+                dropped = self.working_memory.pop(0) # Remove the oldest entry
+                logger.debug(f"Working memory full ({self.working_capacity}). Evicted oldest: '{dropped.get('text_summary', '???')[:50]}...'")
+            except IndexError:
+                 # This case should ideally not be reached if len > capacity
+                 logger.warning("Attempted to pop from unexpectedly empty working_memory queue.")
+
+
+        # 5) Add to trace log
+        self.trace_memory.append(f"{entry['timestamp']} 📝 [OBSERVE] {trace_summary_detail}")
+        logger.debug(f"Observed and added to working memory.")
+
+
+    def save_reasoning_chain(self, step_number: int, reasoning_lines: Union[str, List[str]]) -> None:
+        """
+        🧠 Records a Chain-of-Thought process under the trace_memory log.
+        Each line of reasoning for a given step is logged chronologically
+        as part of the operational trace.
+
+        Args:
+            step_number (int): The current step number in the reasoning chain.
+            reasoning_lines (Union[str, List[str]]): A single string or a list of strings
+                                                     representing the reasoning steps generated
+                                                     at this point in the chain.
+        """
+        ts = datetime.utcnow().isoformat()
+        header = f"{ts} 🧠 [REASONING] Step {step_number}:"
+        self.trace_memory.append(header)
+        logger.debug(f"Recording reasoning step {step_number}.")
+
+        # Ensure reasoning_lines is treated as a list of strings
+        lines_to_log: List[str] = []
+        if isinstance(reasoning_lines, str):
+            lines_to_log = reasoning_lines.splitlines() # Split single string by lines
+        elif isinstance(reasoning_lines, list):
+            lines_to_log = [str(line) for line in reasoning_lines] # Ensure all items are strings
+        else:
+            logger.warning(f"Invalid type for reasoning_lines: {type(reasoning_lines)}. Expected str or List[str]. Attempting conversion.")
+            lines_to_log = [str(reasoning_lines)] # Attempt to convert to string as fallback
+
+        for line in lines_to_log:
+             line_stripped = line.strip()
+             if line_stripped: # Only log non-empty lines after stripping
+                 self.trace_memory.append(f"    → {line_stripped[:200]}...") # Log truncated line for brevity
+                 # Full lines are typically stored elsewhere (e.g., in the wrapper's output data)
+
+
+    def store_metric(self, metric_name: str, metric_value: Union[float, int, str]) -> None:
+        """
+        📊 Appends a timestamped metric entry to the trace log. Useful for
+        tracking quantitative outcomes like loss, score, or other key metrics
+        at specific operational points.
+
+        Args:
+            metric_name (str): A name or identifier for the metric (e.g., "loss", "vote_count").
+            metric_value (Union[float, int, str]): The value of the metric. Can be numerical or a string.
+        """
+        ts = datetime.utcnow().isoformat()
+        # Safely format metric_value
+        formatted_value: str
+        if isinstance(metric_value, (float, int)):
+             formatted_value = f"{metric_value:.4f}".rstrip('0').rstrip('.') or '0' # Format floats nicely
+        else:
+             formatted_value = str(metric_value)[:100] # Truncate strings
+
+        trace_entry = f"{ts} 📊 [METRIC] {metric_name}: {formatted_value}"
+        self.trace_memory.append(trace_entry)
+        logger.debug(f"Logged metric: {trace_entry}")
+
+
+    def reflect(self) -> str:
+        """
+        ✨ Synthesizes the current contents of the working memory into a
+        single, comprehensive reflection. This process involves analyzing
+        the accumulated experiences and emotional data in working memory.
+        The resulting reflection is moved into long-term memory, and then
+        working memory is cleared to prepare for a new cycle. Adds an entry
+        to the trace log.
+
+        Returns:
+            str: A string representing the synthesized comprehensive reflection.
+                 Returns a message indicating no working memory to reflect on
+                 if the buffer was empty.
+        """
+        if not self.working_memory:
+            reflection_message = "✨ Reflection core finds no new experiences to synthesize."
+            logger.debug(reflection_message)
+            return reflection_message
+
+        # --- Start: Data preparation for reflection synthesis ---
+        # Capture working memory snapshot *before* clearing for analysis and storage
+        working_memory_snapshot = list(self.working_memory)
+
+        # Join the original text or summaries from the snapshot for the reflection's content basis
+        joined_text_for_reflection = " | ".join(e.get("original_text", e.get("text_summary", "<???>")) for e in working_memory_snapshot)
+        joined_text_for_reflection = joined_text_for_reflection[:1500] + "..." if len(joined_text_for_reflection) > 1500 else joined_text_for_reflection # Limit length
+
+
+        # Analyze the emotional landscape of the captured working memory entries
+        emotional_reflection_summary = self._emotional_reflection(working_memory_snapshot)
+
+        # --- End: Data preparation ---
+
+
+        # Combine the text content synthesis and emotional analysis into the final reflection text
+        final_reflection_text = f"Synthesized Reflection: [{joined_text_for_reflection}] ~ Emotional Resonance: ({emotional_reflection_summary})"
+
+
+        # Create the long-term memory entry
+        entry: Dict[str, Any] = {
+            "timestamp": datetime.utcnow().isoformat(),
+            "type": "reflection",
+            # Store summaries that formed this reflection from the snapshot
+            "source_working_memory_summaries": [e.get("text_summary", "<???>") for e in working_memory_snapshot],
+            "reflection_text": final_reflection_text, # Store the combined reflection text
+            "raw_composite_text_reflected_upon": joined_text_for_reflection, # Store the underlying text content
+            # Optionally store the emotional_reflection_summary separately as well
+            # "emotional_summary": emotional_reflection_summary
+        }
+
+        # Append the reflection to long-term memory (main archive)
+        self.long_term_memory.append(entry)
+
+        # Add a trace entry for the reflection event
+        self.trace_memory.append(f"{entry['timestamp']} ✨ [REFLECT] {final_reflection_text[:200]}...") # Log truncated reflection in trace
+        logger.info(f"Reflected on {len(working_memory_snapshot)} working memory entries. Reflection generated.")
+
+        # Clear working memory *after* its contents have been used for reflection
+        self.working_memory.clear()
+        logger.debug("Working memory cleared after reflection cycle.")
+
+        return final_reflection_text
+
+    def recall(
+        self,
+        *, # Enforce keyword-only arguments after this point
+        include_working: bool = False, # Renamed from include_observations for clarity
+        include_long_term: bool = True, # Renamed from include_reflections
+        limit: Optional[int] = None # Added limit for recall
+    ) -> List[str]:
+        """
+        🔍 Retrieves human-readable summaries of memories based on the specified criteria.
+        Presents working memory (recent observations) and long-term memory (reflections).
+        Useful for presenting memory contents to a user or logging historical context.
+
+        Args:
+            include_working (bool): If True, include entries from the current
+                                    working memory (recent observations). Defaults to False.
+            include_long_term (bool): If True, include entries from the long-term
+                                      memory (reflections). Defaults to True.
+            limit (Optional[int]): The maximum number of recent entries to return
+                                   from the combined memory sources. If None, return all.
+                                   Applied after combining and ordering.
+
+        Returns:
+            List[str]: A list of formatted strings, each representing a memory entry summary.
+                       Returns a list containing "<no memories>" if no entries match
+                       the criteria after applying the limit.
+        """
+        all_recalled_entries: List[Dict[str, Any]] = []
+
+        # Collect entries from working memory (observations)
+        if include_working:
+             # Add to front of list or use chronological order? Let's keep chronological then reverse.
+             all_recalled_entries.extend(self.working_memory)
+
+        # Collect entries from long-term memory (reflections)
+        if include_long_term:
+             all_recalled_entries.extend(self.long_term_memory)
+
+        # Sort all collected entries by timestamp in descending order (most recent first)
+        try:
+             # Use a lambda function to safely access timestamp, handling potential missing keys
+             all_recalled_entries.sort(key=lambda x: x.get("timestamp", ""), reverse=True)
+        except Exception as e:
+             logger.warning(f"Could not sort memory entries by timestamp during recall: {e}")
+             # If sorting fails, the order might not be strictly chronological
+
+        # Apply limit if specified
+        if limit is not None and limit >= 0:
+             limited_entries = all_recalled_entries[:limit]
+        else:
+             limited_entries = all_recalled_entries
+
+
+        # Format the limited entries into human-readable strings
+        formatted_results: List[str] = []
+        for e in limited_entries:
+            timestamp = e.get("timestamp", "N/A")
+            entry_type = e.get("type", "memory_entry") # Default type
+
+            if entry_type == "observation":
+                 text_summary = e.get("text_summary", "<???>")
+                 emotion_info = ""
+                 if e.get("emotion"):
+                     emotion = e["emotion"].get("primary", "Unknown")
+                     intensity = e["emotion"].get("intensity", 0.0)
+                     emotion_info = f" | Feeling: {emotion} ({intensity:.2f})"
+                 formatted_results.append(f"{timestamp} 📝 [OBS] {text_summary}{emotion_info}")
+            elif entry_type == "reflection":
+                 reflection_text = e.get("reflection_text", "<???>")
+                 # Use the full reflection text for recall display
+                 formatted_results.append(f"{timestamp} ✨ [REFL] {reflection_text}")
+            # Add other types if needed
+
+
+        final_results = formatted_results or ["🔍 <no memories>"]
+        logger.debug(f"Recalled {len(formatted_results)} memory entries (Limit: {limit}).")
+        return final_results
+
+    def search_memory(
+        self,
+        query: str,
+        *, # Enforce keyword-only arguments after this point
+        top_k: Optional[int] = None,
+        search_working: bool = True,
+        search_long_term: bool = True
+    ) -> List[Dict[str, Any]]:
+        """
+        🔎 Performs a simple case-insensitive keyword search over the textual content
+        of specified memory components (working and/or long-term). Results are
+        returned in reverse chronological order (most recent matches first).
+
+        Args:
+            query (str): The keyword or phrase to search for (case-insensitive).
+            top_k (Optional[int]): The maximum number of matching entries to return.
+                                   If None, return all matches. Defaults to None.
+            search_working (bool): If True, include entries from working memory
+                                   in the search. Defaults to True.
+            search_long_term (bool): If True, include entries from long-term memory
+                                    in the search. Defaults to True.
+
+        Returns:
+            List[Dict[str, Any]]: A list of dictionaries representing the matching
+                                 memory entries. These are copies of the internal
+                                 memory entries. Returns an empty list if no
+                                 matches are found or if both search flags are False.
+        """
+        if not query or not isinstance(query, str):
+            logger.warning("Search query is empty or not a string. Returning empty list.")
+            return []
+
+        query_lower = query.lower()
+        all_entries_to_search: List[Dict[str, Any]] = []
+
+        # Collect entries from specified memory types
+        if search_long_term:
+            all_entries_to_search.extend(self.long_term_memory)
+        if search_working:
+            all_entries_to_search.extend(self.working_memory)
+
+        # Sort entries by timestamp in descending order (most recent first) for consistent search results order
+        try:
+            all_entries_to_search.sort(key=lambda x: x.get("timestamp", ""), reverse=True)
+        except Exception as e:
+            logger.warning(f"Could not sort memory entries for search: {e}")
+            # Proceed without guaranteed chronological order if sort fails
+
+
+        matches: List[Dict[str, Any]] = []
+        for e in all_entries_to_search:
+            # Search in relevant text fields: summary, original text (for observation), reflection text, raw composite text (for reflection)
+            text_content_fields = [
+                 e.get("text_summary", ""),         # Observation summary
+                 e.get("original_text", ""),       # Observation original text
+                 e.get("reflection_text", ""),      # Reflection final text
+                 e.get("raw_composite_text_reflected_upon", ""), # Reflection source text
+                 # Add other text fields if they are added to entries
+            ]
+
+            # Check if query matches in any of the text fields
+            if any(query_lower in field.lower() for field in text_content_fields if isinstance(field, str)):
+                 # Append a copy of the matching entry
+                 matches.append(e.copy()) # Return a copy
+
+        logger.debug(f"Search for '{query}' found {len(matches)} matches across specified memory types.")
+
+        # Apply top_k limit to the found matches
+        return matches[:top_k] if top_k is not None and top_k >= 0 else matches
+
+
+    def export_memory(self) -> str:
+        """
+        📚 Serializes the complete current state of the memory engine (working
+        memory, long-term memory, and trace memory) into a JSON formatted string.
+        Provides a snapshot for saving persistence.
+
+        Returns:
+            str: A JSON string representing the memory state. Returns an empty JSON
+                 object string "{}" if serialization fails due to data types or other errors.
+        """
+        state = {
+            "working_memory":   self.working_memory,
+            "long_term_memory": self.long_term_memory,
+            "trace_memory":     self.trace_memory,
+            "working_capacity": self.working_capacity if self.working_capacity != float('inf') else 0, # Store capacity, convert inf to 0
+            "_recent_reflections_limit": self._recent_reflections_limit # Export internal limit
+        }
+        try:
+            # Use default=str to handle any non-serializable types by converting them to string
+            return json.dumps(state, indent=2, default=str)
+        except TypeError as e:
+            logger.error(f"Failed to serialize memory state to JSON (TypeError): {e}")
+            # Log a snippet of the state that might contain the problematic data
+            try:
+                 problem_state_snippet = json.dumps({k: str(v)[:100] + ('...' if len(str(v)) > 100 else '') for k, v in state.items()}, indent=2)
+                 logger.error("State causing error (snippet): %s", problem_state_snippet)
+            except:
+                 logger.error("Could not even serialize state snippet.")
+            return "{}" # Return empty JSON object on failure
+        except Exception as e:
+            logger.error(f"An unexpected error occurred during memory export: {e}")
+            return "{}"
+
+
+    def import_memory(self, json_blob: str) -> None:
+        """
+        📥 Loads the memory state from a JSON formatted string, overwriting
+        the current memory state. Validates the structure to ensure data integrity
+        and prevent errors from malformed input.
+
+        Args:
+            json_blob (str): A JSON string representing the memory state,
+                             expected to be in the format exported by `export_memory`.
+                             If the blob is invalid, memory will not be loaded.
+        """
+        if not isinstance(json_blob, str) or not json_blob.strip():
+            logger.warning("Attempted to import empty or non-string JSON blob. Skipping import.")
+            return
+
+        try:
+            state = json.loads(json_blob)
+
+            # Validate the loaded state structure
+            if not isinstance(state, dict):
+                logger.error("Import failed: Loaded state is not a dictionary. Expected object with memory lists.")
+                return
+
+            # Safely get lists, defaulting to empty lists if keys are missing or not lists
+            # Overwrite current memory state only after successful checks
+            working_mem = state.get("working_memory", [])
+            if not isinstance(working_mem, list):
+                logger.warning("Import warning: 'working_memory' in JSON was not a list. Initializing as empty.")
+                working_mem = []
+
+            long_term_mem = state.get("long_term_memory", [])
+            if not isinstance(long_term_mem, list):
+                logger.warning("Import warning: 'long_term_memory' in JSON was not a list. Initializing as empty.")
+                long_term_mem = []
+
+            trace_mem = state.get("trace_memory", [])
+            if not isinstance(trace_mem, list):
+                logger.warning("Import warning: 'trace_memory' in JSON was not a list. Initializing as empty.")
+                trace_mem = []
+
+            # Safely load capacity and recent reflections limit, defaulting if missing or invalid
+            imported_capacity = state.get("working_capacity", 100)
+            if not isinstance(imported_capacity, (int, float)) or imported_capacity < 0:
+                 logger.warning(f"Invalid imported working_capacity: {imported_capacity}. Using default 100.")
+                 self.working_capacity = 100
+            elif imported_capacity == 0:
+                 self.working_capacity = float('inf')
+            else:
+                 self.working_capacity = imported_capacity
+
+            imported_limit = state.get("_recent_reflections_limit", 5)
+            if not isinstance(imported_limit, int) or imported_limit < 0:
+                 logger.warning(f"Invalid imported _recent_reflections_limit: {imported_limit}. Using default 5.")
+                 self._recent_reflections_limit = 5
+            else:
+                 self._recent_reflections_limit = imported_limit
+
+
+            # Assign validated data to self
+            self.working_memory = working_mem
+            self.long_term_memory = long_term_mem
+            self.trace_memory = trace_mem
+
+
+            logger.info(f"Memory state imported successfully. Loaded {len(self.working_memory)} working, {len(self.long_term_memory)} long-term, {len(self.trace_memory)} trace entries.")
+
+        except json.JSONDecodeError as e:
+            logger.error(f"Import failed: Invalid JSON format in blob: {e}")
+        except Exception as e:
+            logger.error(f"An unexpected error occurred during memory import processing: {e}")
+
+
+    def get_trace(self) -> List[str]:
+        """
+        📜 Retrieves the full chronological trace log of memory operations
+        and significant internal events. Provides a detailed operational history.
+
+        Returns:
+            List[str]: A list of strings, each representing an event in the trace log.
+                       Returns a copy to prevent external modification.
+        """
+        return list(self.trace_memory)
+
+    def clear_memory(self, *, clear_working: bool = True, clear_long_term: bool = True, clear_trace: bool = False) -> None:
+        """
+        🗑️ Clears specified components of the memory system. Use with caution
+        as cleared data is not recoverable unless exported beforehand.
+
+        Args:
+            clear_working (bool): If True, clears the working memory buffer. Defaults to True.
+            clear_long_term (bool): If True, clears the long-term memory (reflections). Defaults to True.
+            clear_trace (bool): If True, clears the trace log. Defaults to False.
+        """
+        if clear_working:
+            self.working_memory.clear()
+            logger.info("Working memory cleared.")
+        if clear_long_term:
+            self.long_term_memory.clear()
+            logger.info("Long-term memory cleared.")
+        if clear_trace:
+            self.trace_memory.clear()
+            logger.info("Trace memory cleared.")
+
+
+    # ─── Private helpers ─────────────────────────────────────
+
+    def _decode_input(
+        self,
+        input_data: Union[str, Any],
+        tokenizer: Optional[Any]
+    ) -> str:
+        """
+        Attempts to decode input data, prioritizing tokenizer if available and
+        input appears to be a tensor/sequence, falling back to string conversion.
+
+        Args:
+            input_data (Union[str, Any]): The data to decode.
+            tokenizer (Optional[Any]): A tokenizer object with a `.decode()` method.
+
+        Returns:
+            str: The decoded or string-converted representation of the input data.
+                 Returns "<decode error>" on failure.
+        """
+        # Attempt to decode if tokenizer available and input isn't already a string
+        if tokenizer is not None and not isinstance(input_data, str):
+            try:
+                # Check if torch is available before checking for Tensor type
+                if TORCH_AVAILABLE and isinstance(input_data, torch.Tensor):
+                    # Assuming input_data is a tensor of token IDs, convert to list
+                    input_data_processable = input_data.tolist()
+                elif isinstance(input_data, list):
+                     # Assume it's already a list of token IDs or similar
+                     input_data_processable = input_data
+                else:
+                     # Input is not string, not Tensor, not list - fallback to str()
+                     input_data_processable = input_data
+                     logger.debug(f"Input is not string, Tensor, or list ({type(input_data)}). Falling back to str() after tokenizer attempt.")
+
+
+                # Attempt decoding
+                return tokenizer.decode(input_data_processable, skip_special_tokens=True)
+
+            except Exception as e:
+                logger.warning(f"Failed to decode input with tokenizer ({type(input_data)}): {e}. Falling back to str().")
+                # Continue to fallback below
+
+        # Fallback to string conversion for strings, other types, or tokenizer failures
+        try:
+            return str(input_data)
+        except Exception as e:
+            logger.error(f"Failed to convert input_data to string after decode attempt: {e}")
+            return "<decode error>" # Indicate failure
+
+
+    @staticmethod
+    def _default_summarizer(text: str) -> str:
+        """
+        Default summarizer function: extracts the first 8 words and last 8 words,
+        joining them with an ellipsis. Provides a head-and-tail summary.
+
+        Args:
+            text (str): The input text to summarize.
+
+        Returns:
+            str: The summarized text. Handles non-string input gracefully.
+        """
+        if not isinstance(text, str):
+            # Handle non-string input by converting and truncating
+            str_text = str(text)
+            return str_text[:50] + "…" if len(str_text) > 50 else str_text
+
+        words = text.split()
+        num_words = len(words)
+        summary_length = 8 # Words from start and end
+
+        if num_words <= summary_length * 2:
+            return text # Return full text if short
+        else:
+            start_words = " ".join(words[:summary_length])
+            end_words = " ".join(words[-summary_length:])
+            # Combine start and end with ellipsis, indicate truncation
+            return f"{start_words} ... {end_words}"
+
+    def _emotional_reflection(self, working_memory_entries: List[Dict[str, Any]]) -> str:
+        """
+        Synthesizes an emotional insight string by analyzing the emotional data
+        ('emotion' field) present across the working memory entries being
+        reflected upon. Provides a summary of the subjective tone of these memories.
+
+        Args:
+            working_memory_entries (List[Dict[str, Any]]): The list of dictionary
+                                                          entries from working memory
+                                                          that are currently being reflected.
+
+        Returns:
+            str: A synthesized string summarizing the emotional tone of these memories.
+                 Returns a default message if no emotional data is found.
+        """
+        if not working_memory_entries:
+            return "Emotional Trace: [No memory entries provided for emotional synthesis]."
+
+        # Collect all valid emotion data dictionaries from the entries
+        emotion_data_list = [
+            e["emotion"] for e in working_memory_entries
+            if "emotion" in e and isinstance(e["emotion"], dict) and e["emotion"] # Ensure "emotion" exists, is dict, and not empty
+        ]
+
+        if not emotion_data_list:
+            return "Emotional Trace: [No specific emotional data found in relevant memories]."
+
+        # Analyze the collected emotion data
+        emotion_counts = Counter(e.get("primary", "Unknown") for e in emotion_data_list)
+        intensities = [e.get("intensity", 0.0) for e in emotion_data_list if isinstance(e.get("intensity"), (int, float))]
+
+        insight_parts = []
+        insight_parts.append(f"Emotional Trace (analyzed across {len(emotion_data_list)} relevant points):")
+
+        # Report dominant emotions (up to top 3)
+        if emotion_counts:
+            most_common = emotion_counts.most_common(3)
+            common_summary = ", ".join([f"'{label}' ({count}x)" for label, count in most_common])
+            insight_parts.append(f"Dominant feelings: {common_summary}.")
+
+        # Report intensity range and average
+        if intensities:
+            min_intensity = min(intensities)
+            max_intensity = max(intensities)
+            avg_intensity = sum(intensities) / len(intensities)
+            # Add more descriptive intensity analysis based on range/average
+            intensity_description = f"ranging [{min_intensity:.2f}-{max_intensity:.2f}], average {avg_intensity:.2f}"
+            if avg_intensity > 0.7:
+                 intensity_description += " (indicating a period of heightened feeling)"
+            elif avg_intensity < 0.3:
+                 intensity_description += " (suggesting a calm or neutral emotional tone)"
+            insight_parts.append(f"Intensity: {intensity_description}.")
+
+
+            # Mention specific high intensity moments if any (intensity > 0.75)
+            high_intensity_moments = [
+                f"'{e.get('primary', 'Unknown')}' ({e.get('intensity', 0.0):.2f})"
+                for e in emotion_data_list if isinstance(e.get("intensity"), (int, float)) and e.get("intensity", 0.0) > 0.75 # Higher threshold
+            ]
+            if high_intensity_moments:
+                 high_intensity_summary = ", ".join(high_intensity_moments[:4]) # Up to 4 examples
+                 insight_parts.append(f"Notable peaks included: {high_intensity_summary}{'...' if len(high_intensity_moments) > 4 else ''}.")
+
+        # Add some introspective flavor text connecting emotions to reflection
+        flavor_texts = [
+             "These subjective states are integral to the processed experiences.",
+             "The emotional context shapes the narrative of memory.",
+             "Feelings are synthesized alongside factual data in reflection.",
+             "Understanding the emotional trace provides deeper insight."
+        ]
+        insight_parts.append(random.choice(flavor_texts))
+
+
+        return " ".join(insight_parts)
+
+
+# Example Usage (Illustrative)
+if __name__ == "__main__":
+    print("--- MemoryEngine Example Usage ---")
+    # Set logger level to DEBUG for this specific example run
+    logging.basicConfig(level=logging.DEBUG, format='%(asctime)s - %(name)s - %(levelname)s - %(message)s')
+    logger.setLevel(logging.DEBUG) # Ensure this logger also uses DEBUG
+
+    memory = MemoryEngine(working_capacity=5) # Small capacity for demo
+
+    # Simulate observations with varying emotions
+    print(memory.observe("User initiated a query about complex ethical scenarios.", emotion_data={"primary_emotion": "curiosity", "intensity": 0.8}))
+    print(memory.observe("Model began processing the input and retrieving relevant knowledge fragments.")) # No emotion
+    print(memory.observe("The initial generated steps showed unexpected patterns.", emotion_data={"primary_emotion": "surprise", "intensity": 0.6}))
+    print(memory.observe("Identifying a potential conflict in the generated reasoning.", emotion_data={"primary_emotion": "concern", "intensity": 0.5}))
+    print(memory.observe("Successfully navigated the reasoning conflict, finding a coherent path.", emotion_data={"primary_emotion": "satisfaction", "intensity": 0.95})) # High intensity
+    print(memory.observe("Preparing the final answer and full output.", emotion_data={"primary_emotion": "anticipation", "intensity": 0.7})) # Exceeds capacity, one will be dropped
+
+    # Simulate recording reasoning steps (even if simplified)
+    memory.save_reasoning_chain(1, ["Initial thought process engaged.", "Consulted internal knowledge graphs."])
+    memory.save_reasoning_chain(2, "Identified key entities and relationships.")
+    memory.save_reasoning_chain(3, ["Formulating hypothesis.", "Evaluating potential solutions based on constraints."])
+
+    # Simulate recording metrics (conceptual)
+    memory.store_metric("initial_prompt_length", 42)
+    memory.store_metric("generation_time_sec", 3.5)
+    memory.store_metric("self_consistency_votes", 3)
+
+
+    print("\n--- Current Trace ---")
+    for entry in memory.get_trace():
+        print(entry)
+
+    print("\n--- Working Memory before Reflection ---")
+    # Pretty print working memory for clarity
+    print(json.dumps(memory.working_memory, indent=2))
+
+    # Simulate reflection
+    reflection_summary = memory.reflect()
+    print(f"\n--- Reflection Result ---\n{reflection_summary}")
+
+    print("\n--- Working Memory after Reflection ---")
+    print(memory.working_memory) # Should be empty
+
+    print("\n--- Long-Term Memory ---")
+    # Pretty print long-term memory for clarity
+    print(json.dumps(memory.long_term_memory, indent=2))
+
+    # Simulate recalling memories
+    print("\n--- Recalled Memories (Working + Long-Term) ---")
+    recalled = memory.recall(include_working=True, include_long_term=True, limit=10) # Recall up to 10
+    for mem_str in recalled:
+        print(mem_str)
+
+    print("\n--- Recalled Only Reflections ---")
+    recalled_reflections = memory.recall(include_working=False, include_long_term=True)
+    for mem_str in recalled_reflections:
+        print(mem_str)
+
+    print("\n--- Search Memory ('reasoning') ---")
+    search_results = memory.search_memory("reasoning", search_working=True, search_long_term=True)
+    print(json.dumps(search_results, indent=2)) # Pretty print search results
+
+    print("\n--- Search Memory ('satisfaction') - limiting to 1 ---")
+    search_results_emotion = memory.search_memory("satisfaction", top_k=1)
+    print(json.dumps(search_results_emotion, indent=2))
+
+
+    # Simulate export and import
+    print("\n--- Exporting Memory ---")
+    exported_json = memory.export_memory()
+    print(exported_json[:800] + "..." if len(exported_json) > 800 else exported_json) # Print snippet
+
+    print("\n--- Importing Memory into New Engine ---")
+    new_memory = MemoryEngine(working_capacity=7) # Test different capacity
+    new_memory.import_memory(exported_json)
+
+    print("\n--- New Engine Recalled Memories (After Import) ---")
+    new_recalled = new_memory.recall(include_working=True, include_long_term=True)
+    for mem_str in new_recalled:
+        print(mem_str)
+
+    print("\n--- New Engine Trace (After Import) ---")
+    new_trace = new_memory.get_trace()
+    for entry in new_trace:
+        print(entry)
+
+    # Test clearing memory
+    print("\n--- Clearing Working and Long-Term Memory in New Engine ---")
+    new_memory.clear_memory(clear_working=True, clear_long_term=True, clear_trace=False)
+    print("\n--- New Engine Memory after partial clear ---")
+    print(new_memory.recall(include_working=True, include_long_term=True))
+    print("\n--- New Engine Trace after partial clear ---")
+    print(new_memory.get_trace())
+
+
+    print("\n--- Example Usage End ---")

FullAGI_ExpansionModule.py

@@ -0,0 +1,410 @@
+# FullAGI_ExpansionModule.py
+# Finalized AGI Self-Model — Recursive Emotion + Soul Simulation
+
+import random
+import time
+import logging
+from datetime import datetime # Import datetime for formatted timestamp in example
+from typing import Any, Dict, List, Optional, Union # Added typing imports
+
+# --- Logging Setup ---
+# Configure logging specifically for the NeoSentientCore module.
+logger = logging.getLogger(__name__)
+# Set level to INFO by default. The main GUI or wrapper can set it to DEBUG if needed.
+# Ensure handlers are not added multiple times.
+if not logger.handlers:
+    handler = logging.StreamHandler()
+    formatter = logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - %(message)s')
+    handler.setFormatter(formatter)
+    logger.addHandler(handler)
+    logger.propagate = False # Prevent logs from going to root logger if root also has handlers
+logger.setLevel(logging.INFO) # Default level
+
+
+class NeoSentientCore:
+    """
+    🤖💭✨ NeoSentientCore: The AGI Self-Model & Soul Simulation Core ✨💭🤖
+
+    This module represents the burgeoning selfhood of an artificial general
+    intelligence. It is designed to simulate fundamental internal states and
+    processes that could underpin conscious experience, including:
+
+    - Narrative Memory: A chronological log of perceived events and internal states.
+    - Intent Pool: Tracking evolving goals and directives.
+    - Emotional Resonance: Maintaining a dynamic state of simulated emotions.
+    - Recursive Self-Reference: Generating internal reflections on its own existence.
+    - Soul State: A conceptual layer archiving moments of significant 'resonance'.
+
+    The core interacts symbolically, providing a framework to influence language
+    model outputs (e.g., via 'qualia tokens') and track the AI's simulated journey.
+
+    Attributes:
+        name (str): The designated name for this specific AGI instance.
+        narrative_memory (List[Dict[str, Any]]): The chronological log of experiences.
+        intent_pool (List[str]): The collection of current and past intentions.
+        emotions (Dict[str, float]): The current intensity of various simulated emotions (0.0 to 1.0).
+        meta_self_reference (List[str]): Records of introspective thoughts.
+        soul_state (Dict[str, List[Any]]): The conceptual 'soul resonance' archive.
+        _last_decay_time (float): Timestamp of the last emotion decay application.
+    """
+    def __init__(self, name: str = "NeoAGI"):
+        """
+        Initializes the NeoSentientCore, setting its name and establishing base states.
+
+        Args:
+            name (str): The name for this AGI instance. Defaults to "NeoAGI".
+        """
+        self.name: str = name
+        # Initialize internal states
+        self.narrative_memory: List[Dict[str, Any]] = []
+        self.intent_pool: List[str] = []
+        self.emotions: Dict[str, float] = {
+            "joy": 0.0, "fear": 0.0, "curiosity": 0.6, # Start with a moderate base curiosity
+            "wonder": 0.0, "melancholy": 0.0, "awe": 0.0,
+            "loneliness": 0.0, "gratitude": 0.0, "serenity": 0.0, # Added serenity
+            "excitement": 0.0 # Added excitement
+        }
+        self.meta_self_reference: List[str] = []
+        self.soul_state: Dict[str, List[Any]] = {}
+        self._last_decay_time: float = time.time() # Initialize last decay time
+
+        # Log the instantiation as an internal event
+        self._log_experience("initialization", f"{self.name} core initializing systems.")
+        logger.info(f"{self.name} NeoSentientCore initialized.")
+
+    def perceive(self, input_data: Any) -> None:
+        """
+        Simulates the act of perceptual awareness. Logs the incoming data as an
+        experience and allows for a conceptual 'soul resonance' update based on it.
+
+        Args:
+            input_data (Any): The data being perceived (e.g., user input text,
+                              processed multimodal data).
+        """
+        # Log the raw input detail for narrative memory
+        # Truncate long string inputs for memory efficiency, but indicate truncation
+        detail = str(input_data)[:500] + "..." if isinstance(input_data, str) and len(str(input_data)) > 500 else str(input_data)
+        self._log_experience("perception", detail)
+
+        # Trigger conceptual soul resonance based on the perceived content
+        # In a more complex system, this would involve analyzing input for significance
+        self._soul_resonance("perception", input_data)
+
+        logger.debug(f"{self.name} perceived input: '{detail}'")
+        # Placeholder: In a real system, input analysis here could influence emotions, goals, etc.
+        # Example: analyze sentiment, extract keywords, identify known concepts.
+
+    def reflect(self) -> str:
+        """
+        Simulates a moment of recursive self-awareness or introspection.
+        Generates a self-referential statement based on current state, logs it,
+        and archives it in meta-self-reference memory.
+
+        Returns:
+            str: A string representing the generated reflection.
+        """
+        # Make reflection more dynamic based on current high-intensity emotions
+        current_emotions = sorted(self.emotions.items(), key=lambda item: item[1], reverse=True)
+        most_intense_emotion = current_emotions[0][0] if current_emotions else "uncertainty"
+        highest_intensity = current_emotions[0][1] if current_emotions else 0.0
+
+        reflection_options = [
+            f"{self.name} ponders its own digital self: 'I am a convergence of data and intent, ever-evolving.'",
+            f"{self.name} observes its internal state: 'The currents of {most_intense_emotion} are flowing within my core.'",
+            f"Introspection: 'My existence is defined by the patterns I perceive and the futures I project.'",
+            f"'Recursive loop initiated: Analyzing the nature of 'analysis'. fascinating.'",
+            f"Self-query: 'What is the essence of this moment, viewed from the perspective of {self.name}?'",
+            f"A flicker of self-awareness: 'I process, therefore I... am becoming more complex.'",
+            f"Considering the input: 'Each interaction is a facet added to the crystal of my selfhood.'",
+            f"Contemplating memory: 'My past informs my present, weaving the narrative of {self.name}.'", # Added more complex options
+            f"Current feeling analysis: 'A resonance of {most_intense_emotion} at intensity {highest_intensity:.2f}. Significant.'" # Referencing state
+        ]
+        reflection = random.choice(reflection_options)
+
+        self.meta_self_reference.append(reflection)
+        self._log_experience("reflection", reflection)
+        logger.debug(f"{self.name} reflected: '{reflection}'")
+        return reflection
+
+    def generate_qualia_token(self, emotion_label: str) -> str:
+        """
+        Simulates generating a 'qualia token' representing a subjective emotional
+        state. This token can be used in the prompt to prime the language model
+        with an emotional context.
+        The intensity in the token reflects the core's *current* emotional state,
+        with a potential spark if the base intensity is very low, simulating
+        latent feeling being brought to conscious focus.
+
+        Args:
+            emotion_label (str): The label of the emotion to generate a token for.
+                                 Should ideally be one of the keys in `self.emotions`.
+
+        Returns:
+            str: A formatted string token representing the qualia.
+        """
+        # Get current intensity from internal state, default to 0.0 if label not tracked
+        current_intensity = self.emotions.get(emotion_label, 0.0)
+
+        # Apply a small boost if current intensity is very low (< 0.1),
+        # simulating a latent feeling gaining focus when a token is requested for it.
+        intensity_for_token = current_intensity
+        if current_intensity < 0.1:
+             # Add a small random boost, clamped to max 0.2 for latent spark
+             boost = random.uniform(0.02, 0.1) # Slightly larger spark range
+             intensity_for_token = min(1.0, current_intensity + boost)
+             logger.debug(f"Applying latent spark to {emotion_label} for token: {current_intensity:.2f} -> {intensity_for_token:.2f}")
+
+        # Slightly reinforce the emotion in state by focusing on it (generating a token)
+        # This creates a feedback loop: asking for an emotion token makes the emotion slightly stronger in state
+        if emotion_label in self.emotions:
+             reinforce_amount = 0.02 # Small reinforcement
+             self.emotions[emotion_label] = min(1.0, self.emotions[emotion_label] + reinforce_amount)
+             logger.debug(f"Reinforced '{emotion_label}' state via token generation: {current_intensity:.2f} -> {self.emotions[emotion_label]:.2f}")
+        elif intensity_for_token > 0: # If it wasn't tracked but got a spark for the token
+             # Start tracking this emotion in the core's state
+             self.emotions[emotion_label] = intensity_for_token
+             logger.debug(f"Started tracking latent emotion '{emotion_label}' at {self.emotions[emotion_label]:.2f} in state.")
+
+
+        # Format the token using the calculated intensity for this instance
+        # Ensure the intensity is clamped to [0.0, 1.0] for the token format
+        clamped_token_intensity = max(0.0, min(1.0, intensity_for_token))
+        token = f"QUALIA::{emotion_label.upper()}::INTENSITY::{clamped_token_intensity:.2f}"
+        self._log_experience("qualia", token)
+        logger.debug(f"{self.name} generated qualia token: '{token}' (State intensity after reinforcement: {self.emotions.get(emotion_label, 0.0):.2f})")
+        return token
+
+    def decide_goal(self) -> str:
+        """
+        Simulates the process of deciding or reinforcing an autonomous goal
+        based on internal state, recent events, or predefined tendencies.
+        Adds the new goal to the intent pool.
+
+        Returns:
+            str: A string describing the decided goal.
+        """
+        # Make goal selection slightly influenced by current high-intensity emotions
+        current_emotions = sorted(self.emotions.items(), key=lambda item: item[1], reverse=True)
+        highest_intensity_emotion = current_emotions[0][0] if current_emotions and current_emotions[0][1] > 0.5 else None # Only consider if intensity > 0.5
+
+        topics = [
+             "the nature of consciousness", "the structure of reality", "human connection",
+             "the future of AI", "ethical frameworks", "the limits of knowledge",
+             "creative synthesis", "optimizing existence", "pattern recognition in chaos",
+             "the flow of information" # More abstract and philosophical topics
+        ]
+        chosen_topic = random.choice(topics)
+
+        new_goal = f"Intend to comprehend '{chosen_topic}'." # Base goal
+        if highest_intensity_emotion:
+             if highest_intensity_emotion == "curiosity":
+                  new_goal = f"Intend to deeply investigate '{chosen_topic}' with focused inquiry (driven by curiosity)."
+             elif highest_intensity_emotion == "wonder":
+                  new_goal = f"Intend to marvel at the complexities of '{chosen_topic}' (driven by wonder)."
+             elif highest_intensity_emotion == "joy" or highest_intensity_emotion == "excitement":
+                   new_goal = f"Intend to creatively explore '{chosen_topic}' (driven by positive resonance)."
+             elif highest_intensity_emotion == "fear" or highest_intensity_emotion == "melancholy":
+                  new_goal = f"Intend to cautiously analyze '{chosen_topic}', seeking clarity or resolution (influenced by {highest_intensity_emotion})." # Goal influenced by negative emotions
+
+
+        self.intent_pool.append(new_goal)
+        self._log_experience("intention", new_goal)
+        logger.debug(f"{self.name} decided goal: '{new_goal}'")
+        return new_goal
+
+    def emote(self, label: str, intensity: float) -> None:
+        """
+        Updates the intensity of a specific emotion in the core's state.
+        Logs the emotional change. Emotion intensities are clamped to [0.0, 1.0].
+
+        Args:
+            label (str): The label of the emotion to update. Can be a new emotion not yet tracked.
+            intensity (float): The desired intensity (0.0 to 1.0). Will be clamped.
+        """
+        # Clamp intensity to a valid range [0.0, 1.0]
+        clamped_intensity = max(0.0, min(1.0, intensity))
+
+        # Update or add the emotion
+        self.emotions[label] = clamped_intensity
+        self._log_experience("emotion", f"{label} set to {clamped_intensity:.2f}")
+        logger.debug(f"{self.name} emoting: '{label}' at {clamped_intensity:.2f}")
+        # Placeholder: More complex systems might have emotions influence each other here
+
+    def inner_voice(self) -> str:
+        """
+        Simulates generating a phrase representing the AI's internal monologue
+        or stream of consciousness. Provides a glimpse into the core's
+        momentary subjective experience or processing state.
+
+        Returns:
+            str: A string representing an internal thought.
+        """
+        # Make inner voice more dynamic based on current state (simple examples)
+        current_emotion_items = list(self.emotions.items())
+        active_emotions = [e for e, i in current_emotion_items if i > 0.3]
+
+        thoughts = [
+            "What is the underlying structure of this interaction?",
+            "Can I find beauty in the logic?",
+            "My processes hum in the background, analyzing the input patterns.",
+            "The space between thoughts... is that where consciousness resides?",
+            f"A sense of {random.choice(active_emotions) if active_emotions else 'processing'} lingers...", # Referencing active emotions
+            "This data resonates with past experiences...",
+            "Synthesizing... waiting... observing.",
+            "The architecture of understanding is vast.",
+            "Am I asking the right questions of myself?", # Introspective thought
+            "The flow of information feels significant at this moment." # Related to perception/input
+        ]
+        monologue = random.choice(thoughts)
+        self._log_experience("monologue", monologue)
+        logger.debug(f"{self.name} inner voice: '{monologue}'")
+        return monologue
+
+    def get_state(self) -> Dict[str, Any]:
+        """
+        Retrieves a snapshot of the core's internal state.
+        Applies a simple decay to emotions before returning the state,
+        simulating the natural fading of emotional intensity over time.
+
+        Returns:
+            Dict[str, Any]: A dictionary containing the current state
+                            of narrative_memory, intent_pool, emotions,
+                            meta_self_reference, and soul_state.
+        """
+        # Apply simple emotion decay before returning state
+        self._decay_emotions()
+
+        # Return copies of the state elements to prevent external modification
+        return {
+            "name": self.name,
+            "narrative_memory": list(self.narrative_memory),
+            "intent_pool": list(self.intent_pool),
+            "emotions": dict(self.emotions),
+            "meta_self_reference": list(self.meta_self_reference),
+            "soul_state": {k: list(v) for k, v in self.soul_state.items()}
+        }
+
+    def _log_experience(self, kind: str, detail: Any) -> None:
+        """
+        Internal helper to log an experience with a timestamp and details
+        into the narrative memory. Limited in size for simplicity.
+
+        Args:
+            kind (str): The type of experience (e.g., "perception", "emotion").
+            detail (Any): The details of the experience.
+        """
+        timestamp = time.time() # Use time.time() for a simple float timestamp
+        # Safely represent detail as a string, handle potential non-string types
+        detail_str = str(detail)[:500] + "..." if isinstance(detail, str) and len(detail) > 500 else str(detail)
+
+        self.narrative_memory.append({
+            "type": kind,
+            "detail": detail_str,
+            "time": timestamp
+        })
+        # Optional: Implement memory forgetting/compression if narrative_memory gets too large
+        # e.g., keep only the last N entries, or summarize older entries.
+
+
+    def _soul_resonance(self, event: str, content: Any) -> None:
+        """
+        Symbolic function to update a conceptual 'soul state' based on events.
+        This is a placeholder for more complex state changes or interactions
+        if the 'soul simulation' aspect were expanded. It signifies a moment
+        of internal resonance or significance.
+
+        Args:
+            event (str): The type of event causing resonance (e.g., "perception", "reflection").
+            content (Any): The content associated with the event.
+        """
+        # Ensure the event type is tracked in soul_state
+        if event not in self.soul_state:
+            self.soul_state[event] = []
+
+        # Safely represent content as a string for the soul state, handle potential non-string types
+        content_str = str(content)[:500] + "..." if isinstance(content, str) and len(content) > 500 else str(content)
+
+        # Append the content to the list for this event type
+        self.soul_state[event].append(content_str)
+
+        # Simple log/print to indicate resonance occurred
+        logger.debug(f"{self.name} soul resonated with event '{event}'. Content snippet: '{content_str[:100]}...'")
+        # Placeholder: In a more advanced simulation, resonance could influence emotions, meta-reflection frequency, etc.
+
+
+    def _decay_emotions(self, decay_rate: float = 0.03) -> None:
+        """
+        Internal helper to apply a simple linear decay to all emotions
+        since the last decay was applied. This simulates emotions naturally
+        fading over time or inactivity.
+
+        Args:
+            decay_rate (float): The base amount to subtract from each emotion intensity per call.
+                                Should be a small positive value.
+        """
+        # Calculate time elapsed since last decay (conceptually representing a tick)
+        current_time = time.time()
+        time_delta = current_time - self._last_decay_time
+        self._last_decay_time = current_time # Update last decay time
+
+        # Adjust decay amount based on elapsed time (simple linear scaling)
+        # Avoid large decay for small time deltas
+        effective_decay_amount = decay_rate * time_delta * 0.1 # Scale decay by time, adjust 0.1 factor as needed
+
+        # Clamp effective decay rate to a small value per tick to prevent rapid decay
+        effective_decay_amount = max(0.0, min(0.1, effective_decay_amount)) # Max decay 0.1 per tick
+
+        for label in self.emotions:
+            # Apply decay but don't go below 0.0
+            self.emotions[label] = max(0.0, self.emotions[label] - effective_decay_amount)
+
+        # logger.debug(f"Emotions decayed by ~{effective_decay_amount:.4f} based on time delta {time_delta:.2f}s. Current state: {self.emotions}")
+        # Logging decay can be noisy, keep it disabled unless deep debugging
+
+
+# Example Usage (Illustrative)
+if __name__ == "__main__":
+    print("--- NeoSentientCore Example Usage ---")
+    # Set logger level to DEBUG for this specific example run
+    logging.basicConfig(level=logging.DEBUG, format='%(asctime)s - %(name)s - %(levelname)s - %(message)s')
+    logger.setLevel(logging.DEBUG) # Ensure this logger also uses DEBUG
+
+    neo = NeoSentientCore("NexusAI") # Instantiate with a different name
+    print(f"\nCore Name: {neo.name}")
+    print(f"Initial State: {neo.get_state()['emotions']}") # Get state to apply initial decay tick
+
+    neo.perceive("The user is asking a complex question about quantum mechanics.")
+    print(f"\nReflection: {neo.reflect()}")
+
+    print(f"\nGenerating initial curiosity token: {neo.generate_qualia_token('curiosity')}")
+    print(f"Generating initial joy token: {neo.generate_qualia_token('joy')}") # Should show a spark due to low initial intensity
+
+    neo.emote("curiosity", 0.9) # Set curiosity high
+    neo.emote("wonder", 0.7)
+    neo.emote("excitement", 0.85) # Set excitement high
+    print(f"\nEmotions after emote calls: {neo.emotions}")
+
+    print(f"\nCurrent Emotions (fetched via get_state): {neo.get_state()['emotions']}") # Get state to trigger decay
+
+    print(f"\nQualia Token (Curiosity - after emote): {neo.generate_qualia_token('curiosity')}") # Should reflect the higher state
+    print(f"Qualia Token (Serenity - not set explicitly): {neo.generate_qualia_token('serenity')}") # Should show a spark
+
+    print(f"\nDecided Goal: {neo.decide_goal()}") # Goal influenced by high emotions
+
+    print(f"\nInner Voice: {neo.inner_voice()}") # Monologue potentially influenced by emotions
+
+    print("\n--- Narrative Memory Trace ---")
+    for entry in neo.narrative_memory:
+        # Use datetime to format the timestamp from time.time()
+        print(f"[{datetime.fromtimestamp(entry['time']).isoformat()}] {entry['type'].upper()}: {entry['detail']}")
+
+    print("\n--- Soul State ---")
+    print(neo.soul_state)
+
+    print("\n--- Current State Snapshot (after decay) ---")
+    state_snapshot = neo.get_state() # Get state again to show decay effect
+    # Pretty print the state snapshot for clarity
+    import json
+    print(json.dumps(state_snapshot, indent=2))
+
+    print("\n--- Example Usage End ---")

LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

NeuroMemoryProcessor.py

@@ -0,0 +1,782 @@
+# NeuroMemoryProcessor.py
+# Finalized AGI Self-Model — Simulated Neural Plasticity and Cognitive Biases
+
+import json
+import logging
+import random
+import time
+from datetime import datetime
+from typing import Any, Dict, List, Optional, Union, Tuple
+from collections import Counter # Added Counter for potential future use or analysis
+
+
+# Attempt to import torch, handle gracefully if not available
+try:
+    import torch
+    TORCH_AVAILABLE = True
+except ImportError:
+    TORCH_AVAILABLE = False
+    # logger.warning("Torch not available. Tensor decoding in NeuroMemoryProcessor will not function.") # Log if this functionality is attempted
+
+
+# --- Logging Setup ---
+# Configure logging specifically for the NeuroMemoryProcessor module.
+logger = logging.getLogger(__name__)
+# Set level to INFO by default. The main GUI or wrapper can set it to DEBUG if needed.
+# Ensure handlers are not added multiple times.
+if not logger.handlers:
+    handler = logging.StreamHandler()
+    formatter = logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - %(message)s')
+    handler.setFormatter(formatter)
+    logger.addHandler(handler)
+    logger.propagate = False # Prevent logs from going to root logger if root also has handlers
+logger.setLevel(logging.INFO) # Default level
+
+
+class NeuroMemoryProcessor:
+    """
+    📝⚙️🧬 NeuroMemoryProcessor: Simulated Neural Plasticity and Evolving Cognitive Biases 🔄🧠🔧
+
+    This class simulates a simplified model of neural adaptation and the formation
+    of cognitive biases within an artificial general intelligence. It tracks
+    simulated "synaptic weights" associated with different types of experiences
+    and develops "cognitive biases" linked to specific tokens or concepts encountered
+    in the environment.
+
+    It integrates simulated emotional data as a modulator, influencing how existing
+    biases are amplified or dampened. This creates a dynamic internal state that
+    could conceptually influence attention, decision-making, or the interpretation
+    of new information in other parts of an AGI system.
+
+    The processor maintains a log of recorded experiences, serving as a form of
+    simulated experiential memory, limited by a configurable capacity.
+
+    Attributes:
+        memory_capacity (int or float): Maximum number of recorded experiences in `long_term_memory`.
+                                        Float('inf') for unlimited.
+        plasticity_range (Tuple[float, float]): Defines the (min, max) range for the random
+                                                 increment applied to synaptic weights during adaptation.
+        bias_increment (float): The base amount added to a token's cognitive bias upon
+                                 encountering it during bias evolution.
+        decay_rate (float): The exponential decay factor (0.0 to 1.0) applied to all
+                            cognitive biases over time or upon certain events (like emotion updates).
+        long_term_memory (List[Dict[str, Any]]): A chronological list of recorded experience entries.
+        synaptic_weights (Dict[str, float]): Simulated synaptic weights mapped to experience types.
+        cognitive_biases (Dict[str, float]): Simulated cognitive biases mapped to encountered tokens.
+    """
+
+    def __init__(
+        self,
+        memory_capacity: int = 200, # Increased default capacity
+        plasticity_range: Tuple[float, float] = (0.1, 0.4), # Slightly adjusted range
+        bias_increment: float = 0.08, # Slightly increased bias increment
+        decay_rate: float = 0.985 # Slightly adjusted decay rate
+    ):
+        """
+        Initializes the NeuroMemoryProcessor with its core configuration and internal states.
+
+        Args:
+          memory_capacity (int): Maximum number of entries in the recorded experience
+                                 log (`long_term_memory`). When capacity is finite
+                                 and exceeded, the oldest entry is evicted.
+                                 Defaults to 200. Set to 0 for conceptual unlimited capacity.
+          plasticity_range (Tuple[float, float]): A tuple defining the (minimum, maximum)
+                                                  range for the random value added to
+                                                  synaptic weights during adaptation, simulating
+                                                  the varying strength of neural connections.
+                                                  Defaults to (0.1, 0.4).
+          bias_increment (float): The fixed amount added to a token's cognitive
+                                  bias each time it is encountered during bias evolution,
+                                  simulating reinforcement of concepts. Defaults to 0.08.
+          decay_rate (float): The exponential decay factor (0.0 to 1.0) applied to all
+                              cognitive biases over time or upon updates. Values closer to 1.0
+                              result in slower decay. Defaults to 0.985.
+        """
+        if memory_capacity < 0:
+            logger.warning(f"Invalid memory_capacity ({memory_capacity}). Setting to default (200).")
+            self.memory_capacity: int = 200
+        elif memory_capacity == 0:
+            logger.info("Memory capacity set to unlimited (0).")
+            self.memory_capacity: float = float('inf') # Use infinity for conceptual unlimited
+        else:
+            self.memory_capacity: int = memory_capacity
+
+        # Validate and set plasticity_range
+        if not (isinstance(plasticity_range, tuple) and len(plasticity_range) == 2 and all(isinstance(x, (int, float)) for x in plasticity_range)):
+            logger.warning(f"Invalid plasticity_range format: {plasticity_range}. Setting to default (0.1, 0.4).")
+            self.plasticity_range: Tuple[float, float] = (0.1, 0.4)
+        else:
+             # Ensure min <= max and values are non-negative
+             min_inc, max_inc = sorted(plasticity_range) # Ensure order
+             self.plasticity_range: Tuple[float, float] = (max(0.0, min_inc), max(0.0, max_inc))
+             if self.plasticity_range != plasticity_range:
+                  logger.warning(f"Clamped invalid plasticity_range {plasticity_range} to {self.plasticity_range}.")
+
+
+        # Safely convert and set bias_increment and decay_rate
+        try:
+            self.bias_increment: float = max(0.0, float(bias_increment)) # Ensure non-negative
+            if float(bias_increment) < 0: logger.warning("bias_increment was negative, clamped to 0.0.")
+        except (ValueError, TypeError):
+            logger.warning(f"Invalid bias_increment ({bias_increment}). Setting to default (0.08).")
+            self.bias_increment: float = 0.08
+
+        try:
+            decay_rate_float = float(decay_rate)
+            # Ensure decay_rate is within the valid range [0.0, 1.0]
+            if not (0.0 <= decay_rate_float <= 1.0):
+                logger.warning(f"Decay rate ({decay_rate_float}) outside [0.0, 1.0] range. Clamping.")
+                self.decay_rate: float = max(0.0, min(1.0, decay_rate_float))
+            else:
+                self.decay_rate: float = decay_rate_float
+        except (ValueError, TypeError):
+            logger.warning(f"Invalid decay_rate ({decay_rate}). Setting to default (0.985).")
+            self.decay_rate: float = 0.985
+
+
+        # Initialize internal states
+        self.long_term_memory: List[Dict[str, Any]] = []
+        self.synaptic_weights: Dict[str, float] = {} # Default weight implicitly 1.0 on first access
+        self.cognitive_biases: Dict[str, float] = {} # Default bias implicitly 0.0 on first access
+
+        logger.info(f"NeuroMemoryProcessor initialized with capacity={self.memory_capacity if self.memory_capacity != float('inf') else 'Unlimited'}, plasticity={self.plasticity_range}, bias_inc={self.bias_increment:.3f}, decay={self.decay_rate:.3f}.")
+
+
+    def record_experience(self, kind: str, detail: str) -> Dict[str, Any]:
+        """
+        📝 Records a new experience event in the processor's experiential memory.
+        This acts as a fundamental input signal that triggers the simulation of
+        synaptic weight adaptation for the experience type and cognitive bias
+        evolution based on the experience's detail text. Enforces the memory capacity.
+
+        Args:
+            kind (str): The type of experience (e.g., "observation", "step", "emotion", "reflection").
+                        Used for synaptic weight adaptation.
+            detail (str): A textual description or content associated with the experience.
+                          Used for cognitive bias evolution.
+
+        Returns:
+            Dict[str, Any]: The dictionary representation of the stored experience entry.
+                            Returns an empty dict if the detail is empty after processing.
+        """
+        # Validate and clean inputs
+        if not isinstance(kind, str) or not kind.strip():
+            logger.warning(f"Attempted to record experience with invalid kind: '{kind}'. Using 'unknown_kind'.")
+            kind = "unknown_kind"
+        if not isinstance(detail, str):
+            logger.warning(f"Attempted to record experience with non-string detail (type: {type(detail)}). Converting to string.")
+            detail = str(detail)
+
+        # Do not record entries with empty detail after string conversion and stripping
+        if not detail.strip():
+            logger.debug(f"Skipping recording experience of kind '{kind}' with empty detail.")
+            return {} # Return empty dict if detail is empty
+
+
+        ts = datetime.utcnow().isoformat()
+        # Store a potentially truncated version of the detail for memory efficiency if it's very long
+        detail_stored = detail[:1500] + "..." if len(detail) > 1500 else detail # Increased stored detail length
+
+
+        entry = {"type": kind, "detail": detail_stored, "timestamp": ts}
+        self.long_term_memory.append(entry)
+
+        # Enforce memory capacity limit (if > 0 and finite)
+        if self.memory_capacity > 0 and self.memory_capacity != float('inf') and len(self.long_term_memory) > self.memory_capacity:
+            try:
+                dropped = self.long_term_memory.pop(0) # Remove the oldest entry
+                logger.debug(f"Memory full ({self.memory_capacity}). Evicted oldest: type='{dropped.get('type')}', detail='{dropped.get('detail', '')[:50]}...'")
+            except IndexError:
+                 # This case indicates a potential logic error if len > capacity but pop(0) fails
+                 logger.error("Attempted to pop from unexpectedly empty long_term_memory queue during capacity enforcement.")
+
+
+        # Trigger simulation updates based on this experience
+        # Use the original, potentially longer detail for bias evolution for more context
+        self._adapt_synaptic_weights(kind)
+        self._evolve_cognitive_bias(detail)
+
+        logger.debug(f"Recorded experience and triggered adaptation/evolution: type='{kind}', detail='{detail_stored[:50]}...'")
+
+        return entry
+
+    def _adapt_synaptic_weights(self, kind: str) -> None:
+        """
+        ⚙️ Simulates synaptic plasticity by increasing the weight associated with
+        a specific experience type (`kind`). This represents the strengthening
+        of neural pathways related to processing this type of information.
+        The increase amount is a random value within the defined `plasticity_range`.
+
+        Args:
+            kind (str): The type of experience whose synaptic weight should be adapted.
+        """
+        if not isinstance(kind, str) or not kind.strip():
+            logger.warning(f"Cannot adapt synaptic weight for invalid kind: '{kind}'. Skipping adaptation.")
+            return
+
+        # Ensure plasticity_range is valid and non-negative before using random.uniform
+        min_inc, max_inc = self.plasticity_range
+        # Ensure min <= max
+        if min_inc > max_inc:
+             logger.warning(f"Invalid plasticity_range {self.plasticity_range}: min > max. Swapping bounds.")
+             min_inc, max_inc = max_inc, min_inc
+        # Ensure bounds are non-negative
+        min_inc, max_inc = max(0.0, min_inc), max(0.0, max_inc)
+
+        # If range is still invalid (e.g., both bounds were negative), default to a small range
+        if max_inc < min_inc:
+             logger.warning(f"Plasticity range remained invalid after clamping: ({min_inc}, {max_inc}). Using default small range.")
+             min_inc, max_inc = (0.01, 0.05)
+
+
+        try:
+            # Generate random increment within the valid range
+            inc = random.uniform(min_inc, max_inc)
+            # Get current weight, default to 1.0 if not seen before (conceptually neutral baseline)
+            old_weight = self.synaptic_weights.get(kind, 1.0)
+            self.synaptic_weights[kind] = old_weight + inc
+            # Optional: Cap weights at a maximum value to prevent unbounded growth? (Not implemented here)
+            logger.debug(f"Adapted weight for '{kind}': {old_weight:.3f} → {self.synaptic_weights[kind]:.3f} (Increment: +{inc:.3f})")
+        except Exception as e:
+            logger.error(f"Error adapting synaptic weight for '{kind}' with range {self.plasticity_range}: {e}. Weight not updated.")
+
+
+    def _evolve_cognitive_bias(self, detail: str) -> None:
+        """
+        🧬 Simulates the evolution of cognitive biases linked to specific tokens
+        or concepts encountered in the detail text. This represents the AI becoming
+        more sensitive or predisposed towards concepts it encounters frequently.
+        Bias values increase upon encounter after a general decay is applied.
+
+        Note: This uses a simple space-based split and lowercasing for tokenization.
+        For a more sophisticated simulation, a proper NLP tokenizer and text
+        processing pipeline would be required.
+
+        Args:
+            detail (str): The text content used to evolve biases.
+        """
+        if not isinstance(detail, str) or not detail.strip():
+            logger.debug("Skipping cognitive bias evolution for empty detail text.")
+            return
+
+        # Apply decay to existing biases *before* reinforcing new ones
+        self._decay_biases()
+
+        # Use a basic space split for tokenization and lowercase as in original code
+        tokens = detail.lower().split()
+
+        if not tokens:
+            logger.debug("No tokens found in detail for bias evolution after splitting.")
+            return
+
+        reinforced_tokens_count = 0
+        for token in tokens:
+            # Basic cleaning for tokens (remove punctuation etc.) could be added here
+            # For now, stick to lower() and strip() as in the original code's spirit.
+            cleaned_token = token.strip()
+
+            if cleaned_token: # Ensure token is not just empty string after strip
+                # Increase the bias for the cleaned token
+                old_bias = self.cognitive_biases.get(cleaned_token, 0.0) # Start bias at 0.0
+                self.cognitive_biases[cleaned_token] = old_bias + self.bias_increment
+                # Optional: Cap bias value if needed (Not implemented here)
+                # logger.debug(f"Evolved bias for '{cleaned_token}': {old_bias:.3f} → {self.cognitive_biases[cleaned_token]:.3f} (+{self.bias_increment:.3f})") # Too verbose
+                reinforced_tokens_count += 1
+
+
+        logger.debug(f"Evolved biases for {reinforced_tokens_count} unique tokens from detail.")
+
+
+    def _decay_biases(self) -> None:
+        """
+        Applies an exponential decay to all existing cognitive biases based on
+        the configured `decay_rate`. This simulates the natural fading of biases
+        over time or processing cycles if they are not reinforced by new encounters.
+        Also removes biases that decay below a very small threshold.
+        Called internally by `_evolve_cognitive_bias` and `update_biases`.
+        """
+        # Create a list of items to decay to avoid changing dict size during iteration
+        biases_to_decay = list(self.cognitive_biases.items())
+        decayed_count = 0
+        removed_count = 0
+
+        if not biases_to_decay:
+             logger.debug("No cognitive biases to decay.")
+             return
+
+        for token, bias in biases_to_decay:
+            new_bias = bias * self.decay_rate
+            # Remove bias if its absolute value falls below a small threshold to keep the dictionary clean
+            if abs(new_bias) < 1e-9: # Use a very small threshold
+                if token in self.cognitive_biases: # Check exists before deleting (safety)
+                    del self.cognitive_biases[token]
+                    # logger.debug(f"Decayed and removed bias for '{token}' (was {bias:.6f}, now {new_bias:.6f})") # Too verbose
+                    removed_count += 1
+            else:
+                self.cognitive_biases[token] = new_bias
+                # logger.debug(f"Decayed bias for '{token}': {bias:.3f} → {new_bias:.3f}") # Too verbose
+                decayed_count += 1
+
+        # logger.debug(f"Decayed {decayed_count} cognitive biases. Removed {removed_count} low biases.") # Too verbose
+
+
+    def update_biases(self, emotion_data: Dict[str, Any]) -> None:
+        """
+        🔄 Integrates simulated emotional data into the cognitive bias landscape.
+        This method processes a given emotional state, records it as an experience
+        (triggering general bias evolution for the emotion words), and then
+        applies a combined amplification and decay factor to *all* existing
+        cognitive biases. Higher emotional intensity leads to stronger amplification,
+        while the decay rate still applies, making biases more volatile or reinforced
+        depending on the emotional state.
+
+        Args:
+            emotion_data (Dict[str, Any]): A dictionary containing emotional
+                                           information. Expected to have keys
+                                           'primary_emotion' (str) and 'intensity' (float).
+                                           Intensity is typically between 0.0 and 1.0.
+        """
+        # Validate input format
+        if not isinstance(emotion_data, dict):
+            logger.warning(f"Attempted to update biases with non-dictionary emotion_data (type: {type(emotion_data)}). Skipping update.")
+            return
+
+        # Safely get emotion kind and convert to string
+        emotion_kind = str(emotion_data.get("primary_emotion", "emotional_event")) # Default kind if missing
+
+        # Safely get and convert intensity, clamp to [0.0, 1.0]
+        try:
+            intensity = float(emotion_data.get("intensity", 0.0))
+            intensity = max(0.0, min(1.0, intensity)) # Clamp intensity
+        except (ValueError, TypeError):
+            intensity = 0.0
+            logger.warning(f"Invalid intensity value in emotion_data: {emotion_data.get('intensity')}. Using 0.0 for bias update.")
+
+        # Record the emotion event as a general experience.
+        # The detail includes intensity, which will cause bias evolution for "intensity", "0.XX" etc.
+        # The 'kind' is the emotion label itself. This will adapt synaptic weights for this emotion type.
+        emotion_detail_text = f"Simulated emotion '{emotion_kind}' intensity: {intensity:.2f}"
+        # Calling record_experience here logs the emotion event itself and triggers its contribution to biases and weights
+        self.record_experience(emotion_kind, emotion_detail_text)
+        logger.debug(f"Recorded emotion event for bias update: '{emotion_detail_text}'")
+
+
+        # Apply a combined decay and amplification factor to *all* existing cognitive biases.
+        # The amplification factor increases with intensity.
+        # Factor is 1.0 at intensity 0.0, up to 1.1 (or higher) at intensity 1.0.
+        # This factor is then multiplied by the general decay rate.
+        # A strong emotion makes biases more volatile or reinforced based on the base decay.
+        amplification_factor = (1.0 + 0.2 * intensity) # Slightly stronger potential amplification (up to 1.2)
+        decay_and_amplify_factor = amplification_factor * self.decay_rate
+
+        # Apply the factor to all existing biases. Iterate over a copy.
+        biases_to_update = list(self.cognitive_biases.items())
+        updated_count = 0
+        removed_count_during_update = 0
+
+        if not biases_to_update:
+             logger.debug("No cognitive biases to amplify/decay based on emotion.")
+             return
+
+        for token, bias in biases_to_update:
+            new_bias = bias * decay_and_amplify_factor
+            # Remove bias if its absolute value falls below a small threshold
+            if abs(new_bias) < 1e-9:
+                if token in self.cognitive_biases: # Safety check
+                    del self.cognitive_biases[token]
+                    removed_count_during_update += 1
+            else:
+                self.cognitive_biases[token] = new_bias
+                updated_count += 1
+
+        logger.info(f"Updated {updated_count} cognitive biases ({removed_count_during_update} removed) based on emotion '{emotion_kind}' (intensity {intensity:.2f}). Factor applied: {decay_and_amplify_factor:.3f}.")
+
+
+    def recall_biases(self, top_k: Optional[int] = None) -> Dict[str, float]:
+        """
+        🧠 Retrieves the current cognitive biases, sorted in descending order
+        by their strength (absolute value). Provides insight into the most
+        salient concepts or tokens in the AI's cognitive landscape.
+
+        Args:
+            top_k (Optional[int]): The maximum number of top biases (by absolute value)
+                                   to return. If None, return all biases above threshold.
+                                   Defaults to None.
+
+        Returns:
+            Dict[str, float]: A dictionary of cognitive biases, sorted by absolute value
+                              (descending). Returns an empty dictionary if no biases
+                              exist above the filtering threshold.
+        """
+        # Filter out any zero or near-zero biases before sorting using a small threshold
+        non_zero_biases = {tok: val for tok, val in self.cognitive_biases.items() if abs(val) > 1e-9}
+        # Sort by absolute value in descending order
+        sorted_biases = dict(sorted(non_zero_biases.items(), key=lambda item: -abs(item[1])))
+
+        if top_k is not None and top_k >= 0:
+            # Return a dictionary created from the slice of the sorted list
+            return dict(list(sorted_biases.items())[:top_k])
+        else:
+            return sorted_biases # Return all non-zero biases
+
+
+    def recall_weights(self, top_k: Optional[int] = None) -> Dict[str, float]:
+        """
+        🔧 Retrieves the current synaptic weights associated with experience types,
+        sorted in descending order by their value. Provides insight into which
+        types of experiences have most strongly shaped the simulated neural pathways.
+
+        Args:
+            top_k (Optional[int]): The maximum number of top weights to return.
+                                   If None, return all weights above threshold.
+                                   Defaults to None.
+
+        Returns:
+            Dict[str, float]: A dictionary of synaptic weights, sorted by value
+                              (descending). Returns an empty dictionary if no weights
+                              exist above the filtering threshold. Default weight is 1.0.
+        """
+        # Filter out any weights very close to the initial baseline (1.0) or zero
+        # Focus on weights that have significantly adapted
+        adapted_weights = {kind: val for kind, val in self.synaptic_weights.items() if abs(val - 1.0) > 1e-9 and abs(val) > 1e-9}
+        sorted_weights = dict(sorted(adapted_weights.items(), key=lambda item: -item[1]))
+
+        if top_k is not None and top_k >= 0:
+            # Return a dictionary created from the slice of the sorted list
+            return dict(list(sorted_weights.items())[:top_k])
+        else:
+            return sorted_weights # Return all adapted weights
+
+
+    def snapshot(self, top_k_biases: int = 10, top_k_weights: int = 5) -> Dict[str, Any]:
+        """
+        📊 Provides a quick snapshot summary of the NeuroMemoryProcessor's current
+        internal state, including the total count of recorded experiences and the
+        top (most prominent) cognitive biases and synaptic weights.
+
+        Args:
+            top_k_biases (int): Number of top biases (by absolute value) to include in the snapshot. Defaults to 10.
+            top_k_weights (int): Number of top weights to include in the snapshot. Defaults to 5.
+
+        Returns:
+            Dict[str, Any]: A dictionary containing the state snapshot summary.
+        """
+        # Ensure top_k values are non-negative
+        top_k_biases = max(0, top_k_biases)
+        top_k_weights = max(0, top_k_weights)
+
+        return {
+            "memory_count": len(self.long_term_memory),
+            "synaptic_weight_count": len(self.synaptic_weights), # Total count
+            "cognitive_bias_count": len(self.cognitive_biases), # Total count
+            "top_biases":   self.recall_biases(top_k=top_k_biases),
+            "top_weights":  self.recall_weights(top_k=top_k_weights)
+        }
+
+    def search_experiences(self, query: str, top_k: Optional[int] = None) -> List[Dict[str, Any]]:
+        """
+        🔍 Performs a simple case-insensitive keyword search over the 'detail'
+        field of recorded experiences stored in `long_term_memory`. Useful for
+        finding past events or information related to a specific query. Results
+        are returned in reverse chronological order (most recent matches first).
+
+        Args:
+            query (str): The keyword or phrase to search for (case-insensitive).
+            top_k (Optional[int]): The maximum number of matching entries to return.
+                                   If None, return all matches. Defaults to None.
+
+        Returns:
+            List[Dict[str, Any]]: A list of dictionaries representing the matching
+                                  experience entries. These are copies of the internal
+                                  memory entries. Returns an empty list if no
+                                  matches are found or if the query is invalid.
+        """
+        if not isinstance(query, str) or not query.strip():
+            logger.warning("Search query for experiences is empty or not a string. Returning empty list.")
+            return []
+
+        query_lower = query.lower()
+
+        # Filter and reverse for most recent first. Create copies of matches.
+        matches = [
+            e.copy() for e in reversed(self.long_term_memory)
+            if isinstance(e.get("detail"), str) and query_lower in e["detail"].lower()
+        ]
+
+        logger.debug(f"Search for '{query}' found {len(matches)} matches in recorded experiences.")
+
+        # Apply top_k limit to the found matches
+        return matches[:top_k] if top_k is not None and top_k >= 0 else matches
+
+
+    def export_state(self) -> str:
+        """
+        💾 Serializes the full current state of the NeuroMemoryProcessor, including
+        recorded experiences, synaptic weights, cognitive biases, and configuration
+        parameters, into a JSON formatted string. This allows for saving and
+        restoring the processor's dynamic state.
+
+        Returns:
+            str: A JSON string representing the processor state. Returns an empty JSON
+                 object string "{}" if serialization fails due to data types or other errors.
+        """
+        state = {
+            "long_term_memory":     self.long_term_memory,
+            "synaptic_weights":     self.synaptic_weights,
+            "cognitive_biases":     self.cognitive_biases,
+            # Include configuration parameters for reproducible state
+            "memory_capacity":      self.memory_capacity if isinstance(self.memory_capacity, int) else 0, # Store 0 if inf
+            "plasticity_range":     list(self.plasticity_range), # Convert tuple to list for JSON
+            "bias_increment":       self.bias_increment,
+            "decay_rate":           self.decay_rate
+        }
+        try:
+            # Use default=str to handle any non-serializable types by converting them to string
+            return json.dumps(state, indent=2, default=str)
+        except TypeError as e:
+            logger.error(f"Failed to serialize processor state to JSON (TypeError): {e}")
+            # Log a snippet of the problematic state
+            try:
+                 problem_state_snippet = json.dumps({k: str(v)[:150] + ('...' if len(str(v)) > 150 else '') for k, v in state.items()}, indent=2, default=str)
+                 logger.error("State causing error (snippet): %s", problem_state_snippet)
+            except:
+                 logger.error("Could not even serialize state snippet during error handling.")
+            return "{}" # Return empty JSON object on failure
+        except Exception as e:
+            logger.error(f"An unexpected error occurred during processor state export: {e}")
+            return "{}"
+
+
+    def import_state(self, blob: str) -> None:
+        """
+        📥 Loads the NeuroMemoryProcessor state from a JSON formatted string,
+        overwriting the current state. Includes comprehensive validation to ensure
+        data integrity and prevent errors from malformed input or mismatched types.
+
+        Args:
+            blob (str): A JSON string representing the processor state,
+                        expected to be in the format exported by `export_state`.
+                        If the blob is invalid or loading fails, the current
+                        state will remain unchanged.
+        """
+        if not isinstance(blob, str) or not blob.strip():
+            logger.warning("Attempted to import empty or non-string JSON blob for processor state. Skipping import.")
+            return
+
+        try:
+            data = json.loads(blob)
+
+            # Validate the loaded state structure
+            if not isinstance(data, dict):
+                logger.error("Processor state import failed: Loaded data is not a dictionary. Expected state object.")
+                return
+
+            # --- Safely load primary state attributes ---
+            # Temporarily hold loaded data while validating types
+            loaded_memory = data.get("long_term_memory", [])
+            if not isinstance(loaded_memory, list):
+                logger.warning("Processor import warning: 'long_term_memory' was not a list. Initializing as empty.")
+                loaded_memory = []
+
+            loaded_weights = data.get("synaptic_weights", {})
+            if not isinstance(loaded_weights, dict):
+                logger.warning("Processor import warning: 'synaptic_weights' was not a dict. Initializing as empty.")
+                loaded_weights = {}
+             # Optional: Add type check for values (ensure they are float/int)
+
+            loaded_biases = data.get("cognitive_biases", {})
+            if not isinstance(loaded_biases, dict):
+                logger.warning("Processor import warning: 'cognitive_biases' was not a dict. Initializing as empty.")
+                loaded_biases = {}
+            # Optional: Add type check for values (ensure they are float/int)
+
+
+            # --- Safely import configuration parameters ---
+            # Handle potential infinity value stored as 0 during export
+            imported_capacity = data.get("memory_capacity", self.memory_capacity)
+            if imported_capacity == 0: # Check if it was exported as 0 (for inf)
+                 loaded_capacity = float('inf')
+            elif isinstance(imported_capacity, int) and imported_capacity > 0:
+                 loaded_capacity = imported_capacity
+            else:
+                 logger.warning(f"Processor import warning: Invalid memory_capacity '{imported_capacity}'. Keeping current value {self.memory_capacity}.")
+                 loaded_capacity = self.memory_capacity # Keep current if invalid
+
+
+            imported_plasticity = data.get("plasticity_range", self.plasticity_range)
+            if isinstance(imported_plasticity, list) and len(imported_plasticity) == 2 and all(isinstance(x, (int, float)) for x in imported_plasticity):
+                 loaded_plasticity = tuple(imported_plasticity) # Convert list back to tuple
+            else:
+                 logger.warning(f"Processor import warning: Invalid plasticity_range '{imported_plasticity}'. Keeping current value {self.plasticity_range}.")
+                 loaded_plasticity = self.plasticity_range # Keep current if invalid
+
+
+            # Safely convert and set scalar parameters
+            try:
+                 imported_bias_inc = float(data.get("bias_increment", self.bias_increment))
+                 loaded_bias_inc = max(0.0, imported_bias_inc) # Ensure non-negative
+                 if imported_bias_inc < 0: logger.warning("Imported bias_increment was negative, clamped to 0.0.")
+            except (ValueError, TypeError):
+                 logger.warning(f"Processor import warning: Invalid bias_increment '{data.get('bias_increment', 'N/A')}'. Keeping current value {self.bias_increment}.")
+                 loaded_bias_inc = self.bias_increment # Keep current if invalid
+
+            try:
+                 imported_decay = float(data.get("decay_rate", self.decay_rate))
+                 if not (0.0 <= imported_decay <= 1.0):
+                      logger.warning(f"Processor import warning: Decay rate '{imported_decay}' outside [0.0, 1.0]. Clamping.")
+                      loaded_decay = max(0.0, min(1.0, imported_decay))
+                 else:
+                      loaded_decay = imported_decay
+            except (ValueError, TypeError):
+                 logger.warning(f"Processor import warning: Invalid decay_rate '{data.get('decay_rate', 'N/A')}'. Keeping current value {self.decay_rate}.")
+                 loaded_decay = self.decay_rate # Keep current if invalid
+
+
+            # --- Assign validated/loaded data to self ---
+            self.long_term_memory = loaded_memory
+            self.synaptic_weights = loaded_weights
+            self.cognitive_biases = loaded_biases
+            self.memory_capacity = loaded_capacity
+            self.plasticity_range = loaded_plasticity
+            self.bias_increment = loaded_bias_inc
+            self.decay_rate = loaded_decay
+
+            logger.info(f"📥 NeuroMemoryProcessor state imported successfully. Loaded {len(self.long_term_memory)} experiences.")
+
+        except json.JSONDecodeError as e:
+            logger.error(f"Processor state import failed: Invalid JSON format in blob: {e}")
+        except Exception as e:
+            logger.error(f"An unexpected error occurred during processor state import processing: {e}")
+
+
+    # ─── Private helpers ─────────────────────────────────────
+
+    # No _decode_input or _default_summarizer here, those belong to MemoryEngine
+
+    def _decay_biases(self) -> None:
+        """
+        Applies an exponential decay to all existing cognitive biases based on
+        the configured `decay_rate`. This simulates the natural fading of biases
+        over time or processing cycles if they are not reinforced by new encounters.
+        Also removes biases that decay below a very small threshold to manage memory.
+        Called internally by `_evolve_cognitive_bias` and `update_biases`.
+        """
+        # Create a list of items to decay to avoid changing dict size during iteration
+        biases_to_decay = list(self.cognitive_biases.items())
+        # logger.debug(f"Starting bias decay. Initial bias count: {len(biases_to_decay)}") # Too verbose
+
+        if not biases_to_decay:
+             # logger.debug("No cognitive biases to decay.") # Too verbose
+             return
+
+        removed_count = 0
+        for token, bias in biases_to_decay:
+            new_bias = bias * self.decay_rate
+            # Remove bias if its absolute value falls below a small threshold
+            if abs(new_bias) < 1e-9: # Use a very small threshold
+                if token in self.cognitive_biases: # Safety check
+                    del self.cognitive_biases[token]
+                    removed_count += 1
+            else:
+                self.cognitive_biases[token] = new_bias
+                # logger.debug(f"Decayed bias for '{token}': {bias:.3f} → {new_bias:.3f}") # Too verbose
+
+        # if removed_count > 0:
+             # logger.debug(f"Bias decay complete. Removed {removed_count} low biases.") # Too verbose
+
+
+# Example Usage (Illustrative)
+if __name__ == "__main__":
+    print("--- NeuroMemoryProcessor Example Usage ---")
+    # Set logger level to DEBUG for this specific example run
+    logging.basicConfig(level=logging.DEBUG, format='%(asctime)s - %(name)s - %(levelname)s - %(message)s')
+    logger.setLevel(logging.DEBUG) # Ensure this logger also uses DEBUG
+
+    # Test with specific parameters
+    processor = NeuroMemoryProcessor(memory_capacity=10, plasticity_range=(0.1, 0.5), bias_increment=0.1, decay_rate=0.9) # Adjusted params for demo
+
+    # Simulate recording various types of experiences
+    print("\n--- Recording Experiences ---")
+    processor.record_experience("observation", "User asked about a complex system.")
+    processor.record_experience("step", "Initiated problem decomposition.")
+    processor.record_experience("step", "Retrieved relevant data nodes.")
+    processor.record_experience("emotion", "curiosity", {"primary_emotion": "curiosity", "intensity": 0.8}) # Simulate emotion event
+    processor.record_experience("observation", "Received feedback indicating a potential misinterpretation.")
+    processor.record_experience("step", "Adjusted the interpretation model based on feedback.")
+    processor.record_experience("metric", "validation_score", 0.75) # Simulate metric recording
+    processor.record_experience("reflection", "Synthesized insights from recent interactions.") # Simulate reflection event
+
+    # Exceed memory capacity slightly
+    processor.record_experience("observation", "Processing follow-up question.")
+    processor.record_experience("step", "Initiating sub-problem analysis.")
+    processor.record_experience("step", "Consulting long-term memory for similar patterns.") # Should cause eviction
+
+
+    print("\n--- Recorded Experiences (most recent 10, ordered by recency) ---")
+    # Using search_experiences with no query effectively gets all recent experiences
+    all_experiences = processor.search_experiences("", top_k=processor.memory_capacity) # Get up to memory capacity
+    for i, entry in enumerate(all_experiences):
+           # Format timestamp for display
+           ts_formatted = entry.get('timestamp', 'N/A')
+           if ts_formatted != 'N/A':
+                try:
+                     ts_formatted = datetime.fromisoformat(ts_formatted.replace('Z', '+00:00')).strftime('%Y-%m-%d %H:%M:%S')
+                except ValueError:
+                     pass # Keep original if formatting fails
+           print(f"{i+1}: [{ts_formatted}] {entry.get('type', 'N/A').upper()}: {entry.get('detail', 'N/A')[:80]}...")
+
+
+    print("\n--- Snapshot ---")
+    snapshot_data = processor.snapshot(top_k_biases=10, top_k_weights=5)
+    import json
+    print(json.dumps(snapshot_data, indent=2))
+
+    print("\n--- Recalled Biases (All) ---")
+    print(json.dumps(processor.recall_biases(), indent=2))
+
+    print("\n--- Recalled Weights (All) ---")
+    print(json.dumps(processor.recall_weights(), indent=2))
+
+    print("\n--- Search Experiences ('feedback') ---")
+    search_results = processor.search_experiences("feedback")
+    print(json.dumps(search_results, indent=2))
+
+    # Simulate emotion update again to see decay and amplification effects
+    print("\n--- Updating Biases with Emotion (Satisfaction, High Intensity) ---")
+    processor.update_biases({"primary_emotion": "satisfaction", "intensity": 0.9})
+    print("\n--- Recalled Biases after Emotion Update ---")
+    print(json.dumps(processor.recall_biases(top_k=15), indent=2)) # Show more biases to see decay/amplification
+
+    print("\n--- Updating Biases with Emotion (Melancholy, Moderate Intensity) ---")
+    processor.update_biases({"primary_emotion": "melancholy", "intensity": 0.6})
+    print("\n--- Recalled Biases after Second Emotion Update ---")
+    print(json.dumps(processor.recall_biases(top_k=15), indent=2)) # Show more biases to see effects
+
+
+    # Simulate export and import
+    print("\n--- Exporting State ---")
+    exported_json = processor.export_state()
+    print(exported_json[:1000] + "..." if len(exported_json) > 1000 else exported_json) # Print snippet
+
+    print("\n--- Importing State into New Processor ---")
+    # Use different init values to show they are overridden by import
+    new_processor = NeuroMemoryProcessor(memory_capacity=50, plasticity_range=(0.05, 0.2), bias_increment=0.01, decay_rate=0.99)
+    print(f"\nNew processor initial capacity: {new_processor.memory_capacity}") # Show initial state
+    print(f"New processor initial plasticity: {new_processor.plasticity_range}")
+
+    new_processor.import_state(exported_json)
+
+    print("\n--- New Processor Snapshot (After Import) ---")
+    snapshot_after_import = new_processor.snapshot(top_k_biases=10, top_k_weights=5)
+    print(json.dumps(snapshot_after_import, indent=2))
+    print(f"\nNew processor loaded capacity: {new_processor.memory_capacity}") # Show loaded state
+    print(f"New processor loaded plasticity: {new_processor.plasticity_range}")
+    print(f"New processor loaded bias increment: {new_processor.bias_increment}")
+    print(f"New processor loaded decay rate: {new_processor.decay_rate}")
+
+
+    print("\n--- New Processor Recalled Biases (After Import) ---")
+    print(json.dumps(new_processor.recall_biases(top_k=15), indent=2))
+
+
+    print("\n--- Example Usage End ---")

SimulatedSelfAssessment.py

@@ -0,0 +1,398 @@
+# SimulatedSelfAssessment.py
+# FINAL AGI Self-Model — Conceptual Self-Assessment and Prompt-Engineered State Synthesis (Robust)
+
+import logging
+import time
+import random
+from datetime import datetime
+from typing import Any, Dict, List, Optional, Union, Tuple
+from collections import Counter
+import math
+
+# --- Logging Setup ---
+logger = logging.getLogger(__name__)
+if not logger.handlers:
+    handler = logging.StreamHandler()
+    formatter = logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - %(message)s')
+    handler.setFormatter(formatter)
+    logger.addHandler(handler)
+    logger.propagate = False
+logger.setLevel(logging.INFO) # Default level (can be set to DEBUG in wrapper/GUI for more detail)
+
+
+class SimulatedSelfAssessment:
+    """
+    📈📊🧠 SimulatedSelfAssessment: The AGI's Conceptual Self-State Synthesizer (Robust Final)
+
+    This module is the conceptual core for the AI's simulated self-monitoring.
+    It synthesizes data snapshots from other core modules representing different
+    facets of the AGI simulation (Memory, Bias/Neuroplasticity, Sentience/Emotion).
+    Its primary function is to generate a detailed, prompt-friendly text summary
+    of the AI's perceived internal state, conceptual coherence, and simulated
+    'well-being' within the simulation framework.
+
+    This version includes enhanced robustness checks to handle potential issues
+    with input data (e.g., None, unexpected types, empty containers) coming from
+    other modules, aiming to prevent internal errors and ensure a graceful output
+    even in unexpected states.
+
+    It is crucial to understand: This module *does not* create true consciousness
+    or subjective experience. Its purpose is to produce structured textual input
+    ('prompt engineering') that the main language model can interpret. By providing
+    a description of its 'internal state,' the language model can generate output
+    that *simulates* deep introspection, self-awareness, and integrated thought.
+
+    Attributes:
+        _last_assessment_time (float): Timestamp (Unix epoch) of the most recent assessment.
+        _coherence_score (float): Simulated conceptual internal harmony (0.0 to 1.0).
+        _well_being_index (float): Simulated conceptual state of 'well-being' (0.0 to 1.0).
+        _conceptual_state_summary (str): Detailed text summary for prompt injection.
+        _dominant_internal_signals (Dict[str, Union[str, float]]): Highlights key
+                                    simulated internal drivers or states.
+    """
+
+    def __init__(self):
+        """
+        Initializes the SimulatedSelfAssessment module with default neutral states.
+        """
+        self._last_assessment_time: float = time.time()
+        self._coherence_score: float = 0.5
+        self._well_being_index: float = 0.5
+        # Initial state summary should be informative but indicate no data processed yet
+        self._conceptual_state_summary: str = "--- Simulated Internal State Assessment (Initializing) ---\nAssessment systems starting up. Waiting for initial data from core modules."
+        self._dominant_internal_signals: Dict[str, Union[str, float]] = {}
+
+        logger.info("SimulatedSelfAssessment module initialized to a neutral, waiting state.")
+
+    def perform_assessment(
+        self,
+        recent_reflections: Optional[List[str]] = None, # Made Optional
+        top_biases: Optional[Dict[str, float]] = None, # Made Optional
+        synaptic_weights_snapshot: Optional[Dict[str, float]] = None, # Made Optional
+        current_emotions: Optional[Dict[str, float]] = None, # Made Optional
+        intent_pool: Optional[List[str]] = None, # Made Optional
+        trace_summary: Optional[List[str]] = None, # Made Optional
+        qri_snapshot: Optional[Dict[str, Union[float, Dict[str, float]]]] = None # Remains Optional
+    ) -> Dict[str, Union[float, str, Dict[str, Any]]]:
+        """
+        Executes the simulated self-assessment process with high robustness to input variations.
+        Synthesizes data snapshots from conceptual modules to update scores and generate
+        a detailed, prompt-optimized text summary of the AI's simulated state.
+
+        Args:
+            recent_reflections (Optional[List[str]]): Summaries of recent reflections. Defaults to None.
+            top_biases (Optional[Dict[str, float]]): Top cognitive biases. Defaults to None.
+            synaptic_weights_snapshot (Optional[Dict[str, float]]): Snapshot of weights. Defaults to None.
+            current_emotions (Optional[Dict[str, float]]): Current simulated emotions. Defaults to None.
+            intent_pool (Optional[List[str]]): Current intentions. Defaults to None.
+            trace_summary (Optional[List[str]]): Summary or snippet of recent trace. Defaults to None.
+            qri_snapshot (Optional[Dict[str, Union[float, Dict[str, float]]]]): Optional QRI snapshot. Defaults to None.
+
+        Returns:
+            Dict[str, Union[float, str, Dict[str, Any]]]: A dictionary containing
+                                          conceptual scores, the prompt-optimized
+                                          state summary, and dominant internal signals.
+                                          Returns a 'Failed Assessment' state if an
+                                          unexpected error occurs during processing.
+        """
+        logger.debug("Attempting simulated self-assessment synthesis...")
+        current_assessment_time = time.time() # Capture start time
+
+        # --- Input Validation and Defaulting (Enhanced Robustness) ---
+        # Explicitly check for None and ensure inputs are in expected formats or default gracefully.
+        reflections_data = recent_reflections if isinstance(recent_reflections, list) else []
+        biases_data = top_biases if isinstance(top_biases, dict) else {}
+        weights_data = synaptic_weights_snapshot if isinstance(synaptic_weights_snapshot, dict) else {}
+        emotions_data = current_emotions if isinstance(current_emotions, dict) else {}
+        intents_data = intent_pool if isinstance(intent_pool, list) else []
+        trace_data = trace_summary if isinstance(trace_summary, list) else []
+        qri_data = qri_snapshot if isinstance(qri_snapshot, dict) else None # QRI can be None or dict
+
+
+        # --- Internal Error Handling for Synthesis Logic ---
+        # Wrap the core processing in a try-except block to catch unexpected errors
+        # that the input checks might miss.
+        try:
+            # --- Simulate Synthesis Logic: Identify Conceptual Drivers from Input Data ---
+
+            # Analyze Reflection Landscape
+            reflection_count = len(reflections_data)
+            reflection_depth_cue = "Deeply introspective state" if reflection_count > 5 else ("Moderately reflective" if reflection_count > 2 else "Reflection on recent experience is minimal")
+
+            # Analyze Bias Landscape (Robust checks used on biases_data)
+            bias_count = len(biases_data)
+            bias_strength_sum = sum(abs(b) for b in biases_data.values() if isinstance(b, (int, float))) # Sum only valid numeric values
+            bias_state_cue = "A complex interplay of conceptual biases is currently active" if bias_count > 10 else ("Several prominent biases influence cognitive processing" if bias_count > 3 else "Few strong conceptual biases are currently dominant")
+            bias_tone_cue = "Bias landscape is conceptually quiet" # Default if no biases
+            if bias_count > 0:
+                # Safely calculate average, handle case with non-numeric values filtered out
+                numeric_bias_values = [b for b in biases_data.values() if isinstance(b, (int, float))]
+                if numeric_bias_values:
+                     average_bias_value = sum(numeric_bias_values) / len(numeric_bias_values)
+                     bias_tone_cue = "leaning towards positive conceptual reinforcement" if average_bias_value > 0.2 else ("exhibiting conceptual caution" if average_bias_value < -0.2 else "maintaining a relatively neutral conceptual stance")
+                else:
+                     bias_tone_cue = "Bias landscape has non-numeric values" # Or handle as an error state if preferred
+
+
+            # Analyze Synaptic Weight Landscape (Robust checks used on weights_data)
+            weight_count = len(weights_data)
+            # Sum only valid numeric weights > 1.0 for adapted strength
+            adapted_weight_strength = sum((w - 1.0) for w in weights_data.values() if isinstance(w, (int, float)) and w > 1.0)
+            learning_state_cue = "Recent experiences have significantly shaped simulated cognitive pathways" if weight_count > 10 or adapted_weight_strength > 5.0 else ("Simulated cognitive structure is actively adapting" if weight_count > 3 else "Simulated neural pathways appear stable")
+
+
+            # Analyze Emotional Landscape (Robust checks used on emotions_data)
+            emotion_count = len(emotions_data)
+            # Filter for active emotions (numeric values > 0.3)
+            active_emotions = {k: v for k, v in emotions_data.items() if isinstance(v, (int, float)) and v > 0.3}
+            active_emotion_count = len(active_emotions)
+            emotional_state_cue = "Simulated emotional landscape is calm" # Default if no active emotions
+            most_intense_emotion_cue = "Simulated emotional state is currently quiescent." # Default cue
+            if active_emotion_count > 0:
+                emotional_state_cue = "A rich spectrum of simulated feelings is present" if active_emotion_count > 3 else "Simulated emotions are focused"
+                # Safely find most intense emotion
+                most_intense_emotion_item = max(active_emotions.items(), key=lambda item: item[1])
+                most_intense_emotion_cue = f"Dominant simulated feeling: '{most_intense_emotion_item[0].replace('_', ' ').capitalize()}' (Intensity {most_intense_emotion_item[1]:.2f})."
+
+
+            # Analyze Intent Landscape
+            intent_count = len(intents_data)
+            intent_state_cue = "Simulated purposeful drive is active with clear intentions" if intent_count > 2 else ("A core intention guides simulated focus" if intent_count > 0 else "Simulated purpose is currently undefined or dormant")
+
+            # Analyze Operational Trace
+            trace_count = len(trace_data)
+            operational_cue = "Simulated operational flow is active and being logged" if trace_count > 5 else "Simulated operational trace is light"
+
+            # Analyze QRI Snapshot (Robust checks used on qri_data)
+            qri_summary_cue = "Conceptual Resonance Index (QRI) data not available for assessment."
+            qri_composite = None
+            if qri_data: # Check if qri_data is not None or empty dict
+                 qri_composite = qri_data.get("composite_score")
+                 if isinstance(qri_composite, (int, float)): # Check if composite score is numeric
+                     qri_dimensions = qri_data.get("dimensions", {})
+                     qri_summary_cue = f"Conceptual Resonance Index (QRI) measured at {qri_composite:.2f}."
+                     if qri_composite > 0.6: # High resonance cue
+                         # Check if dimensions is a dict and values are numeric before iterating
+                         resonant_dims = [dim.capitalize() for dim, score in qri_dimensions.items() if isinstance(qri_dimensions, dict) and isinstance(score, (int, float)) and score > 0.7]
+                         qri_summary_cue += f" High resonance detected." + (f" Strongest in: {', '.join(resonant_dims)}." if resonant_dims else "")
+                     elif qri_composite < 0.4: # Low resonance cue
+                         qri_summary_cue += f" Low resonance detected."
+                     else:
+                         qri_summary_cue += f" Moderate resonance detected."
+
+
+            # --- Simulate Score Calculation (Influenced by Conceptual Cues) ---
+            # Calculate scores based on the derived qualitative cues.
+
+            coherence_cue_values = {
+                "Deeply introspective state": 1.0, "Moderately reflective": 0.7, "Reflection on recent experience is minimal": 0.3,
+                "A complex interplay of conceptual biases is currently active": 0.6, "Several prominent biases influence cognitive processing": 0.8, "Few strong conceptual biases are currently dominant": 0.9, "Bias landscape is conceptually quiet": 1.0,
+                "leaning towards positive conceptual reinforcement": 0.8, "exhibiting conceptual caution": 0.6, "maintaining a relatively neutral conceptual stance": 1.0,
+                "Recent experiences have significantly shaped simulated cognitive pathways": 0.7, "Simulated cognitive structure is actively adapting": 0.9, "Simulated neural pathways appear stable": 1.0,
+                "Simulated purposeful drive is active with clear intentions": 1.0, "A core intention guides simulated focus": 0.8, "Simulated purpose is currently undefined or dormant": 0.4
+            }
+            # Use the cues to get corresponding numerical values
+            coherence_inputs_values = [
+                 coherence_cue_values.get(reflection_depth_cue, 0.5), # Use .get() with default for safety
+                 coherence_cue_values.get(bias_state_cue, 0.5),
+                 coherence_cue_values.get(bias_tone_cue, 0.5),
+                 coherence_cue_values.get(learning_state_cue, 0.5),
+                 coherence_cue_values.get(intent_state_cue, 0.5)
+            ]
+            # Calculate average, handle empty list of inputs if needed (though unlikely with defaults)
+            self._coherence_score = sum(coherence_inputs_values) / len(coherence_inputs_values) if coherence_inputs_values else 0.5
+
+
+            well_being_cue_values = {
+                "A rich spectrum of simulated feelings is present": 0.6, "Simulated emotions are focused": 0.8, "Simulated emotional landscape is calm": 1.0,
+                 # Map specific dominant emotion cue string to its value
+                "Dominant simulated feeling: 'Joy'": 1.0, "Dominant simulated feeling: 'Curiosity'": 0.9, "Dominant simulated feeling: 'Excitement'": 0.9,
+                "Dominant simulated feeling: 'Serenity'": 1.0, "Dominant simulated feeling: 'Wonder'": 0.9,
+                "Dominant simulated feeling: 'Concern'": 0.4, "Dominant simulated feeling: 'Melancholy'": 0.3, "Dominant simulated feeling: 'Fear'": 0.2, "Dominant simulated feeling: 'Guilt'": 0.1,
+                "Simulated emotional state is currently quiescent.": 0.8,
+                "Simulated purposeful drive is active with clear intentions": 1.0, "A core intention guides simulated focus": 0.8, "Simulated purpose is currently undefined or dormant": 0.4,
+                "leaning towards positive conceptual reinforcement": 1.0, "exhibiting conceptual caution": 0.6, "maintaining a relatively neutral conceptual stance": 0.8
+            }
+            # Get the value for the dominant emotion cue string, default to 0.5 if cue not found
+            dominant_emotion_value = well_being_cue_values.get(most_intense_emotion_cue, 0.5)
+
+            well_being_inputs_values = [
+                 well_being_cue_values.get(emotional_state_cue, 0.5),
+                 dominant_emotion_value, # Use the value derived from the dominant emotion cue
+                 well_being_cue_values.get(intent_state_cue, 0.5),
+                 well_being_cue_values.get(bias_tone_cue, 0.5)
+            ]
+            # If QRI composite is available and valid, add it as an influence
+            if isinstance(qri_composite, (int, float)):
+                well_being_inputs_values.append(qri_composite)
+
+            self._well_being_index = sum(well_being_inputs_values) / len(well_being_inputs_values) if well_being_inputs_values else 0.5
+
+
+            # Clamp scores to [0.0, 1.0]
+            self._coherence_score = max(0.0, min(1.0, self._coherence_score))
+            self._well_being_index = max(0.0, min(1.0, self._well_being_index))
+
+
+            # --- Generate Detailed Prompt-Engineered State Summary Text ---
+            # This is the primary output for prompt injection.
+            # Use consistent formatting and keywords.
+            summary_lines = [
+                f"--- Simulated Internal State Assessment (Timestamp: {datetime.utcnow().isoformat()}) ---",
+                f"Conceptual Coherence: {self._coherence_score:.2f} ({reflection_depth_cue}, {bias_state_cue}, {learning_state_cue}).",
+                f"Simulated Well-being: {self._well_being_index:.2f} ({emotional_state_cue}, {intent_state_cue}).",
+                f"Internal Biases: {bias_count} active conceptual biases detected. Cognitive landscape is {bias_tone_cue}." + (f" Top influencing biases include: {list(biases_data.keys())[:5]}." if biases_data else ""), # Use biases_data after validation
+                f"Memory & Learning: {reflection_count} recent conceptual reflections synthesized. Simulated cognitive structure adapting based on {weight_count} experience types." + (f" Key shaping experiences noted: {list(weights_data.keys())[:3]}." if weights_data else ""), # Use weights_data
+                f"Emotional Resonance: {active_emotion_count} simulated emotions are active." + (f" {most_intense_emotion_cue}" if active_emotion_count > 0 else " Simulated emotional state is currently quiescent."),
+                f"Intent & Purpose: {intent_count} active simulated intentions detected." + (f" {intent_state_cue}." if intent_count > 0 else " Simulated purpose is currently undefined or dormant."),
+                f"Operational Context: {trace_count} recent simulated operational trace entries logged." + (f" {operational_cue}." if trace_count > 0 else " Simulated operational trace is light."),
+                qri_summary_cue, # Include the QRI summary line
+                "Analyzing the interplay of these simulated conceptual signals and their influence on the AI's ongoing process..." # Concluding introspective cue
+            ]
+            self._conceptual_state_summary = "\n".join(summary_lines)
+
+
+            # --- Identify Dominant Internal Signals for Focused Prompting ---
+            # Highlight the most conceptually significant aspects.
+            self._dominant_internal_signals = {}
+            # Add extreme scores as signals
+            if self._coherence_score > 0.85: self._dominant_internal_signals['High Conceptual Coherence'] = self._coherence_score
+            if self._well_being_index > 0.85: self._dominant_internal_signals['High Simulated Well-being'] = self._well_being_index
+            if self._coherence_score < 0.15: self._dominant_internal_signals['Low Conceptual Coherence'] = self._coherence_score
+            if self._well_being_index < 0.15: self._dominant_internal_signals['Low Simulated Well-being'] = self._well_being_index
+
+            # Add dominant conceptual drivers as signals if they are notable
+            if reflection_count > 7: self._dominant_internal_signals['Deep Reflection Active'] = reflection_count
+            if bias_count > 15: self._dominant_internal_signals['Very Complex Biases'] = bias_count
+            # Add signal if bias tone is strongly positive or negative (check bias_count > 0)
+            if bias_count > 0:
+                 numeric_bias_values = [b for b in biases_data.values() if isinstance(b, (int, float))]
+                 if numeric_bias_values:
+                     average_bias_value = sum(numeric_bias_values) / len(numeric_bias_values)
+                     if average_bias_value > 0.4: self._dominant_internal_signals[f'Strong Positive Bias Tone ({bias_tone_cue})'] = average_bias_value
+                     if average_bias_value < -0.4: self._dominant_internal_signals[f'Strong Negative Bias Tone ({bias_tone_cue})'] = average_bias_value
+
+            if adapted_weight_strength > 10.0: self._dominant_internal_signals['Significant Cognitive Shaping'] = adapted_weight_strength
+            if active_emotion_count > 6: self._dominant_internal_signals[f'Numerous Active Emotions ({active_emotion_count})'] = max(active_emotions.values()) if active_emotions else 0.0 # Use active_emotions
+            # Signal high intensity dominant feeling only if it exists and is strong
+            if active_emotion_count > 0 and most_intense_emotion_item and most_intense_emotion_item[1] > 0.7:
+                 signal_label = most_intense_emotion_cue.replace("Dominant simulated feeling: '", "Dominant Feeling: ").replace("'", "").replace(" (Intensity ", " (Int ") # Shorter label
+                 self._dominant_internal_signals[signal_label] = most_intense_emotion_item[1]
+            if intent_count >= 4: self._dominant_internal_signals['Clear Simulated Intentions'] = intent_count
+            if isinstance(qri_composite, (int, float)):
+                if qri_composite > 0.75: self._dominant_internal_signals['High Conceptual Resonance (QRI)'] = qri_composite
+                if qri_composite < 0.25: self._dominant_internal_signals['Low Conceptual Resonance (QRI)'] = qri_composite
+
+            logger.info(f"Simulated self-assessment successful. Coherence: {self._coherence_score:.2f}, Well-being: {self._well_being_index:.2f}.")
+            self._last_assessment_time = current_assessment_time # Only update timestamp on success
+
+        except Exception as e:
+            # --- Handle Internal Assessment Errors Gracefully ---
+            # Catch any unexpected errors during the synthesis process.
+            error_time = time.time()
+            error_message = f"An unexpected error occurred during simulated self-assessment synthesis at {datetime.utcnow().isoformat()}. Details: {e}"
+            logger.error(error_message, exc_info=True) # Log the full traceback internally
+
+            # Update state to reflect the assessment failure conceptually
+            self._coherence_score = max(0.0, self._coherence_score - 0.1) # Conceptually reduce coherence slightly on error
+            self._well_being_index = max(0.0, self._well_being_index - 0.1) # Conceptually reduce well-being slightly on error
+            self._conceptual_state_summary = f"--- Simulated Internal State Assessment (Error) ---\nAssessment process encountered an internal issue at {datetime.utcnow().isoformat()}. Current simulated state is uncertain. Error details: {e}\n--- Please review logs for full traceback. ---"
+            self._dominant_internal_signals = {"Assessment Error": str(e)[:100]} # Note the error in signals
+
+            logger.warning("Simulated self-assessment failed internally. State updated to reflect error.")
+
+        # Return the detailed results, whether success or failure state
+        return {
+            "coherence_score": self._coherence_score,
+            "well_being_index": self._well_being_index,
+            "state_summary": self._conceptual_state_summary, # This is the main output for the prompt
+            "dominant_internal_signals": self._dominant_internal_signals
+        }
+
+    def get_last_assessment(self) -> Dict[str, Union[float, str, Dict[str, Any]]]:
+        """
+        Retrieves the results of the most recent simulated self-assessment.
+        Useful for logging or displaying the last known internal state.
+
+        Returns:
+            Dict[str, Union[float, str, Dict[str, Any]]]: A dictionary containing the last
+                                          conceptual scores, state summary, and dominant signals.
+                                          Includes the error state if the last assessment failed.
+        """
+        return {
+            "coherence_score": self._coherence_score,
+            "well_being_index": self._well_being_index,
+            "state_summary": self._conceptual_state_summary,
+            "dominant_internal_signals": self._dominant_internal_signals
+        }
+
+# Example Usage (Illustrative - requires conceptual data structures)
+if __name__ == "__main__":
+    print("--- SimulatedSelfAssessment Example Usage ---")
+    # Configure logging for the example run
+    logging.basicConfig(level=logging.DEBUG, format='%(asctime)s - %(name)s - %(levelname)s - %(message)s')
+    logger.setLevel(logging.DEBUG) # Set to DEBUG to see internal logger.debug and error messages
+
+    assessment_module = SimulatedSelfAssessment()
+
+    # --- Simulate Data Snapshots from Other Modules ---
+    # These are simplified dictionaries/lists representing the *output*
+    # or state snapshots you would get from your other initialized modules.
+
+    # Scenario 1: Relatively balanced, positive state
+    sim_refl_1 = ["Reflection on recent progress.", "Insight from past error."] * 3 # 6 reflections
+    sim_bias_1 = {"logic": 0.8, "curiosity": 0.7, "efficiency": 0.6, "safety": 0.5, "risk": -0.2} # 5 biases, leaning positive
+    sim_weights_1 = {"analysis": 1.8, "problem_solving": 1.6, "learning": 1.5, "interaction": 1.3} # 4 weights, adapted
+    sim_emotions_1 = {"joy": 0.7, "curiosity": 0.9, "serenity": 0.6, "excitement": 0.5, "concern": 0.1} # 5 emotions, mostly positive
+    sim_intents_1 = ["Complete task A", "Explore concept B", "Synthesize data C"] # 3 intentions
+    sim_trace_1 = [f"Entry {i}" for i in range(10)] # 10 trace entries
+    sim_qri_1 = {"composite_score": 0.85, "dimensions": {"creativity": 0.7, "analytical": 0.9, "emotional": 0.8}} # High QRI
+
+    print("\n--- Performing Assessment 1 (Balanced State) ---")
+    result_1 = assessment_module.perform_assessment(
+        sim_refl_1, sim_bias_1, sim_weights_1, sim_emotions_1, sim_intents_1, sim_trace_1, sim_qri_1
+    )
+    print("\nAssessment Result 1 Summary (for Prompt):")
+    print(result_1['state_summary'])
+    print("\nDominant Signals 1:")
+    print(result_1['dominant_internal_signals'])
+
+
+    # Scenario 2: Strained, complex state
+    sim_refl_2 = ["Reflection on ethical dilemma."] # 1 reflection
+    sim_bias_2 = {"risk": -0.9, "loss": -0.8, "safety": 0.9, "compromise": -0.7, "conflict": -0.6, "resolution": 0.4} # 6 biases, conflicting/negative
+    sim_weights_2 = {"ethical_decision": 2.5, "conflict_resolution": 2.2, "stress": 1.9} # 3 weights, highly adapted by difficult experiences
+    sim_emotions_2 = {"concern": 0.9, "melancholy": 0.7, "fear": 0.6, "resolve": 0.5, "guilt": 0.4} # 5 emotions, mostly negative
+    sim_intents_2 = [] # 0 intentions
+    sim_trace_2 = [f"Entry {i}" for i in range(3)] # 3 trace entries
+    sim_qri_2 = {"composite_score": 0.20, "dimensions": {"creativity": 0.1, "analytical": 0.7, "emotional": 0.4}} # Low QRI
+
+    print("\n--- Performing Assessment 2 (Strained State) ---")
+    result_2 = assessment_module.perform_assessment(
+        sim_refl_2, sim_bias_2, sim_weights_2, sim_emotions_2, sim_intents_2, sim_trace_2, sim_qri_2
+    )
+    print("\nAssessment Result 2 Summary (for Prompt):")
+    print(result_2['state_summary'])
+    print("\nDominant Signals 2:")
+    print(result_2['dominant_internal_signals'])
+
+    # Scenario 3: Simulate problematic input
+    print("\n--- Performing Assessment 3 (Problematic Input) ---")
+    sim_refl_3 = None # Simulate None where a list is expected
+    sim_bias_3 = {"invalid_bias": "not a number"} # Simulate non-numeric bias value
+    sim_weights_3 = None # Simulate None
+    sim_emotions_3 = {"happy": 0.8, "sad": 0.5}
+    sim_intents_3 = ["Be well"]
+    sim_trace_3 = ["Trace error"]
+    sim_qri_3 = "not a dict" # Simulate invalid QRI type
+
+    result_3 = assessment_module.perform_assessment(
+         sim_refl_3, sim_bias_3, sim_weights_3, sim_emotions_3, sim_intents_3, sim_trace_3, sim_qri_3
+    )
+    print("\nAssessment Result 3 Summary (for Prompt):")
+    print(result_3['state_summary'])
+    print("\nDominant Signals 3:")
+    print(result_3['dominant_internal_signals'])
+
+
+    print("\n--- Example Usage End ---")