neuro-simulator 0.4.4__py3-none-any.whl → 0.5.0__py3-none-any.whl

neuro_simulator/chatbot/core.py

@@ -0,0 +1,235 @@
+# neuro_simulator/chatbot/core.py
+"""
+Core module for the Neuro Simulator's Chatbot agent.
+Implements a dual-LLM "Actor/Thinker" architecture.
+"""
+
+import asyncio
+import json
+import logging
+import re
+import shutil
+import importlib.resources
+import os
+from pathlib import Path
+from typing import Any, Dict, List
+from datetime import datetime
+
+from ..core.path_manager import path_manager
+from .llm import ChatbotLLMClient
+from .memory.manager import ChatbotMemoryManager
+from .tools.manager import ChatbotToolManager
+from .nickname_gen.generator import NicknameGenerator
+
+logger = logging.getLogger("neuro_chatbot")
+
+class ChatbotAgent:
+    """
+    Chatbot Agent class implementing the Actor/Thinker model.
+    """
+    
+    def __init__(self):
+        if not path_manager:
+            raise RuntimeError("PathManager must be initialized before the Chatbot Agent.")
+        
+        self.memory_manager = ChatbotMemoryManager(path_manager.chatbot_memories_dir)
+        self.tool_manager = ChatbotToolManager(self.memory_manager)
+        self.nickname_generator = NicknameGenerator()
+        
+        self.chatbot_llm = ChatbotLLMClient()
+        self.memory_llm = ChatbotLLMClient()
+        
+        self._initialized = False
+        self.turn_counter = 0
+        self.reflection_threshold = 5 # Consolidate memory every 5 turns
+
+    async def initialize(self):
+        """Initialize the agent, copying default files and loading components."""
+        if not self._initialized:
+            logger.info("Initializing Chatbot Agent...")
+            self._setup_working_directory()
+            self.tool_manager.load_tools()
+            await self.memory_manager.initialize()
+            await self.nickname_generator.initialize()
+            self._initialized = True
+            logger.info("Chatbot Agent initialized successfully.")
+
+    def _setup_working_directory(self):
+        """Ensures the chatbot's working directory is populated with default files."""
+        logger.info("Setting up chatbot working directory...")
+        try:
+            package_source_dir = Path(importlib.resources.files('neuro_simulator'))
+        except (ModuleNotFoundError, AttributeError):
+             package_source_dir = Path(__file__).parent.parent
+
+        files_to_copy = {
+            "chatbot/prompts/chatbot_prompt.txt": path_manager.chatbot_agent_prompt_path,
+            "chatbot/prompts/memory_prompt.txt": path_manager.chatbot_memory_agent_prompt_path,
+            "chatbot/memory/init_memory.json": path_manager.chatbot_init_memory_path,
+            "chatbot/memory/core_memory.json": path_manager.chatbot_core_memory_path,
+            "chatbot/memory/temp_memory.json": path_manager.chatbot_temp_memory_path,
+            "chatbot/nickname_gen/data/adjectives.txt": path_manager.chatbot_nickname_data_dir / "adjectives.txt",
+            "chatbot/nickname_gen/data/nouns.txt": path_manager.chatbot_nickname_data_dir / "nouns.txt",
+            "chatbot/nickname_gen/data/special_users.txt": path_manager.chatbot_nickname_data_dir / "special_users.txt",
+        }
+
+        for src_rel_path, dest_path in files_to_copy.items():
+            if not dest_path.exists():
+                source_path = package_source_dir / src_rel_path
+                if source_path.exists():
+                    try:
+                        dest_path.parent.mkdir(parents=True, exist_ok=True)
+                        shutil.copy(source_path, dest_path)
+                        logger.info(f"Copied default file to {dest_path}")
+                    except Exception as e:
+                        logger.error(f"Could not copy default file from {source_path}: {e}")
+        
+        self._copy_builtin_tools(package_source_dir)
+
+    def _copy_builtin_tools(self, package_source_dir: Path):
+        """Copies the packaged built-in tools to the working directory."""
+        source_dir = package_source_dir / "chatbot" / "tools"
+        dest_dir = path_manager.chatbot_builtin_tools_dir
+
+        if not source_dir.exists():
+            logger.warning(f"Default chatbot tools source directory not found at {source_dir}")
+            return
+
+        dest_dir.mkdir(parents=True, exist_ok=True)
+
+        for item in os.listdir(source_dir):
+            source_item = source_dir / item
+            if source_item.is_file() and source_item.name.endswith('.py') and not item.startswith(('__', 'base', 'manager')):
+                dest_item = dest_dir / item
+                if not dest_item.exists():
+                    shutil.copy(source_item, dest_item)
+                    logger.info(f"Copied default chatbot tool to {dest_item}")
+
+    async def _append_to_history(self, file_path: Path, data: Dict[str, Any]):
+        """Appends a new entry to a JSON Lines history file."""
+        data['timestamp'] = datetime.now().isoformat()
+        with open(file_path, 'a', encoding='utf-8') as f:
+            f.write(json.dumps(data, ensure_ascii=False) + '\n')
+
+    async def _read_history(self, file_path: Path, limit: int) -> List[Dict[str, Any]]:
+        """Reads the last N lines from a JSON Lines history file."""
+        if not file_path.exists(): return []
+        try:
+            with open(file_path, 'r', encoding='utf-8') as f:
+                lines = f.readlines()
+            return [json.loads(line) for line in lines[-limit:]]
+        except (json.JSONDecodeError, IndexError): return []
+
+    def _format_tool_schemas_for_prompt(self, agent_name: str) -> str:
+        """Formats tool schemas for a specific agent (actor or thinker)."""
+        schemas = self.tool_manager.get_tool_schemas_for_agent(agent_name)
+        if not schemas: return "No tools available."
+        lines = ["Available tools:"]
+        for i, schema in enumerate(schemas):
+            params = ", ".join([f"{p.get('name')}: {p.get('type')}" for p in schema.get("parameters", [])])
+            lines.append(f"{i+1}. {schema.get('name')}({params}) - {schema.get('description')}")
+        return "\n".join(lines)
+
+    async def _build_chatbot_prompt(self, neuro_speech: str, recent_history: List[Dict[str, str]]) -> str:
+        """Builds the prompt for the Chatbot (Actor) LLM."""
+        with open(path_manager.chatbot_agent_prompt_path, 'r', encoding='utf-8') as f:
+            prompt_template = f.read()
+        
+        tool_descriptions = self._format_tool_schemas_for_prompt('chatbot_agent')
+        init_memory_text = json.dumps(self.memory_manager.init_memory, indent=2)
+        core_memory_text = json.dumps(self.memory_manager.core_memory, indent=2)
+        temp_memory_text = json.dumps(self.memory_manager.temp_memory, indent=2)
+        recent_history_text = "\n".join([f"{msg.get('role')}: {msg.get('content')}" for msg in recent_history])
+
+        from ..core.config import config_manager
+        chats_per_batch = config_manager.settings.chatbot_agent.chats_per_batch
+
+        return prompt_template.format(
+            tool_descriptions=tool_descriptions,
+            init_memory=init_memory_text,
+            core_memory=core_memory_text,
+            temp_memory=temp_memory_text,
+            recent_history=recent_history_text,
+            neuro_speech=neuro_speech,
+            chats_per_batch=chats_per_batch
+        )
+
+    async def _build_memory_prompt(self, conversation_history: List[Dict[str, str]]) -> str:
+        """Builds the prompt for the Memory (Thinker) LLM."""
+        with open(path_manager.chatbot_memory_agent_prompt_path, 'r', encoding='utf-8') as f:
+            prompt_template = f.read()
+        tool_descriptions = self._format_tool_schemas_for_prompt('chatbot_memory_agent')
+        history_text = "\n".join([f"{msg.get('role')}: {msg.get('content')}" for msg in conversation_history])
+        return prompt_template.format(tool_descriptions=tool_descriptions, conversation_history=history_text)
+
+    def _parse_tool_calls(self, response_text: str) -> List[Dict[str, Any]]:
+        """Extracts and parses a JSON array from the LLM's response text."""
+        try:
+            # Find the start and end of the main JSON array
+            start_index = response_text.find('[')
+            end_index = response_text.rfind(']')
+
+            if start_index != -1 and end_index != -1 and end_index > start_index:
+                json_str = response_text[start_index : end_index + 1]
+                return json.loads(json_str)
+            else:
+                logger.warning(f"Could not find a valid JSON array in response: {response_text}")
+                return []
+        except Exception as e:
+            logger.error(f"Failed to parse tool calls from LLM response: {e}\nRaw text: {response_text}")
+            return []
+
+    async def _execute_tool_calls(self, tool_calls: List[Dict[str, Any]], agent_name: str) -> List[Dict[str, str]]:
+        generated_messages = []
+        for tool_call in tool_calls:
+            tool_name = tool_call.get("name")
+            params = tool_call.get("params", {})
+            result = await self.tool_manager.execute_tool(tool_name, **params)
+            
+            if agent_name == 'chatbot_agent' and tool_name == "post_chat_message" and result.get("status") == "success":
+                text_to_post = result.get("text_to_post", "")
+                if text_to_post:
+                    nickname = self.nickname_generator.generate_nickname()
+                    message = {"username": nickname, "text": text_to_post}
+                    generated_messages.append(message)
+                    await self._append_to_history(path_manager.chatbot_agent_history_path, {'role': 'assistant', 'content': f"{nickname}: {text_to_post}"})
+        logger.info(f"Returning generated messages: {generated_messages}")
+        return generated_messages
+
+    async def generate_chat_messages(self, neuro_speech: str, recent_history: List[Dict[str, str]]) -> List[Dict[str, str]]:
+        """The main actor loop to generate chat messages."""
+        for entry in recent_history:
+            await self._append_to_history(path_manager.chatbot_agent_history_path, entry)
+        
+        prompt = await self._build_chatbot_prompt(neuro_speech, recent_history)
+        response_text = await self.chatbot_llm.generate(prompt)
+        if not response_text: return []
+
+        tool_calls = self._parse_tool_calls(response_text)
+        if not tool_calls: return []
+
+        messages = await self._execute_tool_calls(tool_calls, 'chatbot_agent')
+        
+        self.turn_counter += 1
+        if self.turn_counter >= self.reflection_threshold:
+            asyncio.create_task(self._reflect_and_consolidate())
+        
+        return messages
+
+    async def _reflect_and_consolidate(self):
+        """The main thinker loop to consolidate memories."""
+        logger.info("Chatbot is reflecting on recent conversations...")
+        self.turn_counter = 0
+        history = await self._read_history(path_manager.chatbot_agent_history_path, limit=50)
+        if len(history) < self.reflection_threshold:
+            return
+
+        prompt = await self._build_memory_prompt(history)
+        response_text = await self.memory_llm.generate(prompt)
+        if not response_text: return
+
+        tool_calls = self._parse_tool_calls(response_text)
+        if not tool_calls: return
+
+        await self._execute_tool_calls(tool_calls, 'chatbot_memory_agent')
+        logger.info("Chatbot memory consolidation complete.")

neuro_simulator/chatbot/llm.py

@@ -0,0 +1,105 @@
+# neuro_simulator/chatbot/llm.py
+"""
+LLM client for the Neuro Simulator's Chatbot agent.
+"""
+
+import asyncio
+import logging
+from typing import Any
+
+from google import genai
+from google.genai import types
+from openai import AsyncOpenAI
+
+from ..core.config import config_manager
+
+logger = logging.getLogger(__name__.replace("neuro_simulator", "chatbot", 1))
+
+class ChatbotLLMClient:
+    """A completely independent LLM client for the chatbot agent, with lazy initialization."""
+    
+    def __init__(self):
+        self.client: Any = None
+        self.model_name: str | None = None
+        self._generate_func = None
+        self._initialized = False
+
+    async def _ensure_initialized(self):
+        """Initializes the client on first use."""
+        if self._initialized:
+            return
+
+        logger.info("First use of Chatbot's LLMClient, performing initialization...")
+        settings = config_manager.settings
+        # Use the new chatbot_agent config block
+        provider = settings.chatbot_agent.agent_provider.lower()
+        
+        if provider == "gemini":
+            api_key = settings.api_keys.gemini_api_key
+            if not api_key:
+                raise ValueError("GEMINI_API_KEY is not set in configuration for the chatbot agent.")
+            
+            genai.configure(api_key=api_key)
+            self.model_name = settings.chatbot_agent.agent_model
+            self._generate_func = self._generate_gemini
+            
+        elif provider == "openai":
+            api_key = settings.api_keys.openai_api_key
+            if not api_key:
+                raise ValueError("OPENAI_API_KEY is not set in configuration for the chatbot agent.")
+            
+            self.model_name = settings.chatbot_agent.agent_model
+            self.client = AsyncOpenAI(
+                api_key=api_key, 
+                base_url=settings.api_keys.openai_api_base_url
+            )
+            self._generate_func = self._generate_openai
+        else:
+            raise ValueError(f"Unsupported agent provider in chatbot_agent config: {provider}")
+            
+        self._initialized = True
+        logger.info(f"Chatbot LLM client initialized. Provider: {provider.upper()}, Model: {self.model_name}")
+
+    async def _generate_gemini(self, prompt: str, max_tokens: int) -> str:
+        """Generates text using the Gemini model."""
+        generation_config = types.GenerationConfig(
+            max_output_tokens=max_tokens,
+        )
+        model = genai.GenerativeModel(self.model_name)
+        try:
+            response = await model.generate_content_async(
+                contents=prompt,
+                generation_config=generation_config
+            )
+            return response.text
+        except Exception as e:
+            logger.error(f"Error in chatbot _generate_gemini: {e}", exc_info=True)
+            return ""
+
+    async def _generate_openai(self, prompt: str, max_tokens: int) -> str:
+        """Generates text using the OpenAI model."""
+        try:
+            response = await self.client.chat.completions.create(
+                model=self.model_name,
+                messages=[{"role": "user", "content": prompt}],
+                max_tokens=max_tokens,
+            )
+            if response.choices and response.choices[0].message and response.choices[0].message.content:
+                return response.choices[0].message.content.strip()
+            return ""
+        except Exception as e:
+            logger.error(f"Error in chatbot _generate_openai: {e}", exc_info=True)
+            return ""
+        
+    async def generate(self, prompt: str, max_tokens: int = 1000) -> str:
+        """Generate text using the configured LLM, ensuring client is initialized."""
+        await self._ensure_initialized()
+
+        if not self._generate_func:
+            raise RuntimeError("Chatbot LLM Client could not be initialized.")
+        try:
+            result = await self._generate_func(prompt, max_tokens)
+            return result if result is not None else ""
+        except Exception as e:
+            logger.error(f"Error generating text with Chatbot LLM: {e}", exc_info=True)
+            return "My brain is not working, tell Vedal to check the logs."

neuro_simulator/chatbot/memory/manager.py

@@ -0,0 +1,90 @@
+# neuro_simulator/chatbot/memory/manager.py
+"""
+Manages the chatbot agent's shared memory state (init, core, temp).
+"""
+
+import json
+import logging
+import random
+import string
+from typing import Any, Dict, List, Optional
+from datetime import datetime
+from pathlib import Path
+
+logger = logging.getLogger(__name__.replace("neuro_simulator", "chatbot", 1))
+
+def generate_id(length=6) -> str:
+    """Generate a random ID string."""
+    return ''.join(random.choices(string.ascii_letters + string.digits, k=length))
+
+class ChatbotMemoryManager:
+    """Manages the three types of shared memory for the chatbot agent."""
+    
+    def __init__(self, memory_root_path: Path):
+        """Initializes the MemoryManager with a specific root path for its memory files."""
+        if not memory_root_path:
+            raise ValueError("memory_root_path must be provided.")
+
+        self.init_memory_file = memory_root_path / "init_memory.json"
+        self.core_memory_file = memory_root_path / "core_memory.json"
+        self.temp_memory_file = memory_root_path / "temp_memory.json"
+        
+        self.init_memory: Dict[str, Any] = {}
+        self.core_memory: Dict[str, Any] = {}
+        self.temp_memory: List[Dict[str, Any]] = []
+        
+    async def initialize(self):
+        """Load all memory types from files. Assumes files have been created by the setup mechanism."""
+        # Load init memory
+        if self.init_memory_file.exists():
+            with open(self.init_memory_file, 'r', encoding='utf-8') as f:
+                self.init_memory = json.load(f)
+        else:
+            logger.error(f"Init memory file not found at {self.init_memory_file}, proceeding with empty memory.")
+            self.init_memory = {}
+            
+        # Load core memory
+        if self.core_memory_file.exists():
+            with open(self.core_memory_file, 'r', encoding='utf-8') as f:
+                self.core_memory = json.load(f)
+        else:
+            logger.error(f"Core memory file not found at {self.core_memory_file}, proceeding with empty memory.")
+            self.core_memory = {"blocks": {}}
+            
+        # Load temp memory
+        if self.temp_memory_file.exists():
+            with open(self.temp_memory_file, 'r', encoding='utf-8') as f:
+                self.temp_memory = json.load(f)
+        else:
+            # This is less critical, can start empty
+            self.temp_memory = []
+            await self._save_temp_memory()
+                
+        logger.info(f"Chatbot MemoryManager initialized from {self.init_memory_file.parent}.")
+        
+    async def _save_init_memory(self):
+        with open(self.init_memory_file, 'w', encoding='utf-8') as f:
+            json.dump(self.init_memory, f, ensure_ascii=False, indent=2)
+
+    async def _save_core_memory(self):
+        with open(self.core_memory_file, 'w', encoding='utf-8') as f:
+            json.dump(self.core_memory, f, ensure_ascii=False, indent=2)
+            
+    async def _save_temp_memory(self):
+        with open(self.temp_memory_file, 'w', encoding='utf-8') as f:
+            json.dump(self.temp_memory, f, ensure_ascii=False, indent=2)
+            
+    async def reset_temp_memory(self):
+        """Reset temp memory to a default empty state."""
+        self.temp_memory = []
+        await self._save_temp_memory()
+        logger.info("Chatbot temp memory has been reset.")
+        
+    async def add_temp_memory(self, content: str, role: str = "system"):
+        self.temp_memory.append({"id": generate_id(), "content": content, "role": role, "timestamp": datetime.now().isoformat()})
+        if len(self.temp_memory) > 20:
+            self.temp_memory = self.temp_memory[-20:]
+        await self._save_temp_memory()
+
+    async def get_core_memory_blocks(self) -> Dict[str, Any]:
+        return self.core_memory.get("blocks", {})

neuro_simulator/chatbot/nickname_gen/generator.py

@@ -0,0 +1,144 @@
+# neuro_simulator/chatbot/nickname_gen/generator.py
+"""
+Nickname generator for the chatbot agent.
+Implements a dual-pool system (base and dynamic) with multiple generation strategies.
+"""
+
+import logging
+import random
+from pathlib import Path
+from typing import List, Dict, Callable
+
+from ..llm import ChatbotLLMClient
+from ...core.config import config_manager
+from ...core.path_manager import path_manager
+
+logger = logging.getLogger(__name__.replace("neuro_simulator", "chatbot", 1))
+
+class NicknameGenerator:
+    """Generates diverse nicknames using a multi-strategy, dual-pool system."""
+
+    def __init__(self):
+        if not path_manager:
+            raise RuntimeError("PathManager must be initialized before NicknameGenerator.")
+        
+        self.base_adjectives: List[str] = []
+        self.base_nouns: List[str] = []
+        self.special_users: List[str] = []
+        
+        self.dynamic_adjectives: List[str] = []
+        self.dynamic_nouns: List[str] = []
+
+        self.llm_client = ChatbotLLMClient()
+
+    def _load_word_pool(self, filename: str) -> List[str]:
+        """Loads a word pool from the nickname_gen/data directory."""
+        file_path = path_manager.chatbot_nickname_data_dir / filename
+        if not file_path.exists():
+            logger.warning(f"Nickname pool file not found: {file_path}. The pool will be empty.")
+            return []
+        with open(file_path, 'r', encoding='utf-8') as f:
+            return [line.strip() for line in f if line.strip()]
+
+    async def initialize(self):
+        """Loads base pools and attempts to generate dynamic pools."""
+        logger.info("Initializing NicknameGenerator...")
+        self.base_adjectives = self._load_word_pool("adjectives.txt")
+        self.base_nouns = self._load_word_pool("nouns.txt")
+        self.special_users = self._load_word_pool("special_users.txt")
+
+        if not self.base_adjectives or not self.base_nouns:
+            logger.warning("Base adjective or noun pools are empty. Nickname generation quality will be affected.")
+
+        if config_manager.settings.chatbot_agent.nickname_generation.enable_dynamic_pool:
+            await self._populate_dynamic_pools()
+        
+        logger.info("NicknameGenerator initialized.")
+
+    async def _populate_dynamic_pools(self):
+        """Uses an LLM to generate and populate the dynamic word pools."""
+        logger.info("Attempting to populate dynamic nickname pools using LLM...")
+        pool_size = config_manager.settings.chatbot_agent.nickname_generation.dynamic_pool_size
+        try:
+            adj_prompt = f"Generate a list of {pool_size} diverse, cool-sounding English adjectives for online usernames. Output only the words, one per line."
+            noun_prompt = f"Generate a list of {pool_size} diverse, cool-sounding English nouns for online usernames. Output only the words, one per line."
+
+            adj_list_str = await self.llm_client.generate(adj_prompt, max_tokens=pool_size * 10)
+            noun_list_str = await self.llm_client.generate(noun_prompt, max_tokens=pool_size * 10)
+
+            self.dynamic_adjectives = [line.strip() for line in adj_list_str.split('\n') if line.strip()]
+            self.dynamic_nouns = [line.strip() for line in noun_list_str.split('\n') if line.strip()]
+
+            if self.dynamic_adjectives and self.dynamic_nouns:
+                logger.info(f"Successfully populated dynamic pools with {len(self.dynamic_adjectives)} adjectives and {len(self.dynamic_nouns)} nouns.")
+            else:
+                logger.warning("LLM generated empty lists for dynamic pools.")
+
+        except Exception as e:
+            logger.error(f"Failed to generate dynamic nickname pool: {e}. Falling back to base pool only.", exc_info=True)
+            self.dynamic_adjectives = []
+            self.dynamic_nouns = []
+
+    def _get_combined_pools(self) -> tuple[List[str], List[str]]:
+        """Returns the combination of base and dynamic pools."""
+        adjectives = self.base_adjectives + self.dynamic_adjectives
+        nouns = self.base_nouns + self.dynamic_nouns
+        return adjectives, nouns
+
+    def _generate_from_word_pools(self) -> str:
+        adjectives, nouns = self._get_combined_pools()
+        if not adjectives or not nouns:
+            return self._generate_random_numeric() # Fallback
+
+        noun = random.choice(nouns)
+        # 50% chance to add an adjective
+        if random.random() < 0.5:
+            adjective = random.choice(adjectives)
+            # Formatting variations
+            format_choice = random.random()
+            if format_choice < 0.4:
+                return f"{adjective.capitalize()}{noun.capitalize()}"
+            elif format_choice < 0.7:
+                return f"{adjective.lower()}_{noun.lower()}"
+            else:
+                return f"{adjective.lower()}{noun.lower()}"
+        else:
+            # Add a number suffix 30% of the time
+            if random.random() < 0.3:
+                return f"{noun.capitalize()}{random.randint(1, 999)}"
+            return noun.capitalize()
+
+    def _generate_from_special_pool(self) -> str:
+        if not self.special_users:
+            return self._generate_from_word_pools() # Fallback
+        return random.choice(self.special_users)
+
+    def _generate_random_numeric(self) -> str:
+        return f"user{random.randint(10000, 99999)}"
+
+    def generate_nickname(self) -> str:
+        """Generates a single nickname based on weighted strategies."""
+        strategies: Dict[Callable[[], str], int] = {
+            self._generate_from_word_pools: 70,
+            self._generate_from_special_pool: 15,
+            self._generate_random_numeric: 15,
+        }
+
+        # Filter out strategies that can't be run (e.g., empty special pool)
+        if not self.special_users:
+            strategies.pop(self._generate_from_special_pool, None)
+            # Redistribute weight
+            if strategies:
+                total_weight = sum(strategies.values())
+                strategies = {k: v/total_weight * 100 for k,v in strategies.items()}
+
+        if not any(self._get_combined_pools()):
+             strategies = {self._generate_random_numeric: 100}
+
+        chosen_strategy = random.choices(
+            population=list(strategies.keys()),
+            weights=list(strategies.values()),
+            k=1
+        )[0]
+
+        return chosen_strategy()

neuro_simulator/chatbot/tools/add_temp_memory.py

@@ -0,0 +1,51 @@
+# neuro_simulator/chatbot/tools/add_temp_memory.py
+"""The Add Temp Memory tool for the chatbot agent."""
+
+from typing import Any, Dict, List
+
+from neuro_simulator.chatbot.tools.base import BaseChatbotTool
+from neuro_simulator.chatbot.memory.manager import ChatbotMemoryManager
+
+class AddTempMemoryTool(BaseChatbotTool):
+    """Tool to add an entry to the chatbot's temporary memory."""
+
+    def __init__(self, memory_manager: ChatbotMemoryManager):
+        self.memory_manager = memory_manager
+
+    @property
+    def name(self) -> str:
+        return "add_temp_memory"
+
+    @property
+    def description(self) -> str:
+        return "Adds an entry to the temporary memory. Use for short-term observations, recent facts, or topics to bring up soon."
+
+    @property
+    def parameters(self) -> List[Dict[str, Any]]:
+        return [
+            {
+                "name": "content",
+                "type": "string",
+                "description": "The content of the memory entry.",
+                "required": True,
+            },
+            {
+                "name": "role",
+                "type": "string",
+                "description": "The role associated with the memory (e.g., 'system', 'user'). Defaults to 'system'.",
+                "required": False,
+            }
+        ]
+
+    async def execute(self, **kwargs: Any) -> Dict[str, Any]:
+        content = kwargs.get("content")
+        if not isinstance(content, str) or not content:
+            raise ValueError("The 'content' parameter must be a non-empty string.")
+        
+        role = kwargs.get("role", "system")
+        if not isinstance(role, str):
+            raise ValueError("The 'role' parameter must be a string.")
+
+        await self.memory_manager.add_temp_memory(content=content, role=role)
+        
+        return {"status": "success", "message": f"Added entry to temporary memory with role '{role}'."}