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

autobyteus/agent/lifecycle/base_processor.py

@@ -0,0 +1,109 @@
+# file: autobyteus/agent/lifecycle/base_processor.py
+"""
+Base class for lifecycle processors.
+Follows the same pattern as other processors (InputProcessor, LLMResponseProcessor, etc.)
+"""
+import logging
+from abc import ABC, abstractmethod, ABCMeta
+from typing import TYPE_CHECKING, Any, Dict
+
+from autobyteus.agent.lifecycle.events import LifecycleEvent
+
+if TYPE_CHECKING:
+    from autobyteus.agent.context import AgentContext
+
+logger = logging.getLogger(__name__)
+
+class LifecycleEventProcessorMeta(ABCMeta):
+    """
+    Metaclass that automatically registers subclasses of BaseLifecycleEventProcessor.
+    """
+    def __new__(mcs, name, bases, namespace):
+        cls = super().__new__(mcs, name, bases, namespace)
+        
+        # Avoid registering the base abstract class itself
+        if name != "BaseLifecycleEventProcessor":
+             # Avoid circular imports by importing inside the method
+            from autobyteus.agent.lifecycle.processor_definition import LifecycleEventProcessorDefinition
+            from autobyteus.agent.lifecycle.processor_registry import default_lifecycle_event_processor_registry
+            
+            # Use get_name() if available, otherwise class name. 
+            # Note: get_name is a classmethod on BaseLifecycleEventProcessor, but cls is not fully formed?
+            # Actually, standard pattern calls cls.get_name() if defined.
+            try:
+                # We can instantiate a definition using the class
+                reg_name = cls.get_name()
+                definition = LifecycleEventProcessorDefinition(name=reg_name, processor_class=cls)
+                default_lifecycle_event_processor_registry.register_processor(definition)
+            except Exception as e:
+                # This might happen if get_name fails or other issues during definition creation
+                # Logging as warning because intermediate abstract classes might fail
+                logger.debug(f"Skipping auto-registration for {name}: {e}")
+
+        return cls
+
+
+class BaseLifecycleEventProcessor(ABC, metaclass=LifecycleEventProcessorMeta):
+    """
+    Abstract base class for lifecycle event processors.
+    
+    Users extend this class to add custom logic at specific lifecycle events.
+    Only requires specifying a single event (unlike the legacy hooks system which required
+    source + target status).
+    
+    Example:
+        class MySetupProcessor(BaseLifecycleEventProcessor):
+            @property
+            def event(self) -> LifecycleEvent:
+                return LifecycleEvent.AGENT_READY
+            
+            async def process(self, context, event_data):
+                print("Agent is ready!")
+    """
+
+    @classmethod
+    def get_name(cls) -> str:
+        """
+        Returns the unique name for this processor.
+        Defaults to the class name.
+        """
+        return cls.__name__
+
+    @classmethod
+    def get_order(cls) -> int:
+        """
+        Returns the execution order. Lower numbers execute earlier.
+        Defaults to 500 (normal priority).
+        """
+        return 500
+
+    @classmethod
+    def is_mandatory(cls) -> bool:
+        """
+        Returns True if this processor logic is mandatory and cannot be skipped by user config.
+        Defaults to False.
+        """
+        return False
+
+    @property
+    @abstractmethod
+    def event(self) -> LifecycleEvent:
+        """The lifecycle event this processor handles."""
+        raise NotImplementedError
+
+    @abstractmethod
+    async def process(self, context: 'AgentContext', event_data: Dict[str, Any]) -> None:
+        """
+        Execute processor logic.
+        
+        Args:
+            context: The agent's context with full state access.
+            event_data: Event-specific data (e.g., tool_name for tool events).
+        """
+        raise NotImplementedError
+
+    def __repr__(self) -> str:
+        try:
+            return f"<{self.__class__.__name__} event='{self.event.value}'>"
+        except (NotImplementedError, AttributeError):
+            return f"<{self.__class__.__name__} (unconfigured)>"

autobyteus/agent/lifecycle/events.py

@@ -0,0 +1,35 @@
+# file: autobyteus/agent/lifecycle/events.py
+"""
+Defines the LifecycleEvent enum for user-facing lifecycle extension points.
+These are simplified, intuitive event names that map internally to status changes.
+"""
+from enum import Enum
+
+
+class LifecycleEvent(str, Enum):
+    """
+    User-facing lifecycle events for agent extension.
+    
+    These events provide simple, intuitive hook points without requiring
+    users to understand the internal status machine.
+    """
+    AGENT_READY = "agent_ready"
+    """Triggered once after bootstrap completes and agent is ready for input."""
+    
+    BEFORE_LLM_CALL = "before_llm_call"
+    """Triggered just before sending a request to the LLM."""
+    
+    AFTER_LLM_RESPONSE = "after_llm_response"
+    """Triggered after receiving a complete LLM response."""
+    
+    BEFORE_TOOL_EXECUTE = "before_tool_execute"
+    """Triggered just before a tool starts execution."""
+    
+    AFTER_TOOL_EXECUTE = "after_tool_execute"
+    """Triggered after a tool completes execution."""
+    
+    AGENT_SHUTTING_DOWN = "agent_shutting_down"
+    """Triggered when agent shutdown is initiated."""
+
+    def __str__(self) -> str:
+        return self.value

autobyteus/agent/lifecycle/processor_definition.py

@@ -0,0 +1,36 @@
+# file: autobyteus/agent/lifecycle/processor_definition.py
+import logging
+from typing import Type, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .base_processor import BaseLifecycleEventProcessor
+
+logger = logging.getLogger(__name__)
+
+class LifecycleEventProcessorDefinition:
+    """
+    Represents the definition of a lifecycle event processor.
+    Contains its registered name and the class itself.
+    """
+    def __init__(self, name: str, processor_class: Type['BaseLifecycleEventProcessor']):
+        """
+        Initializes the LifecycleEventProcessorDefinition.
+
+        Args:
+            name: The unique registered name of the processor.
+            processor_class: The class of the lifecycle event processor.
+
+        Raises:
+            ValueError: If name is empty or processor_class is not a type.
+        """
+        if not name or not isinstance(name, str):
+            raise ValueError("Processor name must be a non-empty string.")
+        if not isinstance(processor_class, type):
+            raise ValueError("processor_class must be a class type.")
+        
+        self.name: str = name
+        self.processor_class: Type['BaseLifecycleEventProcessor'] = processor_class
+        logger.debug(f"LifecycleEventProcessorDefinition created: name='{name}', class='{processor_class.__name__}'.")
+
+    def __repr__(self) -> str:
+        return f"<LifecycleEventProcessorDefinition name='{self.name}', class='{self.processor_class.__name__}'>"

autobyteus/agent/lifecycle/processor_registry.py

@@ -0,0 +1,106 @@
+# file: autobyteus/agent/lifecycle/processor_registry.py
+import logging
+from typing import TYPE_CHECKING, Dict, List, Optional, Type
+
+from autobyteus.utils.singleton import SingletonMeta
+from .processor_definition import LifecycleEventProcessorDefinition
+
+if TYPE_CHECKING:
+    from .base_processor import BaseLifecycleEventProcessor
+
+logger = logging.getLogger(__name__)
+
+class LifecycleEventProcessorRegistry(metaclass=SingletonMeta):
+    """
+    A singleton registry for LifecycleEventProcessorDefinition objects.
+    Processors are typically auto-registered via LifecycleEventProcessorMeta.
+    """
+
+    def __init__(self):
+        """Initializes the LifecycleEventProcessorRegistry with an empty store."""
+        self._definitions: Dict[str, LifecycleEventProcessorDefinition] = {}
+        logger.info("LifecycleEventProcessorRegistry initialized.")
+
+    def register_processor(self, definition: LifecycleEventProcessorDefinition) -> None:
+        """
+        Registers a lifecycle event processor definition.
+        """
+        if not isinstance(definition, LifecycleEventProcessorDefinition):
+            raise TypeError(f"Expected LifecycleEventProcessorDefinition instance, got {type(definition).__name__}.")
+
+        processor_name = definition.name
+        if processor_name in self._definitions:
+            logger.warning(f"Overwriting existing lifecycle event processor definition for name: '{processor_name}'.")
+        
+        self._definitions[processor_name] = definition
+        logger.info(f"Lifecycle event processor definition '{processor_name}' (class: '{definition.processor_class.__name__}') registered successfully.")
+
+    def get_processor_definition(self, name: str) -> Optional[LifecycleEventProcessorDefinition]:
+        """
+        Retrieves a lifecycle event processor definition by its name.
+        """
+        if not isinstance(name, str):
+            logger.warning(f"Attempted to retrieve lifecycle event processor definition with non-string name: {type(name).__name__}.")
+            return None
+        definition = self._definitions.get(name)
+        if not definition:
+            logger.debug(f"Lifecycle event processor definition with name '{name}' not found in registry.")
+        return definition
+
+    def get_processor(self, name: str) -> Optional['BaseLifecycleEventProcessor']:
+        """
+        Retrieves an instance of a lifecycle event processor by its name.
+        """
+        definition = self.get_processor_definition(name)
+        if definition:
+            try:
+                return definition.processor_class()
+            except Exception as e:
+                logger.error(f"Failed to instantiate lifecycle event processor '{name}' from class '{definition.processor_class.__name__}': {e}", exc_info=True)
+                return None
+        return None
+
+    def list_processor_names(self) -> List[str]:
+        """
+        Returns an unordered list of names of all registered lifecycle processor definitions.
+        """
+        return list(self._definitions.keys())
+
+    def get_ordered_processor_options(self) -> List['ProcessorOption']:
+        """
+        Returns a list of ProcessorOption objects, sorted by their execution order.
+        """
+        from autobyteus.agent.processor_option import ProcessorOption
+        definitions = list(self._definitions.values())
+        sorted_definitions = sorted(definitions, key=lambda d: d.processor_class.get_order())
+        return [
+            ProcessorOption(
+                name=d.name,
+                is_mandatory=d.processor_class.is_mandatory()
+            ) for d in sorted_definitions
+        ]
+
+    def get_all_definitions(self) -> Dict[str, LifecycleEventProcessorDefinition]:
+        """
+        Returns a shallow copy of the dictionary containing all registered lifecycle processor definitions.
+        """
+        return dict(self._definitions)
+
+    def clear(self) -> None:
+        """Removes all definitions from the registry."""
+        count = len(self._definitions)
+        self._definitions.clear()
+        logger.info(f"Cleared {count} definitions from the LifecycleProcessorRegistry.")
+
+    def __len__(self) -> int:
+        """Returns the number of registered lifecycle processor definitions."""
+        return len(self._definitions)
+
+    def __contains__(self, name: str) -> bool:
+        """Checks if a processor definition is in the registry by name."""
+        if isinstance(name, str):
+            return name in self._definitions
+        return False
+
+# Default instance of the registry
+default_lifecycle_event_processor_registry = LifecycleEventProcessorRegistry()

autobyteus/agent/llm_request_assembler.py

@@ -0,0 +1,98 @@
+from dataclasses import dataclass
+from typing import Any, List, Optional, Union
+
+from autobyteus.llm.prompt_renderers.base_prompt_renderer import BasePromptRenderer
+from autobyteus.llm.user_message import LLMUserMessage
+from autobyteus.llm.utils.messages import Message, MessageRole
+from autobyteus.memory.compaction_snapshot_builder import CompactionSnapshotBuilder
+from autobyteus.memory.memory_manager import MemoryManager
+
+
+@dataclass
+class RequestPackage:
+    messages: List[Message]
+    rendered_payload: Any
+    did_compact: bool
+
+
+class LLMRequestAssembler:
+    def __init__(
+        self,
+        memory_manager: MemoryManager,
+        renderer: BasePromptRenderer,
+        compaction_snapshot_builder: Optional[CompactionSnapshotBuilder] = None,
+        max_episodic: int = 3,
+        max_semantic: int = 20,
+    ):
+        self.memory_manager = memory_manager
+        self.renderer = renderer
+        self.compaction_snapshot_builder = compaction_snapshot_builder or CompactionSnapshotBuilder()
+        self.max_episodic = max_episodic
+        self.max_semantic = max_semantic
+
+    async def prepare_request(
+        self,
+        processed_user_input: Union[str, LLMUserMessage],
+        current_turn_id: Optional[str] = None,
+        system_prompt: Optional[str] = None,
+    ) -> RequestPackage:
+        user_message = self._build_user_message(processed_user_input)
+        self._ensure_system_prompt(system_prompt)
+
+        did_compact = False
+        policy = self.memory_manager.compaction_policy
+        compactor = self.memory_manager.compactor
+
+        if self.memory_manager.compaction_required and policy and compactor:
+            turn_ids = compactor.select_compaction_window()
+            if turn_ids:
+                compactor.compact(turn_ids)
+                bundle = self.memory_manager.retriever.retrieve(
+                    max_episodic=self.max_episodic,
+                    max_semantic=self.max_semantic,
+                )
+                raw_tail = self.memory_manager.get_raw_tail(
+                    policy.raw_tail_turns,
+                    exclude_turn_id=current_turn_id,
+                )
+                snapshot_messages = self.compaction_snapshot_builder.build(
+                    system_prompt=system_prompt or "",
+                    bundle=bundle,
+                    raw_tail=raw_tail,
+                )
+                self.memory_manager.reset_transcript(snapshot_messages)
+                self.memory_manager.clear_compaction_request()
+                did_compact = True
+
+        self.memory_manager.active_transcript.append_message(user_message)
+        final_messages = self.memory_manager.get_transcript_messages()
+        rendered_payload = await self.render_payload(final_messages)
+
+        return RequestPackage(
+            messages=final_messages,
+            rendered_payload=rendered_payload,
+            did_compact=did_compact,
+        )
+
+    async def render_payload(self, messages: List[Message]) -> Any:
+        return await self.renderer.render(messages)
+
+    def _build_user_message(self, processed_user_input: Union[str, LLMUserMessage]) -> Message:
+        if isinstance(processed_user_input, LLMUserMessage):
+            return Message(
+                role=MessageRole.USER,
+                content=processed_user_input.content,
+                image_urls=processed_user_input.image_urls,
+                audio_urls=processed_user_input.audio_urls,
+                video_urls=processed_user_input.video_urls,
+            )
+        return Message(role=MessageRole.USER, content=str(processed_user_input))
+
+    def _ensure_system_prompt(self, system_prompt: Optional[str]) -> None:
+        if not system_prompt:
+            return
+        existing = self.memory_manager.get_transcript_messages()
+        if not existing:
+            self.memory_manager.active_transcript.append_message(
+                Message(role=MessageRole.SYSTEM, content=system_prompt)
+            )

autobyteus/agent/llm_response_processor/__init__.py

@@ -1,16 +1,9 @@
 # file: autobyteus/autobyteus/agent/llm_response_processor/__init__.py
 """
-Components for processing LLM responses, primarily for extracting tool invocations.
+Components for processing LLM responses.
 """
 from .base_processor import BaseLLMResponseProcessor
-from .provider_aware_tool_usage_processor import ProviderAwareToolUsageProcessor
-
-# This __init__ should only export the high-level processors that live in this directory.
-# The low-level parsers and formatters live in the `tools` module and are not
-# part of this module's public API.
 
 __all__ = [
-    # Primary public classes
     "BaseLLMResponseProcessor",
-    "ProviderAwareToolUsageProcessor",
 ]

autobyteus/agent/message/context_file_type.py

@@ -63,7 +63,7 @@ class ContextFileType(str, Enum):
             return cls.PYTHON
         elif extension == ".js":
             return cls.JAVASCRIPT
-        elif extension in [".mp3", ".wav", ".m4a", ".flac", ".ogg"]:
+        elif extension in [".mp3", ".wav", ".m4a", ".flac", ".ogg", ".aac"]:
             return cls.AUDIO
         elif extension in [".mp4", ".mov", ".avi", ".mkv", ".webm"]:
             return cls.VIDEO

autobyteus/agent/runtime/agent_runtime.py

@@ -6,9 +6,11 @@ import concurrent.futures
 from typing import Optional, Any, Callable, Awaitable, TYPE_CHECKING 
 
 from autobyteus.agent.context import AgentContext, AgentContextRegistry
-from autobyteus.agent.phases import AgentOperationalPhase, AgentPhaseManager 
+from autobyteus.agent.status.status_enum import AgentStatus 
+from autobyteus.agent.status.manager import AgentStatusManager 
 from autobyteus.agent.events.notifiers import AgentExternalEventNotifier 
-from autobyteus.agent.events import BaseEvent
+from autobyteus.agent.events import BaseEvent, AgentErrorEvent, AgentStoppedEvent, ShutdownRequestedEvent
+from autobyteus.agent.status.status_update_utils import apply_event_and_derive_status
 from autobyteus.agent.handlers import EventHandlerRegistry
 from autobyteus.agent.runtime.agent_worker import AgentWorker
 
@@ -30,9 +32,9 @@ class AgentRuntime:
         self.event_handler_registry: EventHandlerRegistry = event_handler_registry
         
         self.external_event_notifier: AgentExternalEventNotifier = AgentExternalEventNotifier(agent_id=self.context.agent_id)
-        self.phase_manager: AgentPhaseManager = AgentPhaseManager(context=self.context, notifier=self.external_event_notifier) 
+        self.status_manager: AgentStatusManager = AgentStatusManager(context=self.context, notifier=self.external_event_notifier) 
         
-        self.context.state.phase_manager_ref = self.phase_manager 
+        self.context.state.status_manager_ref = self.status_manager 
         
         self._worker: AgentWorker = AgentWorker(
             context=self.context,
@@ -88,8 +90,8 @@ class AgentRuntime:
             return
         
         logger.info(f"AgentRuntime for '{agent_id}': Starting worker.")
-        # The first meaningful phase change to BOOTSTRAPPING is triggered by the AgentBootstrapper
-        # within the worker's async context.
+        # The first meaningful status change to BOOTSTRAPPING is triggered within
+        # the worker's async initialization sequence.
         self._worker.start() 
         logger.info(f"AgentRuntime for '{agent_id}': Worker start command issued. Worker will initialize itself.")
 
@@ -100,28 +102,31 @@ class AgentRuntime:
             logger.info(f"AgentRuntime '{agent_id}': Worker thread completed successfully.")
         except Exception as e:
             logger.error(f"AgentRuntime '{agent_id}': Worker thread terminated with an exception: {e}", exc_info=True)
-            if not self.context.current_phase.is_terminal():
-                # Since the phase manager is now async, we must run it in a new event loop.
+            if not self.context.current_status.is_terminal():
                 try:
-                    asyncio.run(self.phase_manager.notify_error_occurred("Worker thread exited unexpectedly.", traceback.format_exc()))
+                    asyncio.run(self._apply_event_and_derive_status(
+                        AgentErrorEvent(
+                            error_message="Worker thread exited unexpectedly.",
+                            exception_details=traceback.format_exc()
+                        )
+                    ))
                 except Exception as run_e:
-                    logger.critical(f"AgentRuntime '{agent_id}': Failed to run async error notification: {run_e}")
+                    logger.critical(f"AgentRuntime '{agent_id}': Failed to emit derived error: {run_e}")
         
-        if not self.context.current_phase.is_terminal():
-             # Use asyncio.run() to execute the final async phase transition from a sync callback.
+        if not self.context.current_status.is_terminal():
              try:
-                 asyncio.run(self.phase_manager.notify_final_shutdown_complete())
+                 asyncio.run(self._apply_event_and_derive_status(AgentStoppedEvent()))
              except Exception as run_e:
-                 logger.critical(f"AgentRuntime '{agent_id}': Failed to run async final shutdown notification: {run_e}")
+                 logger.critical(f"AgentRuntime '{agent_id}': Failed to emit derived shutdown complete: {run_e}")
         
     async def stop(self, timeout: float = 10.0) -> None:
         agent_id = self.context.agent_id
         if not self._worker.is_alive() and not self._worker._is_active: 
-            if not self.context.current_phase.is_terminal():
-                await self.phase_manager.notify_final_shutdown_complete()
+            if not self.context.current_status.is_terminal():
+                await self._apply_event_and_derive_status(AgentStoppedEvent())
             return
-        
-        await self.phase_manager.notify_shutdown_initiated() 
+
+        await self._apply_event_and_derive_status(ShutdownRequestedEvent())
         await self._worker.stop(timeout=timeout) 
         
         # LLM instance cleanup is now handled by the AgentWorker before its loop closes.
@@ -130,12 +135,15 @@ class AgentRuntime:
         self._context_registry.unregister_context(agent_id)
         logger.info(f"AgentRuntime for '{agent_id}': Context unregistered.")
 
-        await self.phase_manager.notify_final_shutdown_complete() 
+        await self._apply_event_and_derive_status(AgentStoppedEvent()) 
         logger.info(f"AgentRuntime for '{agent_id}' stop() method completed.")
 
+    async def _apply_event_and_derive_status(self, event: BaseEvent) -> None:
+        await apply_event_and_derive_status(event, self.context)
+
     @property 
-    def current_phase_property(self) -> AgentOperationalPhase: 
-        return self.context.current_phase 
+    def current_status_property(self) -> AgentStatus: 
+        return self.context.current_status 
         
     @property
     def is_running(self) -> bool: