neuro-simulator 0.1.3__py3-none-any.whl → 0.2.0__py3-none-any.whl

neuro_simulator/services/letta.py

@@ -0,0 +1,206 @@
+# neuro_simulator/services/letta.py
+import asyncio
+import logging
+from typing import Union, List, Dict, Any, Optional
+
+from fastapi import HTTPException, status
+from letta_client import Letta, MessageCreate, TextContent, LlmConfig, AssistantMessage
+
+from ..core.agent_interface import BaseAgent
+from ..core.config import config_manager
+
+# Standard logger for this module
+logger = logging.getLogger(__name__.replace("neuro_simulator", "server", 1))
+
+# Global client instance, initialized once
+letta_client: Union[Letta, None] = None
+
+def initialize_letta_client():
+    """Initializes the global Letta client if not already initialized."""
+    global letta_client
+    if letta_client:
+        return
+
+    try:
+        if not config_manager.settings.api_keys.letta_token:
+            raise ValueError("LETTA_API_TOKEN is not set. Cannot initialize Letta client.")
+        
+        client_args = {'token': config_manager.settings.api_keys.letta_token}
+        if config_manager.settings.api_keys.letta_base_url:
+            client_args['base_url'] = config_manager.settings.api_keys.letta_base_url
+            logger.info(f"Letta client is being initialized for self-hosted URL: {config_manager.settings.api_keys.letta_base_url}")
+        else:
+            logger.info("Letta client is being initialized for Letta Cloud.")
+
+        letta_client = Letta(**client_args)
+
+        agent_id = config_manager.settings.api_keys.neuro_agent_id
+        if agent_id:
+            try:
+                agent_data = letta_client.agents.retrieve(agent_id=agent_id)
+                logger.info(f"Successfully verified Letta Agent, ID: {agent_data.id}, Name: {agent_data.name}")
+            except Exception as e:
+                error_msg = f"Error: Cannot retrieve Letta Agent (ID: {agent_id}). Details: {e}"
+                logger.error(error_msg)
+                raise HTTPException(status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail=error_msg)
+    except Exception as e:
+        logger.error(f"Failed to initialize Letta client: {e}")
+        letta_client = None
+
+def get_letta_client() -> Letta:
+    if letta_client is None:
+        raise ValueError("Letta client is not initialized.")
+    return letta_client
+
+class LettaAgent(BaseAgent):
+    """Letta Agent implementation that adheres to the BaseAgent interface."""
+    
+    def __init__(self):
+        self.client: Letta = None
+        self.agent_id: str = None
+
+    async def initialize(self):
+        initialize_letta_client()
+        self.client = get_letta_client()
+        self.agent_id = config_manager.settings.api_keys.neuro_agent_id
+        if not self.agent_id:
+            raise ValueError("Letta agent ID (neuro_agent_id) is not configured.")
+
+    async def reset_memory(self):
+        try:
+            await asyncio.to_thread(self.client.agents.messages.reset, agent_id=self.agent_id)
+            logger.info(f"Letta Agent (ID: {self.agent_id}) message history has been reset.")
+        except Exception as e:
+            logger.warning(f"Failed to reset Letta Agent message history: {e}")
+
+    async def process_messages(self, messages: List[Dict[str, str]]) -> Dict[str, Any]:
+        if messages:
+            injected_chat_lines = [f"{chat['username']}: {chat['text']}" for chat in messages]
+            injected_chat_text = (
+                "Here are some recent messages from my Twitch chat:\n---\n" +
+                "\n".join(injected_chat_lines) + 
+                "\n---\nNow, as the streamer Neuro-Sama, please continue the conversation naturally."
+            )
+        else:
+            injected_chat_text = "My chat is quiet right now. As Neuro-Sama, what should I say to engage them?"
+
+        logger.info(f"Sending input to Letta Agent ({len(messages)} messages)...")
+
+        response_text = ""
+        error_str = None
+
+        try:
+            response = await asyncio.to_thread(
+                self.client.agents.messages.create,
+                agent_id=self.agent_id,
+                messages=[MessageCreate(role="user", content=injected_chat_text)]
+            )
+
+            if not response or not response.messages:
+                raise ValueError("Letta response is empty or contains no messages.")
+
+            for message in reversed(response.messages):
+                if isinstance(message, AssistantMessage) and hasattr(message, 'content'):
+                    content = message.content
+                    if isinstance(content, str) and content.strip():
+                        response_text = content.strip()
+                        break
+                    elif isinstance(content, list) and content:
+                        first_part = content[0]
+                        if isinstance(first_part, TextContent) and hasattr(first_part, 'text') and first_part.text.strip():
+                            response_text = first_part.text.strip()
+                            break
+            
+            if not response_text:
+                logger.warning(f"No valid AssistantMessage content found in Letta response.")
+                response_text = "I'm not sure what to say to that."
+
+        except Exception as e:
+            logger.error(f"Error calling Letta Agent ({self.agent_id}): {e}")
+            error_str = str(e)
+            response_text = "Someone tell Vedal there is a problem with my AI."
+
+        return {
+            "input_messages": messages,
+            "final_response": response_text,
+            "llm_response": response_text,
+            "tool_executions": [],
+            "error": error_str
+        }
+
+    # Memory Block Management
+    async def get_memory_blocks(self) -> List[Dict[str, Any]]:
+        try:
+            blocks = await asyncio.to_thread(self.client.agents.blocks.list, agent_id=self.agent_id)
+            return [block.model_dump() for block in blocks]
+        except Exception as e:
+            raise HTTPException(status_code=500, detail=f"Error getting memory blocks from Letta: {e}")
+
+    async def get_memory_block(self, block_id: str) -> Optional[Dict[str, Any]]:
+        try:
+            block = await asyncio.to_thread(self.client.agents.blocks.retrieve, agent_id=self.agent_id, block_id=block_id)
+            return block.model_dump()
+        except Exception as e:
+            raise HTTPException(status_code=500, detail=f"Error getting memory block from Letta: {e}")
+
+    async def create_memory_block(self, title: str, description: str, content: List[str]) -> Dict[str, str]:
+        try:
+            block = await asyncio.to_thread(
+                self.client.agents.blocks.create,
+                agent_id=self.agent_id,
+                name=title,
+                content="\n".join(content),
+                description=description
+            )
+            return {"block_id": block.id}
+        except Exception as e:
+            raise HTTPException(status_code=500, detail=f"Error creating memory block in Letta: {e}")
+
+    async def update_memory_block(self, block_id: str, title: Optional[str], description: Optional[str], content: Optional[List[str]]):
+        try:
+            update_params = {}
+            if title is not None: update_params["name"] = title
+            if description is not None: update_params["description"] = description
+            if content is not None: update_params["content"] = "\n".join(content)
+
+            await asyncio.to_thread(
+                self.client.agents.blocks.modify,
+                agent_id=self.agent_id,
+                block_id=block_id,
+                **update_params
+            )
+        except Exception as e:
+            raise HTTPException(status_code=500, detail=f"Error updating memory block in Letta: {e}")
+
+    async def delete_memory_block(self, block_id: str):
+        try:
+            await asyncio.to_thread(self.client.agents.blocks.delete, agent_id=self.agent_id, block_id=block_id)
+        except Exception as e:
+            raise HTTPException(status_code=500, detail=f"Error deleting memory block in Letta: {e}")
+
+    # Unsupported Features for Letta Agent
+    async def get_init_memory(self) -> Dict[str, Any]:
+        raise HTTPException(status_code=400, detail="Getting init memory is not supported for Letta agent")
+
+    async def update_init_memory(self, memory: Dict[str, Any]):
+        raise HTTPException(status_code=400, detail="Updating init memory is not supported for Letta agent")
+
+    async def get_temp_memory(self) -> List[Dict[str, Any]]:
+        raise HTTPException(status_code=400, detail="Getting temp memory is not supported for Letta agent")
+
+    async def add_temp_memory(self, content: str, role: str):
+        raise HTTPException(status_code=400, detail="Adding to temp memory is not supported for Letta agent")
+
+    async def clear_temp_memory(self):
+        raise HTTPException(status_code=400, detail="Clearing temp memory is not supported for Letta agent")
+
+    async def get_available_tools(self) -> str:
+        return "Tool management is not supported for Letta agent via this API"
+
+    async def execute_tool(self, tool_name: str, params: Dict[str, Any]) -> Any:
+        raise HTTPException(status_code=400, detail="Tool execution is not supported for Letta agent via this API")
+
+    async def get_message_history(self, limit: int = 20) -> List[Dict[str, Any]]:
+        # Letta's history is managed on their server and not directly exposed.
+        # Return an empty list to prevent breaking internal consumers like the admin panel.
+        return []

neuro_simulator/{stream_manager.py → services/stream.py}

@@ -1,11 +1,16 @@
-# backend/stream_manager.py
+# neuro_simulator/services/stream.py
 import asyncio
-import time
+import logging
 import os
-from .config import config_manager
-import neuro_simulator.shared_state as shared_state
+import time
+
 from mutagen.mp4 import MP4, MP4StreamInfoError
 
+from ..core.config import config_manager
+from ..utils.state import app_state
+
+logger = logging.getLogger(__name__.replace("neuro_simulator", "server", 1))
+
 class LiveStreamManager:
     class NeuroAvatarStage:
         HIDDEN = "hidden"
@@ -20,121 +25,108 @@ class LiveStreamManager:
     
     event_queue: asyncio.Queue = asyncio.Queue()
 
-    # Get the working directory where media files are located
-    _working_dir = os.getcwd()  # This will be set by cli.py to the --dir path
-    _WELCOME_VIDEO_PATH_BACKEND = os.path.join(_working_dir, "media", "neuro_start.mp4")
+    _working_dir = os.getcwd()
+    _WELCOME_VIDEO_PATH_BACKEND = os.path.join(_working_dir, "assets", "neuro_start.mp4")
     _WELCOME_VIDEO_DURATION_SEC_DEFAULT = 10.0
     
-    # --- NEW: 使用 mutagen 获取时长的静态方法 ---
     @staticmethod
-    def _get_video_duration_mutagen_static(video_path: str) -> float:
-        """使用 mutagen 库可靠地获取 MP4 视频时长。"""
+    def _get_video_duration(video_path: str) -> float:
+        """Gets the duration of an MP4 video file using mutagen."""
         if not os.path.exists(video_path):
-            print(f"警告: 视频文件 '{video_path}' 不存在。将使用默认值。")
+            logger.warning(f"Video file '{video_path}' not found. Using default duration.")
             return LiveStreamManager._WELCOME_VIDEO_DURATION_SEC_DEFAULT
         try:
             video = MP4(video_path)
             duration = video.info.length
-            print(f"已通过 mutagen 成功读取视频 '{video_path}' 时长: {duration:.2f} 秒。")
+            logger.info(f"Successfully read video duration for '{video_path}': {duration:.2f}s.")
             return duration
         except MP4StreamInfoError:
-            print(f"警告: mutagen 无法解析 '{video_path}' 的流信息。它可能不是一个标准的MP4文件。将使用默认值。")
+            logger.warning(f"Could not parse stream info for '{video_path}'. Using default duration.")
             return LiveStreamManager._WELCOME_VIDEO_DURATION_SEC_DEFAULT
         except Exception as e:
-            print(f"使用 mutagen 获取视频时长时出错: {e}. 将使用默认视频时长。")
+            logger.error(f"Error getting video duration: {e}. Using default duration.")
             return LiveStreamManager._WELCOME_VIDEO_DURATION_SEC_DEFAULT
 
-    # --- 核心修改点: 调用新的 mutagen 方法 ---
-    _WELCOME_VIDEO_DURATION_SEC = _get_video_duration_mutagen_static(_WELCOME_VIDEO_PATH_BACKEND)
+    _WELCOME_VIDEO_DURATION_SEC = _get_video_duration(_WELCOME_VIDEO_PATH_BACKEND)
     AVATAR_INTRO_TOTAL_DURATION_SEC = 3.0
 
     def __init__(self):
         self._current_phase: str = self.StreamPhase.OFFLINE
         self._stream_start_global_time: float = 0.0
         self._is_neuro_speaking: bool = False
-        # Note: We don't call reset_stream_state here to avoid asyncio issues during initialization
-        print("LiveStreamManager 初始化完成。")
+        logger.info("LiveStreamManager initialized.")
 
     async def broadcast_stream_metadata(self):
-        """将直播元数据放入事件队列进行广播。"""
+        """Puts the stream metadata into the event queue for broadcasting."""
         metadata_event = {
             "type": "update_stream_metadata",
             **config_manager.settings.stream_metadata.model_dump()
         }
         await self.event_queue.put(metadata_event)
-        print("直播元数据已放入广播队列。")
 
     def reset_stream_state(self):
-        """重置直播状态到初始离线状态。"""
+        """Resets the stream state to offline."""
         self._current_phase = self.StreamPhase.OFFLINE
         self._stream_start_global_time = 0.0
         self._is_neuro_speaking = False
         while not self.event_queue.empty():
             self.event_queue.get_nowait()
-        shared_state.live_phase_started_event.clear()
-        print("直播状态已重置为 OFFLINE。")
-        # Don't create task during initialization, will be called properly in main.py startup
+        app_state.live_phase_started_event.clear()
+        logger.info("Stream state has been reset to OFFLINE.")
 
     async def start_new_stream_cycle(self):
-        """开始一个全新的直播周期，从欢迎视频开始。"""
+        """Starts a new stream cycle, from the welcome video onwards."""
         if self._current_phase != self.StreamPhase.OFFLINE:
-            print("警告: 直播已在进行中，无法开始新周期。")
             return
 
-        print("正在启动新的直播周期...")
+        logger.info("Starting new stream cycle...")
         self._stream_start_global_time = time.time()
         
-        # 清除旧的上下文历史
-        from .builtin_agent import local_agent
-        if local_agent is not None:
-            await local_agent.memory_manager.reset_context()
-            print("旧的上下文历史已清除。")
+        from ..core.agent_factory import create_agent
+        try:
+            agent = await create_agent()
+            await agent.reset_memory()
+            logger.info("Agent memory has been reset for the new stream cycle.")
+        except Exception as e:
+            logger.error(f"Failed to reset agent memory: {e}", exc_info=True)
         
         self._current_phase = self.StreamPhase.INITIALIZING
-        print(f"进入阶段: {self.StreamPhase.INITIALIZING}. 广播 'play_welcome_video' 事件。")
         await self.event_queue.put({
             "type": "play_welcome_video",
             "progress": 0,
             "elapsed_time_sec": self.get_elapsed_time()
         })
         
-        print(f"等待视频时长: {self._WELCOME_VIDEO_DURATION_SEC:.2f} 秒")
         await asyncio.sleep(self._WELCOME_VIDEO_DURATION_SEC)
         
         self._current_phase = self.StreamPhase.AVATAR_INTRO
-        print(f"进入阶段: {self.StreamPhase.AVATAR_INTRO}. 广播 'start_avatar_intro' 事件。")
         await self.event_queue.put({"type": "start_avatar_intro", "elapsed_time_sec": self.get_elapsed_time()})
         
-        print(f"等待立绘入场动画: {self.AVATAR_INTRO_TOTAL_DURATION_SEC} 秒")
         await asyncio.sleep(self.AVATAR_INTRO_TOTAL_DURATION_SEC)
 
         self._current_phase = self.StreamPhase.LIVE
-        print(f"进入阶段: {self.StreamPhase.LIVE}. 广播 'enter_live_phase' 事件。")
         await self.event_queue.put({"type": "enter_live_phase", "elapsed_time_sec": self.get_elapsed_time()})
         
-        shared_state.live_phase_started_event.set()
-        print("Live phase started event has been set.")
+        app_state.live_phase_started_event.set()
+        logger.info("Live phase started event has been set.")
     
     def set_neuro_speaking_status(self, speaking: bool):
-        """设置并广播Neuro是否正在说话。"""
+        """Sets and broadcasts the agent's speaking status."""
         if self._is_neuro_speaking != speaking:
             self._is_neuro_speaking = speaking
-            # Only create task if we're in an event loop
             try:
-                asyncio.get_running_loop()
                 asyncio.create_task(self.event_queue.put({"type": "neuro_is_speaking", "speaking": speaking}))
             except RuntimeError:
-                # No running loop, just put directly (this might block)
                 self.event_queue.put_nowait({"type": "neuro_is_speaking", "speaking": speaking})
     
     def get_elapsed_time(self) -> float:
-        """获取从直播开始到现在的总时长（秒）。"""
+        """Gets the total elapsed time since the stream started."""
         if self._stream_start_global_time > 0:
             return time.time() - self._stream_start_global_time
         return 0.0
 
     def get_initial_state_for_client(self) -> dict:
-        """为新连接的客户端生成当前的初始状态事件。"""
+        """Generates the initial state event for a newly connected client."""
         elapsed_time = self.get_elapsed_time()
         base_state = {"elapsed_time_sec": elapsed_time}
         if self._current_phase == self.StreamPhase.INITIALIZING:
@@ -145,5 +137,5 @@ class LiveStreamManager:
             return {"type": "enter_live_phase", "is_speaking": self._is_neuro_speaking, **base_state}
         return {"type": "offline", **base_state}
 
-# 全局单例
-live_stream_manager = LiveStreamManager()
+# Global singleton instance
+live_stream_manager = LiveStreamManager()

neuro_simulator/utils/__init__.py

@@ -0,0 +1 @@
+# This file makes the 'utils' directory a Python package.

neuro_simulator/utils/logging.py

@@ -0,0 +1,90 @@
+# neuro_simulator/utils/logging.py
+import logging
+import sys
+from collections import deque
+from typing import Deque
+
+# Define a single, consistent format for all logs
+LOG_FORMAT = '%(asctime)s - [%(name)-32s] - %(levelname)-8s - %(message)s'
+DATE_FORMAT = '%H:%M:%S'
+
+# --- Custom Colored Formatter for Console Output ---
+class ColoredFormatter(logging.Formatter):
+    """A custom log formatter that adds color ONLY to the log level name."""
+
+    GREY = "\x1b[38;20m"
+    GREEN = "\x1b[32m"
+    YELLOW = "\x1b[33m"
+    RED = "\x1b[31m"
+    BOLD_RED = "\x1b[31;1m"
+    RESET = "\x1b[0m"
+
+    def __init__(self, fmt):
+        super().__init__(fmt, datefmt=DATE_FORMAT)
+        self.level_colors = {
+            logging.DEBUG: self.GREY,
+            logging.INFO: self.GREEN,
+            logging.WARNING: self.YELLOW,
+            logging.ERROR: self.RED,
+            logging.CRITICAL: self.BOLD_RED
+        }
+
+    def format(self, record):
+        # Create a copy of the record to avoid modifying the original
+        record_copy = logging.makeLogRecord(record.__dict__)
+        
+        # Get the color for the level
+        color = self.level_colors.get(record_copy.levelno)
+        
+        # If a color is found, apply it to the levelname
+        if color:
+            record_copy.levelname = f"{color}{record_copy.levelname}{self.RESET}"
+            
+        # Use the parent class's formatter with the modified record
+        return super().format(record_copy)
+
+# Create two independent, bounded queues for different log sources
+server_log_queue: Deque[str] = deque(maxlen=1000)
+agent_log_queue: Deque[str] = deque(maxlen=1000)
+
+class QueueLogHandler(logging.Handler):
+    """A handler that sends log records to a specified queue."""
+    def __init__(self, queue: Deque[str]):
+        super().__init__()
+        self.queue = queue
+
+    def emit(self, record: logging.LogRecord):
+        log_entry = self.format(record)
+        self.queue.append(log_entry)
+
+def configure_server_logging():
+    """Configures the server (root) logger to use the server_log_queue and a standard format."""
+    # Non-colored formatter for the queue (for the web UI)
+    queue_formatter = logging.Formatter(LOG_FORMAT, datefmt=DATE_FORMAT)
+    
+    # Colored formatter for the console
+    console_formatter = ColoredFormatter(LOG_FORMAT)
+
+    # Create a handler that writes to the server log queue for the web UI
+    server_queue_handler = QueueLogHandler(server_log_queue)
+    server_queue_handler.setFormatter(queue_formatter)
+
+    # Create a handler that writes to the console (stdout)
+    console_handler = logging.StreamHandler(sys.stdout)
+    console_handler.setFormatter(console_formatter)
+
+    # Get the root logger, clear any existing handlers, and add our new ones
+    root_logger = logging.getLogger()
+    if root_logger.hasHandlers():
+        root_logger.handlers.clear()
+    root_logger.addHandler(server_queue_handler)
+    root_logger.addHandler(console_handler)
+    root_logger.setLevel(logging.INFO)
+
+    # Force uvicorn loggers to use our handlers
+    for logger_name in ["uvicorn", "uvicorn.access", "uvicorn.error"]:
+        uvicorn_logger = logging.getLogger(logger_name)
+        uvicorn_logger.handlers = [server_queue_handler, console_handler]
+        uvicorn_logger.propagate = False # Prevent double-logging
+
+    root_logger.info("Server logging configured with unified formatting for queue and console.")

neuro_simulator/utils/process.py

@@ -0,0 +1,67 @@
+# neuro_simulator/utils/process.py
+import asyncio
+import logging
+
+logger = logging.getLogger(__name__.replace("neuro_simulator", "server", 1))
+
+class ProcessManager:
+    """Manages the lifecycle of core background tasks for the stream."""
+
+    def __init__(self):
+        self._tasks: list[asyncio.Task] = []
+        self._is_running = False
+        logger.info("ProcessManager initialized.")
+
+    @property
+    def is_running(self) -> bool:
+        """Returns True if the core stream processes are running."""
+        return self._is_running
+
+    def start_live_processes(self):
+        """
+        Starts all background tasks related to the live stream.
+        Imports are done locally to prevent circular dependencies.
+        """
+        if self.is_running:
+            logger.warning("Processes are already running.")
+            return
+
+        logger.info("Starting core stream processes...")
+        from ..core.application import generate_audience_chat_task, neuro_response_cycle, broadcast_events_task
+        from ..services.stream import live_stream_manager
+        from ..utils.queue import clear_all_queues
+        from ..core.agent_factory import create_agent
+        
+        asyncio.create_task(create_agent())
+        
+        clear_all_queues()
+        live_stream_manager.reset_stream_state()
+
+        self._tasks.append(asyncio.create_task(live_stream_manager.start_new_stream_cycle()))
+        self._tasks.append(asyncio.create_task(broadcast_events_task()))
+        self._tasks.append(asyncio.create_task(generate_audience_chat_task()))
+        self._tasks.append(asyncio.create_task(neuro_response_cycle()))
+        
+        self._is_running = True
+        logger.info(f"Core processes started: {len(self._tasks)} tasks.")
+
+    def stop_live_processes(self):
+        """Stops and cleans up all running background tasks."""
+        if not self.is_running:
+            return
+            
+        logger.info(f"Stopping {len(self._tasks)} core tasks...")
+        for task in self._tasks:
+            if not task.done():
+                task.cancel()
+        
+        self._tasks.clear()
+        self._is_running = False
+        
+        from ..services.stream import live_stream_manager
+        live_stream_manager.reset_stream_state()
+        
+        logger.info("All core tasks have been stopped.")
+
+# Global singleton instance
+process_manager = ProcessManager()

neuro_simulator/{stream_chat.py → utils/queue.py}

@@ -1,29 +1,42 @@
-# backend/stream_chat.py
+# neuro_simulator/utils/queue.py
+"""Manages the chat queues for audience and agent input."""
+
+import logging
 from collections import deque
-from .config import config_manager
+from pathlib import Path
+
+from ..core.config import config_manager
+
+logger = logging.getLogger(__name__.replace("neuro_simulator", "server", 1))
 
-# 使用 settings 对象来初始化 deque 的 maxlen
+# Use settings from the config manager to initialize deque maxlen
 audience_chat_buffer: deque[dict] = deque(maxlen=config_manager.settings.performance.audience_chat_buffer_max_size)
 neuro_input_queue: deque[dict] = deque(maxlen=config_manager.settings.performance.neuro_input_queue_max_size)
 
 def clear_all_queues():
+    """Clears all chat queues."""
     audience_chat_buffer.clear()
     neuro_input_queue.clear()
-    print("所有聊天队列已清空。")
+    logger.info("All chat queues have been cleared.")
 
 def add_to_audience_buffer(chat_item: dict):
+    """Adds a chat item to the audience buffer."""
     audience_chat_buffer.append(chat_item)
 
 def add_to_neuro_input_queue(chat_item: dict):
+    """Adds a chat item to the agent's input queue."""
     neuro_input_queue.append(chat_item)
 
 def get_recent_audience_chats(limit: int) -> list[dict]:
+    """Returns a list of recent chats from the audience buffer."""
     return list(audience_chat_buffer)[-limit:]
 
 def get_all_neuro_input_chats() -> list[dict]:
+    """Returns all chats from the agent's input queue and clears it."""
     chats = list(neuro_input_queue)
     neuro_input_queue.clear()
     return chats
 
 def is_neuro_input_queue_empty() -> bool:
+    """Checks if the agent's input queue is empty."""
     return not bool(neuro_input_queue)

neuro_simulator/utils/state.py

@@ -0,0 +1,14 @@
+# neuro_simulator/utils/state.py
+"""Manages the shared state of the application using a singleton class."""
+
+import asyncio
+
+class AppState:
+    """A singleton class to hold all shared application state."""
+    def __init__(self):
+        self.live_phase_started_event = asyncio.Event()
+        self.neuro_last_speech_lock = asyncio.Lock()
+        self.neuro_last_speech: str = "Neuro-Sama has just started the stream and hasn't said anything yet."
+
+# Create a single, globally accessible instance of the AppState.
+app_state = AppState()