autobyteus 1.2.1__py3-none-any.whl → 1.3.0__py3-none-any.whl

autobyteus/tools/multimedia/image_tools.py

@@ -1,14 +1,81 @@
 import os
 import logging
-from typing import Optional, List
+from typing import Optional, List, Dict, Tuple, Any
+from pathlib import Path
 
 from autobyteus.tools.base_tool import BaseTool
 from autobyteus.utils.parameter_schema import ParameterSchema, ParameterDefinition, ParameterType
 from autobyteus.tools.tool_category import ToolCategory
 from autobyteus.multimedia.image import image_client_factory, ImageModel, ImageClientFactory
+from autobyteus.multimedia.image.base_image_client import BaseImageClient
+from autobyteus.utils.download_utils import download_file_from_url
+from autobyteus.utils.file_utils import resolve_safe_path
 
 logger = logging.getLogger(__name__)
 
+def _get_workspace_root(context) -> str:
+    if not context.workspace:
+        error_msg = (
+            f"Relative path provided, but no workspace is configured for agent '{context.agent_id}'. "
+            "A workspace is required to resolve relative paths."
+        )
+        logger.error(error_msg)
+        raise ValueError(error_msg)
+
+    base_path = context.workspace.get_base_path()
+    if not base_path or not isinstance(base_path, str):
+        error_msg = (
+            f"Agent '{context.agent_id}' has a configured workspace, but it provided an invalid base path "
+            f"('{base_path}'). Cannot resolve relative paths."
+        )
+        logger.error(error_msg)
+        raise ValueError(error_msg)
+
+    return base_path
+
+
+class _SharedImageClientManager:
+    """
+    Internal manager to share image client instances between tools (e.g., Generate and Edit)
+    WITHIN the same agent instance.
+    
+    It keys clients by (agent_id, model_identifier). This ensures that:
+    1. Multiple tools (Generate/Edit) used by Agent A share the same client (preserving session/context).
+    2. Agent B gets a completely separate client instance, preventing state leakage between agents.
+    """
+    # Key: (agent_id, model_identifier) -> Client Instance
+    _clients: Dict[Tuple[str, str], BaseImageClient] = {}
+    # Key: (agent_id, model_identifier) -> Reference Count
+    _ref_counts: Dict[Tuple[str, str], int] = {}
+
+    @classmethod
+    def get_client(cls, agent_id: str, model_identifier: str) -> BaseImageClient:
+        key = (agent_id, model_identifier)
+        
+        if key not in cls._clients:
+            logger.info(f"SharedImageClientManager: Creating new client for model '{model_identifier}' scoped to agent '{agent_id}'.")
+            cls._clients[key] = image_client_factory.create_image_client(model_identifier=model_identifier)
+            cls._ref_counts[key] = 0
+        
+        cls._ref_counts[key] += 1
+        logger.debug(f"SharedImageClientManager: Client for '{model_identifier}' (Agent: {agent_id}) ref count incremented to {cls._ref_counts[key]}")
+        return cls._clients[key]
+
+    @classmethod
+    async def release_client(cls, agent_id: str, model_identifier: str) -> None:
+        key = (agent_id, model_identifier)
+        
+        if key in cls._ref_counts:
+            cls._ref_counts[key] -= 1
+            logger.debug(f"SharedImageClientManager: Client for '{model_identifier}' (Agent: {agent_id}) ref count decremented to {cls._ref_counts[key]}")
+            
+            if cls._ref_counts[key] <= 0:
+                logger.info(f"SharedImageClientManager: Cleaning up client for '{model_identifier}' (Agent: {agent_id})")
+                client = cls._clients.pop(key, None)
+                del cls._ref_counts[key]
+                if client:
+                    await client.cleanup()
+
 
 def _get_configured_model_identifier(env_var: str, default_model: Optional[str] = None) -> str:
     """
@@ -52,13 +119,34 @@ def _build_dynamic_image_schema(base_params: List[ParameterDefinition], model_en
     return schema
 
 
+def _get_model_description_suffix(model_env_var: str, default_model: str) -> str:
+    """
+    Fetches the configured model's specific description suffix, if available.
+    """
+    try:
+        model_identifier = _get_configured_model_identifier(model_env_var, default_model)
+        ImageClientFactory.ensure_initialized()
+        model = ImageModel[model_identifier]
+        if model.description:
+            return f"\n\n**MODEL SPECIFIC CAPABILITIES:** {model.description}"
+    except Exception:
+        # Fail gracefully if model lookup fails; rely on base tool description
+        pass
+    return ""
+
+
 class GenerateImageTool(BaseTool):
     """
     An agent tool for generating images from a text prompt using a pre-configured model.
     """
     CATEGORY = ToolCategory.MULTIMEDIA
     MODEL_ENV_VAR = "DEFAULT_IMAGE_GENERATION_MODEL"
-    DEFAULT_MODEL = "gpt-image-1"
+    DEFAULT_MODEL = "gpt-image-1.5"
+
+    def __init__(self, config=None):
+        super().__init__(config)
+        self._client: Optional[BaseImageClient] = None
+        self._model_identifier: Optional[str] = None
 
     @classmethod
     def get_name(cls) -> str:
@@ -66,11 +154,19 @@ class GenerateImageTool(BaseTool):
 
     @classmethod
     def get_description(cls) -> str:
-        return (
-            "Generates one or more images based on a textual description (prompt) using the system's default image model. "
-            "Can optionally accept reference images to influence the style or content. "
-            "Returns a list of URLs to the generated images upon success."
+        base_desc = (
+            "Generates one or more images based on a textual description (prompt). "
+            "This versatile tool handles both creation from scratch and modification of existing images. "
+            "If 'input_images' are provided, it serves as a powerful editing and variation engine. "
+            "Use cases include: creating or editing posters, modifying scene elements (e.g., 'add a cat to the sofa'), "
+            "style transfer (e.g., 'turn this photo into an oil painting'), generating variations of a design, "
+            "or any imaging task requiring consistency with an input reference (e.g., preserving a specific composition or background while changing the subject). "
+            "Saves the generated image to the specified local file path and returns the path. "
+            "Please refer to the specific capabilities of the configured model below to check if it supports "
+            "input images for variations/editing."
         )
+        suffix = _get_model_description_suffix(cls.MODEL_ENV_VAR, cls.DEFAULT_MODEL)
+        return f"{base_desc}{suffix}"
 
     @classmethod
     def get_argument_schema(cls) -> Optional[ParameterSchema]:
@@ -82,37 +178,71 @@ class GenerateImageTool(BaseTool):
                 required=True
             ),
             ParameterDefinition(
-                name="input_image_urls",
+                name="input_images",
                 param_type=ParameterType.STRING,
-                description="Optional. A comma-separated string of URLs to reference images. The generated image will try to match the style or content of these images.",
+                description="Optional. A comma-separated string of image locations (URLs or file paths).",
                 required=False
+            ),
+            ParameterDefinition(
+                name="output_file_path",
+                param_type=ParameterType.STRING,
+                description=(
+                    "Required. The local file path (relative to workspace) where the generated image should be saved. "
+                    "Example: 'assets/images/result.png'"
+                ),
+                required=True
             )
         ]
         return _build_dynamic_image_schema(base_params, cls.MODEL_ENV_VAR, cls.DEFAULT_MODEL)
 
-    async def _execute(self, context, prompt: str, input_image_urls: Optional[str] = None, generation_config: Optional[dict] = None) -> List[str]:
-        model_identifier = _get_configured_model_identifier(self.MODEL_ENV_VAR, self.DEFAULT_MODEL)
-        logger.info(f"generate_image executing with configured model '{model_identifier}'.")
-        client = None
-        try:
-            urls_list = None
-            if input_image_urls:
-                urls_list = [url.strip() for url in input_image_urls.split(',') if url.strip()]
-
-            client = image_client_factory.create_image_client(model_identifier=model_identifier)
-            response = await client.generate_image(
-                prompt=prompt, 
-                input_image_urls=urls_list,
-                generation_config=generation_config
-            )
-            
-            if not response.image_urls:
-                raise ValueError("Image generation failed to return any image URLs.")
-            
-            return response.image_urls
-        finally:
-            if client:
-                await client.cleanup()
+    async def _execute(
+        self,
+        context,
+        prompt: str,
+        output_file_path: str,
+        input_images: Optional[str] = None,
+        generation_config: Optional[dict] = None,
+    ) -> Any:
+        # 1. Resolve Model ID
+        if not self._model_identifier:
+            self._model_identifier = _get_configured_model_identifier(self.MODEL_ENV_VAR, self.DEFAULT_MODEL)
+
+        logger.info(f"generate_image executing with configured model '{self._model_identifier}' for agent '{context.agent_id}'.")
+        
+        # 2. Obtain Shared Client (Scoped to Agent ID)
+        if self._client is None:
+            self._client = _SharedImageClientManager.get_client(context.agent_id, self._model_identifier)
+
+        # 3. Process Inputs
+        urls_list = None
+        if input_images:
+            urls_list = [url.strip() for url in input_images.split(',') if url.strip()]
+
+        # 4. Execute Generation (client enforces single image where applicable)
+        response = await self._client.generate_image(
+            prompt=prompt, 
+            input_image_urls=urls_list,
+            generation_config=generation_config
+        )
+
+        if not response.image_urls:
+            raise ValueError("Image generation failed to return any image URLs.")
+
+        first_url = response.image_urls[0]
+
+        if not output_file_path:
+            raise ValueError("output_file_path is required but was not provided.")
+
+        # 5. Save to File
+        resolved_path = resolve_safe_path(output_file_path, _get_workspace_root(context))
+        await download_file_from_url(first_url, resolved_path)
+
+        return {"file_path": str(resolved_path)}
+
+    async def cleanup(self) -> None:
+        if self._client and self._model_identifier and self.agent_id:
+            await _SharedImageClientManager.release_client(self.agent_id, self._model_identifier)
+            self._client = None
 
 
 class EditImageTool(BaseTool):
@@ -121,7 +251,12 @@ class EditImageTool(BaseTool):
     """
     CATEGORY = ToolCategory.MULTIMEDIA
     MODEL_ENV_VAR = "DEFAULT_IMAGE_EDIT_MODEL"
-    DEFAULT_MODEL = "gpt-image-1"
+    DEFAULT_MODEL = "gpt-image-1.5"
+
+    def __init__(self, config=None):
+        super().__init__(config)
+        self._client: Optional[BaseImageClient] = None
+        self._model_identifier: Optional[str] = None
 
     @classmethod
     def get_name(cls) -> str:
@@ -129,11 +264,13 @@ class EditImageTool(BaseTool):
 
     @classmethod
     def get_description(cls) -> str:
-        return (
-            "Edits an existing image based on a textual description (prompt) using the system's default image model. "
+        base_desc = (
+            "Edits an existing image based on a textual description (prompt)"
             "A mask can be provided to specify the exact area to edit (inpainting). "
-            "Returns a list of URLs to the edited images."
+            "Saves the edited image to the specified local file path and returns the path."
         )
+        suffix = _get_model_description_suffix(cls.MODEL_ENV_VAR, cls.DEFAULT_MODEL)
+        return f"{base_desc}{suffix}"
 
     @classmethod
     def get_argument_schema(cls) -> Optional[ParameterSchema]:
@@ -145,41 +282,88 @@ class EditImageTool(BaseTool):
                 required=True
             ),
             ParameterDefinition(
-                name="input_image_urls",
+                name="input_images",
                 param_type=ParameterType.STRING,
-                description="A comma-separated string of URLs to the source images that need to be edited. Some models may only use the first URL.",
+                description=(
+                    "A comma-separated string of image locations (URLs or file paths) to be edited. Logic for providing this:\n"
+                    "1. **Has Context & Image IN Context:** OMIT.\n"
+                    "2. **Has Context & Image NOT in Context:** PROVIDE.\n"
+                    "3. **No Context & Supports Input:** PROVIDE.\n"
+                    "4. **No Context & No Input Support:** OMIT."
+                ),
+                required=False
+            ),
+            ParameterDefinition(
+                name="output_file_path",
+                param_type=ParameterType.STRING,
+                description=(
+                    "Required. The local file path (relative to workspace) where the edited image should be saved. "
+                    "Example: 'assets/images/edited_result.png'"
+                ),
                 required=True
             ),
             ParameterDefinition(
-                name="mask_image_url",
+                name="mask_image",
                 param_type=ParameterType.STRING,
-                description="Optional. A URL to a mask image (PNG). The transparent areas of this mask define where the input image should be edited.",
+                description=(
+                    "Optional. Path or URL to a mask image (PNG) for inpainting. "
+                    "Transparent areas are regenerated; opaque areas stay unchanged."
+                ),
                 required=False
-            )
+            ),
         ]
         return _build_dynamic_image_schema(base_params, cls.MODEL_ENV_VAR, cls.DEFAULT_MODEL)
 
-    async def _execute(self, context, prompt: str, input_image_urls: str, generation_config: Optional[dict] = None, mask_image_url: Optional[str] = None) -> List[str]:
-        model_identifier = _get_configured_model_identifier(self.MODEL_ENV_VAR, self.DEFAULT_MODEL)
-        logger.info(f"edit_image executing with configured model '{model_identifier}'.")
-        client = None
-        try:
-            urls_list = [url.strip() for url in input_image_urls.split(',') if url.strip()]
-            if not urls_list:
-                raise ValueError("The 'input_image_urls' parameter cannot be empty.")
-
-            client = image_client_factory.create_image_client(model_identifier=model_identifier)
-            response = await client.edit_image(
-                prompt=prompt,
-                input_image_urls=urls_list,
-                mask_url=mask_image_url,
-                generation_config=generation_config
-            )
+    async def _execute(
+        self,
+        context,
+        prompt: str,
+        output_file_path: str,
+        input_images: Optional[str] = None,
+        generation_config: Optional[dict] = None,
+        mask_image: Optional[str] = None,
+    ) -> Any:
+        # 1. Resolve Model ID
+        if not self._model_identifier:
+            self._model_identifier = _get_configured_model_identifier(self.MODEL_ENV_VAR, self.DEFAULT_MODEL)
+
+        logger.info(f"edit_image executing with configured model '{self._model_identifier}' for agent '{context.agent_id}'.")
+
+        # 2. Obtain Shared Client (Scoped to Agent ID)
+        if self._client is None:
+            self._client = _SharedImageClientManager.get_client(context.agent_id, self._model_identifier)
+
+        # 3. Process Inputs
+        urls_list = []
+        if input_images:
+             urls_list = [url.strip() for url in input_images.split(',') if url.strip()]
+        
+        # 4. Execute Edit
+        # Note: If urls_list is empty, we still call edit_image.
+        # Conversational clients will interpret this as a text-only follow-up.
+        # Stateless API clients may throw an error if they enforce input images, which is expected behavior.
+        response = await self._client.edit_image(
+            prompt=prompt,
+            input_image_urls=urls_list,
+            mask_url=mask_image,
+            generation_config=generation_config
+        )
+
+        if not response.image_urls:
+            raise ValueError("Image editing failed to return any image URLs.")
+
+        if not output_file_path:
+            raise ValueError("output_file_path is required but was not provided.")
+
+        first_url = response.image_urls[0]
+        
+        # 5. Save to File
+        resolved_path = resolve_safe_path(output_file_path, _get_workspace_root(context))
+        await download_file_from_url(first_url, resolved_path)
 
-            if not response.image_urls:
-                raise ValueError("Image editing failed to return any image URLs.")
+        return {"file_path": str(resolved_path)}
 
-            return response.image_urls
-        finally:
-            if client:
-                await client.cleanup()
+    async def cleanup(self) -> None:
+        if self._client and self._model_identifier and self.agent_id:
+            await _SharedImageClientManager.release_client(self.agent_id, self._model_identifier)
+            self._client = None

autobyteus/tools/operation_executor/journal_manager.py

@@ -0,0 +1,107 @@
+"""
+File: tools/operation_executor/journal_manager.py
+
+This module provides the JournalManager class that handles the journaling of operations for recovery purposes.
+It works in collaboration with the OperationEventProducer to emit real-time events every time an operation is journaled.
+"""
+import os
+import json
+from datetime import datetime
+from tools.operation.operation import Operation
+from tools.operation_executor.operation_event_producer import OperationEventProducer
+
+class JournalManager:
+    """
+    Manages the journaling of operations for recovery purposes.
+    Collaborates with the OperationEventProducer to emit real-time events every time an operation is journaled.
+    """
+
+    def __init__(self, journal_path: str, event_producer: OperationEventProducer):
+        """
+        Initializes the JournalManager with a specified journal path and an event producer.
+
+        Args:
+            journal_path (str): The path where the journal files will be stored.
+            event_producer (OperationEventProducer): The event producer to emit real-time events.
+        """
+        self.journal_path = journal_path
+        self.event_producer = event_producer
+        os.makedirs(journal_path, exist_ok=True)
+
+    def initialize_journal(self, transaction_id: str, user: str = None, description: str = None) -> None:
+        """
+        Prepares the journal for a new transaction.
+
+        Args:
+            transaction_id (str): The unique identifier for the transaction.
+            user (str): The user who initiated the transaction. Default is None.
+            description (str): Description or purpose of the transaction. Default is None.
+        """
+        journal_file = os.path.join(self.journal_path, f"{transaction_id}.json")
+        with open(journal_file, 'w') as file:
+            data = {
+                "transaction_id": transaction_id,
+                "start_time": datetime.now().isoformat(),
+                "user": user,
+                "description": description,
+                "operations": []
+            }
+            json.dump(data, file)
+        self.event_producer.emit_event(f"Journal initialized for transaction {transaction_id}")
+
+
+    def record_operation(self, operation: Operation) -> None:
+        """
+        Records a given operation in the journal.
+
+        Args:
+            operation (Operation): The operation to be recorded.
+        """
+        transaction_id = operation.transaction_id
+        journal_file = os.path.join(self.journal_path, f"{transaction_id}.json")
+        with open(journal_file, 'r+') as file:
+            data = json.load(file)
+            data["operations"].append(operation.to_dict())
+            file.seek(0)
+            json.dump(data, file)
+        self.event_producer.emit_event(f"Operation {operation} recorded in journal for transaction {transaction_id}")
+
+    def finalize_journal(self, transaction_id: str, status: str, error_message: str = None) -> None:
+        """
+        Marks the transaction as complete in the journal.
+
+        Args:
+            transaction_id (str): The unique identifier for the transaction.
+            status (str): The final status of the transaction (e.g., "committed", "rolled_back").
+            error_message (str): Any error message associated with the transaction's end. Default is None.
+        """
+        journal_file = os.path.join(self.journal_path, f"{transaction_id}.json")
+        with open(journal_file, 'r+') as file:
+            data = json.load(file)
+            data["end_time"] = datetime.now().isoformat()
+            data["status"] = status
+            if error_message:
+                data["error_message"] = error_message
+            file.seek(0)
+            json.dump(data, file)
+        self.event_producer.emit_event(f"Journal finalized with status {status} for transaction {transaction_id}")
+
+
+    def log_error(self, transaction_id: str, error_message: str) -> None:
+        """
+        Logs any errors encountered during the transaction's lifecycle.
+
+        Args:
+            transaction_id (str): The unique identifier for the transaction.
+            error_message (str): The error message to be logged.
+        """
+        journal_file = os.path.join(self.journal_path, f"{transaction_id}.json")
+        with open(journal_file, 'r+') as file:
+            data = json.load(file)
+            data.setdefault("errors", []).append({
+                "error_message": error_message,
+                "timestamp": datetime.now().isoformat()
+            })
+            file.seek(0)
+            json.dump(data, file)
+        self.event_producer.emit_event(f"Error logged for transaction {transaction_id}: {error_message}")

autobyteus/tools/operation_executor/operation_event_buffer.py

@@ -0,0 +1,57 @@
+# tools/coordinator/operation_event_buffer.py
+
+"""
+Module for buffering operation events.
+
+The OperationEventBuffer provides a mechanism to temporarily store recent operation events. 
+This ensures that frontend services, which might miss real-time updates, can retrieve the latest events.
+"""
+
+from typing import List
+
+class OperationEventBuffer:
+    """
+    Class to buffer operation events.
+    
+    Attributes:
+        events (List[str]): A list to store recent operation events.
+        max_size (int): Maximum number of events the buffer can store.
+        
+    Methods:
+        add_event(event: str): Adds a new event to the buffer.
+        get_recent_events() -> List[str]: Returns a list of recent events.
+    """
+    
+    def __init__(self, max_size: int = 100):
+        """
+        Initialize the OperationEventBuffer.
+        
+        Args:
+            max_size (int, optional): Maximum number of events the buffer can store. 
+                                      Defaults to 100.
+        """
+        self.events = []
+        self.max_size = max_size
+    
+    def add_event(self, event: str) -> None:
+        """
+        Add a new event to the buffer.
+        
+        If the buffer reaches its max_size, it will remove the oldest event.
+        
+        Args:
+            event (str): The event string to be added to the buffer.
+        """
+        if len(self.events) >= self.max_size:
+            self.events.pop(0)
+        self.events.append(event)
+    
+    def get_recent_events(self) -> List[str]:
+        """
+        Retrieve the list of recent events.
+        
+        Returns:
+            List[str]: List of recent events stored in the buffer.
+        """
+        return self.events
+

autobyteus/tools/operation_executor/operation_event_producer.py

@@ -0,0 +1,29 @@
+#code_start#
+
+# File path: tools/operation_executor/operation_event_producer.py
+
+from autobyteus.tools.operation_executor.operation_event_buffer import OperationEventBuffer
+
+
+class OperationEventProducer:
+    """
+    Class responsible for emitting real-time events for every operation executed or undone.
+    """
+    
+    def __init__(self, event_buffer: OperationEventBuffer):
+        """
+        Initializes the OperationEventProducer with the OperationEventBuffer.
+        
+        Args:
+            event_buffer (OperationEventBuffer): The buffer where events will be stored.
+        """
+        self.event_buffer = event_buffer
+
+    def emit_event(self, event: str):
+        """
+        Emit a real-time event for an operation.
+        
+        Args:
+            event (str): Event to be emitted.
+        """
+        self.event_buffer.add_event(event)

autobyteus/tools/operation_executor/operation_executor.py

@@ -0,0 +1,58 @@
+"""
+# tools/operation_executor/operation_executor.py
+Module to handle the execution and potential reversion of operations.
+"""
+
+from typing import List
+from tools.operation.operation import Operation
+# Note: The below imports are placeholders, actual implementations would need to be linked.
+# from journal_manager import JournalManager
+# from operation_event_producer import OperationEventProducer
+
+class OperationExecutor:
+    """
+    Manages the execution and potential reversion of operations.
+    Interacts with the JournalManager and OperationEventProducer for logging and event emission.
+    """
+    
+    def __init__(self):
+        """
+        Initializes the OperationExecutor with an empty operations list.
+        """
+        self.operations: List[Operation] = []
+        # Assuming instances of JournalManager and OperationEventProducer are passed or instantiated here.
+        # self.journal_manager = JournalManager()
+        # self.event_producer = OperationEventProducer()
+    
+    def add_operation(self, operation: Operation):
+        """
+        Adds an operation to the list of operations to be executed.
+
+        Args:
+            operation (Operation): The operation to be added.
+        """
+        self.operations.append(operation)
+        
+    def execute_operations(self, transaction_id: str):
+        """
+        Executes all operations added to the executor. Logs and emits events for each operation.
+
+        Args:
+            transaction_id (str): The ID of the current transaction.
+        """
+        # self.journal_manager.initialize_journal(transaction_id)
+        for operation in self.operations:
+            operation.execute()
+            # Log the operation and emit event
+            # self.journal_manager.record_operation(operation)
+            # self.event_producer.emit_event(f"Operation {operation} executed.")
+            
+    def rollback_operations(self):
+        """
+        Reverts all executed operations. This is done in reverse order to ensure the correct undoing of operations.
+        """
+        for operation in reversed(self.operations):
+            operation.undo()
+            # Emit event for rollback
+            # self.event_producer.emit_event(f"Operation {operation} rolled back.")
+