Metadata-Version: 2.4
Name: bantubyte
Version: 1.2.8
Summary: AI-powered coding assistant CLI — powered by Kimi K2.6 via the BantuByte platform (more models coming)
Project-URL: Homepage, https://bantubyte.dev
Project-URL: Documentation, https://docs.bantubyte.dev
Project-URL: Support, https://bantubyte.dev/contacto
Author-email: BantuByte <support@bantubyte.dev>
License: Proprietary
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Code Generators
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: bashlex<1,>=0.18
Requires-Dist: click<9,>=8.1
Requires-Dist: httpx[http2]<1,>=0.27
Requires-Dist: jsonschema<5,>=4.20
Requires-Dist: pathspec<2,>=1.0
Requires-Dist: pillow<13,>=12.2.0
Requires-Dist: prompt-toolkit<4,>=3.0
Requires-Dist: psutil<8,>=5.9
Requires-Dist: pydantic<3,>=2.0
Requires-Dist: pymupdf<2,>=1.26.7
Requires-Dist: rich<14,>=13.0
Provides-Extra: dev
Requires-Dist: mypy>=1.8; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest-httpx>=0.30; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Description-Content-Type: text/markdown

# BantuByte CLI

**Assistente de programação com IA, no teu terminal.** Conversa em
streaming, edição de ficheiros, execução de comandos, sub-agentes e
integração [Model Context Protocol (MCP)](https://modelcontextprotocol.io)
— tudo a partir da linha de comandos.

Atualmente com o modelo **Kimi K2.6**; a camada de modelos é
extensível e novos modelos vão ficar selecionáveis em versões futuras.

> BantuByte é um serviço. O acesso requer uma conta e um plano ativo em
> [bantubyte.dev](https://bantubyte.dev).

---

## Início rápido

### 1. Instalar

```bash
pip install bantubyte
```

Requer Python 3.10 – 3.13. Funciona em macOS, Linux e Windows.

### 2. Autenticar

```bash
bantubyte login
```

Abre o browser, corre o fluxo OAuth2 (PKCE) com a tua conta Google e
guarda os tokens em `~/.bantubyte/auth.json` (permissão `0600` em
sistemas POSIX). O CLI renova os tokens automaticamente antes de
expirarem.

### 3. Começar a conversar

```bash
bantubyte                       # REPL interativo
bantubyte --resume              # escolher uma sessão anterior de uma lista
bantubyte --resume <session-id> # retomar uma sessão específica
```

O REPL aceita:
- Texto simples — enviado ao modelo como mensagem.
- `/<comando>` — um comando (ver abaixo).
- Entrada multilinha com Esc-Enter (um único Enter envia quando ainda
  não há nova linha).

---

## Comandos

| Comando | Descrição |
|---|---|
| `/help` | Lista todos os comandos. |
| `/clear` | Inicia uma sessão nova no mesmo REPL. |
| `/exit`, `/quit` | Sai do REPL de forma limpa. |
| `/login`, `/logout` | Re-autentica ou revoga as credenciais. |
| `/config` | Ver e editar `~/.bantubyte/config.json`. |
| `/model` | Trocar de modelo. |
| `/theme` | Alternar entre tema escuro e claro. |
| `/permissions` | Editar as listas allow/deny de ferramentas do projeto. |
| `/session` | Ver, retomar ou apagar sessões anteriores. |
| `/usage` | Uso de tokens + quota mensal do teu plano. |
| `/cost` | Custo estimado da sessão atual. |
| `/compact` | Forçar uma compactação de contexto. |
| `/mcp ...` | Gerir servidores MCP — ver secção seguinte. |

---

## MCP — Model Context Protocol

O MCP permite ligar servidores de ferramentas externos ao CLI sem
alterar o BantuByte. A comunidade publica servidores para sistemas de
ficheiros, git, postgres, sqlite, GitHub, Puppeteer, Slack e muitos
mais — ver o [catálogo oficial](https://github.com/modelcontextprotocol/servers).

### Configurar servidores

Cria `~/.bantubyte/mcp.json` com um mapa `mcpServers`. Cada entrada
declara como arrancar um servidor e quanto tempo esperar por ele.

```jsonc
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "${HOME}/Projects"
      ],
      "timeout_ms": 15000,
      "tool_timeout_ms": 60000
    },

    "time": {
      "command": "uvx",
      "args": ["mcp-server-time"]
    }
  }
}
```

Referência de campos:

| Campo | Default | Notas |
|---|---|---|
| `command` | obrigatório | Executável (resolvido via `PATH`, incl. `.cmd`/`.bat` no Windows) ou caminho absoluto. |
| `args` | `[]` | Argumentos passados ao `command`. |
| `env` | `{}` | Variáveis de ambiente adicionais. |
| `enabled` | `true` | Define `false` para ignorar o servidor no arranque. |
| `timeout_ms` | `10000` | Timeout do handshake + `tools/list` (máx 120 s). |
| `tool_timeout_ms` | `1800000` (30 min) | Timeout por chamada (`tools/call`). Intervalo: 1 s – 4 h. |

A expansão `${VAR}` é suportada em `command`, `args` e `env` com a
sintaxe `${VAR}` (erro se não definida) e `${VAR:-default}`.

### Overrides por projeto

Coloca um `.bantubyte/mcp.json` na pasta de um projeto. O CLI procura
subindo a partir da pasta atual e funde-o sobre a config global. As
entradas do projeto sobrepõem-se às globais com o mesmo nome.

### Gerir servidores a partir do REPL

```text
/mcp                          # alias de /mcp list
/mcp list                     # mostra cada servidor com estado, versão, nº de ferramentas
/mcp info <name>              # detalhe completo
/mcp logs <name>              # último stderr desse servidor
/mcp reload                   # relê o mcp.json e reinicia tudo
/mcp enable <name>            # ativa e recarrega
/mcp disable <name>           # desativa e recarrega
/mcp prompts [server]         # lista templates de prompt
/mcp prompt <server> <name> [key=value ...]
```

O subsistema MCP é resiliente: auto-reconexão com backoff em falhas
transitórias, encerramento gracioso dos subprocessos, propagação de
cancelamento (Ctrl-C), e sanitização Unicode das descrições de
ferramentas para defesa contra ataques de injeção.

---

## Configuração

As definições vivem em camadas, com precedência `env > projeto > utilizador > defaults`:

| Camada | Ficheiro | Propósito |
|---|---|---|
| Defaults | código | Valores sensatos por omissão. |
| Utilizador | `~/.bantubyte/config.json` | Preferências (tema, modelo, etc.). |
| Projeto | `<cwd>/.bantubyte/config.json` | Listas allow/deny de ferramentas do projeto. |
| Env | variáveis `BANTUBYTE_*` | Override no arranque. |

Variáveis de ambiente úteis:

- `BANTUBYTE_MODEL` — sobrepõe o modelo default.
- `BANTUBYTE_VERBOSE=1` — ativa logging detalhado para ficheiro.
- `BANTUBYTE_TOOL_PERMISSION_MODE` — `default`, `auto-allow` ou `always-ask`.
- `BANTUBYTE_CONFIG_DIR` — sobrepõe `~/.bantubyte/`.

---

## Sessões

Cada conversa é uma sessão, persistida como JSONL em
`~/.bantubyte/sessions/<id>.jsonl`. Retoma com `bantubyte --resume`
para escolher de uma lista, ou `bantubyte --resume <id>` para ir direto.

A corrupção de uma sessão (uma linha má, fim truncado) não impede o
carregamento — o CLI regista cada entrada descartada e continua com as
mensagens recuperadas. O `/session` e o seletor de resume marcam
sessões danificadas com `⚠`.

---

## Armazenamento

```
~/.bantubyte/
├── config.json            # definições do utilizador
├── auth.json              # tokens OAuth (0600 em POSIX)
├── mcp.json               # declarações de servidores MCP
├── sessions/              # transcrições JSONL, uma por sessão
├── logs/                  # logs rotativos
└── history                # histórico de input do REPL
```

Cada diretório é criado com permissões restritivas (`0700` em POSIX).

---

## Resolução de problemas

**`Not authenticated. Run 'bantubyte login' first.`** — o token expirou
ou nunca foi criado. Corre `bantubyte login`. Se o browser não abrir,
copia o URL impresso no terminal.

**Servidor MCP preso em "reconnecting"** — corre `/mcp logs <name>` para
ver o stderr. Causas comuns: argumento em falta, caminho de comando
errado no Windows, ou download de dependência do servidor a exceder o
timeout (sobe o `timeout_ms`).

**Onde estão os logs?** — `~/.bantubyte/logs/bantubyte.log`, rotado
diariamente. Define `BANTUBYTE_VERBOSE=1` para granularidade `DEBUG`.

---

## Compatibilidade

- **Python**: 3.10 – 3.13.
- **SO**: macOS, Linux, Windows.
- **Transportes MCP** (v1): stdio. HTTP / SSE / WebSocket planeados para v2.

---

## Licença

Proprietário — Todos os direitos reservados. © BantuByte / Pilartes Lander.

Este pacote é distribuído para uso com o serviço BantuByte. Não é
software livre nem open-source. A utilização está sujeita aos termos em
[bantubyte.dev](https://bantubyte.dev).
