{
  "name": "forge.tool",
  "language": "python",
  "version": "0.1.0",
  "description": "Python tool package; imports are explicit from this package.",
  "manifest": "forge-py/pyproject.toml",
  "manifestSha256": "7f96957378b21995bf2e583af2afd1b9e6fb3b0089ff3559d62c7e012a034696",
  "status": "source-reference",
  "registryPublicationVerified": false,
  "route": "/libraries/python/tool",
  "features": {},
  "files": [
    {
      "path": "forge-py/src/forge/tool/__init__.py",
      "sha256": "047fa45989a08b35c130afdbb798c19668f64b516f24fa022f5b2eb460a3185f",
      "artifactSha256": "28d69b72fa6f67aa35514ea203324675498d278be7ac7383814ec012dc8704dd",
      "url": "/reference/source/forge-py/src/forge/tool/__init__.py.txt",
      "declarations": []
    },
    {
      "path": "forge-py/src/forge/tool/approval.py",
      "sha256": "6ee6480bab1381f983e59a7fe4216b5ff7e7c2873f8d637bc451381465cd37bb",
      "artifactSha256": "0804957fbde857b92bc1fe5bb01c6d43f31975aad1433750686a99e7edf4fc52",
      "url": "/reference/source/forge-py/src/forge/tool/approval.py.txt",
      "declarations": [
        {
          "name": "ApprovalHandler",
          "line": 22,
          "signature": "class ApprovalHandler(ABC)",
          "documentation": "Abstract base class for tool approval decisions.\n\nANVIL Spec section 8.6: The approval step is mandatory."
        },
        {
          "name": "ApprovalHandler.approve",
          "line": 29,
          "signature": "async def approve(self, tool_call: ToolCall, tool_definition: ToolDefinition) -> ToolApproval",
          "documentation": "Decide whether to approve a tool call.\n\nArgs:\n    tool_call: The tool call to evaluate.\n    tool_definition: The tool definition.\n\nReturns:\n    An approval decision (Approve, Deny, or Modify)."
        },
        {
          "name": "AutoApproveHandler",
          "line": 45,
          "signature": "class AutoApproveHandler(ApprovalHandler)",
          "documentation": "An approval handler that automatically approves all tool calls.\n\nThis is the default handler for development and testing. Production\ndeployments should use a more restrictive handler.\n\nExample:\n    >>> import asyncio\n    >>> from forge.core.tool import ToolCall, ToolDefinition, ToolTier\n    >>> from forge.core.schema import JsonSchema\n    >>> handler = AutoApproveHandler()\n    >>> call = ToolCall(id=\"c1\", name=\"test\", arguments={})\n    >>> defn = ToolDefinition(\n    ...     name=\"test\", description=\"test\", parameters=JsonSchema.object_(), tier=ToolTier.EXTERNAL\n    ... )\n    >>> # result = asyncio.run(handler.approve(call, defn))"
        },
        {
          "name": "AutoApproveHandler.approve",
          "line": 63,
          "signature": "async def approve(self, tool_call: ToolCall, tool_definition: ToolDefinition) -> ToolApproval",
          "documentation": "Automatically approve the tool call.\n\nArgs:\n    tool_call: The tool call (ignored).\n    tool_definition: The tool definition (ignored).\n\nReturns:\n    ToolApprovalApprove."
        }
      ]
    },
    {
      "path": "forge-py/src/forge/tool/definition.py",
      "sha256": "4443e54f5aa9acaf27a32023e85a3146940fcf64f5d7160c45b48a02f19fb1b1",
      "artifactSha256": "e90f7aae5f0b7236851021d4a753476b0711a70f27cac881e1072de86d513ddd",
      "url": "/reference/source/forge-py/src/forge/tool/definition.py.txt",
      "declarations": [
        {
          "name": "ToolWithHandler",
          "line": 21,
          "signature": "class ToolWithHandler()",
          "documentation": "A tool definition paired with its execution handler.\n\nArgs:\n    definition: The tool definition.\n    handler: Async function that executes the tool."
        },
        {
          "name": "create_tool",
          "line": 33,
          "signature": "def create_tool(name: str, description: str, parameters: JsonSchema, handler: ToolHandler, *, tier: ToolTier=ToolTier.EXTERNAL) -> ToolWithHandler",
          "documentation": "Create a tool definition with an execution handler.\n\nThis is the primary way to define tools in the Forge SDK.\n\nANVIL Spec section 8.2: Every tool has a name, description, parameters, and tier.\n\nArgs:\n    name: Unique tool name.\n    description: Human-readable description shown to the model.\n    parameters: JSON Schema for the tool's parameters.\n    handler: Async function that processes tool arguments and returns a string result.\n    tier: Tool tier classification (default: External/Tier 2).\n\nReturns:\n    A ToolWithHandler containing both the definition and handler.\n\nExample:\n    >>> import asyncio\n    >>> from forge.core.schema import JsonSchema\n    >>> async def my_handler(args: dict) -> str:\n    ...     return f\"Result: {args}\"\n    >>> tool = create_tool(\"my_tool\", \"Does something\", JsonSchema.object_(), my_handler)\n    >>> tool.definition.name\n    'my_tool'"
        }
      ]
    },
    {
      "path": "forge-py/src/forge/tool/execution.py",
      "sha256": "5da0ac8ee79b67c3372036fa8dda969ebb1fcd58eff9f9322f0385b9914fb967",
      "artifactSha256": "8a485ba34c6ac1c32765e21551b9b4788fe0e0098af101e126ffcda6c2668196",
      "url": "/reference/source/forge-py/src/forge/tool/execution.py.txt",
      "declarations": [
        {
          "name": "ToolExecutor",
          "line": 21,
          "signature": "class ToolExecutor()",
          "documentation": "Executes tool calls through validation, approval, and invocation.\n\nThe executor follows the ANVIL tool execution lifecycle:\n1. Look up tool definition in registry\n2. Validate arguments against parameter schema\n3. Submit to approval handler\n4. Execute the handler function\n5. Return the result\n\nANVIL Spec sections 8.5-8.7: Tool Execution Lifecycle.\n\nArgs:\n    registry: The tool registry containing available tools.\n    approval_handler: The approval handler for gating tool calls.\n        Defaults to AutoApproveHandler.\n\nExample:\n    >>> executor = ToolExecutor(ToolRegistry())"
        },
        {
          "name": "ToolExecutor.__init__",
          "line": 42,
          "signature": "def __init__(self, registry: ToolRegistry, approval_handler: ApprovalHandler | None=None) -> None",
          "documentation": ""
        },
        {
          "name": "ToolExecutor.execute",
          "line": 50,
          "signature": "async def execute(self, tool_call: ToolCall) -> ToolResult",
          "documentation": "Execute a tool call through the full lifecycle.\n\nArgs:\n    tool_call: The tool call to execute.\n\nReturns:\n    The tool result.\n\nRaises:\n    ForgeToolExecutionError: If the tool is not found, validation fails,\n        the call is denied, or execution fails."
        }
      ]
    },
    {
      "path": "forge-py/src/forge/tool/registry.py",
      "sha256": "651bca180e21638b5fe19459750a79b687e8e26ef7615346d392b347050a8cf0",
      "artifactSha256": "5027f7740a1aeba06af540e0eef707c8375d1e855378c09059d3aba7afcd8f4b",
      "url": "/reference/source/forge-py/src/forge/tool/registry.py.txt",
      "declarations": [
        {
          "name": "ToolRegistry",
          "line": 12,
          "signature": "class ToolRegistry()",
          "documentation": "Registry of tools available to an agent.\n\nThe registry maps tool names to their definitions and handlers. Agents\nuse the registry to discover available tools and execute them.\n\nANVIL Spec section 8.3: Tool Discovery.\n\nExample:\n    >>> registry = ToolRegistry()\n    >>> registry.is_empty()\n    True"
        },
        {
          "name": "ToolRegistry.__init__",
          "line": 26,
          "signature": "def __init__(self) -> None",
          "documentation": ""
        },
        {
          "name": "ToolRegistry.register",
          "line": 29,
          "signature": "def register(self, tool: ToolWithHandler) -> None",
          "documentation": "Register a tool.\n\nArgs:\n    tool: The tool definition with handler to register.\n\nRaises:\n    ValueError: If a tool with the same name is already registered."
        },
        {
          "name": "ToolRegistry.get",
          "line": 43,
          "signature": "def get(self, name: str) -> ToolWithHandler | None",
          "documentation": "Retrieve a registered tool by name.\n\nArgs:\n    name: The tool name.\n\nReturns:\n    The tool with handler, or None if not found."
        },
        {
          "name": "ToolRegistry.get_definition",
          "line": 54,
          "signature": "def get_definition(self, name: str) -> ToolDefinition | None",
          "documentation": "Retrieve a tool definition by name.\n\nArgs:\n    name: The tool name.\n\nReturns:\n    The tool definition, or None if not found."
        },
        {
          "name": "ToolRegistry.get_handler",
          "line": 66,
          "signature": "def get_handler(self, name: str) -> ToolHandler | None",
          "documentation": "Retrieve a tool handler by name.\n\nArgs:\n    name: The tool name.\n\nReturns:\n    The tool handler function, or None if not found."
        },
        {
          "name": "ToolRegistry.definitions",
          "line": 78,
          "signature": "def definitions(self) -> list[ToolDefinition]",
          "documentation": "Return all registered tool definitions.\n\nReturns:\n    List of all tool definitions."
        },
        {
          "name": "ToolRegistry.names",
          "line": 86,
          "signature": "def names(self) -> list[str]",
          "documentation": "Return all registered tool names.\n\nReturns:\n    List of tool names."
        },
        {
          "name": "ToolRegistry.is_empty",
          "line": 98,
          "signature": "def is_empty(self) -> bool",
          "documentation": "Return True if no tools are registered.\n\nReturns:\n    True if the registry is empty."
        },
        {
          "name": "ToolRegistry.unregister",
          "line": 106,
          "signature": "def unregister(self, name: str) -> bool",
          "documentation": "Remove a tool from the registry.\n\nArgs:\n    name: The tool name to remove.\n\nReturns:\n    True if the tool was found and removed."
        }
      ]
    }
  ]
}