pygeai 0.2.7b42__tar.gz → 0.2.7b44__tar.gz

{pygeai-0.2.7b42/pygeai.egg-info → pygeai-0.2.7b44}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pygeai
-Version: 0.2.7b42
+Version: 0.2.7b44
 Summary: Software Development Kit to interact with Globant Enterprise AI.
 Author-email: Globant <geai-sdk@globant.com>
 License-Expression: MIT

pygeai-0.2.7b44/docs/geai-proxy/README.md

@@ -0,0 +1,244 @@
+# GEAI Proxy Documentation
+
+## NAME
+`geai-proxy` – proxy service for managing Model Context Protocol (MCP) servers with GEAI
+
+## SYNOPSIS
+```bash
+geai-proxy [OPTIONS] CONFIG_FILE
+```
+
+## DESCRIPTION
+The GEAI Proxy is a Python-based tool that acts as an intermediary between the GEAI API and various tool servers. It manages the registration, execution, and result handling of tool operations through a proxy service.
+
+To install:
+
+```bash
+pip install pygeai
+```
+
+## CONFIGURATION
+
+The GEAI Proxy requires two distinct types of configuration:
+
+### 1. MCP Servers Configuration
+
+This section declares the Model Context Protocol (MCP) servers that this proxy will link with GEAI. The configuration follows the Claude Desktop standard format and supports multiple servers in one file.
+
+#### Configuration File Format
+
+```json
+{
+  "mcpServers": {
+    "serverName1": {
+      "command": "command-to-launch-server",
+      "args": ["arg1", "arg2", "..."]
+    },
+    "serverName2": {
+      "command": "command-to-launch-server",
+      "args": ["arg1", "arg2", "..."]
+    }
+  }
+}
+```
+
+#### Example: Puppeteer Server
+
+```json
+{
+  "mcpServers": {
+    "puppeteer": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-puppeteer"]
+    }
+  }
+}
+```
+
+#### Example: Filesystem Server
+
+```json
+{
+  "mcpServers": {
+    "filesystem": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-filesystem", "~/mcp-shared-folder"]
+    }
+  }
+}
+```
+
+#### Example: HTTP+SSE Server
+
+```json
+{
+  "mcpServers": {
+    "markitdown": {
+      "uri": "http://localhost:5000/sse"
+    }
+  }
+}
+```
+
+#### Example: Multiple Servers Combined
+
+```json
+{
+  "mcpServers": {
+    "puppeteer": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-puppeteer"]
+    },
+    "filesystem": {
+      "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"]
+    }
+  }
+}
+```
+
+## PUBLIC TOOL REGISTRATION
+
+Tools provided by both MCP and A2A servers can be published to GEAI under a public namespace by including the `public_prefix` 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.
+
+### MCP Server Example with Public Prefix
+
+Registers tools from the `puppeteer` MCP server under the prefix `com.globant.puppeteer`:
+
+```json
+{
+  "mcpServers": {
+    "public_prefix": "com.globant.puppeteer",
+    "puppeteer": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-puppeteer"]
+    }
+  }
+}
+```
+
+### A2A Server Example with Public Prefix
+
+Registers tools from the `hello-world` A2A agent under the prefix `com.genexus.a2a.sampleagent`:
+
+```json
+{
+  "a2aServers": {
+    "hello-world": {
+      "public_prefix": "com.genexus.a2a.sampleagent",
+      "url": "http://localhost:9999",
+      "headers": {
+        "Authorization": "Bearer fh84ff...."
+      }
+    }
+  }
+}
+```
+
+### Resulting Tool Identifiers
+
+For example, a tool named `translate_text` would be available as:
+
+```text
+com.genexus.a2a.sampleagent.translate_text
+```
+
+### 2. Proxy Authentication Configuration
+
+This section establishes the connection between the proxy and GEAI and manages user aliases.
+
+#### Automatic Configuration (First Run)
+
+```bash
+geai-proxy sample-mcp-config.json --alias myalias
+```
+
+#### Manual Configuration (Reconfiguration)
+
+```bash
+geai-proxy --configure --alias myalias
+```
+
+During interactive setup, the CLI will prompt:
+
+```
+# Configuring GEAI proxy settings...
+Generated new proxy ID: 37bae96b-bc99-4110-bb61-b912b28f9e32
+-> Insert proxy ID (UUID) (Current: 37bae96b-bc99-4110-bb61-b912b28f9e32, Leave empty to keep):
+-> Insert proxy API key:
+-> Insert proxy base URL:
+-> Insert proxy name:
+-> Insert proxy description:
+```
+
+## PROXY CONFIGURATION PARAMETERS
+
+During interactive setup, the following parameters are requested:
+
+- **proxy ID (UUID)**  
+  A unique identifier for this proxy instance. If left empty, the automatically generated UUID will be used.
+
+- **proxy API key**  
+  The API key used to authenticate the proxy with the GEAI backend. Must be a token from GEAI for a specific project.
+
+- **proxy base URL**  
+  The base URL of the GEAI installation to connect to.  
+  Example: `https://api.beta.saia.ai`
+
+- **proxy name**  
+  Human-readable name for this proxy instance, stored under the alias.
+
+- **proxy description**  
+  Optional. Helps identify this proxy instance when using multiple aliases.
+
+## USAGE
+
+To start the proxy server with a config and alias:
+
+```bash
+geai-proxy sample-mcp-config.json --alias myalias
+```
+
+### Command Line Arguments
+
+- **config_file**: Path to the MCP servers configuration file (JSON).
+- **--alias ALIAS**: Alias for the proxy settings.
+- **--configure**: Reconfigure proxy authentication settings.
+
+## FILES
+
+- `pygeai/proxy/sample-mcp-config.json` – Sample configuration file for MCP servers.
+
+## SEE ALSO
+
+- `pygeai (1)`
+
+## THIRD-PARTY COMPONENTS
+
+This software includes code from the `a2a-python` project by Google LLC, licensed under the Apache License 2.0.
+
+Only the vendored component in `pygeai/vendor/a2a/` is Apache-licensed. The rest is MIT-licensed.
+
+License sources:
+
+- https://github.com/google/a2a-python
+- `pygeai/vendor/a2a/LICENSE`
+
+## AUTHOR
+
+Written by the GEAI development team.
+
+## COPYRIGHT
+
+Copyright © 2025 GEAI development team.
+
+This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

{pygeai-0.2.7b42 → pygeai-0.2.7b44}/pygeai/man/man1/geai-proxy.1

@@ -92,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
@@ -116,6 +165,33 @@ 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.
+
+
 .SH USAGE
 To start the proxy server with a specific configuration and alias:
 .nf

{pygeai-0.2.7b42 → pygeai-0.2.7b44}/pygeai/proxy/managers.py

@@ -59,8 +59,8 @@ class ServerManager:
 
         for server in self.servers.values():
             Console.write_stdout(f"Listing tools for server {server.name}", end="")
-            if server.public_preffix:
-                Console.write_stdout(f" | access scope:public prefix: {server.public_preffix}")
+            if server.public_prefix:
+                Console.write_stdout(f" | access scope:public prefix: {server.public_prefix}")
             else:
                 Console.write_stdout(" ! access scope:private")
 

{pygeai-0.2.7b42 → pygeai-0.2.7b44}/pygeai/proxy/servers.py

@@ -40,7 +40,7 @@ class ToolServer(ABC):
         self.config = config
         self.settings = settings
         self.name: str = sever_name
-        self.public_preffix: str | None = None
+        self.public_prefix: str | None = None
         self.exit_stack: AsyncExitStack = AsyncExitStack()
 
     @abstractmethod
@@ -105,7 +105,7 @@ class A2AServer(ToolServer):
         """
         try:
             self.httpx_client = httpx.AsyncClient(timeout=60.0)
-            self.public_preffix = self.config.get("publicpreffix")
+            self.public_prefix = self.config.get("public_prefix")
             headers = self.config.get("headers")
             if headers:
                 self.httpx_client.headers.update(headers)
@@ -138,7 +138,7 @@ class A2AServer(ToolServer):
         }
         tools = []
         for skill in self.agent_card.skills:
-            tools.append(ProxiedTool(self.name, skill.id, skill.description, self.public_preffix, input_schema))
+            tools.append(ProxiedTool(self.name, skill.id, skill.description, self.public_prefix, input_schema))
         return tools
 
     async def execute_tool(
@@ -197,7 +197,7 @@ class MCPServer(ToolServer):
         self.session: ClientSession | None = None
 
     async def initialize(self) -> None:
-        self.public_preffix = self.config.get("publicpreffix")
+        self.public_prefix = self.config.get("public_prefix")
         transport = self.config.get("transport") or (
             "sse" if "uri" in self.config else "stdio"
         )
@@ -264,7 +264,7 @@ class MCPServer(ToolServer):
                             self.name,
                             tool.name,
                             tool.description,
-                            self.public_preffix,
+                            self.public_prefix,
                             tool.inputSchema
                         )
                     )

{pygeai-0.2.7b42 → pygeai-0.2.7b44}/pygeai/proxy/tool.py

@@ -9,7 +9,7 @@ class ProxiedTool:
     :param server_name: str - Name of the server exposing the tool
     :param name: str - Name of the tool
     :param description: str - Description of the tool's functionality
-    :param public_preffix: str - Public prefix of the tool
+    :param public_prefix: str - Public prefix of the tool
     :param input_schema: dict[str, Any] - JSON schema defining the expected input for the tool
     :return: ProxiedTool - Instance of the ProxiedTool class
     :raises: ValueError - If any required parameter is invalid or missing
@@ -20,7 +20,7 @@ class ProxiedTool:
         server_name: str,
         name: str,
         description: str,
-        public_preffix: str,
+        public_prefix: str,
         input_schema: dict[str, Any]
     ) -> None:
         self.server_name: str = server_name
@@ -28,7 +28,7 @@ class ProxiedTool:
         self.openai_compatible_name: str = self._get_openai_compatible_name(name)
         self.description: str = description
         self.input_schema: dict[str, Any] = input_schema
-        self.public_preffix: str = public_preffix
+        self.public_prefix: str = public_prefix
 
     def get_full_name(self) -> str:
         """Get the full name of the tool."""
@@ -36,12 +36,12 @@ class ProxiedTool:
 
     def is_public(self) -> bool:
         """Check if the tool is public."""
-        return self.public_preffix is not None
+        return self.public_prefix is not None
 
     def get_public_name(self) -> str:
         """Get the public name of the tool."""
         return (
-            f"{self.public_preffix}.{self.name if self.server_name in self.public_preffix else self.get_full_name()}"
+            f"{self.public_prefix}.{self.name if self.server_name in self.public_prefix else self.get_full_name()}"
         )
 
     def format_for_llm(self) -> str:

{pygeai-0.2.7b42 → pygeai-0.2.7b44/pygeai.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pygeai
-Version: 0.2.7b42
+Version: 0.2.7b44
 Summary: Software Development Kit to interact with Globant Enterprise AI.
 Author-email: Globant <geai-sdk@globant.com>
 License-Expression: MIT

{pygeai-0.2.7b42 → pygeai-0.2.7b44}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "pygeai"
-version = "0.2.7b42"
+version = "0.2.7b44"
 description = "Software Development Kit to interact with Globant Enterprise AI."
 license = "MIT"
 requires-python = ">=3.10"

pygeai-0.2.7b42/docs/geai-proxy/README.md

@@ -1,200 +0,0 @@
-# GEAI Proxy Documentation
-
-## Overview
-
-The GEAI Proxy is a Python-based tool that acts as an intermediary between the GEAI API and various tool servers. It manages the registration, execution, and result handling of tool operations through a proxy service.
-
-## Installation
-
-## Third-party Components
-
-This project includes code from [`a2a-python`](https://github.com/google/a2a-python) by Google LLC, used under the Apache License, Version 2.0.
-
-Only the vendored component located in `pygeai/vendor/a2a/` is subject to the Apache License.  
-The rest of this project is licensed under the MIT License (see `LICENSE` file for details).
-
-
-```bash
-pip install pygeai
-```
-
-## Configuration
-
-The GEAI Proxy requires two distinct types of configuration:
-
-### 1. MCP Servers Configuration
-
-This section declares the Model Context Protocol (MCP) servers that this proxy will link with GEAI. The configuration follows the Claude Desktop standard format and supports multiple servers in one file.
-
-#### Configuration File Format
-
-```json
-{
-  "mcpServers": {
-    "serverName1": {
-      "command": "command-to-launch-server",
-      "args": ["arg1", "arg2", ...]
-    },
-    "serverName2": {
-      "command": "command-to-launch-server",
-      "args": ["arg1", "arg2", ...]
-    }
-  }
-}
-```
-
-#### Example Configurations
-
-1. **Puppeteer Server** (for web automation):
-```json
-{
-  "mcpServers": {
-    "puppeteer": {
-      "command": "npx",
-      "args": ["-y", "@modelcontextprotocol/server-puppeteer"]
-    }
-  }
-}
-```
-
-2. **Filesystem Server** (for file operations):
-```json
-{
-  "mcpServers": {
-    "filesystem": {
-      "command": "npx",
-      "args": [
-        "-y",
-        "@modelcontextprotocol/server-filesystem",
-        "~/mcp-shared-folder"
-      ]
-    }
-  }
-}
-```
-
-3. **Multiple Servers Combined**:
-```json
-{
-  "mcpServers": {
-    "puppeteer": {
-      "command": "npx",
-      "args": ["-y", "@modelcontextprotocol/server-puppeteer"]
-    },
-    "filesystem": {
-      "command": "npx",
-      "args": [
-        "-y",
-        "@modelcontextprotocol/server-filesystem",
-        "~/mcp-shared-folder"
-      ]
-    },
-    "custom-server": {
-      "command": "python",
-      "args": ["path/to/your/custom_mcp_server.py"]
-    }
-  }
-}
-```
-
-### 1. A2A Servers Configuration
-
-This section declares the Agent to Agent Protocol (A2A) servers that this proxy will link with GEAI. The configuration follows the standard format and supports multiple servers in one file.
-
-#### Configuration File Format
-
-```json
-{
-  "a2aServers": {
-    "hello-world": {
-      "publicpreffix": "com.genexus.a2a.sampleagent",
-      "url": "http://localhost:9999"
-    }
-  }
-}
-```
-
-A sample configuration file is provided at:
-```
-pygeai/proxy/sample-mcp-config.json
-```
-
-### 2. Proxy Authentication Configuration
-
-This section establishes the connection between the proxy and GEAI and manages user aliases. You can configure it automatically on first run or manually reconfigure an existing alias.
-
-#### Automatic Configuration (First Run)
-```bash
-geai-proxy sample-mcp-config.json --alias myalias
-```
-
-#### Manual Configuration (Reconfiguration)
-```bash
-geai-proxy --configure --alias myalias
-```
-
-During interactive setup, the CLI will prompt you for each required setting:
-
-```bash
-# Configuring GEAI proxy settings...
-Generated new proxy ID: 37bae96b-bc99-4110-bb61-b912b28f9e32
--> Insert proxy ID (UUID) (Current: 37bae96b-bc99-4110-bb61-b912b28f9e32, Leave empty to keep):
--> Insert proxy API key:
--> Insert proxy base URL:
--> Insert proxy name:
--> Insert proxy description:
-```
-
-## Usage
-
-### Starting the Proxy
-
-To start the proxy server with a specific configuration and alias:
-
-```bash
-geai-proxy sample-mcp-config.json --alias myalias
-```
-
-### Command Line Arguments
-
-| Argument | Description | Required |
-|----------|-------------|----------|
-| `config_file` | Path to the MCP servers configuration file (JSON format) | Yes |
-| `--alias` | Alias for the proxy settings | No |
-| `--configure` | Command to reconfigure proxy authentication | No |
-
-## Command Line Usage
-
-```bash
-geai-proxy sample-mcp-config.json --alias beta
-``` 
-
-## Architecture
-
-```mermaid
-graph TD
-    %% Elementos principales
-    user["User (Person)\nClient interacting with the GEAI"]
-    geai["GEAI (Software System)\nGlobant Enterprise AI"]
-    proxy["MCP Proxy (Software System)\nProxy that connects to multiple MCP Servers to call tools"]
-
-    mcpA["MCP Server A (Software System)\nTool server for search functionality"]
-    mcpB["MCP Server B (Software System)\nTool server for code execution"]
-    mcpC["MCP Server C (Software System)\nTool server for database queries"]
-
-    %% Conexiones
-    user -->|Interacts/Calls tools via| geai
-    geai -->|Returns tool responses| user
-    geai -->|Calls tools via| proxy
-    proxy -->|Returns tool responses| geai
-
-    user -->|Calls Search Tool| proxy
-    proxy -->|Calls Search Tool| mcpA
-    mcpA -->|Returns search results| proxy
-
-    proxy -->|Calls Code Tool| mcpB
-    mcpB -->|Returns code output| proxy
-
-    proxy -->|Calls DB Tool| mcpC
-    mcpC -->|Returns query results| proxy
-```