Pular para o conteúdo principal

Exemplos de ponta a ponta

Estes exemplos mostram como ContractForge AI deve ser usado de forma realista projetos de estilo consultoria: gere ou inspecione arquivos de projeto, valide com Núcleo e adaptadores e revise o relatório HTML antes da implementação.

USGS GeoJSON medalhão de cinco adaptadores​

Objetivo:

  • Fonte REST/GeoJSON;
  • resposta bruta de bronze, extração de eventos de prata e agregados de ouro;
  • Alvos Databricks, AWS, Snowflake, Fabric e GCP;
  • diferenças contratuais mínimas;
  • avisos do adaptador visíveis.

Prompt:

Create a USGS earthquake REST GeoJSON medallion project for Databricks, AWS,
Snowflake, Fabric and GCP. Bronze reads the 2.5_day.geojson endpoint as a raw
response. Silver extracts earthquake events from features[]. Gold creates daily
summary and magnitude-band aggregates. Keep source, quality, write behavior and
medallion order aligned. Keep platform-specific differences in environment
files or reviewed adapter extensions only.
Não gere segredos em texto puro. Use placeholders de segredo.

Gerar:

contractforge-ai generate \
  --prompt-file prompts/usgs-geojson-five-adapters.txt \
  --schemas schemas/usgs-events.json \
  --with-ai \
  --provider openai \
  --output-dir generated/usgs-earthquake-rest-medallion

Validar:

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

Resultado esperado:

  • READY ou READY_WITH_WARNINGS;
  • Evidência do planejador Databricks para cada contrato Databricks;
  • Evidência do planejador AWS para cada contrato AWS;
  • Evidência do planejador Snowflake, Fabric e GCP para suas ligações nativas;
  • avisos do adaptador visíveis quando uma plataforma requer um pré-requisito de tempo de execução ou limite de revisão explícito.

Layout representativo do projeto:

generated/usgs-earthquake-rest-medallion/
  project.yaml
  environments/
    aws.environment.yaml
    databricks.environment.yaml
    fabric.environment.yaml
    gcp.environment.yaml
    snowflake.environment.yaml
  connections/
    usgs.yaml
  contracts/
    databricks/
      bronze/bronze_usgs_geojson/bronze_usgs_geojson.ingestion.yaml
      silver/silver_usgs_events/silver_usgs_events.ingestion.yaml
      gold/gold_usgs_daily_summary/gold_usgs_daily_summary.ingestion.yaml
      gold/gold_usgs_magnitude_bands/gold_usgs_magnitude_bands.ingestion.yaml
    aws/
      bronze/bronze_usgs_geojson/bronze_usgs_geojson.ingestion.yaml
    snowflake/
      bronze/bronze_usgs_geojson/bronze_usgs_geojson.ingestion.yaml
    fabric/
      bronze/bronze_usgs_geojson/bronze_usgs_geojson.ingestion.yaml
    gcp/
      bronze/bronze_usgs_geojson/bronze_usgs_geojson.ingestion.yaml
  AI_REVIEW.html
  project_validation.html

Quando existir uma pasta de contrato específica da plataforma, o revisor deverá inspecionar por que. O estado de destino é um desvio mínimo: a maioria dos estados de origem, destino, modo, transformação, campos de qualidade e acesso devem ser os mesmos, com diferenças isoladas em arquivos de ambiente ou extensões de adaptador protegidas.

Exemplo de conexão REST compartilhada:

# connections/usgs.yaml
source:
  type: connector
  connector: rest_api
  system: usgs
  options:
    url: https://earthquake.usgs.gov/earthquakes/feed/v1.0/summary/2.5_day.geojson
    method: GET
    format: geojson
# contracts/.../bronze_usgs_geojson.ingestion.yaml
source:
  type: connection
  connection_path: project://connections/usgs.yaml
  response:
    mode: raw
    raw_column: raw_response

USGS REST/GeoJSON medallion​

Objetivo:

  • Fonte do arquivo REST/HTTP;
  • GeoJSON payload;
  • bronze raw ingest;
  • extração e normalização de prata;
  • resumos de magnitude na camada ouro;
  • Validação Databricks, AWS, Snowflake, Fabric e GCP.

Prompt:

Create a USGS earthquake REST GeoJSON medallion project for Databricks, AWS,
Snowflake, Fabric and GCP.
Bronze reads https://earthquake.usgs.gov/earthquakes/feed/v1.0/summary/all_day.geojson.
Silver extracts event_id, event_time, magnitude, place, longitude and latitude.
Gold creates daily summary and magnitude band aggregates.
Use conectores portáveis sempre que possível.
Keep platform-specific differences in environment or adapter extensions only.

Gerar:

contractforge-ai generate \
  --prompt-file prompts/usgs-geojson.txt \
  --schemas schemas/usgs-events.json \
  --with-ai \
  --provider openai \
  --output-dir generated/usgs-earthquake-rest-medallion

Validar:

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

Resultado esperado:

  • READY_WITH_WARNINGS é aceitável quando AWS relata portabilidade de expressão warnings.
  • O relatório deve mostrar que a intenção de origem, intenção de destino, modos de gravação, a qualidade e a estrutura do medalhão permanecem praticamente inalteradas entre os adaptadores.

Exemplo de conexão REST:

source:
  type: connector
  connector: rest_api
  system: usgs
  options:
    url: https://earthquake.usgs.gov/earthquakes/feed/v1.0/summary/all_day.geojson
    method: GET
    format: geojson
limits:
  max_total_bytes: 104857600
  max_records: 100000

O contrato bronze herda o endpoint. Prata e ouro geralmente são lidos em referências lógicas da tabela downstream, para que o adaptador possa resolver o problema físico Nome da tabela Databricks ou AWS do ambiente do projeto.

Review checklist​

Antes da implantação, revise:

  1. AI_REVIEW.html ou PROJECT_REVIEW.html.
  2. project_validation.html.
  3. Ordem e cronograma de execução do project.yaml.
  4. Destinos de artefatos e evidências environments/*.environment.yaml.
  5. connections/*.yaml secret references.
  6. Mesclar chaves e política de coluna hash.
  7. Avisos do adaptador.
  8. Any extensions.<adapter> blocks.

Em seguida, implante com o adaptador CLI:

contractforge-databricks deploy-project project.yaml --target dev
contractforge-aws deploy-project project.yaml --environment environments/aws.environment.yaml

Os adaptadores são executados ou implementados. ContractForge AI apenas planeja, gera, valida e explica.

O que não fazer​

  • Não cole segredos brutos no YAML gerado.
  • Não permita que o texto do provedor substitua o status do planejador.
  • Não mova as configurações de implantação do adaptador para contratos de ingestão.
  • Não use contratos Databricks/AWS separados, a menos que uma extensão de adaptador real ou a diferença semântica revisada exige isso.
  • Não trate READY_WITH_WARNINGS como um sucesso invisível; mantenha os avisos no approval report.