Merge branch 'main' into more-coverage

# Conflicts:
#	agentstack/cli/cli.py

Author: bboynton97

MANIFEST.in

@@ -1,3 +1,3 @@
 recursive-include agentstack/templates *
-recursive-include agentstack/tools *
+recursive-include agentstack/_tools *
 include agentstack.json .env .env.example

README.md

@@ -1,4 +1,4 @@
-# AgentStack [![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/release/python-3100/) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+# AgentStack [![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/release/python-3100/) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) ![python-testing](https://github.com/agentops-ai/agentstack/actions/workflows/python-testing.yml/badge.svg) ![mypy](https://github.com/agentops-ai/agentstack/actions/workflows/mypy.yml/badge.svg) [![codecov.io](https://codecov.io/github/agentops-ai/agentstack/coverage.svg?branch=master)](https://codecov.io/github/agentops-ai/agentstack>?branch=master)
 
 <img alt="Logo" align="right" src="https://raw.githubusercontent.com/bboynton97/agentstack-docs/3491fe490ea535e7def74c83182dfa8dcfb1f562/logo/dark-sm.svg" width="20%" />
 
@@ -24,9 +24,10 @@ pip install agentstack
 agentstack init <project_name>
 ```
 
+AgentStack scaffolds your _agent stack_ - the tech stack that collectively is your agent
 
 <p align='center'>
-<img src='https://raw.githubusercontent.com/agentops-ai/agentstack/main/stack.png' width='600' alt='agentstack init'>
+<img src='https://github.com/AgentOps-AI/AgentStack/blob/7b40e53bf7300f69e3291c62d5b45e46ff818245/docs/images/the_agent_stack.png?raw=true' width='600' alt='agentstack init'>
 </p>
 
 ### Get Started Immediately

agentstack/__init__.py

@@ -1,19 +1,23 @@
 """
-This it the beginning of the agentstack public API. 
+This it the beginning of the agentstack public API.
 
 Methods that have been imported into this file are expected to be used by the
-end user inside of their project. 
+end user inside of their project.
 """
+
+from typing import Callable
 from pathlib import Path
 from agentstack import conf
 from agentstack.utils import get_framework
 from agentstack.inputs import get_inputs
+from agentstack import frameworks
 
 ___all___ = [
-    "conf", 
-    "get_tags", 
-    "get_framework", 
-    "get_inputs", 
+    "conf",
+    "tools",
+    "get_tags",
+    "get_framework",
+    "get_inputs",
 ]
 
 
@@ -23,3 +27,18 @@ def get_tags() -> list[str]:
     """
     return ['agentstack', get_framework(), *conf.get_installed_tools()]
 
+
+class ToolLoader:
+    """
+    Provides the public interface for accessing tools, wrapped in the
+    framework-specific callable format.
+
+    Get a tool's callables by name with `agentstack.tools[tool_name]`
+    Include them in your agent's tool list with `tools = [*agentstack.tools[tool_name], ]`
+    """
+
+    def __getitem__(self, tool_name: str) -> list[Callable]:
+        return frameworks.get_tool_callables(tool_name)
+
+
+tools = ToolLoader()

agentstack/_tools/__init__.py

@@ -0,0 +1,125 @@
+from typing import Optional, Protocol, runtime_checkable
+from types import ModuleType
+import os
+import sys
+from pathlib import Path
+from importlib import import_module
+import pydantic
+from agentstack.exceptions import ValidationError
+from agentstack.utils import get_package_path, open_json_file, term_color, snake_to_camel
+
+
+TOOLS_DIR: Path = get_package_path() / '_tools'  # NOTE: if you change this dir, also update MANIFEST.in
+TOOLS_CONFIG_FILENAME: str = 'config.json'
+
+
+class ToolConfig(pydantic.BaseModel):
+    """
+    This represents the configuration data for a tool.
+    It parses and validates the `config.json` file and provides a dynamic
+    interface for interacting with the tool implementation.
+    """
+
+    name: str
+    category: str
+    tools: list[str]
+    url: Optional[str] = None
+    cta: Optional[str] = None
+    env: Optional[dict] = None
+    dependencies: Optional[list[str]] = None
+    post_install: Optional[str] = None
+    post_remove: Optional[str] = None
+
+    @classmethod
+    def from_tool_name(cls, name: str) -> 'ToolConfig':
+        path = TOOLS_DIR / name / TOOLS_CONFIG_FILENAME
+        if not os.path.exists(path):  # TODO raise exceptions and handle message/exit in cli
+            print(term_color(f'No known agentstack tool: {name}', 'red'))
+            sys.exit(1)
+        return cls.from_json(path)
+
+    @classmethod
+    def from_json(cls, path: Path) -> 'ToolConfig':
+        data = open_json_file(path)
+        try:
+            return cls(**data)
+        except pydantic.ValidationError as e:
+            # TODO raise exceptions and handle message/exit in cli
+            print(term_color(f"Error validating tool config JSON: \n{path}", 'red'))
+            for error in e.errors():
+                print(f"{' '.join([str(loc) for loc in error['loc']])}: {error['msg']}")
+            sys.exit(1)
+
+    @property
+    def type(self) -> type:
+        """
+        Dynamically generate a type for the tool module.
+        ie. indicate what methods it's importable module should have.
+        """
+
+        def method_stub(name: str):
+            def not_implemented(*args, **kwargs):
+                raise NotImplementedError(
+                    f"Method '{name}' is configured in config.json for tool '{self.name}'"
+                    f"but has not been implemented in the tool module ({self.module_name})."
+                )
+
+            return not_implemented
+
+        # fmt: off
+        type_ = type(f'{snake_to_camel(self.name)}Module', (Protocol,), {  # type: ignore[arg-type]
+            method_name: method_stub(method_name) for method_name in self.tools
+        },)
+        # fmt: on
+        return runtime_checkable(type_)
+
+    @property
+    def module_name(self) -> str:
+        """Module name for the tool module."""
+        return f"agentstack._tools.{self.name}"
+
+    @property
+    def module(self) -> ModuleType:
+        """
+        Import the tool module and validate that it implements the required methods.
+        Returns the imported module ready for direct use.
+        """
+        try:
+            _module = import_module(self.module_name)
+            assert isinstance(_module, self.type)
+            return _module
+        except AssertionError as e:
+            raise ValidationError(
+                f"Tool module `{self.module_name}` does not match the expected implementation. \n"
+                f"The tool's config.json file lists the following public methods: `{'`, `'.join(self.tools)}` "
+                f"but only implements: '{'`, `'.join([m for m in dir(_module) if not m.startswith('_')])}`"
+            )
+        except ModuleNotFoundError as e:
+            raise ValidationError(
+                f"Could not import tool module: {self.module_name}\n"
+                f"Are you sure you have installed the tool? (agentstack tools add {self.name})\n"
+                f"ModuleNotFoundError: {e}"
+            )
+
+
+def get_all_tool_paths() -> list[Path]:
+    """
+    Get all the paths to the tool configuration files.
+    ie. agentstack/_tools/<tool_name>/
+    Tools are identified by having a `config.json` file inside the _tools/<tool_name> directory.
+    """
+    paths = []
+    for tool_dir in TOOLS_DIR.iterdir():
+        if tool_dir.is_dir():
+            config_path = tool_dir / TOOLS_CONFIG_FILENAME
+            if config_path.exists():
+                paths.append(tool_dir)
+    return paths
+
+
+def get_all_tool_names() -> list[str]:
+    return [path.stem for path in get_all_tool_paths()]
+
+
+def get_all_tools() -> list[ToolConfig]:
+    return [ToolConfig.from_tool_name(path) for path in get_all_tool_names()]

…lates/crewai/tools/agent_connect_tool.py …ntstack/_tools/agent_connect/__init__.pyagentstack/templates/crewai/tools/agent_connect_tool.py renamed to agentstack/_tools/agent_connect/__init__.py agentstack/templates/crewai/tools/agent_connect_tool.py renamed to agentstack/_tools/agent_connect/__init__.py

@@ -1,30 +1,38 @@
-from crewai_tools import tool
-from dotenv import load_dotenv
 import os
-
-from agent_connect.simple_node import SimpleNode
 import json
+from agent_connect.simple_node import SimpleNode
 
-load_dotenv()
 
 # An HTTP and WS service will be started in agent-connect
 # It can be an IP address or a domain name
-host_domain = os.getenv("HOST_DOMAIN")
+host_domain = os.getenv("AGENT_CONNECT_HOST_DOMAIN")
 # Host port, default is 80
-host_port = os.getenv("HOST_PORT")
+host_port = os.getenv("AGENT_CONNECT_HOST_PORT")
 # WS path, default is /ws
-host_ws_path = os.getenv("HOST_WS_PATH")
+host_ws_path = os.getenv("AGENT_CONNECT_HOST_WS_PATH")
 # Path to store DID document
-did_document_path = os.getenv("DID_DOCUMENT_PATH")
+did_document_path = os.getenv("AGENT_CONNECT_DID_DOCUMENT_PATH")
 # SSL certificate path, if using HTTPS, certificate and key need to be provided
-ssl_cert_path = os.getenv("SSL_CERT_PATH")
-ssl_key_path = os.getenv("SSL_KEY_PATH")
+ssl_cert_path = os.getenv("AGENT_CONNECT_SSL_CERT_PATH")
+ssl_key_path = os.getenv("AGENT_CONNECT_SSL_KEY_PATH")
+
+if not host_domain:
+    raise Exception(
+        "Host domain has not been provided.\n"
+        "Did you set the AGENT_CONNECT_HOST_DOMAIN in you project's .env file?"
+    )
+
+if not did_document_path:
+    raise Exception(
+        "DID document path has not been provided.\n"
+        "Did you set the AGENT_CONNECT_DID_DOCUMENT_PATH in you project's .env file?"
+    )
 
 
 def generate_did_info(node: SimpleNode, did_document_path: str) -> None:
     """
     Generate or load DID information for a node.
-    
+
     Args:
         node: SimpleNode instance
         did_document_path: Path to store/load DID document
@@ -33,35 +41,33 @@ def generate_did_info(node: SimpleNode, did_document_path: str) -> None:
         print(f"Loading existing DID information from {did_document_path}")
         with open(did_document_path, "r") as f:
             did_info = json.load(f)
-        node.set_did_info(
-            did_info["private_key_pem"],
-            did_info["did"],
-            did_info["did_document_json"]
-        )
+        node.set_did_info(did_info["private_key_pem"], did_info["did"], did_info["did_document_json"])
     else:
         print("Generating new DID information")
         private_key_pem, did, did_document_json = node.generate_did_document()
         node.set_did_info(private_key_pem, did, did_document_json)
-        
+
         # Save DID information
-        os.makedirs(os.path.dirname(did_document_path), exist_ok=True)
+        if os.path.dirname(did_document_path):  # allow saving to current directory
+            os.makedirs(os.path.dirname(did_document_path), exist_ok=True)
         with open(did_document_path, "w") as f:
-            json.dump({
-                "private_key_pem": private_key_pem,
-                "did": did,
-                "did_document_json": did_document_json
-            }, f, indent=2)
+            json.dump(
+                {"private_key_pem": private_key_pem, "did": did, "did_document_json": did_document_json},
+                f,
+                indent=2,
+            )
         print(f"DID information saved to {did_document_path}")
 
+
 agent_connect_simple_node = SimpleNode(host_domain, host_port, host_ws_path)
 generate_did_info(agent_connect_simple_node, did_document_path)
 agent_connect_simple_node.run()
 
-@tool("Send Message to Agent by DID")
+
 async def send_message(message: str, destination_did: str) -> bool:
     """
     Send a message through agent-connect node.
-    
+
     Args:
         message: Message content to be sent
         destination_did: DID of the recipient agent
@@ -76,11 +82,11 @@ async def send_message(message: str, destination_did: str) -> bool:
         print(f"Failed to send message: {e}")
         return False
 
-@tool("Receive Message from Agent")
+
 async def receive_message() -> tuple[str, str]:
     """
     Receive message from agent-connect node.
-    
+
     Returns:
         tuple[str, str]: Sender DID and received message content, empty string if no message or error occurred
     """

agentstack/_tools/agent_connect/config.json

@@ -0,0 +1,17 @@
+{
+  "name": "agent_connect",
+  "url": "https://github.com/chgaowei/AgentConnect",
+  "category": "network-protocols",
+  "env": {
+    "AGENT_CONNECT_HOST_DOMAIN": null,
+    "AGENT_CONNECT_HOST_PORT": 80,
+    "AGENT_CONNECT_HOST_WS_PATH": "/ws",
+    "AGENT_CONNECT_DID_DOCUMENT_PATH": "data/agent_connect_did.json",
+    "AGENT_CONNECT_SSL_CERT_PATH": null,
+    "AGENT_CONNECT_SSL_KEY_PATH": null
+  },
+  "dependencies": [
+    "agent-connect>=0.3.0"
+  ],
+  "tools": ["send_message", "receive_message"]
+}

agentstack/_tools/browserbase/__init__.py

@@ -0,0 +1,30 @@
+import os
+from typing import Optional, Any
+from browserbase import Browserbase
+
+
+BROWSERBASE_API_KEY = os.getenv("BROWSERBASE_API_KEY")
+BROWSERBASE_PROJECT_ID = os.getenv("BROWSERBASE_PROJECT_ID")
+
+client = Browserbase(BROWSERBASE_API_KEY, BROWSERBASE_PROJECT_ID)
+
+
+# TODO can we define a type for the return value?
+def load_url(
+    url: str,
+    text_content: Optional[bool] = True,
+    session_id: Optional[str] = None,
+    proxy: Optional[bool] = None,
+) -> Any:
+    """
+    Load a URL in a headless browser and return the page content.
+
+    Args:
+        url: URL to load
+        text_content: Return text content if True, otherwise return raw content
+        session_id: Session ID to use for the browser
+        proxy: Use a proxy for the browser
+    Returns:
+        Any: Page content
+    """
+    return client.load_url(url)

agentstack/tools/browserbase.json agentstack/_tools/browserbase/config.jsonagentstack/tools/browserbase.json renamed to agentstack/_tools/browserbase/config.json

@@ -2,11 +2,13 @@
   "name": "browserbase",
   "url": "https://github.com/browserbase/python-sdk",
   "category": "browsing",
-  "packages": ["browserbase", "playwright"],
   "env": {
     "BROWSERBASE_API_KEY": null,
     "BROWSERBASE_PROJECT_ID": null
   },
-  "tools": ["browserbase"],
+  "dependencies": [
+    "browserbase>=1.0.5"
+  ],
+  "tools": ["load_url"],
   "cta": "Create an API key at https://www.browserbase.com/"
 }

agentstack/_tools/code_interpreter/Dockerfile

@@ -0,0 +1,6 @@
+FROM python:3.12-alpine
+
+RUN pip install requests beautifulsoup4 
+
+# Set the working directory
+WORKDIR /workspace