Visão geral do ContractForge AI

ContractForge AI ajuda as equipes a transformar intenção de linguagem natural, evidência de esquema e contexto do projeto existente em projetos ContractForge revisáveis. Não é um tempo de execução separado e não substitui o ContractForge Core ou a plataforma adaptadores.

Use-o quando quiser:

• criar um projeto completo a partir de um prompt e evidência de esquema;
• revisar se os contratos gerados são canônicos antes da implantação;
• compare a saída do planejador Databricks, AWS, Snowflake, Fabric e GCP sem executar as plataformas;
• produzir AI_REVIEW.html, PROJECT_REVIEW.html ou project_validation.html para aprovação;
• explicar os avisos do adaptador sem permitir que um modelo altere o status determinístico.

A regra operacional é simples:

1. Interpret user intent deterministically.
2. Gere arquivos de projeto canônicos ContractForge.
3. Valide o projeto com ContractForge Core.
4. Valide o ajuste da plataforma por meio de planejadores públicos adaptadores.
5. Use fornecedores de modelos apenas para enriquecer, explicar ou propor rascunhos revisáveis.

A saída do provedor nunca inventa o status do suporte. A fonte da verdade continua sendo a resultado da validação do planejador determinístico e do adaptador.

Instalação

Instale o pacote AI com os extras do provedor necessários:

pip install contractforge-ai
pip install "contractforge-ai[openai]"

O desenvolvimento local neste repositório normalmente usa:

uv sync --all-extras
uv run contractforge-ai --help

O pacote pode executar validação determinística sem um provedor de modelo. Provedor a configuração é necessária apenas para enriquecimento --with-ai ou apoiado pelo provedor explanations.

O que o ContractForge AI cria

ContractForge AI pode gerar uma estrutura de projeto completa:

File	Propósito
project.yaml	Inventário do projeto, ordem de execução, dependências e cronograma.
environments/*.environment.yaml	Tempo de execução, evidência, destino do artefato e configurações protegidas do adaptador.
connections/*.yaml	Padrões de conector compartilhado e referências de autenticação.
*.ingestion.yaml	Origem, destino, modo, política de esquema, transformação e intenção de qualidade.
*.annotations.yaml	Descrições de tabelas e colunas, tags e metadados.
*.operations.yaml	Propriedade, SLA, criticidade e metadados de runbook.
*.access.yaml	Concessões, filtros de linha e máscaras quando solicitado.
AI_REVIEW.html	Relatório de aprovação para geração guiada/assistida por provedor.
PROJECT_REVIEW.html	Relatório de aprovação de planos de projetos determinísticos.
project_validation.html	Relatório de validação de projeto para uma pasta de projeto real.

O modelo de contrato permanece o mesmo entre os adaptadores, tanto quanto possível. Plataforma as diferenças pertencem a arquivos de ambiente, metadados de implantação ou protegidos extensions.<adapter> blocks.

Modelo operacional

O provedor do modelo está deliberadamente atrasado no fluxo. Pode explicar o planejador produzir, propor rascunhos de metadados ou traduzir orientações narrativas. Não pode alterar silenciosamente o conector, caminho de origem, destino, camada, modo, status de suporte, credenciais de implantação ou comportamento do adaptador.

Superfície da CLI

Comando	Usar
plan-project	Interprete um prompt e recomende comandos de geração determinística.
generate-project	Gere um projeto a partir de parâmetros explícitos.
guided-project	Planeje e desenvolva a partir da intenção guiada, opcionalmente com enriquecimento do provedor.
generate	Geração com intenção inicial com estado do projeto e contexto de relatório mais ricos.
validate-project-structure	Valide uma pasta de projeto real com planejamento de adaptador opcional.
compare-platforms	Compare o planejamento do adaptador e o desvio mínimo da plataforma.
route-task	Escolha uma estratégia de provedor antes de chamar um modelo.
validate-artifact	Valide contratos gerados, planos de projeto ou resultados do fornecedor.

Fluxo recomendado

1. Comece com plan-project quando a intenção estiver incompleta.
2. Gere com parâmetros explícitos ou guided-project.
3. Revise AI_REVIEW.html ou PROJECT_REVIEW.html.
4. Valide a pasta com validate-project-structure.
5. Compare adaptadores quando o mesmo projeto tiver como alvo mais de uma plataforma.
6. Implemente com o adaptador correspondente CLI.

ContractForge AI para na geração, validação e explicação. Implantação pertence a adaptadores.

Status

ContractForge AI separa projetos somente de aviso de projetos bloqueados:

Status	Meaning
READY	A estrutura é válida e os planejadores do adaptador retornaram planos suportados sem avisos.
READY_WITH_WARNINGS	A estrutura é válida e ready=true, mas os avisos do adaptador devem permanecer visíveis.
NEEDS_DECISIONS	As decisões humanas permanecem antes que o projeto seja implantado.
INVALID	A estrutura necessária, o carregamento do contrato ou o planejamento do adaptador falharam.
UNSAFE	Valores secretos embutidos ou entradas de projeto inseguras foram detectados.

READY_WITH_WARNINGS é importante para o trabalho real. Um projeto pode ser executado com sucesso e ainda expor avisos AWS sobre a expressão de qualidade Spark SQL portabilidade ou desempenho de hash-diff Iceberg. ContractForge AI deve reportar esses avisos sem marcar todo o projeto como inválido.

Artefatos principais de revisão

Use relatórios HTML para aprovação:

contractforge-ai guided-project \
  --intent "Create a Supabase medallion project for Databricks, AWS, Snowflake, Fabric and GCP daily at 6 Sao Paulo time." \
  --schema schemas/products.json \
  --target contractforge-yaml \
  --allow-review-required \
  --output-dir generated/supabase

contractforge-ai validate-project-structure generated/supabase \
  --adapter databricks \
  --adapter aws \
  --adapter snowflake \
  --adapter fabric \
  --adapter gcp \
  --format html > generated/supabase/project_validation.html

Os relatórios usam cartões legíveis para descobertas longas e evidências de adaptadores, portanto status do planejador, códigos de alerta, caminhos e recomendações permanecem inspecionáveis.

Guardrails

ContractForge AI deve preservar estes limites:

• A semântica central permanece nos contratos.
• O comportamento do adaptador permanece nos pacotes do adaptador.
• Os campos de ambiente e implantação ficam fora dos contratos de ingestão.
• Secrets are generated only as placeholders such as {{ secret:scope/key }}.
• As propostas dos fornecedores que alteram o comportamento continuam a ser sujeitas a revisão.
• A saída do provedor não pode substituir a validação determinística ou o planejamento do adaptador.