Metadata-Version: 2.4
Name: ai-execution-protocol
Version: 0.7.7
Summary: Protocolo instalavel para orientar agentes de IA em tarefas tecnicas: classifica risco, reduz contexto, controla ferramentas quando configurado e exige validacao antes da entrega.
Author: AI Execution Protocol
License-Expression: MIT
Project-URL: Homepage, https://github.com/rodneigk2/ai-execution-protocol
Project-URL: Repository, https://github.com/rodneigk2/ai-execution-protocol.git
Project-URL: Issues, https://github.com/rodneigk2/ai-execution-protocol/issues
Keywords: ai,agent,codex,agent-safety,context-management,protocol,risk,validation,prompt
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Software Development
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: PyYAML>=6.0
Dynamic: license-file

# AI Execution Protocol

Protocolo instalavel para orientar agentes de IA em tarefas tecnicas: classifica
risco, reduz contexto, controla ferramentas quando configurado e exige
validacao antes da entrega.

AI Execution Protocol ajuda agentes de IA a trabalharem como operadores de
engenharia controlados, nao como seguidores livres de prompt. Ele transforma um
pedido em um contrato de execucao delimitado: classificar risco, carregar apenas
o contexto necessario, selecionar as capacidades minimas, bloquear uso de
ferramentas antes da execucao quando houver suporte, validar o resultado e
relatar evidencias com risco residual.

O projeto e otimizado para Codex em repositorios locais. Hoje ele instala regras
operacionais, scripts de verificacao e checks locais para tornar tarefas com IA
mais previsiveis. Algumas garantias dependem de hooks, CI ou runners
configurados; sem isso, o protocolo atua como disciplina de execucao
`best_effort`.

Ele nao e um produto de seguranca e nao controla magicamente ferramentas que
rodam por fora do caminho configurado. Garantias fortes exigem que o comando,
hook, job de CI, runner ou gateway local chame os checks executaveis.

## O Que Ele Resolve

Agentes de IA costumam falhar de formas previsiveis:

- agem antes de entender o impacto;
- abrem contexto demais e perdem o alvo real;
- tratam trabalho arriscado como uma edicao simples;
- usam ferramentas que nunca foram planejadas;
- pulam validacao ou afirmam testes que nao rodaram;
- entregam sem explicar o que ainda esta incerto.

AI Execution Protocol da ao agente um sistema operacional compacto para esses
momentos. Tarefas simples continuam rapidas. Tarefas arriscadas exigem
mapeamento, confirmacao, disciplina de ferramentas, validacao e um relatorio
claro de entrega.

## Fluxo Central

```text
entender -> classificar risco -> mapear impacto -> executar -> validar -> relatar
```

O protocolo atual combina:

- niveis de risco, de respostas diretas ate operacoes sensiveis;
- route packs para carregar pouco contexto, especifico da tarefa;
- memoria adaptativa que orienta, mas nao sobrepoe o pedido atual;
- orcamentos de contexto para evitar arquivos e tokens desnecessarios;
- regras de economia de prompt para melhorar pedidos sem verbosidade;
- roteamento de capacidades para skills, MCPs, ferramentas e acoes externas;
- roteamento de inteligencia proporcional ao esforco necessario;
- validacao seletiva baseada no raio de impacto;
- contratos comportamentais para aderencia observavel do agente;
- gates executaveis para runners, hooks, proxies e integracoes de host;
- feedback de execucoes reais com consentimento para avaliacao local.

## Niveis De Garantia

AI Execution Protocol e explicito sobre o que consegue ou nao impor.

| Nivel | O Que Controla O Agente | O Que Pode Impor | Limite Principal |
| --- | --- | --- | --- |
| `best_effort` | `AGENTS.md` e arquivos de instrucao da IDE | Melhor planejamento, disciplina de contexto e relato | Ferramentas diretas do host ainda podem desviar do protocolo |
| `wrapped_enforced` | `ai-protocol run`, `run-auto`, hooks, CI ou runners locais | Plano valido, comando permitido e evidencia de validacao | Comandos fora do wrapper nao sao cobertos |
| `proxy_enforced` | Chamadas de ferramenta via gateway/proxy | Bloqueia ferramentas nao planejadas ou sem suporte | O host precisa esconder acesso direto as ferramentas |
| `host_integrated` | Uma integracao propria chama o gateway antes de ferramentas | Checks obrigatorios antes de ferramenta naquele caminho | Fora dessa integracao, ainda precisa de validacao e julgamento humano |

O controle mais forte vem de fronteiras executaveis, nao de um prompt mais
longo:

```text
instrucoes -> runner/hooks -> gateway local -> integracao propria
```

## Onde Roda Hoje

O uso principal hoje e em repositorios locais com agentes de coding, especialmente
Codex.

Na pratica, o projeto entrega:

- arquivos de instrucao para orientar a IA dentro do projeto;
- YAMLs curtos para classificar risco, escolher contexto e validar entrega;
- CLI npm/Python para instalar, verificar e diagnosticar o protocolo;
- hooks, runners e gateway local opcionais para checks mais fortes;
- feedback local de execucoes reais somente com consentimento explicito.

O protocolo nao promete suporte completo a IDEs, chats ou frameworks externos.
Esses caminhos existem como exemplos e pontos de extensao, mas a promessa
publica atual e disciplinar a execucao da IA no projeto instalado.

Exemplos de integracao ficam em:

- `examples/openai_agents_adapter.py`
- `examples/langgraph_adapter.py`
- `examples/crewai_adapter.py`

## Instalacao

Instale a partir de um pacote publicado e inicialize o projeto alvo:

```powershell
npm install -g ai-execution-protocol
ai-protocol init C:\path\to\project
ai-protocol verify C:\path\to\project
```

Ou instale com Python:

```powershell
python -m pip install --upgrade ai-execution-protocol
ai-protocol install C:\path\to\project
ai-protocol verify C:\path\to\project
```

Preveja a instalacao sem alterar arquivos:

```powershell
ai-protocol install C:\path\to\project --dry-run
```

Ative a automacao local strict depois do consentimento:

```powershell
ai-protocol setup-local C:\path\to\project --yes --real-tests accept
```

O resultado esperado da verificacao e `PASS`.

## Demo De Cinco Minutos

```powershell
ai-protocol e2e-demo
ai-protocol explain gateway
ai-protocol init-example C:\tmp\aep-example
cd C:\tmp\aep-example
ai-protocol install .
ai-protocol workflow run workflow.yaml
ai-protocol workflow report
```

Execucoes controladas podem gravar um trace local em
`.ai-protocol-run/trace.jsonl`. Resuma sem coletar logs completos:

```powershell
ai-protocol trace-report C:\path\to\project
```

## Comandos Principais

```powershell
ai-protocol verify C:\path\to\project
ai-protocol --version
ai-protocol doctor C:\path\to\project
ai-protocol strict-status C:\path\to\project
ai-protocol preflight C:\path\to\project --plan plan.json
ai-protocol check-call C:\path\to\project --input call.json
ai-protocol proxy-call C:\path\to\project --input proxy-call.json
ai-protocol run-checks C:\path\to\project --plan plan.json --report report.json
ai-protocol run --target C:\path\to\project --plan plan.json --call call.json --report report.json --npm-script test
ai-protocol run-auto --target C:\path\to\project --risk 1 --npm-script test
ai-protocol feedback-status C:\path\to\project
ai-protocol feedback-test-sync C:\path\to\project
ai-protocol feedback-reconcile C:\path\to\project
```

Use `doctor` para inspecionar estado de instalacao, cobertura strict,
onboarding, feedback consentido, retorno local ao framework, scripts protegidos
de pacote e hooks.

## Feedback De Execucoes Reais Com Consentimento

Projetos instalados incluem uma pasta visivel `ai-protocol-feedback/`. No
primeiro contato, o usuario pode escolher de forma independente se quer:

- reforcar arquivos locais de instrucao do host;
- permitir coleta local de feedback de execucoes reais.

Quando aceito, o coletor armazena resumos sanitizados de tarefas tecnicas
elegiveis. Ele nao coleta arquivos fonte, diffs brutos, arquivos `.env`,
credenciais, dados de clientes, logs completos ou uploads remotos. Se uma raiz
local do framework estiver configurada, lotes validados podem ser importados
em `real-runs/received/` como `received_unreviewed`.

Nenhum feedback e coletado antes do consentimento explicito. Publicacao ou
envio pela internet exige uma acao separada e um consentimento separado.

## Estrutura Do Projeto

- `AGENTS.md`: arquivo principal de instrucao para agentes de IA neste repo.
- `INDEX.yaml`: mapa estruturado para navegacao rapida.
- `config.yaml`: alvo atual, versao do protocolo e modo de operacao.
- `canonical-state.yaml`: fonte compacta do estado do projeto.
- `context-map.yaml`: aliases de dominio e arquivos candidatos.
- `protocol/`: regras operacionais curtas em YAML.
- `behavior/`: contrato comportamental observavel e checklist de auditoria.
- `capabilities/`: registro de skills, MCPs e ferramentas opcionais.
- `ai-protocol-enforcement/`: gateway executavel local e politica.
- `ai-protocol-onboarding/`: configuracao local consentida do host.
- `ai-protocol-feedback/`: consentimento visivel e execucoes locais.
- `docs/`: documentacao conceitual.
- `examples/`: exemplos de adaptadores e workflows.
- `schema/`: schemas de validacao.
- `scripts/`: checks de instalacao, validacao, benchmark e release.
- `real-runs/`: templates e lotes importados de feedback local.
- `dist/minimal/`: pacote minimo gerado para instalacao.

## Status E Limites

Status: alpha operacional.

O pacote ja inclui CLIs npm e Python, instalacao em projetos, onboarding,
roteamento de risco, orcamento de contexto, memoria adaptativa, gates de
capacidades, politica de custo-qualidade, validacao seletiva, enforcement
local, hooks de runtime adapter, exemplos de frameworks e feedback de
execucoes reais com consentimento.

Tarefas criticas ainda exigem revisao tecnica, testes reais, sandboxing do
host e confirmacao explicita para operacoes sensiveis. O protocolo melhora a
disciplina de execucao; ele nao substitui julgamento de engenharia.

## Documentacao

Use `docs/` para explicacoes conceituais e `protocol/` para regras
operacionais compactas. Comece por:

- `docs/00-visao-geral.md`
- `docs/12-instalacao-em-outro-projeto.md`
- `docs/25-testes-reais-com-consentimento.md`
- `docs/26-enforcement-gateway.md`
- `docs/27-runtime-adapter.md`

## Suporte

Abra bugs e pedidos de feature no GitHub:

https://github.com/rodneigk2/ai-execution-protocol/issues

## Licenca

Distribuido sob a licenca MIT. Veja `LICENSE`.
