biatoolkit 1.0.4__tar.gz → 1.1.0__tar.gz

{biatoolkit-1.0.4 → biatoolkit-1.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: biatoolkit
-Version: 1.0.4
+Version: 1.1.0
 Summary: Biblioteca para desenvolvedores que utilizam o BiaAgentBuilder
 Author: Bia Platform Team
 Author-email: data.platform@sankhya.com.br
@@ -19,45 +19,73 @@ Dynamic: summary
 
 # Bia Toolkit
 
-Biblioteca Python para facilitar o desenvolvimento de servidores MCP integrados ao Bia Agent Builder.
+Biblioteca Python para facilitar o desenvolvimento de servidores MCP integrados ao **Bia Agent Builder**.
 
-## **Principais classes da biblioteca**
+O objetivo da Bia Toolkit é abstrair detalhes técnicos do MCP (Model Context Protocol),
+fornecendo utilitários prontos para:
+- Comunicação com servidores MCP
+- Leitura de contexto do runtime (headers)
+- Recuperação segura de parâmetros e segredos
 
-Nesta seção você encontrará uma breve descrição de cada classe da biblioteca **Bia Toolkit**.
+---
 
-### **BiaClient**
+## Principais classes da biblioteca
 
-A classe `BiaClient` tem o objetivo de criar um cliente HTTP para comunicação com servidores MCP (Model Context Protocol).
+### BiaClient
 
-**Principais métodos**:
+A classe `BiaClient` encapsula um cliente HTTP assíncrono para comunicação com servidores MCP
+(Model Context Protocol).
 
-- **list_tools**: Lista todas as ferramentas disponíveis no servidor MCP.
-- **call_tool**: Executa uma ferramenta específica no servidor MCP.
+Ela esconde toda a complexidade de:
+- Conexão HTTP streamable
+- Inicialização de sessões MCP
+- Execução de tools
 
-### **BiaUtil**
+#### Principais métodos
 
-A classe `BiaUtil` fornece métodos auxiliares para gerenciar headers de requisições e parâmetros de configuração em servidores MCP.
+- **list_tools()**
+  - Lista todas as ferramentas disponíveis no servidor MCP.
 
-**Principais métodos**:
+- **call_tool(tool_name, params=None)**
+  - Executa uma ferramenta específica disponível no servidor MCP.
 
-- **construtor**: Recebe uma instância de FastMCP para acessar o contexto das requisições. Armazena a referência do MCP para uso nos métodos.
+---
 
-- **__get_from_ssm**: Busca um parâmetro no AWS SSM Parameter Store.
+### BiaUtil
 
-- **get_header**: Extrai e retorna todos os headers customizados da requisição atual. Retorna um objeto Header com os seguintes campos:
-  - current_host: Host do ERP no qual o copilot está em execução.
-  - user_email: Email do usuário autenticado.
-  - jwt_token: Token JWT do usuário -> SankhyaID, SankhyaPass ou Token interno Bia.
-  - jsessionid: ID de autenticação do ERP.
-  - organization_id: ID da organização da Bia.
-  - codparc: Código do parceiro (parceiro Sankhya).
-  - iam_user_id: ID do usuário do BIA IAM.
-  - gateway_token: Token primário do Sankhya API Gateway.
+A classe `BiaUtil` fornece métodos auxiliares para uso **dentro de MCP Servers**,
+permitindo acesso fácil a:
+- Headers padronizados enviados pelo runtime do Bia Agent Builder
+- Parâmetros sensíveis vindos de variáveis de ambiente ou cofre de segredos (AWS SSM)
+
+#### Principais métodos
+
+- **construtor**
+  - Recebe uma instância de `FastMCP` para acessar o contexto da requisição atual.
+
+- **get_header()**
+  - Extrai e retorna os headers customizados do runtime.
+  - Retorna um objeto `Header` com os campos:
+    - `current_host`: Host do ERP no qual o copilot está em execução.
+    - `user_email`: Email do usuário autenticado.
+    - `jwt_token`: Token JWT do usuário.
+    - `jsessionid`: ID de autenticação do ERP.
+    - `organization_id`: ID da organização da Bia.
+    - `codparc`: Código do parceiro Sankhya.
+    - `iam_user_id`: ID do usuário do BIA IAM.
+    - `gateway_token`: Token primário do Sankhya API Gateway.
+
+- **get_parameter(parameter_name)**
+  - Recupera parâmetros sensíveis seguindo a ordem:
+    1. Variáveis de ambiente do sistema
+    2. AWS SSM Parameter Store (fallback)
+
+  **Observações importantes:**
+  - O SSM só é consultado se o parâmetro **não existir** nas variáveis de ambiente.
+  - Em produção, a busca no SSM depende do header  
+    `X-Amzn-Bedrock-AgentCore-Runtime-Custom-prefix`.
+  - Se esse header não estiver presente, o método retorna `None`.
 
-- **get_parameter**: Busca o parâmetro informado em duas fontes distintas:
-  - Primeiro: Variáveis de ambiente do sistema.
-  - Segundo: AWS SSM Parameter Store (se não encontrado nas variáveis de ambiente).
-  - Retorna o valor do parâmetro ou None se não encontrado em nenhuma fonte.
 
 ## **Como utilizar**
 
@@ -97,7 +125,6 @@ def adicionar(id: int, nome: str) -> str:
     novo_item = {"id": id, "nome": nome}
     return json.dumps(novo_item, indent=4, sort_keys=True)
 
-
 if __name__ == "__main__":
     mcp.run(transport="streamable-http")
 ```
@@ -133,20 +160,17 @@ from biatoolkit.basic_client import BiaClient
 MCP_SERVER_URL = "http://0.0.0.0:8000/mcp"
 client = BiaClient(MCP_SERVER_URL)
 
-async def list_tools() -> None:
+async def list_tools():
     tools = await client.list_tools()
     for tool in tools.tools:
         print(f"Tool: {tool.name}, Description: {tool.description}")
 
-
-async def call_tool(tool_name: str, params: dict = None) -> None:
+async def call_tool(tool_name: str, params: dict = None):
     result = await client.call_tool(tool_name, params)
     print(result.content[0].text)
 
-
 async def main():
     await list_tools()
-    
 
 asyncio.run(main())
 ```

{biatoolkit-1.0.4 → biatoolkit-1.1.0}/README.md

@@ -51,26 +51,62 @@ A classe `BiaClient` tem o objetivo de criar um cliente HTTP para comunicação
 
 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**:
+#### Principais métodos
+
+- **construtor**
+  - Recebe uma instância de `FastMCP` para acessar o contexto da requisição atual.
+  - Permite (opcionalmente) receber configurações via `BiaToolkitSettings`.
+
+- **get_header()**
+  - Extrai e retorna os headers customizados enviados pelo runtime do Bia Agent Builder.
+  - Retorna um objeto `Header` tipado com os campos:
+    - current_host
+    - user_email
+    - jwt_token
+    - jsessionid
+    - organization_id
+    - codparc
+    - iam_user_id
+    - gateway_token
+
+- **get_parameter(parameter_name: str)**
+  - Recupera parâmetros sensíveis seguindo a seguinte ordem:
+    1. Variáveis de ambiente do sistema
+    2. AWS SSM Parameter Store (fallback)
+
+  **Observações importantes:**
+  - O SSM só é consultado se o parâmetro **não existir** nas variáveis de ambiente.
+  - A consulta ao SSM depende do header  
+    `X-Amzn-Bedrock-AgentCore-Runtime-Custom-prefix`.
+  - Caso esse header não esteja presente, o método retorna `None`.
+
+## Configuração da biblioteca (BiaToolkitSettings)
 
-- **construtor**: Recebe uma instância de FastMCP para acessar o contexto das requisições. Armazena a referência do MCP para uso nos métodos.
+A biblioteca utiliza a classe `BiaToolkitSettings` para centralizar configurações
+e permitir ajustes sem alteração de código.
 
-- **__get_from_ssm**: Busca um parâmetro no AWS SSM Parameter Store.
+Essas configurações podem ser sobrescritas via variáveis de ambiente.
 
-- **get_header**: Extrai e retorna todos os headers customizados da requisição atual. Retorna um objeto Header com os seguintes campos:
-  - current_host: Host do ERP no qual o copilot está em execução.
-  - user_email: Email do usuário autenticado.
-  - jwt_token: Token JWT do usuário -> SankhyaID, SankhyaPass ou Token interno Bia.
-  - jsessionid: ID de autenticação do ERP.
-  - organization_id: ID da organização da Bia.
-  - codparc: Código do parceiro (parceiro Sankhya).
-  - iam_user_id: ID do usuário do BIA IAM.
-  - gateway_token: Token primário do Sankhya API Gateway.
+### Parâmetros disponíveis
 
-- **get_parameter**: Busca o parâmetro informado em duas fontes distintas:
-  - Primeiro: Variáveis de ambiente do sistema.
-  - Segundo: AWS SSM Parameter Store (se não encontrado nas variáveis de ambiente).
-  - Retorna o valor do parâmetro ou None se não encontrado em nenhuma fonte.
+- **BIATOOLKIT_HEADER_PREFIX**
+  - Prefixo dos headers enviados pelo runtime
+  - Padrão: `x-amzn-bedrock-agentcore-runtime-custom`
+
+- **BIATOOLKIT_AWS_REGION**
+  - Região AWS utilizada para acesso ao SSM
+  - Padrão: `sa-east-1`
+
+- **BIATOOLKIT_CLIENT_TIMEOUT_SECONDS**
+  - Timeout (em segundos) para chamadas HTTP do `BiaClient`
+  - Padrão: `120`
+
+### Exemplo
+
+```bash
+export BIATOOLKIT_AWS_REGION=us-east-1
+export BIATOOLKIT_CLIENT_TIMEOUT_SECONDS=60
+export BIATOOLKIT_HEADER_PREFIX=x-amzn-bedrock-agentcore-runtime-custom
 
 ## **Como utilizar**
 
@@ -335,7 +371,10 @@ if __name__ == "__main__":
     mcp.run(transport="streamable-http")
 ```
 
-O método `get_parameter(parameter_name: str)` busca o parâmetro informado em duas fontes distintas. Primeiro, o método tenta buscar o parâmetro consultando as **variáveis de ambiente** do sistema. Caso não exista, o método tenta buscar o parâmetro na **AWS SSM Parameter Store**.
+O método `get_parameter(parameter_name: str)` busca o parâmetro informado em duas fontes distintas. Primeiro, o método tenta buscar o parâmetro consultando as **variáveis de ambiente** do sistema. Caso não exista, o método tenta buscar o parâmetro na AWS SSM Parameter Store.
+Essa busca depende da presença do header
+`X-Amzn-Bedrock-AgentCore-Runtime-Custom-prefix`, que é automaticamente
+fornecido em ambiente produtivo pelo Bia Agent Builder.
 
 ✅ Isso é vantajoso pois você pode armazenar o parâmetro em:
 

biatoolkit-1.1.0/biatoolkit/__init__.py

@@ -0,0 +1,4 @@
+from .util import BiaUtil
+from .basic_client import BiaClient
+
+__all__ = ["BiaUtil", "BiaClient"]

biatoolkit-1.1.0/biatoolkit/basic_client.py

@@ -0,0 +1,141 @@
+"""
+biatoolkit.basic_client
+
+Este módulo contém o BiaClient, um cliente HTTP assíncrono para comunicação
+com servidores MCP (Model Context Protocol).
+
+Responsabilidades:
+- Abrir e gerenciar conexões HTTP streamable com servidores MCP.
+- Inicializar sessões MCP.
+- Encapsular chamadas comuns (listar tools, executar tool).
+
+O objetivo é esconder os detalhes de sessão, streams e inicialização,
+expondo uma API simples para quem consome a biblioteca.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Awaitable, Callable, Optional, Dict
+
+from mcp import ClientSession
+from mcp.client.streamable_http import streamablehttp_client
+
+from .settings import BiaToolkitSettings
+
+
+class BiaClient:
+    """
+    Cliente básico para interação com servidores MCP.
+
+    Esta classe encapsula toda a complexidade envolvida em:
+    - Abrir conexões HTTP streamable
+    - Criar e inicializar ClientSession
+    - Executar chamadas MCP
+
+    Exemplos de uso:
+        client = BiaClient("http://localhost:8000")
+        tools = await client.list_tools()
+        result = await client.call_tool("minha_tool", {"x": 1})
+    """
+
+    def __init__(
+        self,
+        url: str = "http://0.0.0.0:8000/mcp",
+        headers: Optional[Dict[str, str]] = None,
+        settings: Optional[BiaToolkitSettings] = None,
+    ):
+        """
+        Inicializa o cliente MCP.
+
+        Args:
+            url:
+                URL base do servidor MCP.
+                - Se não terminar com '/mcp', o sufixo será adicionado automaticamente.
+            headers:
+                Headers HTTP opcionais enviados em todas as requisições.
+                Normalmente usados para enviar contexto (runtime, autenticação, etc.).
+            settings:
+                Configurações opcionais da biblioteca (timeout, etc.).
+                Se None, carrega defaults e overrides via variáveis de ambiente.
+        """
+        # Carrega configurações globais (timeout, etc.)
+        self.settings = settings or BiaToolkitSettings.from_env()
+
+        # Garante que a URL termine com '/mcp'
+        suffix = "/mcp"
+        self.url = url if url.endswith(suffix) else f"{url}{suffix}"
+
+        # Headers HTTP que serão enviados para o servidor MCP
+        self.headers = headers
+
+    async def _with_session(self, fn: Callable[[ClientSession], Awaitable[Any]]) -> Any:
+        """
+        Executa uma função dentro de uma sessão MCP já inicializada.
+
+        Este método centraliza todo o boilerplate necessário para:
+        - Abrir a conexão HTTP streamable
+        - Criar a ClientSession
+        - Chamar session.initialize()
+        - Garantir fechamento correto dos recursos
+
+        Ele recebe uma função (callback) que recebe a ClientSession e
+        executa a lógica específica (listar tools, chamar tool, etc.).
+
+        Args:
+            fn: Função assíncrona que recebe uma ClientSession.
+
+        Returns:
+            O valor retornado pela função fn.
+        """
+        async with streamablehttp_client(
+            self.url,
+            self.headers,
+            # Timeout configurável via settings
+            timeout=self.settings.client_timeout_seconds,
+            # Mantém o servidor ativo mesmo após fechar streams
+            terminate_on_close=False,
+        ) as (read_stream, write_stream, _):
+
+            # Cria a sessão MCP usando os streams
+            async with ClientSession(read_stream, write_stream) as session:
+                # Inicialização obrigatória do protocolo MCP
+                await session.initialize()
+
+                # Executa a lógica específica passada pelo caller
+                return await fn(session)
+
+    async def list_tools(self) -> dict:
+        """
+        Lista todas as ferramentas (tools) disponíveis no servidor MCP.
+
+        Returns:
+            dict: Estrutura contendo as tools expostas pelo servidor.
+        """
+
+        async def _call(session: ClientSession) -> Any:
+            return await session.list_tools()
+
+        return await self._with_session(_call)
+
+    async def call_tool(self, tool_name: str, params: dict = None) -> dict:
+        """
+        Executa uma ferramenta específica disponível no servidor MCP.
+
+        Args:
+            tool_name:
+                Nome da tool a ser executada (exatamente como exposta pelo servidor).
+            params:
+                Parâmetros da tool, enviados como dicionário.
+                Pode ser None se a tool não exigir parâmetros.
+
+        Returns:
+            dict: Resultado da execução da tool.
+        """
+
+        async def _call(session: ClientSession) -> Any:
+            return await session.call_tool(tool_name, params)
+
+        return await self._with_session(_call)
+
+
+__all__ = ["BiaClient"]

biatoolkit-1.1.0/biatoolkit/schema/__init__.py

@@ -0,0 +1 @@
+# biatoolkit/schema/__init__.py

biatoolkit-1.1.0/biatoolkit/settings.py

@@ -0,0 +1,106 @@
+"""
+biatoolkit.settings
+
+Este módulo centraliza todas as configurações globais da Bia Toolkit.
+
+Objetivos:
+- Evitar valores hardcoded espalhados pelo código.
+- Permitir override simples via variáveis de ambiente.
+- Facilitar testes, manutenção e futuras extensões.
+
+Exemplos de override via environment:
+    BIATOOLKIT_HEADER_PREFIX=x-amzn-bedrock-agentcore-runtime-custom
+    BIATOOLKIT_AWS_REGION=us-east-1
+    BIATOOLKIT_CLIENT_TIMEOUT_SECONDS=60
+"""
+
+from dataclasses import dataclass
+import os
+
+
+@dataclass(frozen=True)
+class BiaToolkitSettings:
+    """
+    Objeto imutável (frozen) que representa as configurações da biblioteca.
+
+    Por que usar dataclass + frozen?
+    - Facilita leitura e manutenção.
+    - Garante que as configurações não sejam alteradas em runtime,
+      evitando efeitos colaterais difíceis de rastrear.
+    """
+
+    # ------------------------------------------------------------------
+    # Server / Headers
+    # ------------------------------------------------------------------
+
+    # Prefixo base dos headers customizados aceitos pelo runtime do AgentCore.
+    # Exemplo final:
+    #   x-amzn-bedrock-agentcore-runtime-custom-user-email
+    header_prefix: str = "x-amzn-bedrock-agentcore-runtime-custom"
+
+    # ------------------------------------------------------------------
+    # AWS
+    # ------------------------------------------------------------------
+
+    # Região AWS usada para acessar serviços como SSM Parameter Store.
+    # Default alinhado com o ambiente do Bia Agent Builder.
+    aws_region: str = "sa-east-1"
+
+    # ------------------------------------------------------------------
+    # Client (MCP HTTP Client)
+    # ------------------------------------------------------------------
+
+    # Timeout padrão (em segundos) para chamadas HTTP ao servidor MCP.
+    # Evita requests presos indefinidamente em ambientes instáveis.
+    client_timeout_seconds: int = 120
+
+    # ------------------------------------------------------------------
+    # Factory methods
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def from_env() -> "BiaToolkitSettings":
+        """
+        Cria uma instância de BiaToolkitSettings a partir de variáveis de ambiente.
+
+        Comportamento:
+        - Cada configuração pode ser sobrescrita individualmente via env.
+        - Caso a variável não exista ou seja inválida, usa o valor default.
+
+        Variáveis suportadas:
+        - BIATOOLKIT_HEADER_PREFIX
+        - BIATOOLKIT_AWS_REGION
+        - BIATOOLKIT_CLIENT_TIMEOUT_SECONDS
+
+        Returns:
+            BiaToolkitSettings: instância configurada.
+        """
+
+        # Header prefix (string simples)
+        header_prefix = os.getenv(
+            "BIATOOLKIT_HEADER_PREFIX",
+            "x-amzn-bedrock-agentcore-runtime-custom",
+        )
+
+        # Região AWS
+        aws_region = os.getenv(
+            "BIATOOLKIT_AWS_REGION",
+            "sa-east-1",
+        )
+
+        # Timeout do client (conversão segura para int)
+        timeout_str = os.getenv(
+            "BIATOOLKIT_CLIENT_TIMEOUT_SECONDS",
+            "120",
+        )
+        try:
+            timeout = int(timeout_str)
+        except ValueError:
+            # Se o valor não for um inteiro válido, cai no default
+            timeout = 120
+
+        return BiaToolkitSettings(
+            header_prefix=header_prefix,
+            aws_region=aws_region,
+            client_timeout_seconds=timeout,
+        )

biatoolkit-1.1.0/biatoolkit/util.py

@@ -0,0 +1,228 @@
+"""
+biatoolkit.util
+
+Este módulo contém a classe BiaUtil, uma "fachada" (facade) com utilidades comuns
+para MCP Servers no ecossistema Bia Agent Builder.
+
+Responsabilidades principais:
+- Ler e interpretar headers padronizados enviados no runtime (AWS Bedrock AgentCore).
+- Buscar parâmetros de configuração/segredos primeiro no ambiente (.env/variáveis),
+  e como fallback no AWS SSM Parameter Store (cofre de segredos no ambiente produtivo).
+"""
+
+from typing import Optional
+import os
+
+import boto3
+from mcp.server.fastmcp import FastMCP
+
+from .settings import BiaToolkitSettings
+from .schema.header import Header
+
+
+class BiaUtil:
+    """
+    Classe utilitária para uso dentro de um MCP Server.
+
+    Exemplos de uso:
+        util = BiaUtil(mcp)
+        header = util.get_header()
+        token = util.get_parameter("MEU_TOKEN")
+
+    Observações:
+    - Esta classe depende do contexto de requisição do FastMCP (mcp.get_context()).
+    - Em produção (AgentCore), apenas alguns headers são repassados pelo runtime.
+    """
+
+    # Prefixo base dos headers customizados aceitos no runtime do AgentCore.
+    # Exemplo de header final: "x-amzn-bedrock-agentcore-runtime-custom-user-email"
+    HEADER_PREFIX = "x-amzn-bedrock-agentcore-runtime-custom"
+
+    def __init__(self, mcp: FastMCP, settings: Optional[BiaToolkitSettings] = None):
+        """
+        Inicializa o utilitário.
+
+        Args:
+            mcp: Instância do FastMCP, usada para acessar o contexto da requisição.
+            settings: Configurações opcionais (region, timeout, header_prefix).
+                      Se None, carrega defaults e overrides via variáveis de ambiente.
+        """
+        self.mcp = mcp
+
+        # Settings podem vir explicitamente (testes/uso avançado) ou via environment.
+        self.settings = settings or BiaToolkitSettings.from_env()
+
+        # Permite sobrescrever o prefixo dos headers via settings.
+        # Mantém compatibilidade: self.HEADER_PREFIX é usado na composição das chaves.
+        self.HEADER_PREFIX = self.settings.header_prefix
+
+    def _headers(self) -> dict:
+        """
+        Obtém o dicionário de headers da requisição atual via contexto do MCP.
+
+        Returns:
+            dict: Headers presentes na requisição (ou {} se ausentes).
+        """
+        ctx = self.mcp.get_context()
+        # Estrutura esperada no FastMCP: ctx.request_context.request.headers
+        return ctx.request_context.request.headers or {}
+
+    def _h(self, suffix: str):
+        """
+        Lê um header customizado do runtime, dado o sufixo.
+
+        Exemplo:
+            suffix="user-email" -> lê "x-amzn-bedrock-agentcore-runtime-custom-user-email"
+
+        Args:
+            suffix: Parte final do nome do header.
+
+        Returns:
+            O valor do header (str) ou None.
+        """
+        return self._headers().get(f"{self.HEADER_PREFIX}-{suffix}", None)
+
+    def _to_int(self, value, default: int = 0) -> int:
+        """
+        Converte um valor para int de forma segura.
+
+        Por quê:
+        - Headers podem vir como None, string vazia ou valores inválidos ("abc").
+        - Este método evita exceptions e padroniza o fallback para 'default'.
+
+        Args:
+            value: valor a converter.
+            default: valor retornado caso não seja possível converter.
+
+        Returns:
+            int: valor convertido ou default.
+        """
+        try:
+            if value is None:
+                return default
+            if isinstance(value, str) and value.strip() == "":
+                return default
+            return int(value)
+        except (TypeError, ValueError):
+            return default
+
+    def __get_from_ssm(self, parameter_name: str) -> str:
+        """
+        Busca o valor de um parâmetro no AWS SSM Parameter Store.
+
+        Como funciona:
+        - O runtime envia um header "...-prefix" que define a "pasta" (path) base dos segredos.
+        - O nome final do parâmetro no SSM fica: "{prefix}/{parameter_name}"
+        - WithDecryption=True permite ler SecureString.
+
+        Importante:
+        - Se não houver prefix no header, retorna None (não tenta chamar AWS).
+          Isso evita chamadas inválidas como "None/MEU_PARAM".
+
+        Args:
+            parameter_name: Nome do parâmetro a ser buscado.
+
+        Returns:
+            str | None: Valor do parâmetro, ou None se não encontrado/sem prefix.
+        """
+        # Obtém headers do contexto do MCP
+        headers = self._headers()
+
+        # Prefixo customizado do header que aponta para a "pasta" de segredos
+        prefix = headers.get(f"{self.HEADER_PREFIX}-prefix", None)
+
+        # Sem prefix não é possível montar o path no SSM; evita chamadas inválidas.
+        if not prefix:
+            return None
+
+        # Cria cliente SSM na região configurada (default: sa-east-1)
+        client = boto3.client("ssm", region_name=self.settings.aws_region)
+
+        try:
+            response = client.get_parameter(
+                Name=f"{prefix}/{parameter_name}",
+                WithDecryption=True,
+            )
+        except client.exceptions.ParameterNotFound:
+            # Retorna None se o parâmetro não existir no SSM
+            return None
+
+        # Estrutura da resposta: {"Parameter": {"Value": "..."}}
+        return response.get("Parameter", {}).get("Value")
+
+    def get_header(self) -> Header:
+        """
+        Extrai e retorna um objeto Header com os principais campos do runtime.
+
+        Returns:
+            Header: dataclass/objeto com os campos interpretados do header.
+        """
+        return Header(
+            # Strings (podem ser None)
+            current_host=self._h("current-host"),
+            user_email=self._h("user-email"),
+            jwt_token=self._h("jwt-token"),
+            jsessionid=self._h("jsessionid"),
+
+            # Inteiros (com fallback seguro para 0)
+            organization_id=self._to_int(self._h("organization-id"), 0),
+            codparc=self._to_int(self._h("codparc"), 0),
+            iam_user_id=self._to_int(self._h("iam-user-id"), 0),
+
+            # String (pode ser None)
+            gateway_token=self._h("gateway-token"),
+        )
+
+    def get_parameter(self, parameter_name: str) -> str:
+        """
+        Recupera um parâmetro sensível/configurável.
+
+        Ordem de resolução:
+        1) Variáveis de ambiente (ideal para execução local / CI)
+        2) AWS SSM Parameter Store (ideal para produção via cofre)
+
+        Observação:
+        - Implementação evita avaliar SSM antecipadamente.
+          (Não usamos mais os.getenv(name, default_func()) porque chamaria AWS sempre.)
+
+        Args:
+            parameter_name: Nome do parâmetro.
+
+        Returns:
+            str | None: valor encontrado ou None.
+        """
+        value = self._get_from_env(parameter_name)
+        if value is not None:
+            return value
+        return self._get_from_stores(parameter_name)
+
+    def _get_from_env(self, parameter_name: str):
+        """
+        Provider interno: busca em variáveis de ambiente do sistema.
+
+        Args:
+            parameter_name: Nome do parâmetro.
+
+        Returns:
+            str | None
+        """
+        return os.getenv(parameter_name)
+
+    def _get_from_stores(self, parameter_name: str):
+        """
+        Provider interno: busca em fontes externas (hoje apenas SSM).
+
+        Este método existe para facilitar manutenção e evolução:
+        amanhã pode incluir outros provedores (Secrets Manager, Vault, etc.)
+        sem mudar a API pública de get_parameter().
+
+        Args:
+            parameter_name: Nome do parâmetro.
+
+        Returns:
+            str | None
+        """
+        return self.__get_from_ssm(parameter_name)
+
+
+__all__ = ["BiaUtil"]

{biatoolkit-1.0.4 → biatoolkit-1.1.0}/biatoolkit.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: biatoolkit
-Version: 1.0.4
+Version: 1.1.0
 Summary: Biblioteca para desenvolvedores que utilizam o BiaAgentBuilder
 Author: Bia Platform Team
 Author-email: data.platform@sankhya.com.br
@@ -19,45 +19,73 @@ Dynamic: summary
 
 # Bia Toolkit
 
-Biblioteca Python para facilitar o desenvolvimento de servidores MCP integrados ao Bia Agent Builder.
+Biblioteca Python para facilitar o desenvolvimento de servidores MCP integrados ao **Bia Agent Builder**.
 
-## **Principais classes da biblioteca**
+O objetivo da Bia Toolkit é abstrair detalhes técnicos do MCP (Model Context Protocol),
+fornecendo utilitários prontos para:
+- Comunicação com servidores MCP
+- Leitura de contexto do runtime (headers)
+- Recuperação segura de parâmetros e segredos
 
-Nesta seção você encontrará uma breve descrição de cada classe da biblioteca **Bia Toolkit**.
+---
 
-### **BiaClient**
+## Principais classes da biblioteca
 
-A classe `BiaClient` tem o objetivo de criar um cliente HTTP para comunicação com servidores MCP (Model Context Protocol).
+### BiaClient
 
-**Principais métodos**:
+A classe `BiaClient` encapsula um cliente HTTP assíncrono para comunicação com servidores MCP
+(Model Context Protocol).
 
-- **list_tools**: Lista todas as ferramentas disponíveis no servidor MCP.
-- **call_tool**: Executa uma ferramenta específica no servidor MCP.
+Ela esconde toda a complexidade de:
+- Conexão HTTP streamable
+- Inicialização de sessões MCP
+- Execução de tools
 
-### **BiaUtil**
+#### Principais métodos
 
-A classe `BiaUtil` fornece métodos auxiliares para gerenciar headers de requisições e parâmetros de configuração em servidores MCP.
+- **list_tools()**
+  - Lista todas as ferramentas disponíveis no servidor MCP.
 
-**Principais métodos**:
+- **call_tool(tool_name, params=None)**
+  - Executa uma ferramenta específica disponível no servidor MCP.
 
-- **construtor**: Recebe uma instância de FastMCP para acessar o contexto das requisições. Armazena a referência do MCP para uso nos métodos.
+---
 
-- **__get_from_ssm**: Busca um parâmetro no AWS SSM Parameter Store.
+### BiaUtil
 
-- **get_header**: Extrai e retorna todos os headers customizados da requisição atual. Retorna um objeto Header com os seguintes campos:
-  - current_host: Host do ERP no qual o copilot está em execução.
-  - user_email: Email do usuário autenticado.
-  - jwt_token: Token JWT do usuário -> SankhyaID, SankhyaPass ou Token interno Bia.
-  - jsessionid: ID de autenticação do ERP.
-  - organization_id: ID da organização da Bia.
-  - codparc: Código do parceiro (parceiro Sankhya).
-  - iam_user_id: ID do usuário do BIA IAM.
-  - gateway_token: Token primário do Sankhya API Gateway.
+A classe `BiaUtil` fornece métodos auxiliares para uso **dentro de MCP Servers**,
+permitindo acesso fácil a:
+- Headers padronizados enviados pelo runtime do Bia Agent Builder
+- Parâmetros sensíveis vindos de variáveis de ambiente ou cofre de segredos (AWS SSM)
+
+#### Principais métodos
+
+- **construtor**
+  - Recebe uma instância de `FastMCP` para acessar o contexto da requisição atual.
+
+- **get_header()**
+  - Extrai e retorna os headers customizados do runtime.
+  - Retorna um objeto `Header` com os campos:
+    - `current_host`: Host do ERP no qual o copilot está em execução.
+    - `user_email`: Email do usuário autenticado.
+    - `jwt_token`: Token JWT do usuário.
+    - `jsessionid`: ID de autenticação do ERP.
+    - `organization_id`: ID da organização da Bia.
+    - `codparc`: Código do parceiro Sankhya.
+    - `iam_user_id`: ID do usuário do BIA IAM.
+    - `gateway_token`: Token primário do Sankhya API Gateway.
+
+- **get_parameter(parameter_name)**
+  - Recupera parâmetros sensíveis seguindo a ordem:
+    1. Variáveis de ambiente do sistema
+    2. AWS SSM Parameter Store (fallback)
+
+  **Observações importantes:**
+  - O SSM só é consultado se o parâmetro **não existir** nas variáveis de ambiente.
+  - Em produção, a busca no SSM depende do header  
+    `X-Amzn-Bedrock-AgentCore-Runtime-Custom-prefix`.
+  - Se esse header não estiver presente, o método retorna `None`.
 
-- **get_parameter**: Busca o parâmetro informado em duas fontes distintas:
-  - Primeiro: Variáveis de ambiente do sistema.
-  - Segundo: AWS SSM Parameter Store (se não encontrado nas variáveis de ambiente).
-  - Retorna o valor do parâmetro ou None se não encontrado em nenhuma fonte.
 
 ## **Como utilizar**
 
@@ -97,7 +125,6 @@ def adicionar(id: int, nome: str) -> str:
     novo_item = {"id": id, "nome": nome}
     return json.dumps(novo_item, indent=4, sort_keys=True)
 
-
 if __name__ == "__main__":
     mcp.run(transport="streamable-http")
 ```
@@ -133,20 +160,17 @@ from biatoolkit.basic_client import BiaClient
 MCP_SERVER_URL = "http://0.0.0.0:8000/mcp"
 client = BiaClient(MCP_SERVER_URL)
 
-async def list_tools() -> None:
+async def list_tools():
     tools = await client.list_tools()
     for tool in tools.tools:
         print(f"Tool: {tool.name}, Description: {tool.description}")
 
-
-async def call_tool(tool_name: str, params: dict = None) -> None:
+async def call_tool(tool_name: str, params: dict = None):
     result = await client.call_tool(tool_name, params)
     print(result.content[0].text)
 
-
 async def main():
     await list_tools()
-    
 
 asyncio.run(main())
 ```

{biatoolkit-1.0.4 → biatoolkit-1.1.0}/biatoolkit.egg-info/SOURCES.txt

@@ -2,6 +2,7 @@ README.md
 setup.py
 biatoolkit/__init__.py
 biatoolkit/basic_client.py
+biatoolkit/settings.py
 biatoolkit/util.py
 biatoolkit.egg-info/PKG-INFO
 biatoolkit.egg-info/SOURCES.txt

{biatoolkit-1.0.4 → biatoolkit-1.1.0}/setup.py

@@ -2,7 +2,7 @@ from setuptools import setup, find_packages
 
 setup(
     name='biatoolkit',
-    version='1.0.4',
+    version='1.1.0',
     packages=find_packages(),
     install_requires=[],
     author='Bia Platform Team',  

biatoolkit-1.0.4/biatoolkit/basic_client.py

@@ -1,63 +0,0 @@
-from mcp import ClientSession
-from mcp.client.streamable_http import streamablehttp_client
-
-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.
-
-        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()  # 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 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()  # Inicializa a sessão
-                result = await session.call_tool(tool_name, params)  # Executa a ferramenta
-        return result

biatoolkit-1.0.4/biatoolkit/util.py

@@ -1,79 +0,0 @@
-from mcp.server.fastmcp import FastMCP
-from .schema.header import Header
-
-import boto3
-import os
-
-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 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  # 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.
-
-        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),
-            jwt_token=headers.get(f"{self.HEADER_PREFIX}-jwt-token", None),
-            jsessionid=headers.get(f"{self.HEADER_PREFIX}-jsessionid", None),
-            organization_id=int(headers.get(f"{self.HEADER_PREFIX}-organization-id", 0)),
-            codparc=int(headers.get(f"{self.HEADER_PREFIX}-codparc", 0)),
-            iam_user_id=int(headers.get(f"{self.HEADER_PREFIX}-iam-user-id", 0)),
-            gateway_token=headers.get(f"{self.HEADER_PREFIX}-gateway-token", None)
-        )
-    
-    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 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)
-        )