Metadata-Version: 2.4
Name: atto-personal-agent
Version: 0.2.1
Summary: Tool-driven autonomous software engineering assistant
Author: Atto Personal Assistant
License-Expression: MIT
Project-URL: Repository, https://github.com/Atto-Personal-Assistant/agent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: certifi>=2024.2.2

# Atto Agent

> Biblioteca Python do agente do Atto Personal Assistant.

## 📦 Instalação

```bash
pip install atto-personal-agent
```

## 🚀 Uso rápido

```python
from atto_agent import AgentRuntime

runtime = AgentRuntime(
    ollama_url="https://seu-servidor-ollama.example.com",
    ollama_model="qwen2.5-coder:3b",
)
# Planeja uma ação
decision = runtime.plan("Explique este projeto")
# Executa a ação
result = runtime.run(decision, "Explique este projeto")
print(result)
```

> **Dica**: Se sua aplicação já possui um LLM, basta injetar um objeto que implemente
> `generate(prompt: str) -> str` via `AgentRuntime(llm=...)`.

## ☁️ Integração com Ollama Cloud

Configure as variáveis de ambiente:

```bash
export OLLAMA_URL=https://ollama.com
export OLLAMA_API_KEY=seu_api_key
export OLLAMA_MODEL=nome_do_modelo
```

## 🛠️ Desenvolvimento autônomo

O agente possui a capability `software_engineer` que permite:

* criar branches `atto/*`
* editar arquivos
* executar testes
* criar commits, push e abrir pull requests

Para habilitar, configure:

```bash
export ATTO_WORKSPACE=/caminho/para/repo
export ATTO_INTERNAL_TOKEN=seu_token_secreto
```

### Credenciais de CI/CD

| Plataforma | Token de PR | Token de aprovação | Observação |
|------------|-------------|--------------------|------------|
| GitHub | `GITHUB_TOKEN` | `GITHUB_APPROVAL_TOKEN` | Identidade separada |
| Azure DevOps | `AZURE_TOKEN` | `AZURE_APPROVAL_TOKEN`   | Identidade separada |

Uma revisão remota do Azure precisa apenas de `AZURE_TOKEN` e da URL completa
do PR. `ATTO_WORKSPACE` não é necessário nesse cenário.

### Comando de testes

Defina `ATTO_TEST_COMMAND` se o projeto usar um comando customizado. Caso contrário, o runtime detecta automaticamente `python -m unittest` ou `npm test`.

### Direção arquitetural

A prioridade atual é tornar a `software_engineer` confiavelmente autônoma por
meio de um ciclo com estado: observar, pensar, agir, avaliar e refletir. O
modelo escolhe dinamicamente o próximo passo; o runtime controla permissões,
orçamentos, ferramentas e conclusão baseada em evidências.

Essa evolução preserva Brain, Skills, Workflows e Tools existentes. Novas
Skills, integrações com dispositivos e subagentes especializados ficam depois
da validação reproduzível desse loop. Consulte
[`AUTONOMOUS_AGENT_ARCHITECTURE.md`](AUTONOMOUS_AGENT_ARCHITECTURE.md) e
[`AUTONOMY_TODO.md`](AUTONOMY_TODO.md).

O runtime já registra `AgentState`, usa planejamento dinâmico, recupera contexto
por dependências, mantém memória operacional com proveniência, executa testes e
validações do repositório, cria snapshots antes de editar e exige revisão
independente antes da publicação. O pipeline dedicado de autoaperfeiçoamento e
a classificação de risco também estão integrados; mudanças de alto risco
exigem aprovação explícita antes de qualquer publicação externa.

As avaliações recorrentes com modelos reais complementam os 161 testes
determinísticos: os testes validam os contratos do runtime, mas não substituem a
medição de convergência, tempo, custo, recuperação e regressões do modelo em
cenários versionados. Esse gate está detalhado em `AUTONOMY_TODO.md` e já possui
uma baseline real de seis cenários.

Execute a suíte real com o ambiente do modelo configurado:

```bash
python -m evaluations.live_suite
```

Os relatórios completos são gravados em `ATTO_EVALUATION_STORE` e comparados
com [`evaluations/baseline.json`](evaluations/baseline.json). A promoção falha
quando a taxa mínima não é atingida ou quando tempo/sucesso regridem além dos
limites definidos.

O loop isolado e o fluxo conversacional possuem gates separados. A continuidade
`Brain → Context → Skill → AgentLoop` está em validação no item 15. A Brain
classifica semanticamente `requested_change`, `task_relation` e
`ambiguity_kind`; o runtime rejeita
perguntas de engenharia antes de uma tentativa de descoberta no workspace.

## 🤝 Contribuindo

1. Fork o repositório
2. Crie uma branch `atto/feature-nome`
3. Faça suas alterações
4. Execute `pytest` para garantir que tudo funciona
5. Abra um pull request

## 📄 Licença

MIT © Atto
