neuro-simulator 0.3.2__py3-none-any.whl → 0.4.0__py3-none-any.whl

neuro_simulator/agent/tools/add_to_core_memory_block.py

@@ -0,0 +1,64 @@
+# neuro_simulator/agent/tools/add_to_core_memory_block.py
+"""The Add to Core Memory Block tool for the agent."""
+
+from typing import Dict, Any, List
+
+from neuro_simulator.agent.tools.base import BaseTool
+from neuro_simulator.agent.memory.manager import MemoryManager
+
+class AddToCoreMemoryBlockTool(BaseTool):
+    """Tool to add an item to an existing core memory block's content list."""
+
+    def __init__(self, memory_manager: MemoryManager):
+        self.memory_manager = memory_manager
+
+    @property
+    def name(self) -> str:
+        return "add_to_core_memory_block"
+
+    @property
+    def description(self) -> str:
+        return "Adds a new string item to the content list of a specific core memory block."
+
+    @property
+    def parameters(self) -> List[Dict[str, Any]]:
+        return [
+            {
+                "name": "block_id",
+                "type": "string",
+                "description": "The ID of the memory block to add to.",
+                "required": True,
+            },
+            {
+                "name": "item",
+                "type": "string",
+                "description": "The new string item to add to the block's content list.",
+                "required": True,
+            }
+        ]
+
+    async def execute(self, **kwargs: Any) -> Dict[str, Any]:
+        block_id = kwargs.get("block_id")
+        item = kwargs.get("item")
+        if not block_id or not item:
+            raise ValueError("The 'block_id' and 'item' parameters are required.")
+
+        # This functionality doesn't exist in MemoryManager, so we need to implement it here.
+        # It's a common pattern: get, modify, save.
+        block = await self.memory_manager.get_core_memory_block(block_id)
+        if block is None:
+            raise ValueError(f"Block '{block_id}' not found.")
+        
+        content = block.get("content", [])
+        if not isinstance(content, list):
+            # Handle case where content might not be a list
+            raise TypeError(f"Content of block '{block_id}' is not a list.")
+
+        content.append(item)
+        
+        await self.memory_manager.update_core_memory_block(block_id=block_id, content=content)
+        
+        return {
+            "status": "success",
+            "message": f"Added item to core memory block '{block_id}'."
+        }

neuro_simulator/agent/tools/base.py

@@ -0,0 +1,56 @@
+# neuro_simulator/agent/tools/base.py
+"""Base classes and definitions for the tool system."""
+
+from abc import ABC, abstractmethod
+from typing import Dict, Any, List, Coroutine
+
+class BaseTool(ABC):
+    """
+    Abstract base class for all tools.
+    It defines the standard interface that all tools must implement to be discoverable and executable.
+    """
+
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        """The unique name of the tool (e.g., 'speak', 'create_core_memory_block')."""
+        pass
+
+    @property
+    @abstractmethod
+    def description(self) -> str:
+        """A concise description of what the tool does, intended for use by an LLM."""
+        pass
+
+    @property
+    @abstractmethod
+    def parameters(self) -> List[Dict[str, Any]]:
+        """
+        A list of dictionaries describing the tool's parameters.
+        This follows a JSON Schema-like format.
+        Example:
+        return [
+            {"name": "param1", "type": "string", "description": "The first parameter.", "required": True},
+            {"name": "param2", "type": "integer", "description": "The second parameter.", "required": False}
+        ]
+        """
+        pass
+
+    @abstractmethod
+    async def execute(self, **kwargs: Any) -> Dict[str, Any]:
+        """
+        The method that executes the tool's logic.
+        It must return a JSON-serializable dictionary.
+        """
+        pass
+
+    def get_schema(self) -> Dict[str, Any]:
+        """
+        Returns a serializable dictionary representing the tool's public schema.
+        This is used by the ToolManager to expose tools to agents or future external services.
+        """
+        return {
+            "name": self.name,
+            "description": self.description,
+            "parameters": self.parameters
+        }

neuro_simulator/agent/tools/create_core_memory_block.py

@@ -0,0 +1,78 @@
+# neuro_simulator/agent/tools/create_core_memory_block.py
+"""The Create Core Memory Block tool for the agent."""
+
+from typing import Dict, Any, List
+
+from neuro_simulator.agent.tools.base import BaseTool
+from neuro_simulator.agent.memory.manager import MemoryManager
+
+class CreateCoreMemoryBlockTool(BaseTool):
+    """Tool to create a new core memory block."""
+
+    def __init__(self, memory_manager: MemoryManager):
+        """Initializes the CreateCoreMemoryBlockTool."""
+        self.memory_manager = memory_manager
+
+    @property
+    def name(self) -> str:
+        return "create_core_memory_block"
+
+    @property
+    def description(self) -> str:
+        return "Creates a new core memory block with a specified title and description. Returns the new block's ID."
+
+    @property
+    def parameters(self) -> List[Dict[str, Any]]:
+        return [
+            {
+                "name": "title",
+                "type": "string",
+                "description": "The title for the new memory block.",
+                "required": True,
+            },
+            {
+                "name": "description",
+                "type": "string",
+                "description": "A short description of the purpose of this memory block.",
+                "required": True,
+            },
+            {
+                "name": "content",
+                "type": "array",
+                "description": "An optional list of initial string entries for the block's content.",
+                "required": False,
+            }
+        ]
+
+    async def execute(self, **kwargs: Any) -> Dict[str, Any]:
+        """
+        Executes the action to create a new core memory block.
+
+        Args:
+            **kwargs: Must contain 'title' and 'description', and optionally 'content'.
+
+        Returns:
+            A dictionary with the result, including the new block's ID.
+        """
+        title = kwargs.get("title")
+        description = kwargs.get("description")
+        content = kwargs.get("content", [])
+
+        if not isinstance(title, str) or not title:
+            raise ValueError("The 'title' parameter must be a non-empty string.")
+        if not isinstance(description, str) or not description:
+            raise ValueError("The 'description' parameter must be a non-empty string.")
+        if not isinstance(content, list):
+            raise ValueError("The 'content' parameter must be a list of strings.")
+
+        block_id = await self.memory_manager.create_core_memory_block(
+            title=title,
+            description=description,
+            content=content
+        )
+        
+        return {
+            "status": "success",
+            "message": f"Created core memory block '{block_id}' with title '{title}'.",
+            "block_id": block_id
+        }

neuro_simulator/agent/tools/delete_core_memory_block.py

@@ -0,0 +1,44 @@
+# neuro_simulator/agent/tools/delete_core_memory_block.py
+"""The Delete Core Memory Block tool for the agent."""
+
+from typing import Dict, Any, List
+
+from neuro_simulator.agent.tools.base import BaseTool
+from neuro_simulator.agent.memory.manager import MemoryManager
+
+class DeleteCoreMemoryBlockTool(BaseTool):
+    """Tool to delete an existing core memory block."""
+
+    def __init__(self, memory_manager: MemoryManager):
+        self.memory_manager = memory_manager
+
+    @property
+    def name(self) -> str:
+        return "delete_core_memory_block"
+
+    @property
+    def description(self) -> str:
+        return "Deletes a core memory block using its ID."
+
+    @property
+    def parameters(self) -> List[Dict[str, Any]]:
+        return [
+            {
+                "name": "block_id",
+                "type": "string",
+                "description": "The ID of the memory block to delete.",
+                "required": True,
+            }
+        ]
+
+    async def execute(self, **kwargs: Any) -> Dict[str, Any]:
+        block_id = kwargs.get("block_id")
+        if not block_id:
+            raise ValueError("The 'block_id' parameter is required.")
+
+        await self.memory_manager.delete_core_memory_block(block_id=block_id)
+        
+        return {
+            "status": "success",
+            "message": f"Core memory block '{block_id}' has been deleted."
+        }

neuro_simulator/agent/tools/get_core_memory_block.py

@@ -0,0 +1,44 @@
+# neuro_simulator/agent/tools/get_core_memory_block.py
+"""The Get Core Memory Block tool for the agent."""
+
+from typing import Dict, Any, List
+
+from neuro_simulator.agent.tools.base import BaseTool
+from neuro_simulator.agent.memory.manager import MemoryManager
+
+class GetCoreMemoryBlockTool(BaseTool):
+    """Tool to retrieve a single core memory block by its ID."""
+
+    def __init__(self, memory_manager: MemoryManager):
+        self.memory_manager = memory_manager
+
+    @property
+    def name(self) -> str:
+        return "get_core_memory_block"
+
+    @property
+    def description(self) -> str:
+        return "Retrieves the full details of a single core memory block using its ID."
+
+    @property
+    def parameters(self) -> List[Dict[str, Any]]:
+        return [
+            {
+                "name": "block_id",
+                "type": "string",
+                "description": "The ID of the memory block to retrieve.",
+                "required": True,
+            }
+        ]
+
+    async def execute(self, **kwargs: Any) -> Dict[str, Any]:
+        block_id = kwargs.get("block_id")
+        if not block_id:
+            raise ValueError("The 'block_id' parameter is required.")
+
+        block = await self.memory_manager.get_core_memory_block(block_id)
+        
+        if block is None:
+            return {"status": "error", "message": f"Block '{block_id}' not found."}
+
+        return {"status": "success", "block": block}

neuro_simulator/agent/tools/get_core_memory_blocks.py

@@ -0,0 +1,30 @@
+# neuro_simulator/agent/tools/get_core_memory_blocks.py
+"""The Get Core Memory Blocks tool for the agent."""
+
+from typing import Dict, Any, List
+
+from neuro_simulator.agent.tools.base import BaseTool
+from neuro_simulator.agent.memory.manager import MemoryManager
+
+class GetCoreMemoryBlocksTool(BaseTool):
+    """Tool to retrieve all core memory blocks."""
+
+    def __init__(self, memory_manager: MemoryManager):
+        self.memory_manager = memory_manager
+
+    @property
+    def name(self) -> str:
+        return "get_core_memory_blocks"
+
+    @property
+    def description(self) -> str:
+        return "Retrieves a list of all available core memory blocks, including their IDs, titles, and descriptions."
+
+    @property
+    def parameters(self) -> List[Dict[str, Any]]:
+        return []
+
+    async def execute(self, **kwargs: Any) -> Dict[str, Any]:
+        blocks = await self.memory_manager.get_core_memory_blocks()
+        # The result should be JSON serializable, which a Dict of Dicts already is.
+        return {"status": "success", "blocks": blocks}

neuro_simulator/agent/tools/manager.py

@@ -0,0 +1,143 @@
+# neuro_simulator/agent/tools/manager.py
+"""The central tool manager for the agent, responsible for loading, managing, and executing tools."""
+
+import os
+import json
+import importlib
+import inspect
+import logging
+import shutil
+from pathlib import Path
+from typing import Any, Dict, List
+
+from .base import BaseTool
+from ..memory.manager import MemoryManager
+from ...core.path_manager import path_manager
+
+logger = logging.getLogger(__name__.replace("neuro_simulator", "agent", 1))
+
+class ToolManager:
+    """
+    Acts as a central registry and executor for all available tools.
+    This manager dynamically loads tools from the user's working directory.
+    """
+
+    def __init__(self, memory_manager: MemoryManager):
+        if not path_manager:
+            raise RuntimeError("PathManager not initialized before ToolManager.")
+        self.memory_manager = memory_manager
+        self.tools: Dict[str, BaseTool] = {}
+        self.agent_tool_allocations: Dict[str, List[str]] = {}
+
+        self._copy_builtin_tools()
+        self.reload_tools()  # Initial load
+        self._load_allocations()
+
+    def _copy_builtin_tools(self):
+        """Copies the packaged built-in tools to the working directory, overwriting existing ones."""
+        try:
+            import pkg_resources
+            source_dir_str = pkg_resources.resource_filename('neuro_simulator', 'agent/tools')
+            source_dir = Path(source_dir_str)
+        except (ModuleNotFoundError, KeyError):
+            source_dir = Path(__file__).parent
+
+        dest_dir = path_manager.builtin_tools_dir
+        if not dest_dir.exists():
+            os.makedirs(dest_dir)
+
+        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 source_item.name.startswith(('__', 'manager')):
+                shutil.copy(source_item, dest_dir / item)
+        logger.info(f"Built-in tools copied to {dest_dir}")
+
+    def _load_and_register_tools(self):
+        """Dynamically scans the user tools directory, imports modules, and registers tool instances."""
+        self.tools = {}
+        tools_dir = path_manager.user_tools_dir
+        
+        for root, _, files in os.walk(tools_dir):
+            for filename in files:
+                if filename.endswith('.py') and not filename.startswith('__'):
+                    module_path = Path(root) / filename
+                    # Create a module spec from the file path
+                    spec = importlib.util.spec_from_file_location(module_path.stem, module_path)
+                    if spec:
+                        try:
+                            module = importlib.util.module_from_spec(spec)
+                            spec.loader.exec_module(module)
+                            for _, cls in inspect.getmembers(module, inspect.isclass):
+                                if issubclass(cls, BaseTool) and cls is not BaseTool:
+                                    tool_instance = cls(memory_manager=self.memory_manager)
+                                    if tool_instance.name in self.tools:
+                                        logger.warning(f"Duplicate tool name '{tool_instance.name}' found. Overwriting.")
+                                    self.tools[tool_instance.name] = tool_instance
+                                    logger.info(f"Successfully loaded and registered tool: {tool_instance.name}")
+                        except Exception as e:
+                            logger.error(f"Failed to load tool from {module_path}: {e}", exc_info=True)
+
+    def _load_allocations(self):
+        """Loads tool allocations from JSON files, creating defaults if they don't exist."""
+        default_allocations = {
+            "neuro_agent": ["speak", "get_core_memory_blocks", "get_core_memory_block"],
+            "memory_agent": ["add_temp_memory", "create_core_memory_block", "update_core_memory_block", "delete_core_memory_block", "add_to_core_memory_block", "remove_from_core_memory_block", "get_core_memory_blocks", "get_core_memory_block"]
+        }
+
+        # Load neuro agent allocations
+        if path_manager.neuro_tools_path.exists():
+            with open(path_manager.neuro_tools_path, 'r', encoding='utf-8') as f:
+                self.agent_tool_allocations['neuro_agent'] = json.load(f)
+        else:
+            self.agent_tool_allocations['neuro_agent'] = default_allocations['neuro_agent']
+            with open(path_manager.neuro_tools_path, 'w', encoding='utf-8') as f:
+                json.dump(default_allocations['neuro_agent'], f, indent=2)
+
+        # Load memory agent allocations
+        if path_manager.memory_agent_tools_path.exists():
+            with open(path_manager.memory_agent_tools_path, 'r', encoding='utf-8') as f:
+                self.agent_tool_allocations['memory_agent'] = json.load(f)
+        else:
+            self.agent_tool_allocations['memory_agent'] = default_allocations['memory_agent']
+            with open(path_manager.memory_agent_tools_path, 'w', encoding='utf-8') as f:
+                json.dump(default_allocations['memory_agent'], f, indent=2)
+        
+        logger.info(f"Tool allocations loaded: {self.agent_tool_allocations}")
+
+    def get_all_tool_schemas(self) -> List[Dict[str, Any]]:
+        return [tool.get_schema() for tool in self.tools.values()]
+
+    def get_tool_schemas_for_agent(self, agent_name: str) -> List[Dict[str, Any]]:
+        allowed_names = set(self.agent_tool_allocations.get(agent_name, []))
+        if not allowed_names:
+            return []
+        return [tool.get_schema() for tool in self.tools.values() if tool.name in allowed_names]
+
+    def reload_tools(self):
+        logger.info("Reloading tools...")
+        self._load_and_register_tools()
+        logger.info(f"Tools reloaded. {len(self.tools)} tools available.")
+
+    def get_allocations(self) -> Dict[str, List[str]]:
+        return self.agent_tool_allocations
+
+    def set_allocations(self, allocations: Dict[str, List[str]]):
+        self.agent_tool_allocations = allocations
+        # Persist the changes to the JSON files
+        with open(path_manager.neuro_tools_path, 'w', encoding='utf-8') as f:
+            json.dump(allocations.get('neuro_agent', []), f, indent=2)
+        with open(path_manager.memory_agent_tools_path, 'w', encoding='utf-8') as f:
+            json.dump(allocations.get('memory_agent', []), f, indent=2)
+        logger.info(f"Tool allocations updated and saved: {self.agent_tool_allocations}")
+
+    async def execute_tool(self, tool_name: str, **kwargs: Any) -> Dict[str, Any]:
+        if tool_name not in self.tools:
+            logger.error(f"Attempted to execute non-existent tool: {tool_name}")
+            return {"error": f"Tool '{tool_name}' not found."}
+        tool = self.tools[tool_name]
+        try:
+            result = await tool.execute(**kwargs)
+            return result
+        except Exception as e:
+            logger.error(f"Error executing tool '{tool_name}' with params {kwargs}: {e}", exc_info=True)
+            return {"error": f"An unexpected error occurred while executing the tool: {str(e)}"}

neuro_simulator/agent/tools/remove_from_core_memory_block.py

@@ -0,0 +1,65 @@
+# neuro_simulator/agent/tools/remove_from_core_memory_block.py
+"""The Remove from Core Memory Block tool for the agent."""
+
+from typing import Dict, Any, List
+
+from neuro_simulator.agent.tools.base import BaseTool
+from neuro_simulator.agent.memory.manager import MemoryManager
+
+class RemoveFromCoreMemoryBlockTool(BaseTool):
+    """Tool to remove an item from an existing core memory block's content list by its index."""
+
+    def __init__(self, memory_manager: MemoryManager):
+        self.memory_manager = memory_manager
+
+    @property
+    def name(self) -> str:
+        return "remove_from_core_memory_block"
+
+    @property
+    def description(self) -> str:
+        return "Removes an item from the content list of a specific core memory block by its zero-based index."
+
+    @property
+    def parameters(self) -> List[Dict[str, Any]]:
+        return [
+            {
+                "name": "block_id",
+                "type": "string",
+                "description": "The ID of the memory block to modify.",
+                "required": True,
+            },
+            {
+                "name": "index",
+                "type": "integer",
+                "description": "The zero-based index of the item to remove from the content list.",
+                "required": True,
+            }
+        ]
+
+    async def execute(self, **kwargs: Any) -> Dict[str, Any]:
+        block_id = kwargs.get("block_id")
+        index = kwargs.get("index")
+
+        if not block_id or index is None:
+            raise ValueError("The 'block_id' and 'index' parameters are required.")
+
+        block = await self.memory_manager.get_core_memory_block(block_id)
+        if block is None:
+            raise ValueError(f"Block '{block_id}' not found.")
+        
+        content = block.get("content", [])
+        if not isinstance(content, list):
+            raise TypeError(f"Content of block '{block_id}' is not a list.")
+
+        try:
+            removed_item = content.pop(index)
+        except IndexError:
+            raise IndexError(f"Index {index} is out of bounds for content in block '{block_id}'.")
+        
+        await self.memory_manager.update_core_memory_block(block_id=block_id, content=content)
+        
+        return {
+            "status": "success",
+            "message": f"Removed item '{removed_item}' from core memory block '{block_id}' at index {index}."
+        }

neuro_simulator/agent/tools/speak.py

@@ -0,0 +1,56 @@
+# neuro_simulator/agent/tools/speak.py
+"""The Speak tool for the agent."""
+
+import logging
+from typing import Dict, Any, List
+
+from neuro_simulator.agent.tools.base import BaseTool
+from neuro_simulator.agent.memory.manager import MemoryManager
+
+logger = logging.getLogger(__name__.replace("neuro_simulator", "agent", 1))
+
+class SpeakTool(BaseTool):
+    """Tool for the agent to speak to the audience."""
+
+    def __init__(self, memory_manager: MemoryManager):
+        """Initializes the SpeakTool."""
+        # This tool doesn't directly use the memory manager, but accepts it for consistency.
+        self.memory_manager = memory_manager
+
+    @property
+    def name(self) -> str:
+        return "speak"
+
+    @property
+    def description(self) -> str:
+        return "Outputs text to the user. This is the primary way to communicate with the audience."
+
+    @property
+    def parameters(self) -> List[Dict[str, Any]]:
+        return [
+            {
+                "name": "text",
+                "type": "string",
+                "description": "The text to be spoken to the audience.",
+                "required": True,
+            }
+        ]
+
+    async def execute(self, **kwargs: Any) -> Dict[str, Any]:
+        """
+        Executes the speak action.
+        
+        Args:
+            **kwargs: Must contain a 'text' key with the string to be spoken.
+
+        Returns:
+            A dictionary confirming the action and the text that was spoken.
+        """
+        text = kwargs.get("text")
+        if not isinstance(text, str) or not text:
+            raise ValueError("The 'text' parameter must be a non-empty string.")
+        
+        logger.info(f"Agent says: {text}")
+        # The result of the speak tool is the text that was spoken.
+        # This can be used for logging or further processing.
+        return {"status": "success", "spoken_text": text}

neuro_simulator/agent/tools/update_core_memory_block.py

@@ -0,0 +1,65 @@
+# neuro_simulator/agent/tools/update_core_memory_block.py
+"""The Update Core Memory Block tool for the agent."""
+
+from typing import Dict, Any, List, Optional
+
+from neuro_simulator.agent.tools.base import BaseTool
+from neuro_simulator.agent.memory.manager import MemoryManager
+
+class UpdateCoreMemoryBlockTool(BaseTool):
+    """Tool to update an existing core memory block."""
+
+    def __init__(self, memory_manager: MemoryManager):
+        self.memory_manager = memory_manager
+
+    @property
+    def name(self) -> str:
+        return "update_core_memory_block"
+
+    @property
+    def description(self) -> str:
+        return "Updates an existing core memory block. All parameters are optional, only provided fields will be updated."
+
+    @property
+    def parameters(self) -> List[Dict[str, Any]]:
+        return [
+            {
+                "name": "block_id",
+                "type": "string",
+                "description": "The ID of the memory block to update.",
+                "required": True,
+            },
+            {
+                "name": "title",
+                "type": "string",
+                "description": "The new title for the memory block.",
+                "required": False,
+            },
+            {
+                "name": "description",
+                "type": "string",
+                "description": "The new description for the memory block.",
+                "required": False,
+            },
+            {
+                "name": "content",
+                "type": "array",
+                "description": "The new list of string entries, which will overwrite the existing content.",
+                "required": False,
+            }
+        ]
+
+    async def execute(self, **kwargs: Any) -> Dict[str, Any]:
+        block_id = kwargs.get("block_id")
+        if not block_id:
+            raise ValueError("The 'block_id' parameter is required.")
+
+        # Only include parameters that are not None to avoid overwriting with nulls
+        update_payload = {k: v for k, v in kwargs.items() if v is not None}
+
+        await self.memory_manager.update_core_memory_block(**update_payload)
+        
+        return {
+            "status": "success",
+            "message": f"Successfully updated core memory block '{block_id}'."
+        }

neuro_simulator/api/system.py

@@ -1,10 +1,13 @@
 # neuro_simulator/api/system.py
 """API endpoints for system, config, and utility functions."""
 
-from fastapi import APIRouter, Depends, HTTPException, status, Request
 import time
+from typing import Any, Dict
+
+from fastapi import APIRouter, Depends, HTTPException, status, Request
 
-from ..core.config import config_manager
+from ..core.config import AppSettings, config_manager
+from ..utils.process import process_manager
 
 
 router = APIRouter(tags=["System & Utilities"])