pygeai 0.1.51b3__py3-none-any.whl → 0.6.0b15__py3-none-any.whl

pygeai/lab/tools/clients.py

@@ -1,21 +1,19 @@
 import json
-from json import JSONDecodeError
 
-from pygeai.core.base.clients import BaseClient
+from pygeai import logger
+from pygeai.core.common.exceptions import InvalidAPIResponseException, MissingRequirementException, APIResponseError
+from pygeai.core.utils.validators import validate_status_code
+from pygeai.core.utils.parsers import parse_json_response
+from pygeai.lab.constants import VALID_SCOPES, VALID_ACCESS_SCOPES, VALID_REPORT_EVENTS
 from pygeai.lab.tools.endpoints import CREATE_TOOL_V2, LIST_TOOLS_V2, GET_TOOL_V2, UPDATE_TOOL_V2, UPSERT_TOOL_V2, \
     PUBLISH_TOOL_REVISION_V2, GET_PARAMETER_V2, SET_PARAMETER_V2, DELETE_TOOL_V2
+from pygeai.lab.clients import AILabClient
 
 
-VALID_SCOPES = ["builtin", "external", "api", "proxied"]
-VALID_ACCESS_SCOPES = ["public", "private"]
-VALID_REPORT_EVENTS = ["None", "All", "Start", "Finish", "Progress"]
-
-
-class ToolClient(BaseClient):
+class ToolClient(AILabClient):
 
     def create_tool(
             self,
-            project_id: str,
             name: str,
             description: str = None,
             scope: str = None,
@@ -31,7 +29,6 @@ class ToolClient(BaseClient):
         """
         Creates a new tool in the specified project.
 
-        :param project_id: str - Unique identifier of the project where the tool will be created.
         :param name: str - Name of the tool. Must be non-empty, unique within the project, and exclude ':' or '/'.
         :param description: str - Description of the tool's purpose, helping agents decide when to use it. Optional.
         :param scope: str - Scope of the tool, either 'builtin', 'external', or 'api'. Optional.
@@ -100,33 +97,22 @@ class ToolClient(BaseClient):
         if parameters:
             data["tool"]["parameters"] = parameters
 
+        logger.debug(f"Creating new tool with data: {data}")
+
         endpoint = CREATE_TOOL_V2
         if automatic_publish:
             endpoint = f"{endpoint}?automaticPublish=true"
 
-        headers = {
-            "Accept": "application/json",
-            "Content-Type": "application/json",
-            "Authorization": self.api_service.token,
-            "ProjectId": project_id
-        }
-
         response = self.api_service.post(
             endpoint=endpoint,
-            headers=headers,
             data=data
         )
-
-        try:
-            result = response.json()
-        except JSONDecodeError as e:
-            result = response.text
-
-        return result
+        
+        validate_status_code(response)
+        return parse_json_response(response, f"create tool for project {self.project_id}")
 
     def list_tools(
             self,
-            project_id: str,
             id: str = "",
             count: str = "100",
             access_scope: str = "public",
@@ -137,7 +123,6 @@ class ToolClient(BaseClient):
         """
         Retrieves a list of tools associated with the specified project.
 
-        :param project_id: str - Unique identifier of the project.
         :param id: str - ID of the tool to filter by. Defaults to "" (no filtering).
         :param count: str - Number of tools to retrieve. Defaults to "100".
         :param access_scope: str - Access scope of the tools, either "public" or "private". Defaults to "public".
@@ -147,17 +132,14 @@ class ToolClient(BaseClient):
         :return: dict or str - JSON response containing the list of tools if successful, otherwise the raw response text.
         """
         endpoint = LIST_TOOLS_V2
-        headers = {
-            "Authorization": self.api_service.token,
-            "ProjectId": project_id
-        }
 
         if scope and scope not in VALID_SCOPES:
             raise ValueError(f"Scope must be one of {', '.join(VALID_SCOPES)}.")
 
+        logger.debug(f"Listing tools available for the project with ID: {self.project_id}")
+
         response = self.api_service.get(
             endpoint=endpoint,
-            headers=headers,
             params={
                 "id": id,
                 "count": count,
@@ -167,16 +149,11 @@ class ToolClient(BaseClient):
                 "allowExternal": allow_external
             }
         )
-        try:
-            result = response.json()
-        except JSONDecodeError as e:
-            result = response.text
-
-        return result
+        validate_status_code(response)
+        return parse_json_response(response, f"list tools for project {self.project_id}")
 
     def get_tool(
             self,
-            project_id: str,
             tool_id: str,
             revision: str = 0,
             version: int = 0,
@@ -185,7 +162,6 @@ class ToolClient(BaseClient):
         """
         Retrieves details of a specific tool from the specified project.
 
-        :param project_id: str - Unique identifier of the project.
         :param tool_id: str - Unique identifier of the tool to retrieve.
         :param revision: str - Revision of the tool to retrieve. Defaults to 0 (latest revision).
         :param version: int - Version of the tool to retrieve. Defaults to 0 (latest version).
@@ -193,37 +169,28 @@ class ToolClient(BaseClient):
         :return: dict or str - JSON response containing the tool details if successful, otherwise the raw response text.
         """
         endpoint = GET_TOOL_V2.format(toolId=tool_id)
-        headers = {
-            "Authorization": self.api_service.token,
-            "ProjectId": project_id
-        }
+        logger.debug(f"Retrieving detail of tool with ID: {tool_id}")
 
         response = self.api_service.get(
             endpoint=endpoint,
-            headers=headers,
             params={
                 "revision": revision,
                 "version": version,
                 "allowDrafts": allow_drafts,
             }
         )
-        try:
-            result = response.json()
-        except JSONDecodeError as e:
-            result = response.text
+        validate_status_code(response)
+        return parse_json_response(response, f"retrieve tool {tool_id} for project {self.project_id}")
 
-        return result
 
     def delete_tool(
             self,
-            project_id: str,
             tool_id: str = None,
             tool_name: str = None
     ) -> dict | str:
         """
         Deletes a specific tool from the specified project.
 
-        :param project_id: str - Unique identifier of the project.
         :param tool_id: str, optional - Unique identifier of the tool to delete. Defaults to None.
         :param tool_name: str, optional - Name of the tool to delete. Defaults to None.
         :return: dict or str - JSON response containing the result of the delete operation if successful,
@@ -234,27 +201,26 @@ class ToolClient(BaseClient):
             raise ValueError("Either tool_id or tool_name must be provided.")
 
         endpoint = DELETE_TOOL_V2.format(toolId=tool_id if tool_id else tool_name)
-        headers = {
-            "Authorization": self.api_service.token,
-            "ProjectId": project_id
-        }
+
+        if tool_id:
+            logger.debug(f"Deleting tool with ID {tool_id}")
+        else:
+            logger.debug(f"Deleting tool with name '{tool_name}'")
 
         response = self.api_service.delete(
             endpoint=endpoint,
-            headers=headers
         )
+        validate_status_code(response)
 
-        try:
-            result = response.json()
-        except JSONDecodeError as e:
-            result = response.text
-
-        return result
+        if response.status_code != 204:
+            logger.error(f"Unable to delete tool {tool_id or tool_name} in project {self.project_id}: JSON parsing error (status {response.status_code}). Response: {response.text}")
+            raise InvalidAPIResponseException(f"Unable to delete tool {tool_id or tool_name} in project {self.project_id}: {response.text}")
+        else:
+            return {}
 
     def update_tool(
             self,
-            project_id: str,
-            tool_id: str,
+            tool_id: str = None,
             name: str = None,
             description: str = None,
             scope: str = None,
@@ -271,7 +237,6 @@ class ToolClient(BaseClient):
         """
         Updates an existing tool in the specified project or upserts it if specified.
 
-        :param project_id: str - Unique identifier of the project containing the tool.
         :param tool_id: str - Unique identifier of the tool to update. Required for update operations.
         :param name: str - Updated name of the tool. Must be non-empty, unique within the project, and exclude ':' or '/' if provided. Optional.
         :param description: str - Updated description of the tool's purpose, helping agents decide when to use it. Optional.
@@ -312,6 +277,8 @@ class ToolClient(BaseClient):
         :raises JSONDecodeError: Caught internally if the response cannot be parsed as JSON; returns raw response text.
         :raises Exception: May be raised by `api_service.put` for network issues, authentication errors, or server-side problems (not caught here).
         """
+        if not (tool_id or name):
+            raise ValueError(f"Either tool ID or tool Name must be defined in order to update tool.")
         if scope and scope not in VALID_SCOPES:
             raise ValueError(f"Scope must be one of {', '.join(VALID_SCOPES)}.")
         if access_scope and access_scope not in VALID_ACCESS_SCOPES:
@@ -344,66 +311,48 @@ class ToolClient(BaseClient):
         if parameters:
             data["tool"]["parameters"] = parameters
 
+        logger.debug(f"Updating tool with ID {tool_id} with data: {data}")
+
         endpoint = UPSERT_TOOL_V2 if upsert else UPDATE_TOOL_V2
         endpoint = endpoint.format(toolId=tool_id) if tool_id else endpoint.format(toolId=name)
 
         if automatic_publish:
             endpoint = f"{endpoint}?automaticPublish=true"
 
-        headers = {
-            "Authorization": self.api_service.token,
-            "ProjectId": project_id
-        }
         response = self.api_service.put(
             endpoint=endpoint,
-            headers=headers,
             data=data
         )
-
-        try:
-            result = response.json()
-        except JSONDecodeError as e:
-            result = response.text
-
-        return result
+        validate_status_code(response)
+        return parse_json_response(response, f"update tool {tool_id} in project {self.project_id}")
 
     def publish_tool_revision(
             self,
-            project_id: str,
             tool_id: str,
             revision: str
     ):
         """
         Publishes a specific revision of a tool in the specified project.
 
-        :param project_id: str - Unique identifier of the project.
         :param tool_id: str - Unique identifier of the tool to publish.
         :param revision: str - Revision of the tool to publish.
         :return: dict or str - JSON response containing the result of the publish operation if successful, otherwise the raw response text.
         """
         endpoint = PUBLISH_TOOL_REVISION_V2.format(toolId=tool_id)
-        headers = {
-            "Authorization": self.api_service.token,
-            "ProjectId": project_id
-        }
+        logger.debug(f"Publishing revision {revision} for tool with ID {tool_id}")
 
         response = self.api_service.post(
             endpoint=endpoint,
-            headers=headers,
             data={
                 "revision": revision,
             }
         )
-        try:
-            result = response.json()
-        except JSONDecodeError as e:
-            result = response.text
+        validate_status_code(response)
+        return parse_json_response(response, f"publish revision {revision} for tool {tool_id} in project {self.project_id}")
 
-        return result
 
     def get_parameter(
             self,
-            project_id: str,
             tool_id: str = None,
             tool_public_name: str = None,
             revision: str = 0,
@@ -413,7 +362,6 @@ class ToolClient(BaseClient):
         """
         Retrieves details of parameters for a specific tool identified by either its ID or public name in the specified project.
 
-        :param project_id: str - Unique identifier of the project.
         :param tool_id: str, optional - Unique identifier of the tool whose parameters are to be retrieved. Defaults to None.
         :param tool_public_name: str, optional - Public name of the tool whose parameters are to be retrieved. Defaults to None.
         :param revision: str - Revision of the parameters to retrieve. Defaults to "0" (latest revision).
@@ -425,31 +373,26 @@ class ToolClient(BaseClient):
         if not (tool_id or tool_public_name):
             raise ValueError("Either tool_id or tool_public_name must be provided.")
 
-        endpoint = GET_PARAMETER_V2.format(toolPublicName=tool_public_name) if tool_public_name else GET_PARAMETER_V2.format(toolPublicName=tool_id)
-        headers = {
-            "Authorization": self.api_service.token,
-            "ProjectId": project_id
-        }
+        if tool_id:
+            logger.debug(f"Retrieving parameter for tool with ID {tool_id}")
+        else:
+            logger.debug(f"Retrieving parameter for tool with name '{tool_public_name}'")
 
+        endpoint = GET_PARAMETER_V2.format(toolPublicName=tool_public_name) if tool_public_name else GET_PARAMETER_V2.format(toolPublicName=tool_id)
         response = self.api_service.get(
             endpoint=endpoint,
-            headers=headers,
             params={
                 "revision": revision,
                 "version": version,
                 "allowDrafts": allow_drafts,
             }
         )
-        try:
-            result = response.json()
-        except JSONDecodeError as e:
-            result = response.text
-
-        return result
+        validate_status_code(response)
+        tool_identifier = tool_id or tool_public_name
+        return parse_json_response(response, f"retrieve parameters for tool {tool_identifier} in project {self.project_id}")
 
     def set_parameter(
             self,
-            project_id: str,
             tool_id: str = None,
             tool_public_name: str = None,
             parameters: list = None
@@ -457,7 +400,6 @@ class ToolClient(BaseClient):
         """
         Sets or updates parameters for a specific tool identified by either its ID or public name in the specified project.
 
-        :param project_id: str - Unique identifier of the project.
         :param tool_id: str, optional - Unique identifier of the tool whose parameters are to be set. Defaults to None.
         :param tool_public_name: str, optional - Public name of the tool whose parameters are to be set. Defaults to None.
         :param parameters: list - List of parameter dictionaries defining the tool's parameters.
@@ -472,12 +414,6 @@ class ToolClient(BaseClient):
             raise ValueError("Parameters list must be provided and non-empty.")
 
         endpoint = SET_PARAMETER_V2.format(toolPublicName=tool_public_name) if tool_public_name else SET_PARAMETER_V2.format(toolPublicName=tool_id)
-        headers = {
-            "Authorization": self.api_service.token,
-            "ProjectId": project_id,
-            "Content-Type": "application/json",
-            "Accept": "application/json"
-        }
 
         data = {
             "parameterDefinition": {
@@ -485,14 +421,45 @@ class ToolClient(BaseClient):
             }
         }
 
+        if tool_id:
+            logger.debug(f"Setting parameter for tool with ID {tool_id} with data: {data}")
+        else:
+            logger.debug(f"Setting parameter for tool with name '{tool_public_name}' with data: {data}")
+
         response = self.api_service.post(
             endpoint=endpoint,
-            headers=headers,
             data=data
         )
-        try:
-            result = response.json()
-        except JSONDecodeError as e:
-            result = response.text
+        if response.status_code != 204:
+            logger.error(f"Unable to set parameters for tool {tool_id or tool_public_name} in project {self.project_id}: JSON parsing error (status {response.status_code}). Response: {response.text}")
+            raise InvalidAPIResponseException(f"Unable to set parameters for tool {tool_id or tool_public_name} in project {self.project_id}: {response.text}")
+        else:
+            return {}
+
+    '''
+    def export_tool(
+            self,
+            tool_id: str,
+    ) -> dict:
+        """
+        Retrieves details of a specific tool from the specified project.
+
+        :param tool_id: str - Unique identifier of the tool to retrieve.
+        :return: dict - JSON response containing the tool details.
+        :raises InvalidAPIResponseException: If the response cannot be parsed as JSON or an error occurs.
+        :raises MissingRequirementException: If project_id or tool_id is not provided.
+        """
+
+        if not tool_id:
+            raise MissingRequirementException("tool_id must be specified in order to retrieve the tool")
+
+        endpoint = EXPORT_TOOL_V4.format(toolId=tool_id)
+        logger.debug(f"Exporting tool with ID {tool_id}")
+
+        response = self.api_service.get(
+            endpoint=endpoint,
+        )
+        validate_status_code(response)
+        return parse_json_response(response, f"export tool {tool_id} for project {self.project_id}")
 
-        return result
+    '''

pygeai/lab/tools/endpoints.py

@@ -7,3 +7,7 @@ UPSERT_TOOL_V2 = "v2/tools/{toolId}/upsert"  # PUT -> Update or insert tool data
 PUBLISH_TOOL_REVISION_V2 = "v2/tools/{toolId}/publish-revision"  # POST -> Publish Tool revision
 GET_PARAMETER_V2 = "v2/tools/{toolPublicName}/config"  # GET -> Get tool parameter
 SET_PARAMETER_V2 = "v2/tools/{toolPublicName}/config"  # POST -> Set tool parameter
+EXPORT_TOOL_V2 = "v2/tools/{toolId}/export"  # GET -> Export tool
+IMPORT_TOOL_V2 = "v2/tools/import"  # POST -> Import tool
+EXPORT_TOOL_V4 = "v4/tools/{toolId}/export"  # GET -> Export tool
+IMPORT_TOOL_V4 = "v4/tools/import"  # POST -> Import tool

pygeai/lab/tools/mappers.py

@@ -37,8 +37,8 @@ class ToolMapper:
         """
         return [
             ToolMessage(
-                description=msg["description"],
-                type=msg["type"]
+                description=msg.get("description"),
+                type=msg.get("type")
             )
             for msg in messages_data
         ]
@@ -55,9 +55,9 @@ class ToolMapper:
         """
         tool_data = data.get("tool", data)
 
-        name = tool_data["name"]
-        description = tool_data["description"]
-        scope = tool_data["scope"]
+        name = tool_data.get("name")
+        description = tool_data.get("description")
+        scope = tool_data.get("scope")
         parameter_data = tool_data.get("parameters")
         parameters = cls._map_parameters(parameter_data) if parameter_data else None
 

pygeai/man/man1/geai-proxy.1

@@ -58,6 +58,17 @@ The configuration file should be in JSON format with the following structure:
 }
 .fi
 .TP
+.B Example: HTTP+SSE Server
+.nf
+{
+  "mcpServers": {
+    "markitdown": {
+      "uri": "http://localhost:5000/sse"
+    }
+  }
+}
+.fi
+.TP
 .B Example: Multiple Servers Combined
 .nf
 {
@@ -70,6 +81,9 @@ The configuration file should be in JSON format with the following structure:
       "command": "npx",
       "args": ["-y", "@modelcontextprotocol/server-filesystem", "~/mcp-shared-folder"]
     },
+    "markitdown": {
+      "uri": "http://localhost:5000/sse"
+    },
     "custom-server": {
       "command": "python",
       "args": ["path/to/your/custom_mcp_server.py"]
@@ -78,6 +92,55 @@ The configuration file should be in JSON format with the following structure:
 }
 .fi
 
+.SH PUBLIC TOOL REGISTRATION
+Tools provided by both MCP and A2A servers can be published to GEAI under a public namespace
+by including the \fBpublic_prefix\fR field in their configuration entry.
+
+This allows tools to be registered under a well-defined global identifier, making them
+discoverable and shareable across proxies and clients.
+
+.SS MCP SERVER EXAMPLE WITH PUBLIC PREFIX
+The following configuration registers all tools from the \fBpuppeteer\fR MCP server under
+the public prefix \fIcom.globant.puppeteer\fR:
+
+.nf
+{
+  "mcpServers": {
+    "public_prefix": "com.globant.puppeteer",
+    "puppeteer": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-puppeteer"]
+    }
+  }
+}
+.fi
+
+.SS A2A SERVER EXAMPLE WITH PUBLIC PREFIX
+The following configuration registers the tools provided by the \fBhello-world\fR A2A agent
+under the prefix \fIcom.genexus.a2a.sampleagent\fR:
+
+.nf
+{
+  "a2aServers": {
+    "hello-world": {
+      "public_prefix": "com.genexus.a2a.sampleagent",
+      "url": "http://localhost:9999",
+      "headers": {
+        "Authorization": "Bearer fh84ff...."
+      }
+    }
+  }
+}
+.fi
+
+.SS RESULTING TOOL IDENTIFIERS
+When this prefix is set, all tools will be published using it. For example, a tool named
+\fBtranslate_text\fR would be available as:
+
+.nf
+com.genexus.a2a.sampleagent.translate_text
+.fi
+
 .SS 2. Proxy Authentication Configuration
 This section establishes the connection between the proxy and GEAI and manages user aliases.
 .TP
@@ -102,6 +165,48 @@ Generated new proxy ID: 37bae96b-bc99-4110-bb61-b912b28f9e32
 -> Insert proxy description:
 .fi
 
+.SH PROXY CONFIGURATION PARAMETERS
+During interactive setup, the following parameters are requested:
+
+.TP
+\fBproxy ID (UUID)\fR
+A unique identifier for this proxy instance. If left empty, the automatically generated UUID
+will be used.
+
+.TP
+\fBproxy API key\fR
+The API key used to authenticate the proxy with the GEAI backend. This must be an API token
+generated in GEAI for a specific project.
+
+.TP
+\fBproxy base URL\fR
+The base URL of the GEAI installation this proxy will connect to.
+For example: \fIhttps://api.beta.saia.ai\fR
+
+.TP
+\fBproxy name\fR
+A human-readable name assigned to this instance of \fBgeai-proxy\fR. This name is stored under the configured alias.
+
+.TP
+\fBproxy description\fR
+An optional description to help identify this proxy instance, especially when multiple proxies are used under different aliases.
+
+.SS Environment Variables
+The above configuration parameters can also be set using environment variables:
+
+.TP
+\fBGEAI_API_KEY\fR
+.TP
+\fBGEAI_API_BASE_URL\fR
+.TP
+\fBPROXY_ID\fR
+.TP
+\fBPROXY_NAME\fR
+.TP
+\fBPROXY_DESCRIPTION\fR
+
+These environment variables override or represent the configuration of the \fBdefault alias\fR. Therefore, they are only taken into account if the proxy is invoked with \fB\-\-alias default\fR. When using a different alias, these variables are ignored.
+
 .SH USAGE
 To start the proxy server with a specific configuration and alias:
 .nf
@@ -123,6 +228,17 @@ Reconfigure proxy authentication settings.
 Sample configuration file for MCP servers.
 .SH SEE ALSO
 .BR pygeai (1)
+.SH THIRD-PARTY COMPONENTS
+This software includes code from the \fBa2a-python\fR project developed by Google LLC, which is licensed under the Apache License, Version 2.0.
+
+Only the vendored component located in \fIpygeai/vendor/a2a/\fR is subject to the Apache License. The rest of this software is licensed under the MIT License.
+
+For full license details, see:
+.IP \[bu] 
+https://github.com/google/a2a-python
+.IP \[bu] 
+pygeai/vendor/a2a/LICENSE
+
 .SH AUTHOR
 Written by the GEAI development team.
 .SH COPYRIGHT