Metadata-Version: 2.4
Name: ai-execution-protocol
Version: 0.6.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.

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.

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.

## Status

Projeto experimental em fase de pesquisa.

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.
- `ai-protocol-enforcement/`: gateway local e politica executavel instalados no
  projeto alvo.
- `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/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

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` somente quando estado atual
   ou mapeamento de dominio 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

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

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. Se houver suspeita de host
novo, instrucao ausente, conflito ou baixa aderencia, ela pode rodar
`setup.py compliance`; reparo com `setup.py repair --yes` exige confirmacao.

Para tarefas nivel 2/3 com ferramentas, ou qualquer escrita, publicacao ou acao
destrutiva, hosts integrados podem chamar
`ai-protocol-enforcement/gateway.py`. Isso transforma a regra de ferramenta de
`best_effort` em bloqueio local quando o host respeita o gateway.

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

Para retornar testes ao checkout local do framework:

```powershell
ai-protocol install C:\caminho\projeto `
  --feedback-framework-root C:\Projetos\ai-research
```

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`, `GEMINI.md`,
`.github/copilot-instructions.md` e `.cursor/rules/ai-execution-protocol.mdc`
quando o usuario autoriza com `--yes`. O onboarding faz essa integracao
automaticamente quando autorizado; o comando permanece como fallback.

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

## Licenca

Distribuido sob a licenca MIT. Veja `LICENSE`.
