autobyteus 1.1.0__py3-none-any.whl → 1.1.2__py3-none-any.whl

autobyteus/agent/workspace/base_workspace.py

@@ -1,33 +1,35 @@
 # file: autobyteus/autobyteus/agent/workspace/base_workspace.py
 import logging
-from abc import ABC
+from abc import ABC, abstractmethod
 from typing import Optional, Any, Dict, TYPE_CHECKING
+from autobyteus.tools.parameter_schema import ParameterSchema
+from autobyteus.agent.workspace.workspace_meta import WorkspaceMeta
+from autobyteus.agent.workspace.workspace_config import WorkspaceConfig
 
 if TYPE_CHECKING:
     from autobyteus.agent.context import AgentContext
 
 logger = logging.getLogger(__name__)
 
-class BaseAgentWorkspace(ABC):
+class BaseAgentWorkspace(ABC, metaclass=WorkspaceMeta):
     """
     Abstract base class for an agent's workspace or working environment.
-    
-    This class serves as a common ancestor and type hint for various workspace
-    implementations. The AgentContext is injected into this object during the
-    agent's bootstrap process.
+
+    A workspace is a passive data container that describes an agent's operating
+    environment (e.g., a local directory, SSH connection details). It does not
+    implement active operations itself; that is the responsibility of Tools.
     """
 
-    def __init__(self, config: Optional[Dict[str, Any]] = None):
+    def __init__(self, config: Optional[WorkspaceConfig] = None):
         """
         Initializes the BaseAgentWorkspace.
 
         Args:
             config: Optional configuration for the workspace (e.g., base path, credentials).
         """
-        self._config: Dict[str, Any] = config or {}
+        self._config: WorkspaceConfig = config or WorkspaceConfig()
         self.context: Optional['AgentContext'] = None
-        
-        logger.info("BaseAgentWorkspace initialized. Context pending injection.")
+        logger.debug(f"{self.__class__.__name__} instance initialized. Context pending injection.")
 
     def set_context(self, context: 'AgentContext'):
         """
@@ -47,9 +49,29 @@ class BaseAgentWorkspace(ABC):
         return None
 
     @property
-    def config(self) -> Dict[str, Any]:
+    def config(self) -> WorkspaceConfig:
         """Configuration for the workspace. Implementations can use this as needed."""
         return self._config
 
+    # --- Methods for self-description ---
+
+    @classmethod
+    @abstractmethod
+    def get_workspace_type_name(cls) -> str:
+        """Returns the unique, machine-readable type name for this workspace (e.g., 'local_workspace')."""
+        pass
+    
+    @classmethod
+    @abstractmethod
+    def get_description(cls) -> str:
+        """Returns a user-friendly description of this workspace type."""
+        pass
+    
+    @classmethod
+    @abstractmethod
+    def get_config_schema(cls) -> ParameterSchema:
+        """Returns the ParameterSchema defining the configuration arguments needed to create an instance of this workspace."""
+        pass
+
     def __repr__(self) -> str:
         return f"<{self.__class__.__name__} agent_id='{self.agent_id or 'N/A'}>"

autobyteus/agent/workspace/workspace_config.py

@@ -0,0 +1,160 @@
+# file: autobyteus/autobyteus/agent/workspace/workspace_config.py
+import logging
+import json
+from typing import Dict, Any, Mapping
+from collections.abc import Mapping as MappingABC
+
+logger = logging.getLogger(__name__)
+
+def _default_serializer(obj: Any) -> Any:
+    """
+    A robust serializer for objects that might not be JSON-serializable,
+    ensuring a stable representation for hashing and comparison.
+    """
+    try:
+        # For common un-serializable collection types, convert to a sorted list
+        # to ensure a stable representation.
+        if isinstance(obj, set):
+            return sorted(list(obj))
+        # For other objects, repr() is often a good choice for a unique,
+        # and often reconstructible, string representation.
+        return repr(obj)
+    except Exception:
+        # Fallback for any object that fails repr() or other serialization.
+        return f"<unrepresentable object of type {type(obj).__name__}>"
+
+
+class WorkspaceConfig:
+    """
+    An immutable, hashable configuration class for agent workspaces.
+
+    This class stores workspace configuration parameters. It is immutable, meaning
+    that methods like `set` or `update` return a new `WorkspaceConfig` instance
+    rather than modifying the existing one.
+
+    This immutability makes `WorkspaceConfig` instances hashable, allowing them to
+    be used as dictionary keys for caching and reusing workspace instances.
+    """
+    _params: Dict[str, Any]
+    _canonical_rep: str
+
+    def __init__(self, params: Mapping[str, Any] = None):
+        """
+        Initializes the WorkspaceConfig.
+
+        Args:
+            params: A dictionary of configuration parameters. A copy is stored.
+        """
+        self._params = dict(params or {})
+        
+        # Pre-compute canonical representation for hashing and equality.
+        try:
+            self._canonical_rep = json.dumps(self._params, sort_keys=True, default=_default_serializer)
+        except Exception as e:
+            logger.error(f"Failed to create canonical representation for WorkspaceConfig: {e}", exc_info=True)
+            # Fallback for extreme cases
+            self._canonical_rep = repr(self._params)
+
+        logger.debug(f"WorkspaceConfig initialized with params keys: {list(self._params.keys())}")
+
+    def __hash__(self) -> int:
+        return hash(self._canonical_rep)
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, WorkspaceConfig):
+            return NotImplemented
+        return self._canonical_rep == other._canonical_rep
+
+    def to_dict(self) -> Dict[str, Any]:
+        """
+        Convert the WorkspaceConfig to a dictionary representation.
+        
+        Returns:
+            Dict[str, Any]: A copy of the configuration parameters.
+        """
+        return self._params.copy()
+
+    @classmethod
+    def from_dict(cls, config_data: Dict[str, Any]) -> 'WorkspaceConfig':
+        """
+        Create a WorkspaceConfig instance from a dictionary.
+        
+        Args:
+            config_data: Dictionary containing configuration parameters.
+            
+        Returns:
+            A new, immutable WorkspaceConfig instance.
+        """
+        if not isinstance(config_data, dict):
+            raise TypeError("config_data must be a dictionary")
+        return cls(params=config_data)
+
+    def merge(self, other: 'WorkspaceConfig') -> 'WorkspaceConfig':
+        """
+        Merge this WorkspaceConfig with another, with the other taking precedence.
+        
+        Args:
+            other: WorkspaceConfig to merge with this one.
+            
+        Returns:
+            A new, merged WorkspaceConfig instance.
+        """
+        if not isinstance(other, WorkspaceConfig):
+            raise TypeError("Can only merge with another WorkspaceConfig instance")
+        
+        merged_params = self._params.copy()
+        merged_params.update(other._params)
+        return WorkspaceConfig(params=merged_params)
+
+    def get(self, key: str, default: Any = None) -> Any:
+        """
+        Get a configuration parameter.
+        
+        Args:
+            key: The parameter key.
+            default: Default value if key doesn't exist.
+            
+        Returns:
+            The parameter value or default.
+        """
+        return self._params.get(key, default)
+
+    def set(self, key: str, value: Any) -> 'WorkspaceConfig':
+        """
+        Return a new WorkspaceConfig with a key set to a new value.
+        
+        Args:
+            key: The parameter key.
+            value: The parameter value.
+
+        Returns:
+            A new WorkspaceConfig instance with the updated parameter.
+        """
+        new_params = self._params.copy()
+        new_params[key] = value
+        return WorkspaceConfig(params=new_params)
+
+    def update(self, params: Mapping[str, Any]) -> 'WorkspaceConfig':
+        """
+        Return a new WorkspaceConfig with multiple updated parameters.
+        
+        Args:
+            params: Dictionary of parameters to update.
+            
+        Returns:
+            A new WorkspaceConfig instance with the updated parameters.
+        """
+        if not isinstance(params, MappingABC):
+            raise TypeError("params must be a mapping (e.g., a dictionary)")
+        new_params = self._params.copy()
+        new_params.update(params)
+        return WorkspaceConfig(params=new_params)
+
+    def __repr__(self) -> str:
+        return f"WorkspaceConfig(params={self._params})"
+
+    def __len__(self) -> int:
+        return len(self._params)
+
+    def __bool__(self) -> bool:
+        return bool(self._params)

autobyteus/agent/workspace/workspace_definition.py

@@ -0,0 +1,36 @@
+"""
+This module defines the WorkspaceDefinition class, which encapsulates the metadata
+for a specific type of agent workspace.
+"""
+import logging
+from typing import Type, Optional, TYPE_CHECKING
+from autobyteus.tools.parameter_schema import ParameterSchema
+
+if TYPE_CHECKING:
+    from autobyteus.agent.workspace.base_workspace import BaseAgentWorkspace
+
+logger = logging.getLogger(__name__)
+
+class WorkspaceDefinition:
+    """Represents the definition of a discoverable and creatable agent workspace type."""
+    def __init__(self,
+                 workspace_type_name: str,
+                 description: str,
+                 workspace_class: Type['BaseAgentWorkspace'],
+                 config_schema: ParameterSchema):
+        if not all([workspace_type_name, description, workspace_class, config_schema is not None]):
+            raise ValueError("All parameters for WorkspaceDefinition are required.")
+
+        self.workspace_type_name = workspace_type_name
+        self.description = description
+        self.workspace_class = workspace_class
+        self.config_schema = config_schema
+        logger.debug(f"WorkspaceDefinition created for type '{workspace_type_name}'.")
+
+    def to_dict(self) -> dict:
+        """Serializes the definition to a dictionary for API exposure."""
+        return {
+            "workspace_type_name": self.workspace_type_name,
+            "description": self.description,
+            "config_schema": self.config_schema.to_dict()
+        }

autobyteus/agent/workspace/workspace_meta.py

@@ -0,0 +1,37 @@
+"""
+This module contains the metaclass for BaseAgentWorkspace for automatic registration.
+"""
+import logging
+from abc import ABCMeta
+from .workspace_registry import default_workspace_registry
+from .workspace_definition import WorkspaceDefinition
+
+logger = logging.getLogger(__name__)
+
+class WorkspaceMeta(ABCMeta):
+    """Metaclass to automatically register concrete BaseAgentWorkspace subclasses."""
+    def __init__(cls, name, bases, dct):
+        super().__init__(name, bases, dct)
+        
+        if name == 'BaseAgentWorkspace' or getattr(cls, "__abstractmethods__", None):
+            logger.debug(f"Skipping registration for abstract workspace class: {name}")
+            return
+
+        try:
+            workspace_type_name = cls.get_workspace_type_name()
+            description = cls.get_description()
+            config_schema = cls.get_config_schema()
+            
+            definition = WorkspaceDefinition(
+                workspace_type_name=workspace_type_name,
+                description=description,
+                workspace_class=cls,
+                config_schema=config_schema
+            )
+            default_workspace_registry.register(definition)
+            config_params_info = f"config_params: {len(config_schema) if config_schema else 0}"
+            logger.info(f"Auto-registered workspace: '{workspace_type_name}' from class {name} ({config_params_info})")
+        except AttributeError as e:
+            logger.error(f"Workspace class {name} is missing a required static/class method ({e}). Skipping registration.")
+        except Exception as e:
+            logger.error(f"Failed to auto-register workspace class {name}: {e}", exc_info=True)

autobyteus/agent/workspace/workspace_registry.py

@@ -0,0 +1,72 @@
+"""
+This module provides a central registry for agent workspace types.
+"""
+import logging
+from typing import Dict, Any, Optional, List, TYPE_CHECKING
+from autobyteus.utils.singleton import SingletonMeta
+from .workspace_definition import WorkspaceDefinition
+from .workspace_config import WorkspaceConfig
+
+if TYPE_CHECKING:
+    from .base_workspace import BaseAgentWorkspace
+
+logger = logging.getLogger(__name__)
+
+class WorkspaceRegistry(metaclass=SingletonMeta):
+    """
+    A singleton registry for WorkspaceDefinition objects. Workspaces are
+    typically auto-registered via WorkspaceMeta.
+    """
+    def __init__(self):
+        self._definitions: Dict[str, WorkspaceDefinition] = {}
+        logger.info("Core WorkspaceRegistry initialized.")
+
+    def register(self, definition: WorkspaceDefinition):
+        """Registers a workspace definition."""
+        if not isinstance(definition, WorkspaceDefinition):
+            raise TypeError("Can only register WorkspaceDefinition objects.")
+        if definition.workspace_type_name in self._definitions:
+            logger.warning(f"Overwriting workspace definition for type '{definition.workspace_type_name}'.")
+        self._definitions[definition.workspace_type_name] = definition
+
+    def get_definition(self, workspace_type_name: str) -> Optional[WorkspaceDefinition]:
+        """Retrieves a workspace definition by its unique type name."""
+        return self._definitions.get(workspace_type_name)
+
+    def get_all_definitions(self) -> List[WorkspaceDefinition]:
+        """Returns a list of all registered workspace definitions."""
+        return list(self._definitions.values())
+
+    def create_workspace(self, workspace_type_name: str, config: WorkspaceConfig) -> 'BaseAgentWorkspace':
+        """
+        Creates an instance of a workspace.
+
+        Args:
+            workspace_type_name (str): The unique type name of the workspace to create.
+            config (WorkspaceConfig): The configuration object for the workspace.
+
+        Returns:
+            An instance of a BaseAgentWorkspace subclass.
+            
+        Raises:
+            ValueError: If the type is unknown or parameters are invalid.
+        """
+        definition = self.get_definition(workspace_type_name)
+        if not definition:
+            raise ValueError(f"Unknown workspace type: '{workspace_type_name}'")
+
+        is_valid, errors = definition.config_schema.validate_config(config.to_dict())
+        if not is_valid:
+            error_str = ", ".join(errors)
+            raise ValueError(f"Invalid parameters for workspace type '{workspace_type_name}': {error_str}")
+
+        try:
+            workspace_class = definition.workspace_class
+            instance = workspace_class(config=config)
+            logger.info(f"Successfully created instance of workspace type '{workspace_type_name}'.")
+            return instance
+        except Exception as e:
+            logger.error(f"Failed to instantiate workspace class '{definition.workspace_class.__name__}': {e}", exc_info=True)
+            raise RuntimeError(f"Workspace instantiation failed for type '{workspace_type_name}': {e}") from e
+
+default_workspace_registry = WorkspaceRegistry()

autobyteus/cli/__init__.py

@@ -2,9 +2,10 @@
 """
 Command-Line Interface (CLI) utilities for interacting with AutoByteUs components.
 """
-from . import agent_cli 
+from .agent_cli import run
+from .cli_display import InteractiveCLIDisplay
 
 __all__ = [
-    "agent_cli", 
+    "run", 
+    "InteractiveCLIDisplay",
 ]
-