Metadata-Version: 2.4
Name: ai-execution-protocol
Version: 0.1.0
Summary: Experimental AI execution protocol for safer agent workflows, minimal context, risk classification, 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

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

## 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.
- `config.yaml`: configuracao do alvo atual e versao do protocolo.
- `docs/`: explicacoes conceituais em Markdown.
- `protocol/`: regras operacionais curtas em YAML.
- `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 alvo atual em `config.yaml`.
3. Leia `protocol/fast-path.yaml`.
4. Use `protocol/router.yaml` para escolher o menor contexto suficiente.
5. Abra apenas os arquivos indicados pela rota.
6. Execute, valide e entregue com evidencia.

## 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/05-validacao-e-entrega.md`
- `docs/14-publicacao.md`

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

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

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

## Publicacao

Antes de publicar, revise `docs/14-publicacao.md`.

Resumo minimo:

- nao publique `.env`, chaves, tokens, senhas, logs reais ou dados de cliente;
- mantenha artefatos gerados fora do Git quando nao forem necessarios;
- use `.gitignore`;
- publique com `README.md`, `LICENSE`, `docs/`, `protocol/`, `cases/`,
  `examples/`, `schema/`, `eval/` e `scripts/` quando fizer sentido;
- preserve o posicionamento como pesquisa experimental e framework em evolucao.

## Licenca

Distribuido sob a licenca MIT. Veja `LICENSE`.
