agentspype 0.1.0__tar.gz

agentspype-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Gianluca Pagliara
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

agentspype-0.1.0/PKG-INFO

@@ -0,0 +1,19 @@
+Metadata-Version: 2.1
+Name: agentspype
+Version: 0.1.0
+Summary: A framework for building agents that interact with the world
+Author: Gianluca Pagliara
+Author-email: pagliara.gianluca@gmail.com
+Requires-Python: >=3.13,<4.0
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: eventspype (>=1.0.0,<2.0.0)
+Requires-Dist: pydantic (>=2.10.4,<3.0.0)
+Requires-Dist: pydot (>=3.0.3,<4.0.0)
+Requires-Dist: python-statemachine (>=2.5.0,<3.0.0)
+Description-Content-Type: text/markdown
+
+# Agents Pypeline
+
+A framework for building agents that interact with the world.
+

agentspype-0.1.0/README.md

@@ -0,0 +1,3 @@
+# Agents Pypeline
+
+A framework for building agents that interact with the world.

agentspype-0.1.0/agentspype/agency.py

@@ -0,0 +1,31 @@
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .agent.agent import Agent
+
+
+class Agency:
+    initialized_agents: list["Agent"] = []
+
+    @classmethod
+    def register_agent(cls, agent: "Agent") -> None:
+        """Register an initialized agent."""
+        if agent not in cls.initialized_agents:
+            agent.logger().info(f"[Agency] Registered: {agent.__class__.__name__}")
+            cls.initialized_agents.append(agent)
+
+    @classmethod
+    def deregister_agent(cls, agent: "Agent") -> None:
+        """Deregister an initialized agent."""
+        if agent in cls.initialized_agents:
+            agent.logger().info(f"[Agency] Deregistered: {agent.__class__.__name__}")
+            cls.initialized_agents.remove(agent)
+
+    @classmethod
+    def get_active_agents(cls) -> list["Agent"]:
+        """Get a list of all active agents."""
+        return [
+            agent
+            for agent in cls.initialized_agents
+            if not agent.machine.current_state.final
+        ]

agentspype-0.1.0/agentspype/agent/agent.py

@@ -0,0 +1,79 @@
+import logging
+from typing import TYPE_CHECKING, Any
+
+from ..agency import Agency
+from .configuration import AgentConfiguration
+from .definition import AgentDefinition
+
+if TYPE_CHECKING:
+    from .listening import AgentListening
+    from .publishing import AgentPublishing
+    from .state_machine import AgentStateMachine
+    from .status import AgentStatus
+
+
+class Agent:
+    _logger: logging.Logger | None = None
+
+    # === Definition ===
+
+    definition: AgentDefinition
+
+    # === Initialization ===
+
+    def __init__(self, configuration: AgentConfiguration | dict[str, Any]):
+        self._configuration = (
+            configuration
+            if isinstance(configuration, AgentConfiguration)
+            else self.definition.configuration_class(**configuration)
+        )
+
+        self._events_publishing = self.definition.events_publishing_class(self)
+        self._events_listening = self.definition.events_listening_class(self)
+        self._state_machine = self.definition.state_machine_class(self)
+        self._status = self.definition.status_class()
+
+        Agency.register_agent(self)
+
+        self.initialize()
+
+    def initialize(self) -> None:
+        pass
+
+    def teardown(self) -> None:
+        self.listening.unsubscribe()
+
+        Agency.deregister_agent(self)
+
+    def clone(self) -> "Agent":
+        return self.__class__(self.configuration)
+
+    # === Class Methods ===
+
+    @classmethod
+    def logger(cls) -> logging.Logger:
+        if cls._logger is None:
+            cls._logger = logging.getLogger("agent")
+        return cls._logger
+
+    # === Properties ===
+
+    @property
+    def configuration(self) -> AgentConfiguration:
+        return self._configuration
+
+    @property
+    def machine(self) -> "AgentStateMachine":
+        return self._state_machine
+
+    @property
+    def listening(self) -> "AgentListening":
+        return self._events_listening
+
+    @property
+    def publishing(self) -> "AgentPublishing":
+        return self._events_publishing
+
+    @property
+    def status(self) -> "AgentStatus":
+        return self._status

agentspype-0.1.0/agentspype/agent/configuration.py

@@ -0,0 +1,7 @@
+from pydantic import BaseModel, ConfigDict
+
+
+class AgentConfiguration(BaseModel):
+    """Base configuration class for agents."""
+
+    model_config = ConfigDict(frozen=True, arbitrary_types_allowed=False)

agentspype-0.1.0/agentspype/agent/definition.py

@@ -0,0 +1,19 @@
+from pydantic import BaseModel, ConfigDict
+
+from .configuration import AgentConfiguration
+from .listening import AgentListening
+from .publishing import AgentPublishing
+from .state_machine import AgentStateMachine
+from .status import AgentStatus
+
+
+class AgentDefinition(BaseModel):
+    """Definition of an agent's components and configuration."""
+
+    model_config = ConfigDict(frozen=True)
+
+    state_machine_class: type[AgentStateMachine]
+    events_listening_class: type[AgentListening]
+    events_publishing_class: type[AgentPublishing]
+    configuration_class: type[AgentConfiguration]
+    status_class: type[AgentStatus]

agentspype-0.1.0/agentspype/agent/listening.py

@@ -0,0 +1,33 @@
+import logging
+from abc import abstractmethod
+from typing import TYPE_CHECKING
+
+from eventspype.sub.multisubscriber import MultiSubscriber
+
+if TYPE_CHECKING:
+    from .agent import Agent
+
+
+class AgentListening(MultiSubscriber):
+    def __init__(self, agent: "Agent") -> None:
+        super().__init__()
+        self._agent = agent
+
+    # === Properties ===
+
+    @property
+    def agent(self) -> "Agent":
+        return self._agent
+
+    def logger(self) -> logging.Logger:
+        return self.agent.logger()
+
+    # === Subscriptions ===
+
+    @abstractmethod
+    def subscribe(self) -> None:
+        raise NotImplementedError
+
+    @abstractmethod
+    def unsubscribe(self) -> None:
+        raise NotImplementedError

agentspype-0.1.0/agentspype/agent/publishing.py

@@ -0,0 +1,56 @@
+from dataclasses import dataclass
+from enum import Enum
+from typing import TYPE_CHECKING, Any
+
+from eventspype.pub.multipublisher import MultiPublisher
+from eventspype.pub.publication import EventPublication
+from statemachine import State
+
+if TYPE_CHECKING:
+    from .agent import Agent
+
+
+class AgentPublishing(MultiPublisher):
+    def __init__(self, agent: "Agent") -> None:
+        super().__init__()
+        self._agent = agent
+
+    # === Properties ===
+
+    @property
+    def agent(self) -> "Agent":
+        return self._agent
+
+
+class StateAgentPublishing(AgentPublishing):
+    # === Definitions ===
+
+    class Events(Enum):
+        StateMachineTransition = "sm_transition_event"
+
+    @dataclass
+    class StateMachineEvent:
+        event: Any
+        new_state: State
+
+    # === Publications ===
+
+    sm_transition_event = EventPublication(
+        event_tag=Events.StateMachineTransition, event_class=StateMachineEvent
+    )
+
+    # === Events ===
+
+    def publish_transition(self, event: Any, state: State) -> None:
+        """
+        Publishes a state machine transition event.
+
+        It is recommended to call this method from the state machine.
+        Example:
+            def after_transition(self, event, state):
+                self.agent.publishing.publish_transition(event, state)
+        """
+        self.trigger_event(
+            self.sm_transition_event,
+            self.sm_transition_event.event_class(event, state),
+        )

agentspype-0.1.0/agentspype/agent/state_machine.py

@@ -0,0 +1,134 @@
+from abc import abstractmethod
+from typing import TYPE_CHECKING, Any, ClassVar, TypeVar
+
+from statemachine import State, StateMachine
+from statemachine.factory import StateMachineMetaclass
+from statemachine.transition_list import TransitionList
+
+from .publishing import StateAgentPublishing
+
+if TYPE_CHECKING:
+    from .agent import Agent
+
+
+T = TypeVar("T", bound="AgentStateMachine")
+
+
+class AgentStateMachineMeta(StateMachineMetaclass):
+    """Metaclass for AgentStateMachine that ensures proper state machine inheritance."""
+
+    def __new__(
+        mcs, name: str, bases: tuple[type, ...], namespace: dict[str, Any]
+    ) -> type:
+        # Don't modify the base class
+        if name == "AgentStateMachine":
+            return super().__new__(mcs, name, bases, namespace)
+
+        # Create state definitions if not already defined
+        if "starting" not in namespace:
+            namespace["starting"] = State("Starting", initial=True)
+        if "idle" not in namespace:
+            namespace["idle"] = State("Idle")
+        if "end" not in namespace:
+            namespace["end"] = State("End", final=True)
+
+        # Create transition definitions if not already defined
+        if "start" not in namespace:
+            namespace["start"] = namespace["starting"].to(namespace["idle"])
+        if "stop" not in namespace:
+            namespace["stop"] = namespace["starting"].to(namespace["end"]) | namespace[
+                "idle"
+            ].to(namespace["end"])
+
+        return super().__new__(mcs, name, bases, namespace)
+
+
+class AgentStateMachine(StateMachine, metaclass=AgentStateMachineMeta):
+    """Base class for all agent state machines.
+
+    This class provides the basic state machine structure that all agents should inherit from.
+    Child classes can override states and transitions by defining their own, or inherit the defaults.
+    """
+
+    # === States ===
+
+    starting: ClassVar[State]
+    idle: ClassVar[State]
+    end: ClassVar[State]
+
+    # === Transitions ===
+
+    start: ClassVar[TransitionList]
+    stop: ClassVar[TransitionList]
+
+    def __init__(self, agent: "Agent") -> None:
+        super().__init__()
+        self._agent = agent
+        self._should_stop = False
+
+    # === State actions ===
+
+    def on_enter_end(self) -> None:
+        self.agent.teardown()
+
+    # === Transitions Actions ===
+
+    def before_transition(
+        self, event: str, state: str, source: str, target: str
+    ) -> None:
+        if source == target:
+            return
+
+        self.agent.logger().debug(
+            f"[{self.agent.__class__.__name__}:StateMachine] ({event}) {source} -> {target}"
+        )
+
+    @abstractmethod
+    def after_transition(self, event: str, state: State) -> None:
+        """Handle behavior after a transition.
+
+        This method should be implemented in child classes to handle post-transition behavior.
+        Example implementation:
+            self.agent.publishing.publish_transition(event, state)
+        """
+        raise NotImplementedError
+
+    def on_start(self) -> None:
+        self.agent.listening.subscribe()
+
+    def on_stop(self) -> None:
+        self._should_stop = True
+
+    # === Conditions ===
+
+    def should_stop(self) -> bool:
+        return self._should_stop
+
+    # === Properties ===
+
+    @property
+    def agent(self) -> "Agent":
+        return self._agent
+
+    # === Functions ===
+
+    def safe_stop(self) -> None:
+        """Safely stop the state machine if not already in final state."""
+        if self.current_state.final:
+            return
+        self.stop(f=True)
+
+    # === Diagrams ===
+
+
+# Example of how to create a concrete state machine:
+class BasicAgentStateMachine(AgentStateMachine):
+    """A basic implementation of an agent state machine.
+
+    This class inherits all the default states and transitions from AgentStateMachine.
+    It only needs to implement the required after_transition method.
+    """
+
+    def after_transition(self, event: str, state: State) -> None:
+        if isinstance(self.agent.publishing, StateAgentPublishing):
+            self.agent.publishing.publish_transition(event, state)

agentspype-0.1.0/agentspype/agent/status.py

@@ -0,0 +1,7 @@
+from pydantic import BaseModel, ConfigDict
+
+
+class AgentStatus(BaseModel):
+    """Base status class for agents."""
+
+    model_config = ConfigDict()

agentspype-0.1.0/pyproject.toml

@@ -0,0 +1,72 @@
+[tool.poetry]
+name = "agentspype"
+version = "0.1.0"
+description = "A framework for building agents that interact with the world"
+authors = ["Gianluca Pagliara <pagliara.gianluca@gmail.com>"]
+readme = "README.md"
+
+[tool.poetry.dependencies]
+python = "^3.13"
+pydantic = "^2.10.4"
+python-statemachine = "^2.5.0"
+pydot = "^3.0.3"
+eventspype = "^1.0.0"
+
+[tool.poetry.group.dev.dependencies]
+pytest = "^7.4.3"
+pytest-cov = "^4.1.0"
+black = "^23.11.0"
+isort = "^5.12.0"
+mypy = "^1.7.0"
+safety = "^2.3.5"
+pre-commit = "^3.5.0"
+ruff = "^0.8.4"
+pytest-asyncio = "<0.25.0"
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.black]
+line-length = 88
+target-version = ['py312']
+include = '\.pyi?$'
+
+[tool.isort]
+profile = "black"
+multi_line_output = 3
+line_length = 88
+
+[tool.mypy]
+python_version = "3.13"
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = true
+check_untyped_defs = true
+strict = true
+disallow_untyped_decorators = false
+ignore_missing_imports = true
+disable_error_code = ["misc"]
+exclude = ["tests/.*"]
+
+[tool.ruff]
+line-length = 88
+target-version = "py312"
+
+[tool.ruff.lint]
+select = [
+    "E",   # pycodestyle errors
+    "W",   # pycodestyle warnings
+    "F",   # pyflakes
+    "I",   # isort
+    "C",   # flake8-comprehensions
+    "B",   # flake8-bugbear
+    "UP"   # pyupgrade
+]
+ignore = [
+    "E203",  # See https://github.com/psf/black/issues/315
+    "E501"   # Line too long (handled by black)
+]
+
+[tool.ruff.lint.per-file-ignores]
+"__init__.py" = ["F401"]  # Ignore unused imports in __init__ files