Geração de projetos de IA

A geração do projeto começa a partir de uma das duas entradas:

parâmetros CLI explícitos, quando o usuário já conhece origem, destino e modo;
intenção de linguagem natural, quando ContractForge AI deve extrair o projeto specification first.

Ambos os caminhos produzem um ProjectPlan antes de gravar os arquivos. O plano contém artefatos, suposições, decisões necessárias, avisos e evidências de rastreabilidade.

Canonical files

ContractForge AI escreve a mesma estrutura pública ContractForge de uma equipe de plataforma escreveria à mão:

project.yaml
environments/
  databricks.environment.yaml
  aws.environment.yaml
  snowflake.environment.yaml
  fabric.environment.yaml
  gcp.environment.yaml
connections/
  source.yaml
contracts/
  bronze/
    b_products/
      b_products.ingestion.yaml
      b_products.annotations.yaml
      b_products.operations.yaml
      b_products.access.yaml
README.md
RUNBOOK.md
VALIDATION.md
DECISIONS.md
AI_REVIEW.html or PROJECT_REVIEW.html

O gerador não deve emitir campos simples legados, como target_table, target_schema, ctrl_schema ou source_system de nível superior.

Explicit generation

Use generate-project quando o projeto já estiver especificado:

contractforge-ai generate-project \
  --target aws-glue-iceberg \
  --schema schemas/usgs-events.json \
  --project-name usgs_geojson_aws \
  --connector rest_api \
  --source-path "https://earthquake.usgs.gov/earthquakes/feed/v1.0/summary/2.5_day.geojson" \
  --target-catalog contractforge \
  --target-schema bronze \
  --target-table b_usgs_earthquake_geojson \
  --mode overwrite \
  --schedule-cron "0 6 * * *" \
  --schedule-timezone America/Sao_Paulo \
  --output-dir generated/usgs-aws

A geração equivalente de Databricks usa a mesma intenção de contrato:

contractforge-ai generate-project \
  --target databricks-dab \
  --schema schemas/usgs-events.json \
  --project-name usgs_geojson_databricks \
  --connector rest_api \
  --source-path "https://earthquake.usgs.gov/earthquakes/feed/v1.0/summary/2.5_day.geojson" \
  --target-catalog contractforge \
  --target-schema bronze \
  --target-table b_usgs_earthquake_geojson \
  --mode overwrite \
  --schedule-cron "0 6 * * *" \
  --schedule-timezone America/Sao_Paulo \
  --output-dir generated/usgs-databricks

A geração equivalente de Snowflake, Fabric e GCP usa --target snowflake-sql-warehouse, --target fabric-lakehouse ou --target gcp-bigquery com a mesma origem, destino, modo, transformação e intenção de qualidade. As diferenças significativas devem ser os arquivos do projeto e do ambiente, não a semântica de ingestão portátil.

Forma do projeto YAML

project.yaml é o limite de inventário e programação do projeto:

name: usgs_geojson

schedule:
  cron: "0 6 * * *"
  timezone: America/Sao_Paulo
  enabled: false

environments:
  databricks: environments/databricks.environment.yaml
  aws: environments/aws.environment.yaml
  snowflake: environments/snowflake.environment.yaml
  fabric: environments/fabric.environment.yaml
  gcp: environments/gcp.environment.yaml

connections:
  usgs: connections/usgs.yaml

execution_order:
  - name: bronze_products
    depends_on: []
    contracts:
      databricks: contracts/bronze/b_usgs_geojson/b_usgs_geojson.ingestion.yaml
      aws: contracts/bronze/b_usgs_geojson/b_usgs_geojson.ingestion.yaml
      snowflake: contracts/bronze/b_usgs_geojson/b_usgs_geojson.ingestion.yaml
      fabric: contracts/bronze/b_usgs_geojson/b_usgs_geojson.ingestion.yaml
      gcp: contracts/bronze/b_usgs_geojson/b_usgs_geojson.ingestion.yaml

O mesmo caminho de contrato é preferido entre adaptadores. Caminhos separados são apenas necessário quando uma extensão de adaptador revisada é necessária.

Environment YAML shape

Os arquivos de ambiente contêm configurações do adaptador e de implantação, não a semântica do conjunto de dados:

name: aws
adapter: aws
runtime:
  runtime: aws_glue_spark

artifacts:
  destination:
    type: s3
    path: s3://contractforge-artifacts/projects/usgs_geojson/

evidence:
  destination:
    type: iceberg_table
    database: cf_usgs_ops

extensions:
  aws:
    glue_version: "4.0"
    worker_type: G.1X

O contrato de ingestão ainda possui origem, destino, modo de gravação, transformações, qualidade e intenção de acesso.

Os destinos do projeto adaptador seguem o mesmo padrão:

Alvo	Adaptador	Generated environment	Pasta de contrato
`databricks-dab`	`databricks`	`environments/review.environment.yaml` plus Databricks Asset Bundle files	`contracts/<layer>/...`
`aws-glue-iceberg`	`aws`	`environments/aws.environment.yaml`	`contracts/aws/<layer>/...`
`snowflake-sql-warehouse`	`snowflake`	`environments/snowflake.environment.yaml`	`contracts/snowflake/<layer>/...`
`fabric-lakehouse`	`fabric`	`environments/fabric.environment.yaml`	`contracts/fabric/<layer>/...`
`gcp-bigquery`	`gcp`	`environments/gcp.environment.yaml`	`contracts/gcp/<layer>/...`

Os projetos de adaptadores gerados permanecem como artefatos de revisão até que contractforge-ai validate-project-structure --adapter <name> e o planejador de adaptador sejam aprovados.

Guided generation

Use guided-project quando um comando precisar planejar e estruturar:

contractforge-ai guided-project \
  --intent "Create a bronze to gold USGS earthquake GeoJSON medallion project for AWS, Databricks, Snowflake, Fabric and GCP. Run daily at 6 in America/Sao_Paulo. Bronze stores the raw response, silver extracts events and gold aggregates by date and magnitude band." \
  --schema schemas/usgs-events.json \
  --target contractforge-yaml \
  --allow-review-required \
  --output-dir generated/usgs-geojson-medallion

O planejador extrai:

sistema de origem e conector;
requested layers;
dicas de plataforma alvo;
modos de gravação;
horário e fuso horário;
expectativas de governança e qualidade;
decisões necessárias, como chaves de mesclagem e política de coluna hash.

Decisões perdidas ou inseguras não são adivinhadas. Eles são escritos para a revisão report.

Provider-enriched generation

Use --with-ai quando um provedor precisar enriquecer a especificação determinística do projeto:

contractforge-ai guided-project \
  --intent "Create a REST GeoJSON medallion ingestion for USGS earthquakes into Databricks, AWS, Snowflake, Fabric and GCP. Keep source portable and generate quality checks for magnitude and event_id." \
  --schema schemas/usgs-events.json \
  --target contractforge-yaml \
  --with-ai \
  --provider openai \
  --allow-review-required \
  --output-dir generated/usgs

O enriquecimento do provedor pode propor rascunho:

transform e shape;
regras de qualidade;
anotações;
metadados de operações;
seleção de alvo quando não resolvido;
revise perguntas e explicações.

O enriquecimento do provedor não pode mudar silenciosamente:

conector;
caminho de origem;
catálogo/esquema/tabela de destino;
layer;
modo de gravação;
platform support status;
secrets;
configurações de implantação.

Sugestões de mudança de comportamento permanecem necessárias para revisão mesmo quando são escritas em rascunhos de artefatos para inspeção.

Projetos multi-esquema

Quando um prompt fizer referência a muitos esquemas, passe-os juntos:

contractforge-ai generate \
  --prompt "Create a Supabase medallion project for products and product_movements. Use the same shared JDBC connection. Products use hash_diff_upsert; movements use append." \
  --schemas schemas/products.json schemas/product_movements.json \
  --with-ai \
  --provider openai \
  --output-dir generated/supabase-multi

O gerador deve usar uma conexão compartilhada YAML quando o conector de origem é o mesmo. As substituições específicas do conjunto de dados permanecem em cada contrato de ingestão.

Connection inheritance

YAMLs de conexão compartilhada centralizam opções de endpoint, autenticação e leitura comum:

# connections/supabase.yaml
source:
  type: connector
  connector: postgres
  system: supabase
  options:
    url: "{{ secret:supabase/jdbc_url }}"
    driver: org.postgresql.Driver
auth:
  type: basic
  username: "{{ secret:supabase/user }}"
  password: "{{ secret:supabase/password }}"
read:
  fetchsize: 20000

Um contrato de ingestão pode herdar e substituir apenas os campos específicos do conjunto de dados:

source:
  type: connection
  connection_path: project://connections/supabase.yaml
  table: public.products
  read:
    partition_column: product_id
    lower_bound: 1
    upper_bound: 1000000
    num_partitions: 8

Os valores no nível de ingestão substituem a conexão global. O núcleo resolve o conexão antes que os adaptadores planejem ou executem o contrato.

Resultado do projeto

Um projeto gerado normalmente contém:

project.yaml
environments/
  databricks.environment.yaml
  aws.environment.yaml
connections/
  source.yaml
contracts/
  bronze/
    b_products/
      b_products.ingestion.yaml
      b_products.annotations.yaml
      b_products.operations.yaml
README.md
RUNBOOK.md
VALIDATION.md
DECISIONS.md
AI_REVIEW.html or PROJECT_REVIEW.html

Valide a pasta após geração:

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

Canonical files​

Explicit generation​

Forma do projeto YAML​

Environment YAML shape​

Guided generation​

Provider-enriched generation​

Projetos multi-esquema​

Connection inheritance​

Resultado do projeto​