Metadata-Version: 2.4
Name: codeen
Version: 0.1.0
Summary: Codeen — agente de IA em Python com TUI que edita ficheiros e executa comandos de shell com confirmação explícita.
Author: Codeen contributors
License: MIT
Project-URL: Homepage, https://github.com/<utilizador>/codeen
Project-URL: Repository, https://github.com/<utilizador>/codeen
Project-URL: Issues, https://github.com/<utilizador>/codeen/issues
Keywords: agent,cli,tui,llm,assistant,textual
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Environment :: Console
Classifier: Topic :: Software Development
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: textual>=0.80
Requires-Dist: httpx>=0.27
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.24; extra == "dev"
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: twine>=5.0; extra == "dev"

# Codeen

**Codeen** — agente de codificação com interface TUI (Text User Interface) que
edita ficheiros e executa comandos de shell no teu nome, com
**confirmação obrigatória** antes de cada ação destrutiva.

Inspirado no loop minimalista de
[MinimalAgent](https://github.com/99991/MinimalAgent) (chama o LLM →
executa a ação decidida → alimenta o resultado de volta → repete), o Codeen
expande essa base com uma interface interativa (Textual), suporte a múltiplos
provedores de LLM com *tool calling* nativo, detecção automática do ambiente
(incluindo Termux/Android) e adaptação de comandos de shell entre
plataformas.

## Funcionalidades

- **Interface TUI** construída com [Textual](https://textual.textualize.io/):
histórico colorido da conversa, input de comando e modais de confirmação.
- **Multi-provedor** com *tool calling* nativo (não parseia texto livre):
  - **Anthropic** (Claude)
  - **OpenAI** (GPT)
  - **Google** (Gemini)
  - **Qualquer provedor compatível com OpenAI** (DeepSeek, Ollama local,
    LM Studio, OpenRouter, Together, Groq, etc.) — basta apontar `base_url`.
- **Confirmação obrigatória**: antes de editar um ficheiro ou correr um comando, o
  que será feito é mostrado na TUI e o agente só avança com o teu "sim".
  Nunca executa nada sem a tua autorização.
- **Detecção de ambiente**: detecta SO, Termux, arquitetura da CPU (incluindo
  armv7l 32-bit do Android) e as ferramentas disponíveis, adaptando os
  comandos de shell (`bash` no Termux/Unix, `cmd` no Windows).
- **Diff claro** de edições antes de aplicar, usando `difflib` unificado.
- **Configuração persistente** em `~/.codeen/config.json`, com chaves
  mascaradas ao serem exibidas.

## Requisitos

- **Python >= 3.10** (funciona no 3.11/3.12 do Termux, Linux, macOS e WSL).
- Conexão com a internet e uma chave de API de algum provedor suportado.
- Em Termux: `pkg install python git` (o resto é resolvido no arranque).

Não há dependências nativas para compilar — só Python puro
(`textual` + `httpx`).

## Instalação

### Termux (Android) — foco primário

```bash
pkg update && pkg upgrade
pkg install python git
pip install --upgrade pip
pip install codeen
```

### Linux

```bash
pip install --user codeen
```

### macOS / Windows (WSL)

```bash
pip install codeen
```

Para contribuir ou correr em modo desenvolvimento:

```bash
git clone <este-repositorio>
cd codeen
pip install -e ".[dev]"
```

## Configuração da primeira chave de API

```bash
# Exemplo com Anthropic
codeen config set anthropic.api_key sk-ant-xxx

# Outros provedores
codeen config set openai.api_key sk-xxx
codeen config set google.api_key AIza...

# Escolhe o provedor ativo
codeen config set active_provider anthropic   # openai | google
```

As chaves também podem ser providenciadas por variáveis de ambiente
(`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GOOGLE_API_KEY`), que servem como
fallback quando não houver chave na configuração.

> As chaves são **sempre exibidas mascaradas** (`sk-***7890`). Nunca são
> escritas em logs nem no histórico da conversa.

Para inspecionar a configuração corrente:

```bash
codeen config list
codeen providers
```

## Uso

Inicia a TUI:

```bash
codeen
```

Ecrã principal:

```
┌ Codeen  anthropic/claude-sonnet-4-5 ─────────────────────────────┐
│ ... histórico da conversa ...                                   │
│ [yellow]Proposta: run_command 'ls -la'[/yellow]                  │
│ [dim]Aprovado: run_command[/dim]                                │
│ [dim]Resultado (run_command): ok[/dim]                          │
└─ Digite uma tarefa... ──────────────────────────────────────────┘
```

Comandos dentro da TUI:

| Tecla | Ação |
|-------|------|
| `Enter` (no input) | Envia a tarefa para o agente |
| `p` | Alterna o provedor ativo |
| `c` | Limpa o histórico da conversa |
| `q` | Sai |

Fluxo de cada tarefa:

1. Descreves a tarefa em linguagem natural.
2. O agente lista e lê o contexto do projeto (`list_files`, `read_file`).
3. Propõe a próxima ação — `edit_file` (mostra um diff) ou `run_command` (mostra o comando exato).
4. Um modal exige a tua confirmação (`y`/`Sim` ou `n`/`Não`).
5. O resultado (diff aplicado / stdout + código de saída) é mostrado e o ciclo continua até concluir ou até o limite de iterações.

## Comandos CLI

```
codeen                       # inicia a TUI
codeen doctor                # diagnóstico do ambiente
codeen config set <chave> <valor>
codeen config get <chave>
codeen config unset <chave>
codeen config list
codeen providers             # lista provedores e estado das chaves
codeen --version
```

## Como o loop do agente funciona

O núcleo (`codeen/agent/loop.py`) segue o mesmo princípio do MinimalAgent:

```
mensagens = [sistema + contexto_do_projeto, tua_tarefa]
loop:
  resposta = provedor.chat(mensagens, ferramentas)
  se a resposta contiver tool_calls:
      para cada chamada:
        se for ação de escrita/execução:
            pede confirmação (modal y/n)          <-- confirmação obrigatória
        executa a ferramentas
        alimenta o resultado de volta às mensagens
  senão:
      devolve a resposta final e termina
```

A diferença fundamental em relação ao MinimalAgent: as chamadas de função
são feitas via *tool calling* nativo da API de cada provedor, e **nenhuma
ação que modifique o sistema é executada sem a tua confirmação
explícita**.

## Arquitetura

```
codeen/
├── cli.py                  # CLI: codeen, doctor, config
├── environment.py          # deteção de SO, Termux, arch, ferramentas, shell
├── config.py               # persistência ~/.codeen/config.json, mascaramento
├── providers/
│   ├── base.py             # tipos comuns (Message, ToolCall, ToolDef)
│   ├── anthropic.py        # Claude
│   ├── openai.py           # OpenAI + compatíveis
│   └── google.py           # Gemini
├── agent/
│   ├── context.py          # prompt de sistema + recolha de contexto
│   └── loop.py             # ciclo do agente (com approver)
├── tools/
│   ├── base.py             # ToolResult + BaseTool
│   ├── file_tools.py       # list_files, read_file (read-only, sem confirmação)
│   ├── edit_tool.py        # edit_file, write_file (com diff, confirmação)
│   ├── shell_tool.py       # run_command, adaptado à plataforma
│   └── registry.py         # esquemas + despacho de ferramentas
└── tui/
    ├── app.py              # app Textual principal
    ├── confirm.py          # modal de confirmação de ações
    └── provider_screen.py  # ecrã de seleção de provedor
```

### Provedores

A camada de provedor traduz o formato interno neutro (`Message`,
`ToolCall`) para o payload HTTP de cada API e volta a converter a
resposta para o mesmo formato. Usa [`httpx`](https://www.python-httpx.org/)
diretamente, por modo a manter dependências leves e evitar builds nativos.

| Provedor   | Endpoint                                          | Envio de tool calls         |
|------------|---------------------------------------------------|-----------------------------|
| Anthropic  | `POST /v1/messages` (`x-api-key`)                 | `tool_use` / `tool_result`  |
| OpenAI     | `POST /chat/completions` (`Authorization: Bearer`)| `tool_calls` / `tool`       |
| Google     | `POST /v1beta/models/{model}:generateContent` (`x-goog-api-key`) | `functionCall` / `functionResponse` |
| OpenAI-like| aponta `base_url` para o provedor compatível       | idêntico a OpenAI           |

### Ferramentas (tool calling)

| Ferramenta   | Confirmação | Descrição |
|--------------|-------------|-----------|
| `list_files` | não         | lista a estrutura do projeto |
| `read_file`  | não         | lê um ficheiro com números de linha |
| `edit_file`  | **sim**     | substitui uma string exacta; mostra o diff |
| `write_file` | **sim**     | cria ou reescreve um ficheiro; mostra o diff |
| `run_command`| **sim**     | executa um comando de shell; mostra o comando exacto |

As leituras são consideradas seguras e executadas diretamente (são o
"ler o contexto necessário" do passo 2 do loop). Qualquer escrita ou
execução requer confirmação.

## Testes

```bash
pytest            # suite de testes (inclui TUI headless)
```

Cobertura: deteção de ambiente, config (com env e máscaras), tradução de
mensagens de cada provedor (via `httpx.MockTransport`), tools (diff, shell,
escopo de caminhos), o loop do agente (confirmação/recusa, leituras sem
confirmação) e a TUI (fluxo de confirmação aprovado/recusado e troca de
provedor).

## Personalização

- Variável `AGENT_MAX_ITERATIONS` / `codeen config set max_iterations N`
  limita o número de ciclos do agente (padrão: 20).
- Coloca `CODEN_DIR` para usar um directório de config alternativo
  (`~/.codeen` por defeito).
- O sistema é montado para ser extendida: basta implementar `Provider`
  em `providers/` e registar a fábrica em `providers/registry.py`.

## Limites de segurança

- O Codeen **nunca** escreve, lê ou transmite chaves directamente do
  ambiente de execução. As chaves vêm **do utilizador** (via
  configurador ou env vars).
- As leituras/escritas de ficheiros estão limitadas ao directório de
  trabalho do projecto.
- Comandos de shell exigem confirmação em cada iteração.
- Não contém lógica de análise de segurança nem testes de intrusão.
