grasp_agents 0.1.5__tar.gz

grasp_agents-0.1.5/.gitignore

@@ -0,0 +1,174 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/latest/usage/project/#working-with-version-control
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc

grasp_agents-0.1.5/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Grasp
+
+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.

grasp_agents-0.1.5/PKG-INFO

@@ -0,0 +1,14 @@
+Metadata-Version: 2.4
+Name: grasp_agents
+Version: 0.1.5
+Summary: Add your description here
+License-File: LICENSE
+Requires-Python: <3.12,>=3.11.4
+Requires-Dist: httpx<1,>=0.27.0
+Requires-Dist: openai<2,>=1.68.2
+Requires-Dist: tenacity>=9.1.2
+Requires-Dist: termcolor<3,>=2.4.0
+Requires-Dist: tqdm<5,>=4.66.2
+Description-Content-Type: text/markdown
+
+# grasp-agents

grasp_agents-0.1.5/README.md

@@ -0,0 +1 @@
+# grasp-agents

grasp_agents-0.1.5/pyproject.toml

@@ -0,0 +1,43 @@
+[project]
+name = "grasp_agents"
+version = "0.1.5"
+description = "Add your description here"
+readme = "README.md"
+requires-python = ">=3.11.4,<3.12"
+dependencies = [
+    "httpx>=0.27.0,<1",
+    "openai>=1.68.2,<2",
+    "tenacity>=9.1.2",
+    "termcolor>=2.4.0,<3",
+    "tqdm>=4.66.2,<5",
+]
+
+[dependency-groups]
+dev = [
+    "dotenv>=0.9.9",
+    "ipython>=8.3.0,<9",
+    "ipykernel>=6.19.1,<7",
+    "ipywidgets>=8.0.4,<9",
+    "widgetsnbextension>=4.0.5,<5",
+    "tk>=0.1.0,<0.2",
+    "types-cachetools>=5.0.1,<6",
+    "keyring>=24.2.0,<25",
+    "pydantic>=2",
+    "pre-commit-uv>=4.1.4",
+    "twine>=5.1.1,<6",
+    "keyrings-google-artifactregistry-auth>=1.1.2,<2",
+    "ruff>=0.11.8",
+    "pyright>=1.1.400",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.sdist]
+include = ["src/grasp_agents"]
+exclude = ["src/grasp_agents/examples", "*.ipynb"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/grasp_agents"]
+exclude = ["src/grasp_agents/examples", "*.ipynb"]

grasp_agents-0.1.5/src/grasp_agents/agent_message.py

@@ -0,0 +1,28 @@
+from collections.abc import Sequence
+from typing import Generic, TypeVar
+from uuid import uuid4
+
+from pydantic import BaseModel, ConfigDict, Field
+
+# from .base_agent import StateT
+from .typing.io import AgentID, AgentPayload, AgentState
+
+_PayloadT = TypeVar("_PayloadT", bound=AgentPayload, covariant=True)  # noqa: PLC0105
+_StateT = TypeVar("_StateT", bound=AgentState, covariant=True)  # noqa: PLC0105
+
+
+class AgentMessage(BaseModel, Generic[_PayloadT, _StateT]):
+    payloads: Sequence[_PayloadT]
+    sender_id: AgentID
+    sender_state: _StateT | None = None
+    recipient_ids: Sequence[AgentID] = Field(default_factory=list)
+
+    message_id: str = Field(default_factory=lambda: str(uuid4())[:8])
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    def __repr__(self) -> str:
+        return (
+            f"From: {self.sender_id}, To: {', '.join(self.recipient_ids)}, "
+            f"Payloads: {len(self.payloads)}"
+        )

grasp_agents-0.1.5/src/grasp_agents/agent_message_pool.py

@@ -0,0 +1,94 @@
+import asyncio
+import logging
+from typing import Any, Generic, Protocol, TypeVar
+
+from .agent_message import AgentMessage
+from .run_context import CtxT, RunContextWrapper
+from .typing.io import AgentID, AgentPayload, AgentState
+
+logger = logging.getLogger(__name__)
+
+
+_MH_PayloadT = TypeVar("_MH_PayloadT", bound=AgentPayload, contravariant=True)  # noqa: PLC0105
+_MH_StateT = TypeVar("_MH_StateT", bound=AgentState, contravariant=True)  # noqa: PLC0105
+
+
+class MessageHandler(Protocol[_MH_PayloadT, _MH_StateT, CtxT]):
+    async def __call__(
+        self,
+        message: AgentMessage[_MH_PayloadT, _MH_StateT],
+        ctx: RunContextWrapper[CtxT] | None,
+        **kwargs: Any,
+    ) -> None: ...
+
+
+class AgentMessagePool(Generic[CtxT]):
+    def __init__(self) -> None:
+        self._queues: dict[
+            AgentID, asyncio.Queue[AgentMessage[AgentPayload, AgentState]]
+        ] = {}
+        self._message_handlers: dict[
+            AgentID, MessageHandler[AgentPayload, AgentState, CtxT]
+        ] = {}
+        self._tasks: dict[AgentID, asyncio.Task[None]] = {}
+
+    async def post(self, message: AgentMessage[AgentPayload, AgentState]) -> None:
+        for recipient_id in message.recipient_ids:
+            queue = self._queues.setdefault(recipient_id, asyncio.Queue())
+            await queue.put(message)
+
+    def register_message_handler(
+        self,
+        agent_id: AgentID,
+        handler: MessageHandler[AgentPayload, AgentState, CtxT],
+        ctx: RunContextWrapper[CtxT] | None = None,
+        **run_kwargs: Any,
+    ) -> None:
+        self._message_handlers[agent_id] = handler
+        self._queues.setdefault(agent_id, asyncio.Queue())
+        if agent_id not in self._tasks:
+            self._tasks[agent_id] = asyncio.create_task(
+                self._process_messages(agent_id, ctx=ctx, **run_kwargs)
+            )
+
+    async def _process_messages(
+        self,
+        agent_id: AgentID,
+        ctx: RunContextWrapper[CtxT] | None = None,
+        **run_kwargs: Any,
+    ) -> None:
+        queue = self._queues[agent_id]
+        while True:
+            try:
+                message = await queue.get()
+                handler = self._message_handlers.get(agent_id)
+                if handler is None:
+                    break
+
+                try:
+                    await self._message_handlers[agent_id](
+                        message, ctx=ctx, **run_kwargs
+                    )
+                except Exception:
+                    logger.exception(f"Error handling message for {agent_id}")
+
+                queue.task_done()
+
+            except Exception:
+                logger.exception(f"Unexpected error in processing loop for {agent_id}")
+
+    async def unregister_message_handler(self, agent_id: AgentID) -> None:
+        if task := self._tasks.get(agent_id):
+            task.cancel()
+            try:
+                await task
+            except asyncio.CancelledError:
+                logger.debug(f"{agent_id} exited")
+
+        self._tasks.pop(agent_id, None)
+        self._queues.pop(agent_id, None)
+        self._message_handlers.pop(agent_id, None)
+
+    async def stop_all(self) -> None:
+        for agent_id in list(self._tasks):
+            await self.unregister_message_handler(agent_id)

grasp_agents-0.1.5/src/grasp_agents/base_agent.py

@@ -0,0 +1,72 @@
+from abc import ABC, abstractmethod
+from typing import Any, Generic, Protocol
+
+from pydantic import BaseModel
+
+from .run_context import CtxT, RunContextWrapper
+from .typing.io import AgentID, AgentPayload, OutT, StateT
+from .typing.tool import BaseTool
+
+
+class ParseOutputHandler(Protocol[OutT, CtxT]):
+    def __call__(
+        self, *args: Any, ctx: RunContextWrapper[CtxT] | None, **kwargs: Any
+    ) -> OutT: ...
+
+
+class BaseAgent(ABC, Generic[OutT, StateT, CtxT]):
+    @abstractmethod
+    def __init__(
+        self,
+        agent_id: AgentID,
+        *,
+        out_schema: type[OutT] = AgentPayload,
+        **kwargs: Any,
+    ) -> None:
+        self._state: StateT
+        self._agent_id = agent_id
+        self._out_schema = out_schema
+        self._parse_output_impl: ParseOutputHandler[OutT, CtxT] | None = None
+
+    def parse_output_handler(
+        self, func: ParseOutputHandler[OutT, CtxT]
+    ) -> ParseOutputHandler[OutT, CtxT]:
+        self._parse_output_impl = func
+
+        return func
+
+    def _parse_output(
+        self, *args: Any, ctx: RunContextWrapper[CtxT] | None = None, **kwargs: Any
+    ) -> OutT:
+        if self._parse_output_impl:
+            return self._parse_output_impl(*args, ctx=ctx, **kwargs)
+
+        return self._out_schema()
+
+    @property
+    def agent_id(self) -> AgentID:
+        return self._agent_id
+
+    @property
+    def state(self) -> StateT:
+        return self._state
+
+    @property
+    def out_schema(self) -> type[OutT]:
+        return self._out_schema
+
+    @abstractmethod
+    async def run(
+        self,
+        inp_items: Any,
+        *,
+        ctx: RunContextWrapper[CtxT] | None = None,
+        **kwargs: Any,
+    ) -> Any:
+        pass
+
+    @abstractmethod
+    def as_tool(
+        self, tool_name: str, tool_description: str, tool_strict: bool = True
+    ) -> BaseTool[BaseModel, BaseModel, CtxT]:
+        pass