SDK para Python | Basement Gateway

O pacote é basement-gateway. O código está no GitHub.

Instalar

pip install basement-gateway

Criar o cliente

import os
from basement_gateway import BasementGateway
basement = BasementGateway(api_key=os.environ["BASEMENT_API_KEY"])

Quando você não informa api_key, o cliente lê a variável de ambiente BASEMENT_API_KEY.

Chamar o Gateway

Cada ferramenta é um método. Os argumentos são nomeados, e as respostas são objetos com tipos.

# Documentos
docs = basement.docs.list().docs
doc = basement.docs.read(doc_id=docs[0].id)
basement.docs.edit(
    doc_id=doc.id,
    old_text="Preços em USD",
    new_text="Preços em BRL",
    change_summary="Moeda",
)
# Buscar, e ler uma parte de um texto
results = basement.search(query="preço").results
found = basement.text.find(doc_id=doc.id, query="desconto")
# Tarefas
task = basement.tasks.create(title="Revisar os preços do 4º trimestre")
basement.tasks.update(task_id=task.task_id, status="done")
# Serviços conectados
connected = basement.services.list().connected
issue = basement.services.execute(
    tool_slug="jira__getJiraIssue",
    arguments={"issueIdOrKey": "OPS-12"},
)

Assíncrono

AsyncBasementGateway tem os mesmos métodos, com await:

import asyncio
from basement_gateway import AsyncBasementGateway
basement = AsyncBasementGateway()
async def main():
    docs = (await basement.docs.list()).docs
    print(len(docs))
asyncio.run(main())

Tratar erros

Uma chamada que o Gateway recusa lança um ApiError, com o status HTTP e o corpo do erro.

from basement_gateway.core.api_error import ApiError
try:
    basement.tasks.create(title="Revisar os preços do 4º trimestre")
except ApiError as error:
    print(error.status_code)         # 403
    print(error.body.error.code)     # "forbidden"
    print(error.body.error.message)  # "Role lacks write access"

Veja Erros e limites para cada status.

Tempo limite e novas tentativas

Uma chamada expira depois de 60 segundos. O cliente tenta de novo, até mais 2 vezes, quando recebe 408, 429 ou um status 5xx. Mude os dois no cliente ou em uma chamada:

basement = BasementGateway(timeout=30)
basement.docs.list(request_options={"timeout_in_seconds": 10, "max_retries": 3})

Outro endereço

O cliente fala com https://mcp.basement.chat. Para usar outra instalação, informe base_url:

basement = BasementGateway(base_url="http://127.0.0.1:3214")