Metadata-Version: 2.4
Name: ai-execution-protocol
Version: 0.4.0
Summary: Behavioral execution framework for safer AI agents, minimal context, risk control, validation, and evidence-based delivery.
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,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

Behavioral execution framework for safer AI agents.

Framework experimental para orientar agentes de IA em tarefas tecnicas com mais
seguranca, contexto minimo, validacao e controle de risco.

O alvo atual e Codex. O protocolo e otimizado para Codex agora, mas foi
organizado para continuar portavel para outras IAs no futuro.

## Objetivo

Evitar que a IA execute pedidos de forma impulsiva, perigosa ou fora de escopo.

O framework ajuda a IA a:

- entender a intencao antes de agir;
- classificar o risco da tarefa;
- localizar o dominio certo antes de abrir arquivos grandes;
- ler apenas o contexto necessario;
- mapear impacto antes de alterar arquivos;
- pedir confirmacao em acoes sensiveis;
- validar o resultado antes de entregar;
- explicar limites e risco residual.

## Ideia central

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

O protocolo nao tenta transformar toda tarefa em um processo pesado. A regra e
proporcionalidade: tarefa simples deve ser rapida; tarefa critica exige mais
mapa, confirmacao e evidencia.

Na 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 v0.4.0 tambem adiciona 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.

## Status

Projeto em fase de pesquisa e evolucao.

Este repositorio contem uma proposta tecnica, nao uma garantia de seguranca nem
uma fonte normativa definitiva. Testes reais, revisao humana e criterio tecnico
continuam obrigatorios em tarefas criticas.

## 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`: mapa pequeno de 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.
- `behavior/`: contrato comportamental observavel da v0.4.0.
- `dataset/`: sementes de exemplos para fine-tuning futuro.
- `roadmap/`: trilho de maturidade para evoluir das versoes 0.x ate a v1.0.
- `docs/`: explicacoes conceituais em Markdown.
- `protocol/`: regras operacionais curtas em YAML.
- `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 entre execucao com e sem protocolo.
- `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

1. Leia `INDEX.yaml`.
2. Confirme o estado atual em `canonical-state.yaml` quando a verdade do
   projeto importar.
3. Use `context-map.yaml` para localizar dominio e aliases provaveis.
4. Confirme o alvo atual em `config.yaml`.
5. Leia `protocol/fast-path.yaml`.
6. Use `protocol/router.yaml` para escolher o menor contexto suficiente.
7. Consulte `protocol/route-packs.yaml` antes de abrir todos os YAML da rota.
8. Abra arquivos completos apenas quando o resumo compacto nao bastar.
9. Execute, valide e entregue com evidencia.
10. Atualize memoria apenas quando surgir um fato duravel e seguro.
11. 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.

## Como estudar o framework

Comece por:

- `docs/00-visao-geral.md`
- `docs/01-modelo-de-execucao.md`
- `docs/02-niveis-de-risco.md`
- `docs/03-mapeamento-antes-de-alterar.md`
- `docs/04-janela-de-contexto.md`
- `docs/05-validacao-e-entrega.md`
- `docs/15-contexto-persistente.md`
- `docs/17-documentacao-atomica.md`
- `docs/18-memoria-adaptativa.md`
- `docs/19-orcamento-de-contexto.md`
- `docs/20-validacao-seletiva.md`
- `docs/21-roteamento-de-capacidades.md`
- `docs/22-roadmap-v1.md`
- `docs/23-contrato-comportamental.md`
- `docs/24-gate-de-capacidades-e-inteligencia.md`

Use `docs/` para entender a metodologia. Use `protocol/` quando quiser aplicar
as regras em uma tarefa real.

Para evoluir o projeto ate a v1.0, use `roadmap/v1.yaml` como trilho
operacional e `docs/22-roadmap-v1.md` como explicacao.

## Validacao local

Execute a validacao geral:

```powershell
python scripts/health_check.py
```

Execute a bateria estrutural extra:

```powershell
python scripts/framework_tests.py
```

Meca custo aproximado de leitura por rota:

```powershell
python scripts/token_report.py
```

Valide a memoria e selecione apenas as verificacoes necessarias:

```powershell
python scripts/memory_manager.py --root . validate
python scripts/selective_validation.py
python scripts/capability_router.py --risk 1 --operation read --tag code_search
python scripts/behavior_contract_check.py
```

## Instalacao em outro projeto

Projeto novo:

```powershell
ai-protocol init .
```

Projeto existente:

```powershell
ai-protocol install .
```

Previa sem alterar arquivos:

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

Instalacao local via PowerShell:

```powershell
.\install.ps1 C:\caminho\projeto -Force
```

Instalacao local via npm:

```powershell
npm run install-protocol -- C:\caminho\projeto
npm run dry-run-protocol -- C:\caminho\projeto
```

Instalacao local via Python:

```powershell
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`.

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
```

Integracao opcional com arquivos de instrucao de IDE:

```powershell
ai-protocol integrate C:\caminho\projeto --dry-run
ai-protocol integrate C:\caminho\projeto --yes
```

Esse comando adiciona um bloco marcado em `CLAUDE.md`, `.cursorrules`,
`.github/copilot-instructions.md` e `.cursor/rules/ai-execution-protocol.mdc`
quando o usuario autoriza com `--yes`. O objetivo e aumentar aderencia em hosts
que nao leem `AGENTS.md` diretamente, sem sobrescrever regras existentes.

## Licenca

Distribuido sob a licenca MIT. Veja `LICENSE`.
