Tool permissions

agentstack/__init__.py

@@ -5,48 +5,56 @@
 end user inside their project.
 """
 
-from typing import Callable
+from typing import Callable, TypeAlias
 from pathlib import Path
 from agentstack import conf
 from agentstack.utils import get_framework
 from agentstack.agents import get_agent, get_all_agents, get_all_agent_names
 from agentstack.tasks import get_task, get_all_tasks, get_all_task_names
 from agentstack.inputs import get_inputs
+from agentstack import _tools
+from agentstack._tools import get_tool
 from agentstack import frameworks
 
 ___all___ = [
-    "conf", 
-    "agent", 
-    "task", 
-    "tools", 
-    "get_tags", 
-    "get_framework", 
-    "get_agent", 
+    "conf",
+    "agent",
+    "task",
+    "tools",
+    "get_tags",
+    "get_framework",
+    "get_tool",
+    "get_agent",
     "get_all_agents",
     "get_all_agent_names",
-    "get_task", 
+    "get_task",
     "get_all_tasks",
     "get_all_task_names",
-    "get_inputs", 
+    "get_inputs",
 ]
 
+
 def agent(func):
     """
-    The `agent` decorator is used to mark a method that implements an Agent. 
+    The `agent` decorator is used to mark a method that implements an Agent.
     """
+
     def wrap(*args, **kwargs):
         """Does not alter the function's behavior; this is just a marker."""
         return func(*args, **kwargs)
+
     return wrap
 
 
 def task(func):
     """
     The `task` decorator is used to mark a method that implements a Task.
     """
+
     def wrap(*args, **kwargs):
         """Does not alter the function's behavior; this is just a marker."""
         return func(*args, **kwargs)
+
     return wrap
 
 
@@ -57,16 +65,38 @@
     return ['agentstack', get_framework(), *conf.get_installed_tools()]
 
 
-class ToolLoader:
+class ToolsMetaclass(type):
     """
-    Provides the public interface for accessing tools, wrapped in the
-    framework-specific callable format.
+    Metaclass for the public tools interface.
 
-    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], ]`
+    Define methods here to expose in the public API. Using a metaclass let's us
+    use methods traditionally only available to instances on the class itself.
     """
 
-    def __getitem__(self, tool_name: str) -> list[Callable]:
+    def __getitem__(cls, tool_name: str) -> list[Callable]:
+        """
+        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], ]`
+        """
         return frameworks.get_tool_callables(tool_name)
 
-tools = ToolLoader()
+    def get_permissions(cls, func: Callable) -> _tools.ToolPermission:
+        """
+        Get the permissions for a tool function.
+        """
+        return _tools.get_permissions(func)
+
+
+class tools(metaclass=ToolsMetaclass):
+    """
+    Provides the public interface for accessing `agentstack._tools` methods and
+    types that we explicitly expose.
+
+    Access wrapped tools with `agentstack.tools[tool_name]`
+
+    Access tool permissions with `agentstack.tools.get_permissions(func)`
+
+    Access the tool Action type with `agentstack.tools.Action`
+    """
+
+    Action: TypeAlias = _tools.Action