Metadata-Version: 2.4
Name: ai-execution-protocol
Version: 0.7.2
Summary: Portable execution protocol for AI coding agents: plan first, limit context, gate tools, validate changes, and report evidence.
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
Dynamic: license-file

# AI Execution Protocol

Portable execution protocol for AI coding agents: plan first, limit context,
gate tools, validate changes, and report evidence.

AI Execution Protocol is an installable control layer for projects that use AI
coding agents. It turns a technical request into a bounded execution contract:
classify risk, open only the context that matters, justify tool use before it
happens, validate the result, and report what changed, what was not validated,
and what still needs human judgment.

It is not another agent framework, and it does not promise total control over a
host by itself. It can run as best-effort project instructions, then become
stricter when a host, runner, hook, CI job, or local gateway calls its executable
checks.

The current target is Codex. The protocol is optimized for Codex now, while the
structure remains portable to other AI agents and automation hosts.

## Objective

Reduce common AI execution failures: acting before impact is understood, loading
too much context, treating sensitive work as low risk, using unplanned tools,
skipping validation, or delivering without evidence.

The framework helps the agent:

- understand the intent before acting;
- classify task risk;
- find the right domain before opening large files;
- read only the context needed for the task;
- map impact before changing files;
- request confirmation for sensitive actions;
- choose tools and reasoning effort in proportion to risk;
- reduce cost without weakening context, safety, or required validation;
- validate the result before delivery;
- explain limits and residual risk.

## Core idea

```text
Entender -> classificar risco -> mapear impacto -> executar -> validar -> entregar
```

The protocol does not turn every task into a heavy process. The rule is
proportionality: simple tasks should stay fast; critical tasks require more
mapping, confirmation, and evidence.

Desde a v0.4.0, o framework combina contrato comportamental, memoria adaptativa,
orcamento de contexto, validacao seletiva e roteamento de capacidades:

```text
pedido -> risco -> memoria relevante -> contexto limitado -> acao -> validacao
```

O contrato comportamental transforma regras em comportamento observavel:

```text
tarefa -> comportamento esperado -> avaliacao -> evidencia
```

Memoria orienta, o pedido atual autoriza e arquivos verificados definem a
realidade. Inferencias ficam candidatas ate acumularem evidencia, e conteudo
sensivel e bloqueado.

Skills, MCPs e ferramentas opcionais seguem outro limite:

```text
resultado necessario -> capacidade minima -> permissao -> validacao
```

Risco maior restringe permissoes. Ele nao aumenta automaticamente a quantidade
de ferramentas.

A partir da v0.6.0, hosts que conseguem chamar um gate local tambem podem usar
uma politica executavel:

```text
plano -> ai-protocol-enforcement/gateway.py -> ferramenta
```

Sem essa chamada pelo host, o modo continua `best_effort`. Com ela, chamadas de
ferramenta fora do plano podem ser bloqueadas fora do modelo.

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

```text
instrucao -> runner/hooks -> gateway/proxy -> host proprio
```

`AGENTS.md` e regras de IDE orientam o host. `ai-protocol run`, `run-auto`,
hooks e CI controlam comandos que passam por eles. Gateway/proxy controla
tools e MCPs quando o host nao expoe bypass direto. Controle total de runtime
exige host proprio ou integracao equivalente.

Use `ai-protocol doctor <projeto>` para diagnosticar instalacao, strict mode,
onboarding, testes reais, scripts protegidos e hooks.

Execucoes controladas geram trace local em `.ai-protocol-run/trace.jsonl`.
Use `ai-protocol trace-report <projeto>` para resumir preflight, chamadas,
comandos, validacao e falhas sem coletar logs completos.

Hosts que suportam tools customizadas podem usar `ai-protocol proxy-call` para
executar uma chamada local somente depois de `check-call` aprovar o plano.

A partir da v0.7.0, integracoes com hosts e frameworks de agentes podem usar o
runtime adapter como contrato publico: `start_task -> validate_plan ->
check/proxy tool -> trace -> finish_task -> run_checks`. Isso permite acoplar o
protocolo a Agents SDK, LangGraph, CrewAI ou hosts proprios sem carregar toda a
documentacao a cada tarefa.

Exemplos opcionais: `examples/openai_agents_adapter.py`,
`examples/langgraph_adapter.py` e `examples/crewai_adapter.py`.

A v0.4.0 tambem adicionou gate e orcamento de inteligencia:

```text
risco -> complexidade -> capacidade planejada -> inteligencia suficiente
```

O framework marca como falha o uso de skill, MCP ou ferramenta fora do plano.
Troca real de modelo depende do host, mas a politica de escolha fica explicita.

A v0.6.1 adicionou uma politica explicita de custo e qualidade:

```text
risco -> barra de qualidade -> contexto minimo -> inteligencia suficiente -> validacao
```

Economia so e aceita quando a barra de qualidade, seguranca, escopo e validacao
continuam preservados.

O `Prompt melhorado da IA` tambem segue essa regra: deve ser curto, mas em
tarefa tecnica precisa indicar acao, alvo, limite de escopo, sucesso esperado e
validacao.

Quando risco, rota ou capacidade opcional importam, o PM pode adicionar
`Abrir:` e `Usar:` com poucas entradas indispensaveis. Isso orienta execucao sem
listar catalogo de arquivos, skills ou MCPs.

## Status

Operational alpha under active development.

The project already includes npm/PyPI packages, local onboarding, risk routing,
memory, context budgeting, selective validation, tool gating, local enforcement,
a runtime adapter, examples for agent frameworks, and consent-based real-run
feedback.

Even so, the protocol is not a security guarantee and does not replace human
review. Critical tasks still require technical judgment, real validation, host
sandboxing, and explicit confirmation for sensitive actions.

## Estrutura

- `AGENTS.md`: instrucao principal para agentes no projeto.
- `INDEX.yaml`: mapa estruturado para navegacao rapida.
- `canonical-state.yaml`: estado atual resumido e ordem de verdade.
- `context-map.yaml`: dominios, aliases e arquivos candidatos.
- `config.yaml`: configuracao do alvo atual e versao do protocolo.
- `decisions/`: decisoes importantes com status.
- `memory/`: preferencias, estado e padroes duraveis validados.
- `candidate-memory/`: inferencias ainda nao autoritativas.
- `capabilities/`: registro pequeno de skills, MCPs e ferramentas conhecidas.
- `ai-protocol-enforcement/`: gateway local e politica executavel.
- `behavior/`: contrato comportamental observavel introduzido na v0.4.0.
- `dataset/`: sementes de exemplos para fine-tuning futuro.
- `docs/`: explicacoes conceituais em Markdown.
- `protocol/`: regras operacionais curtas em YAML.
- `protocol/cost-quality-policy.yaml`: economia sem perda da barra de qualidade.
- `protocol/runtime-adapter.yaml`: contrato para hosts e frameworks.
- `protocol/route-packs.yaml`: resumos compactos para reduzir leitura por rota.
- `cases/`: casos estruturados para testar o comportamento da IA.
- `examples/`: exemplos humanos de uso do framework.
- `schema/`: contratos para manter os YAML padronizados.
- `eval/`: rubrica e exemplos de avaliacao.
- `scripts/`: automacoes de instalacao, validacao e avaliacao.
- `responses/`: exemplos de respostas para avaliacao.
- `benchmarks/`: comparacoes, incluindo `public-protocol-comparison.md`.
- `docs/28-comparativo-frameworks.md`: comparacao com Agents SDK, LangGraph e CrewAI.
- `model-runs/`: respostas reais por modelo para comparacao.
- `real-runs/`: templates ou registros de execucoes reais auditaveis.
- `dist/minimal/`: pacote minimo gerado para instalar em outros projetos.

## Como usar como agente

O host carrega `AGENTS.md`. Depois disso:

1. Leia `INDEX.yaml`.
2. Confirme alvo e versao em `config.yaml`.
3. Leia `protocol/fast-path.yaml`.
4. Use `protocol/router.yaml` para escolher o menor contexto suficiente.
5. Consulte `protocol/route-packs.yaml` antes dos YAML completos.
6. Leia `canonical-state.yaml` e `context-map.yaml` so quando importarem.
7. Abra arquivos completos apenas quando o resumo compacto nao bastar.
8. Execute, valide e entregue com evidencia.
9. Atualize memoria apenas quando surgir um fato duravel e seguro.
10. Carregue apenas capacidades necessarias para resultado e validacao.

Regra de seguranca:

```text
A IA pode expandir contexto.
A IA nao pode expandir escopo.
```

Aliases, mapas e decisoes ajudam a navegar. Eles nao substituem verificacao no
codigo ou nos arquivos atuais antes de alterar comportamento.

## Documentacao

Use `docs/` para entender conceitos, limites e comportamento do framework.
Use `protocol/` quando quiser consultar as regras operacionais aplicadas pela
IA. O indice em `docs/README.md` organiza os assuntos disponiveis.

## Instalacao em outro projeto

Com pacote publicado:

```powershell
ai-protocol init .
ai-protocol install .
ai-protocol verify .
```

Com setup local consentido:

```powershell
ai-protocol setup-local C:\caminho\projeto --yes --real-tests accept
```

Previa sem alterar arquivos:

```powershell
ai-protocol install . --dry-run
```

Instalacao a partir deste checkout:

```powershell
.\install.ps1 C:\caminho\projeto -Force
npm run install-protocol -- C:\caminho\projeto
python scripts/install_protocol.py --target C:\caminho\projeto --force
python scripts/verify_install.py --target C:\caminho\projeto
```

O final esperado da verificacao e `PASS`.

No primeiro contato apos a instalacao, a IA mostra um onboarding curto. O
usuario escolhe separadamente se permite reforcar regras locais do host e se
participa dos testes reais. Quando autorizado, a propria IA aplica a escolha;
o usuario nao precisa executar comandos adicionais. O `AGENTS.md` base ja faz
parte da instalacao; o aceite adiciona reforcos para os demais hosts suportados.
O setup precisa retornar `ONBOARDING_VERIFY:PASS` antes de continuar.

Depois do onboarding, a IA le apenas o estado curto. Checks de compliance,
reparo, feedback e integracao com IDEs sao condicionais para evitar custo
recorrente de contexto.

Modo strict com bloqueio executavel:

```powershell
ai-protocol strict-status C:\caminho\projeto
ai-protocol preflight C:\caminho\projeto --plan plan.json
ai-protocol check-call C:\caminho\projeto --input call.json
ai-protocol run-checks C:\caminho\projeto --plan plan.json --report report.json
ai-protocol run --target C:\caminho\projeto --plan plan.json --call call.json --report report.json --npm-script test
ai-protocol run-auto --target C:\caminho\projeto --risk 1 --npm-script test
```

Atualizacao pelos pacotes publicados:

```powershell
npm install -g ai-execution-protocol@latest
python -m pip install --upgrade ai-execution-protocol
ai-protocol install C:\caminho\projeto
ai-protocol verify C:\caminho\projeto
```

Detalhes de runner, hooks, IDEs, feedback consentido, `plan.json` e `report.json`
ficam nos docs e nos arquivos operacionais em `protocol/`.

## Testes reais consentidos

A instalacao cria `ai-protocol-feedback/`, uma pasta visivel para consentimento
e registros locais. No primeiro contato, o onboarding oferece uma escolha
independente para testes reais. Depois do aceite, a IA registra os resumos e,
quando houver framework local configurado, sincroniza com
`real-runs/received/`. Nada e coletado antes da confirmacao e nao existe upload
remoto.

Em estado normal, essa camada le apenas `consent.json`. O aviso completo e o
protocolo detalhado sao condicionais, evitando custo recorrente de contexto.

Consulte `docs/25-testes-reais-com-consentimento.md`.

## Suporte

Encontrou um bug? Abra uma issue no GitHub:
https://github.com/rodneigk2/ai-execution-protocol/issues

Feature request: comente em uma issue existente ou crie uma nova com a tag `[FEATURE]`.

## Licenca

Distribuido sob a licenca MIT. Veja `LICENSE`.
