Tool Management
===============

The Tool module provides functionality to create, manage, and interact with tools in the Globant Enterprise AI Lab. Tools are reusable components that agents can invoke to perform specific actions, such as API calls, data transformations, or external integrations.

This section covers:

* Creating tools
* Retrieving tool information
* Updating tool configuration
* Listing tools
* Publishing tool revisions
* Deleting tools

For each operation, you have three implementation options:

* `Command Line`_
* `Low-Level Service Layer`_ (using clients)
* `High-Level Service Layer`_ (using managers)


Create Tool
~~~~~~~~~~~

Creates a new tool with specified configuration including parameters, scope, and execution details.

Command Line
^^^^^^^^^^^^

.. code-block:: shell

    geai lab tool create \
      --name "data_processor" \
      --description "Processes and transforms data" \
      --scope builtin

Low-Level Service Layer
^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: python

    from pygeai.lab.tools.clients import ToolClient
    
    client = ToolClient()
    
    tool_data = {
        "name": "data_processor",
        "description": "Processes and transforms data",
        "scope": "builtin",
        "parameters": [
            {
                "key": "input_data",
                "dataType": "String",
                "description": "Data to be processed",
                "isRequired": True
            },
            {
                "key": "api_token",
                "dataType": "String",
                "description": "API token for authentication",
                "isRequired": True,
                "type": "config",
                "value": "secret-uuid"
            }
        ]
    }
    
    response = client.create_tool(tool_data=tool_data, automatic_publish=False)
    print(response)

High-Level Service Layer
^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: python

    from pygeai.lab.managers import AILabManager
    from pygeai.lab.models import Tool, ToolParameter
    
    manager = AILabManager()
    
    parameters = [
        ToolParameter(
            key="input_data",
            data_type="String",
            description="Data to be processed",
            is_required=True
        ),
        ToolParameter(
            key="config_value",
            data_type="String",
            description="Static configuration parameter",
            is_required=True,
            type="config",
            from_secret=False,
            value="static-config-value"
        ),
        ToolParameter(
            key="api_token",
            data_type="String",
            description="Sensitive API token from secret manager",
            is_required=True,
            type="config",
            value="secret-uuid"
        )
    ]
    
    tool = Tool(
        name="data_processor",
        description="Processes and transforms data",
        scope="builtin",
        parameters=parameters
    )
    
    result = manager.create_tool(tool=tool, automatic_publish=False)
    print(f"Created tool: {result.name}, ID: {result.id}")


Get Tool
~~~~~~~~

Retrieves detailed information about a specific tool by its ID or name.

Command Line
^^^^^^^^^^^^

.. code-block:: shell

    geai lab tool get --id "tool-uuid"

Low-Level Service Layer
^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: python

    from pygeai.lab.tools.clients import ToolClient
    
    client = ToolClient()
    
    tool_data = client.get_tool(tool_id="tool-uuid")
    print(tool_data)

High-Level Service Layer
^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: python

    from pygeai.lab.managers import AILabManager
    
    manager = AILabManager()
    
    tool = manager.get_tool(id_or_name="tool-uuid")
    print(f"Tool: {tool.name}")
    print(f"Description: {tool.description}")
    print(f"Scope: {tool.scope}")
    print(f"Parameters: {len(tool.parameters)}")


List Tools
~~~~~~~~~~

Retrieves a list of tools with optional filtering.

Command Line
^^^^^^^^^^^^

.. code-block:: shell

    geai lab tool list --start 0 --count 20

Low-Level Service Layer
^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: python

    from pygeai.lab.tools.clients import ToolClient
    
    client = ToolClient()
    
    tools_list = client.list_tools(start="0", count="20")
    print(tools_list)

High-Level Service Layer
^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: python

    from pygeai.lab.managers import AILabManager
    from pygeai.lab.models import FilterSettings
    
    manager = AILabManager()
    
    filter_settings = FilterSettings(start="0", count="20")
    tools = manager.list_tools(filter_settings=filter_settings)
    
    print(f"Found {len(tools.tools)} tools:")
    for tool in tools.tools:
        print(f"  - {tool.name} (ID: {tool.id}, Scope: {tool.scope})")


Update Tool
~~~~~~~~~~~

Updates an existing tool's configuration.

Command Line
^^^^^^^^^^^^

.. code-block:: shell

    geai lab tool update \
      --id "tool-uuid" \
      --name "enhanced_data_processor" \
      --description "Enhanced data processor with new features"

Low-Level Service Layer
^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: python

    from pygeai.lab.tools.clients import ToolClient
    
    client = ToolClient()
    
    updated_data = {
        "name": "enhanced_data_processor",
        "description": "Enhanced data processor with new features",
        "parameters": [
            {
                "key": "input_data",
                "dataType": "String",
                "description": "Data to be processed with enhanced validation",
                "isRequired": True
            }
        ]
    }
    
    response = client.update_tool(
        tool_id="tool-uuid",
        tool_data=updated_data,
        automatic_publish=False
    )
    print(response)

High-Level Service Layer
^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: python

    from pygeai.lab.managers import AILabManager
    from pygeai.lab.models import Tool, ToolParameter
    
    manager = AILabManager()
    
    # First, get the existing tool
    existing_tool = manager.get_tool(id_or_name="tool-uuid")
    
    # Update fields
    existing_tool.name = "enhanced_data_processor"
    existing_tool.description = "Enhanced data processor with new features"
    
    # Update parameters
    existing_tool.parameters[0].description = "Data to be processed with enhanced validation"
    
    result = manager.update_tool(
        id_or_name="tool-uuid",
        tool=existing_tool,
        automatic_publish=False
    )
    print(f"Updated tool: {result.name}")


Publish Tool Revision
~~~~~~~~~~~~~~~~~~~~~~

Publishes a specific revision of a tool, making it available for use by agents.

Command Line
^^^^^^^^^^^^

.. code-block:: shell

    geai lab tool publish --id "tool-uuid" --revision 3

Low-Level Service Layer
^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: python

    from pygeai.lab.tools.clients import ToolClient
    
    client = ToolClient()
    
    response = client.publish_tool_revision(
        tool_id="tool-uuid",
        revision=3
    )
    print(response)

High-Level Service Layer
^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: python

    from pygeai.lab.managers import AILabManager
    
    manager = AILabManager()
    
    result = manager.publish_tool_revision(
        id_or_name="tool-uuid",
        revision=3
    )
    print(f"Published tool revision: {result}")


Delete Tool
~~~~~~~~~~~

Deletes a specific tool by its ID or name.

Command Line
^^^^^^^^^^^^

.. code-block:: shell

    geai lab tool delete --id "tool-uuid"

Low-Level Service Layer
^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: python

    from pygeai.lab.tools.clients import ToolClient
    
    client = ToolClient()
    
    response = client.delete_tool(tool_id="tool-uuid")
    print(response)

High-Level Service Layer
^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: python

    from pygeai.lab.managers import AILabManager
    
    manager = AILabManager()
    
    result = manager.delete_tool(id_or_name="tool-uuid")
    print(f"Tool deleted: {result}")
