biatoolkit 1.0.2__py3-none-any.whl → 1.0.4__py3-none-any.whl

biatoolkit/basic_client.py

@@ -1,34 +1,63 @@
 from mcp import ClientSession
 from mcp.client.streamable_http import streamablehttp_client
 
-class BasicClient:
+class BiaClient:
+    """
+    Cliente básico para interação com o MCP (Middleware de Comunicação de Processos).
+    Permite listar ferramentas disponíveis e executar ferramentas específicas via HTTP.
+    """
 
     def __init__(self, url: str = "http://0.0.0.0:8000/mcp", headers: dict = None):
+        """
+        Inicializa o BasicClient.
+
+        Args:
+            url (str): URL base do MCP. Se não terminar com '/mcp', será adicionado automaticamente.
+            headers (dict): Cabeçalhos HTTP opcionais para requisições.
+        """
         sufix = "/mcp"
+        # Garante que a URL termine com '/mcp'
         self.url = url if url.endswith(sufix) else f"{url}{sufix}"
         self.headers = headers
 
     async def list_tools(self) -> dict:
-        """Lista as ferramentas disponíveis no MCP"""
+        """
+        Lista as ferramentas disponíveis no MCP.
+
+        Returns:
+            dict: Dicionário contendo as ferramentas disponíveis.
+        """
+        # Cria um cliente HTTP streamable para comunicação assíncrona
         async with streamablehttp_client(self.url, self.headers, timeout=120, terminate_on_close=False) as (
             read_stream,
             write_stream,
             _,
         ):
+            # Cria uma sessão de cliente MCP usando os streams
             async with ClientSession(read_stream, write_stream) as session:
-                await session.initialize()
-                tool_result = await session.list_tools()
+                await session.initialize()  # Inicializa a sessão
+                tool_result = await session.list_tools()  # Solicita a lista de ferramentas
         return tool_result
     
     async def call_tool(self, tool_name: str, params: dict = None) -> dict:
-        """Executa a ferramenta disponível no MCP"""
+        """
+        Executa uma ferramenta específica disponível no MCP.
+
+        Args:
+            tool_name (str): Nome da ferramenta a ser executada.
+            params (dict, opcional): Parâmetros para a execução da ferramenta.
+
+        Returns:
+            dict: Resultado da execução da ferramenta.
+        """
+        # Cria um cliente HTTP streamable para comunicação assíncrona
         async with streamablehttp_client(self.url, self.headers, timeout=120, terminate_on_close=False) as (
             read_stream,
             write_stream,
             _,
         ):
+            # Cria uma sessão de cliente MCP usando os streams
             async with ClientSession(read_stream, write_stream) as session:
-                await session.initialize()
-                result = await session.call_tool(tool_name, params)
+                await session.initialize()  # Inicializa a sessão
+                result = await session.call_tool(tool_name, params)  # Executa a ferramenta
         return result
-    

biatoolkit/util.py

@@ -4,32 +4,52 @@ from .schema.header import Header
 import boto3
 import os
 
-class Util():
+class BiaUtil():
 
     HEADER_PREFIX = "x-amzn-bedrock-agentcore-runtime-custom"
 
     def __init__(self, mcp: FastMCP):
+        """
+        Inicializa o utilitário BiaUtil com uma instância do FastMCP.
+
+        Args:
+            mcp (FastMCP): Instância do servidor FastMCP para obter contexto da requisição.
+        """
         self.mcp = mcp
 
     def __get_from_ssm(self, parameter_name: str) -> str:
-        """Busca o parâmetro no AWS SSM Parameter Store"""
-        ctx = self.mcp.get_context()
-        headers = ctx.request_context.request.headers
-        prefix = headers.get(f"{self.HEADER_PREFIX}-prefix", None)
-        client = boto3.client('ssm', region_name="sa-east-1")
+        """
+        Busca o valor de um parâmetro no AWS SSM Parameter Store.
+
+        Args:
+            parameter_name (str): Nome do parâmetro a ser buscado.
+
+        Returns:
+            str: Valor do parâmetro, ou None se não encontrado.
+        """
+        ctx = self.mcp.get_context()  # Obtém o contexto da requisição atual
+        headers = ctx.request_context.request.headers  # Acessa os headers da requisição
+        prefix = headers.get(f"{self.HEADER_PREFIX}-prefix", None)  # Prefixo customizado do header
+        client = boto3.client('ssm', region_name="sa-east-1")  # Cria cliente SSM na região especificada
         try:
             response = client.get_parameter(
                 Name=f"{prefix}/{parameter_name}",
                 WithDecryption=True
             )
         except client.exceptions.ParameterNotFound:
-            return None
-        return response.get('Parameter').get('Value')
+            return None  # Retorna None se o parâmetro não for encontrado
+        return response.get('Parameter').get('Value')  # Retorna o valor do parâmetro
 
     def get_header(self) -> Header:
-        """Retorna os parâmetros padrão contidos no header da requisição"""
-        ctx = self.mcp.get_context()
-        headers = ctx.request_context.request.headers
+        """
+        Retorna os parâmetros padrão contidos no header da requisição.
+
+        Returns:
+            Header: Objeto Header preenchido com os valores dos headers customizados.
+        """
+        ctx = self.mcp.get_context()  # Obtém o contexto da requisição atual
+        headers = ctx.request_context.request.headers  # Acessa os headers da requisição
+        # Preenche o objeto Header com os valores dos headers customizados
         return Header(
             current_host=headers.get(f"{self.HEADER_PREFIX}-current-host", None),
             user_email=headers.get(f"{self.HEADER_PREFIX}-user-email", None),
@@ -43,9 +63,16 @@ class Util():
     
     def get_parameter(self, parameter_name: str) -> str:
         """
-            Retorna o valor do parâmetro, buscando primeiro na variável de
-            ambiente e depois no AWS SSM Parameter Store.
+        Retorna o valor do parâmetro, buscando primeiro na variável de ambiente
+        e depois no AWS SSM Parameter Store caso não exista na variável de ambiente.
+
+        Args:
+            parameter_name (str): Nome do parâmetro a ser buscado.
+
+        Returns:
+            str: Valor do parâmetro, ou None se não encontrado.
         """
+        # Busca o valor na variável de ambiente, se não existir busca no SSM
         return os.getenv(
             parameter_name,
             self.__get_from_ssm(parameter_name)

{biatoolkit-1.0.2.dist-info → biatoolkit-1.0.4.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: biatoolkit
-Version: 1.0.2
+Version: 1.0.4
 Summary: Biblioteca para desenvolvedores que utilizam o BiaAgentBuilder
 Author: Bia Platform Team
 Author-email: data.platform@sankhya.com.br
@@ -25,18 +25,18 @@ Biblioteca Python para facilitar o desenvolvimento de servidores MCP integrados
 
 Nesta seção você encontrará uma breve descrição de cada classe da biblioteca **Bia Toolkit**.
 
-### **BasicClient**
+### **BiaClient**
 
-A classe `BasicClient` tem o objetivo de criar um cliente HTTP para comunicação com servidores MCP (Model Context Protocol).
+A classe `BiaClient` tem o objetivo de criar um cliente HTTP para comunicação com servidores MCP (Model Context Protocol).
 
 **Principais métodos**:
 
 - **list_tools**: Lista todas as ferramentas disponíveis no servidor MCP.
 - **call_tool**: Executa uma ferramenta específica no servidor MCP.
 
-### **Util**
+### **BiaUtil**
 
-A classe `Util` fornece métodos auxiliares para gerenciar headers de requisições e parâmetros de configuração em servidores MCP.
+A classe `BiaUtil` fornece métodos auxiliares para gerenciar headers de requisições e parâmetros de configuração em servidores MCP.
 
 **Principais métodos**:
 
@@ -128,10 +128,10 @@ Crie um novo arquivo chamado `local.py` com o seguinte conteúdo:
 
 ```python
 import asyncio
-from biatoolkit.basic_client import BasicClient
+from biatoolkit.basic_client import BiaClient
 
 MCP_SERVER_URL = "http://0.0.0.0:8000/mcp"
-client = BasicClient(MCP_SERVER_URL)
+client = BiaClient(MCP_SERVER_URL)
 
 async def list_tools() -> None:
     tools = await client.list_tools()
@@ -153,7 +153,7 @@ asyncio.run(main())
 
 #### **Entendendo o código**
 
-- **BasicClient**: É uma classe da biblioteca **Bia Toolkit** que encapsula um cliente HTTP para comunicação com servidores MCP.
+- **BiaClient**: É uma classe da biblioteca **Bia Toolkit** que encapsula um cliente HTTP para comunicação com servidores MCP.
 - **list_tools**: Executa a instrução `client.list_tools()` para recuperar todas as ferramentas disponíveis no servidor MCP.
 - **call_tool**: Executa a instrução `client.call_tool(tool_name, params)` para executar uma ferramenta específica do servidor MCP.
 
@@ -204,7 +204,7 @@ Se seu servidor MCP estiver sendo executado **localmente**, você conseguirá in
 
 ```python
 import asyncio
-from biatoolkit.basic_client import BasicClient
+from biatoolkit.basic_client import BiaClient
 
 MCP_SERVER_URL = "http://0.0.0.0:8000/mcp"
 
@@ -226,7 +226,7 @@ headers = {
     "Content-Type": "application/json"
 }
 
-client = BasicClient(MCP_SERVER_URL, headers=headers)
+client = BiaClient(MCP_SERVER_URL, headers=headers)
 
 async def list_tools() -> None:
     tools = await client.list_tools()
@@ -246,19 +246,13 @@ async def main():
 asyncio.run(main())
 ```
 
-#### **Entendendo o código**
-
-- **headers**: Veja que a variável `headers` é definida com a lista de parâmetros válidos e depois utilizada em `client = BasicClient(MCP_SERVER_URL, headers=headers)`.
-
-⚠️ IMPORTANTE: Ao utilizar os serviços de interação com a Bia (**/agent/stream**, **/agent/message** ou **/agent/invoke**),  os parâmetros já são automaticamente preenchidos e enviados pelos serviços.
-
-### **Recuperando os parâmetros no MCP Server enviados via header**
+...existing code...
 
-Para recuperar os parâmetros no MCP Server que foram enviados por meio do `header` da requisição, basta utilizar a classe `Util` conforme a seguir:
+Para recuperar os parâmetros no MCP Server que foram enviados por meio do `header` da requisição, basta utilizar a classe `BiaUtil` conforme a seguir:
 
 ```python
 from mcp.server.fastmcp import FastMCP
-from biatoolkit.util import Util
+from biatoolkit.util import BiaUtil
 
 mcp = FastMCP(host="0.0.0.0", stateless_http=True)
 
@@ -266,7 +260,7 @@ mcp = FastMCP(host="0.0.0.0", stateless_http=True)
 def processar() -> str:
     """Executa o processamento de algo"""
     
-    util = Util(mcp)
+    util = BiaUtil(mcp)
     header = util.get_header()
 
     # Exemplo de uso dos parâmetros do header. Utilize conforme a necessidade 
@@ -296,11 +290,11 @@ Você pode utilizar parâmetros sensíveis de duas formas:
 - Usando o cofre de segredos do Bia Agent Builder para execução em ambiente produtivo.
   - Você pode adicionar parâmetros sensíveis no cofre de segredos do Bia Agent Builder. Para adicionar, alterar e excluir os parâmetros do cofre, utilize as funcionalidades da Plataforma Bia Agent Builder UI.
 
-Para recuperar um valor sensível no seu MCP Server, utilize o método `get_parameter(parameter_name: str)` da classe `Util`.
+Para recuperar um valor sensível no seu MCP Server, utilize o método `get_parameter(parameter_name: str)` da classe `BiaUtil`.
 
 ```python
 from mcp.server.fastmcp import FastMCP
-from biatoolkit.util import Util
+from biatoolkit.util import BiaUtil
 
 mcp = FastMCP(host="0.0.0.0", stateless_http=True)
 
@@ -308,7 +302,7 @@ mcp = FastMCP(host="0.0.0.0", stateless_http=True)
 def processar() -> str:
     """Executa o processamento de algo"""
     
-    util = Util(mcp)
+    util = BiaUtil(mcp)
     valor = util.get_parameter("meu_parametro")
 
     # Exemplo de uso do parâmetro recuperado. Utilize conforme a necessidade 

biatoolkit-1.0.4.dist-info/RECORD

@@ -0,0 +1,9 @@
+biatoolkit/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+biatoolkit/basic_client.py,sha256=_N2-NcrVWfm-rUuJUksOdR8GONmLYzooMhX1El49A3c,2581
+biatoolkit/util.py,sha256=wP1r29MLVk27iMnMG_Xywa6Yt6H-XfHdlrb4u8Tmg6c,3288
+biatoolkit/schema/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+biatoolkit/schema/header.py,sha256=COJPlqK1cFvvWzDcCw2ru1jszWPgyyvabkjzDCc8AjM,683
+biatoolkit-1.0.4.dist-info/METADATA,sha256=gvwk1ZY8qMHWxqsBfhIyO5t7yeWkr31m2zxXGJV0I5Q,12724
+biatoolkit-1.0.4.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+biatoolkit-1.0.4.dist-info/top_level.txt,sha256=DyrMS0X6u1FDA9uT854LxoT3X7gzMAlsFQabE-WuKMc,11
+biatoolkit-1.0.4.dist-info/RECORD,,

{biatoolkit-1.0.2.dist-info → biatoolkit-1.0.4.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (80.9.0)
+Generator: setuptools (80.10.2)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

biatoolkit-1.0.2.dist-info/RECORD

@@ -1,9 +0,0 @@
-biatoolkit/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-biatoolkit/basic_client.py,sha256=U4JW88QjaMv9VBspnCL_B6JBnGQk8oVH70cFrjNv63Y,1336
-biatoolkit/util.py,sha256=7Dm6dDd-9ju8hmnlv9BzHd_GHTU-2KiWA6d_gP9Ps9E,2081
-biatoolkit/schema/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-biatoolkit/schema/header.py,sha256=COJPlqK1cFvvWzDcCw2ru1jszWPgyyvabkjzDCc8AjM,683
-biatoolkit-1.0.2.dist-info/METADATA,sha256=nq1s0JbUwJ-e0cWMB48jL5UaR5CjhZHxcEIrKdWA6NU,13181
-biatoolkit-1.0.2.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-biatoolkit-1.0.2.dist-info/top_level.txt,sha256=DyrMS0X6u1FDA9uT854LxoT3X7gzMAlsFQabE-WuKMc,11
-biatoolkit-1.0.2.dist-info/RECORD,,