Download core/agentpress/tool.py from Kyrlos11/nniback: direct link, hf CLI and curl.
- Browser
- Download file 10.2 kB
-
https://huggingface.co/spaces/Kyrlos11/nniback/resolve/main/core/agentpress/tool.py
- Command line
-
hf download hf://spaces/Kyrlos11/nniback/core/agentpress/tool.py
-
curl -L -o tool.py https://huggingface.co/spaces/Kyrlos11/nniback/resolve/main/core/agentpress/tool.py
10.2 kB
| """ | |
| Core tool system providing the foundation for creating and managing tools. | |
| This module defines the base classes and decorators for creating tools: | |
| - Tool base class for implementing tool functionality | |
| - Schema decorators for OpenAPI tool definitions | |
| - Metadata decorators for tool and method information | |
| - Result containers for standardized tool outputs | |
| """ | |
| from typing import Dict, Any, Union, Optional, List | |
| from dataclasses import dataclass, field | |
| from abc import ABC | |
| import json | |
| import inspect | |
| from enum import Enum | |
| from core.utils.logger import logger | |
| class SchemaType(Enum): | |
| """Enumeration of supported schema types for tool definitions.""" | |
| OPENAPI = "openapi" | |
| class ToolSchema: | |
| """Container for tool schemas with type information. | |
| Attributes: | |
| schema_type (SchemaType): Type of schema (OpenAPI) | |
| schema (Dict[str, Any]): The actual schema definition | |
| """ | |
| schema_type: SchemaType | |
| schema: Dict[str, Any] | |
| class ToolResult: | |
| """Container for tool execution results. | |
| Attributes: | |
| success (bool): Whether the tool execution succeeded | |
| output (Any): Output data (can be dict, list, or string) | |
| """ | |
| success: bool | |
| output: Any | |
| class ToolMetadata: | |
| """Container for tool-level metadata. | |
| Attributes: | |
| display_name (str): Human-readable tool name | |
| description (str): Tool description (short, for minimal index) | |
| icon (Optional[str]): Icon identifier for UI | |
| color (Optional[str]): Color class for UI styling | |
| is_core (bool): Whether this is a core tool (always enabled) | |
| weight (int): Sort order (lower = higher priority, default 100) | |
| visible (bool): Whether tool is visible in frontend UI (default False) | |
| usage_guide (Optional[str]): Detailed usage instructions loaded on-demand | |
| """ | |
| display_name: str | |
| description: str | |
| icon: Optional[str] = None | |
| color: Optional[str] = None | |
| is_core: bool = False | |
| weight: int = 100 | |
| visible: bool = False | |
| usage_guide: Optional[str] = None | |
| class MethodMetadata: | |
| """Container for method-level metadata. | |
| Attributes: | |
| display_name (str): Human-readable method name | |
| description (str): Method description | |
| is_core (bool): Whether this is a core method (always enabled) | |
| visible (bool): Whether method is visible in frontend UI (default True) | |
| """ | |
| display_name: str | |
| description: str | |
| is_core: bool = False | |
| visible: bool = True | |
| class Tool(ABC): | |
| """Abstract base class for all tools. | |
| Provides the foundation for implementing tools with schema registration | |
| and result handling capabilities. | |
| Attributes: | |
| _schemas (Dict[str, List[ToolSchema]]): Registered schemas for tool methods | |
| _metadata (Optional[ToolMetadata]): Tool-level metadata | |
| _method_metadata (Dict[str, MethodMetadata]): Method-level metadata | |
| Methods: | |
| get_schemas: Get all registered tool schemas | |
| get_metadata: Get tool metadata | |
| get_method_metadata: Get metadata for all methods | |
| success_response: Create a successful result | |
| fail_response: Create a failed result | |
| """ | |
| def __init__(self): | |
| """Initialize tool with empty schema registry.""" | |
| self._schemas: Dict[str, List[ToolSchema]] = {} | |
| self._metadata: Optional[ToolMetadata] = None | |
| self._method_metadata: Dict[str, MethodMetadata] = {} | |
| # logger.debug(f"Initializing tool class: {self.__class__.__name__}") | |
| self._register_metadata() | |
| self._register_schemas() | |
| def _register_metadata(self): | |
| """Register metadata from class and method decorators.""" | |
| # Register tool-level metadata | |
| if hasattr(self.__class__, '__tool_metadata__'): | |
| self._metadata = self.__class__.__tool_metadata__ | |
| # Register method-level metadata | |
| for name, method in inspect.getmembers(self, predicate=inspect.ismethod): | |
| if hasattr(method, '__method_metadata__'): | |
| self._method_metadata[name] = method.__method_metadata__ | |
| def _register_schemas(self): | |
| """Register schemas from all decorated methods.""" | |
| for name, method in inspect.getmembers(self, predicate=inspect.ismethod): | |
| if hasattr(method, 'tool_schemas'): | |
| self._schemas[name] = method.tool_schemas | |
| # logger.debug(f"Registered schemas for method '{name}' in {self.__class__.__name__}") | |
| def get_schemas(self) -> Dict[str, List[ToolSchema]]: | |
| """Get all registered tool schemas. | |
| Returns: | |
| Dict mapping method names to their schema definitions | |
| """ | |
| return self._schemas | |
| def get_metadata(self) -> Optional[ToolMetadata]: | |
| """Get tool-level metadata. | |
| Returns: | |
| ToolMetadata object or None if not set | |
| """ | |
| return self._metadata | |
| def get_method_metadata(self) -> Dict[str, MethodMetadata]: | |
| """Get metadata for all methods. | |
| Returns: | |
| Dict mapping method names to their metadata | |
| """ | |
| return self._method_metadata | |
| def success_response(self, data: Union[Dict[str, Any], str, list]) -> ToolResult: | |
| """Create a successful tool result. | |
| Args: | |
| data: Result data (dictionary, list, or string) | |
| Returns: | |
| ToolResult with success=True and data as JSON string (if dict/list) or plain string | |
| """ | |
| if isinstance(data, (dict, list)): | |
| output = json.dumps(data) | |
| else: | |
| output = str(data) | |
| return ToolResult(success=True, output=output) | |
| def fail_response(self, msg: str) -> ToolResult: | |
| """Create a failed tool result. | |
| Args: | |
| msg: Error message describing the failure | |
| Returns: | |
| ToolResult with success=False and error message | |
| """ | |
| # logger.debug(f"Tool {self.__class__.__name__} returned failed result: {msg}") | |
| return ToolResult(success=False, output=msg) | |
| def _add_schema(func, schema: ToolSchema): | |
| """Helper to add schema to a function.""" | |
| if not hasattr(func, 'tool_schemas'): | |
| func.tool_schemas = [] | |
| func.tool_schemas.append(schema) | |
| # logger.debug(f"Added {schema.schema_type.value} schema to function {func.__name__}") | |
| return func | |
| def openapi_schema(schema: Dict[str, Any]): | |
| """Decorator for OpenAPI schema tools.""" | |
| def decorator(func): | |
| # logger.debug(f"Applying OpenAPI schema to function {func.__name__}") | |
| return _add_schema(func, ToolSchema( | |
| schema_type=SchemaType.OPENAPI, | |
| schema=schema | |
| )) | |
| return decorator | |
| def tool_metadata( | |
| display_name: str, | |
| description: str, | |
| icon: Optional[str] = None, | |
| color: Optional[str] = None, | |
| is_core: bool = False, | |
| weight: int = 100, | |
| visible: bool = False, | |
| usage_guide: Optional[str] = None | |
| ): | |
| """Decorator to add metadata to a Tool class. | |
| Args: | |
| display_name: Human-readable tool name | |
| description: Tool description (short, shown in minimal index) | |
| icon: Icon identifier for UI (optional) | |
| color: Color class for UI styling (optional) | |
| is_core: Whether this is a core tool that's always enabled | |
| weight: Sort order (lower = higher priority, default 100) | |
| Examples: Core tools=10, File ops=20, Advanced=90 | |
| visible: Whether tool is visible in frontend UI (default True) | |
| Set to False to hide from UI (internal/experimental tools) | |
| usage_guide: Detailed usage instructions loaded on-demand by the agent. | |
| Contains comprehensive documentation, examples, and best practices. | |
| Usage: | |
| @tool_metadata( | |
| display_name="File Operations", | |
| description="Create, read, edit, and manage files", | |
| icon="FolderOpen", | |
| color="bg-blue-100 dark:bg-blue-800/50", | |
| weight=20, | |
| visible=True, | |
| usage_guide=''' | |
| ### FILE OPERATIONS GUIDE | |
| - create_file(path, content): Create new files | |
| - read_file(path): Read file contents | |
| ... | |
| ''' | |
| ) | |
| class SandboxFilesTool(Tool): | |
| ... | |
| """ | |
| def decorator(cls): | |
| cls.__tool_metadata__ = ToolMetadata( | |
| display_name=display_name, | |
| description=description, | |
| icon=icon, | |
| color=color, | |
| is_core=is_core, | |
| weight=weight, | |
| visible=visible, | |
| usage_guide=usage_guide | |
| ) | |
| return cls | |
| return decorator | |
| def method_metadata( | |
| display_name: str, | |
| description: str, | |
| is_core: bool = False, | |
| visible: bool = True | |
| ): | |
| """Decorator to add metadata to a tool method. | |
| Args: | |
| display_name: Human-readable method name | |
| description: Method description | |
| is_core: Whether this is a core method that's always enabled | |
| visible: Whether method is visible in frontend UI (default True) | |
| Set to False to hide from UI (internal/experimental methods) | |
| Usage: | |
| @method_metadata( | |
| display_name="Create File", | |
| description="Create new files with content", | |
| visible=True | |
| ) | |
| @openapi_schema({...}) | |
| def create_file(self, ...): | |
| ... | |
| # Example: Hidden from UI (internal method) | |
| @method_metadata( | |
| display_name="Internal Helper", | |
| description="Internal functionality not shown in UI", | |
| visible=False | |
| ) | |
| @openapi_schema({...}) | |
| def internal_method(self, ...): | |
| ... | |
| """ | |
| def decorator(func): | |
| func.__method_metadata__ = MethodMetadata( | |
| display_name=display_name, | |
| description=description, | |
| is_core=is_core, | |
| visible=visible | |
| ) | |
| return func | |
| return decorator | |