Skip to main content

End-to-end examples

These examples show how ContractForge AI should be used in realistic consulting-style projects: generate or inspect project files, validate with Core and adapters, then review the HTML report before deployment.

USGS GeoJSON five-adapter medallion​

Goal:

  • REST/GeoJSON source;
  • bronze raw response, silver event extraction and gold aggregates;
  • Databricks, AWS, Snowflake, Fabric and GCP targets;
  • minimal contract differences;
  • adapter warnings visible.

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.
Do not generate raw secrets. Use secret placeholders.

Generate:

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

Validate:

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

Expected result:

  • READY or READY_WITH_WARNINGS;
  • Databricks planner evidence for each Databricks contract;
  • AWS planner evidence for each AWS contract;
  • Snowflake, Fabric and GCP planner evidence for their native bindings;
  • adapter warnings visible when a platform requires a runtime prerequisite or explicit review boundary.

Representative project layout:

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

When a platform-specific contract folder exists, the reviewer should inspect why. The target state is minimal drift: most source, target, mode, transform, quality and access fields should be the same, with differences isolated in environment files or guarded adapter extensions.

Example shared REST connection:

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

Goal:

  • REST/HTTP file source;
  • GeoJSON payload;
  • bronze raw ingest;
  • silver extraction and normalization;
  • gold magnitude summaries;
  • Databricks, AWS, Snowflake, Fabric and GCP validation.

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 portable connectors where possible.
Keep platform-specific differences in environment or adapter extensions only.

Generate:

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

Validate:

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

Expected result:

  • READY_WITH_WARNINGS is acceptable when AWS reports expression-portability warnings.
  • The report should show that source intent, target intent, write modes, quality and medallion structure are mostly unchanged across adapters.

Example REST connection:

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

The bronze contract inherits the endpoint. Silver and gold usually read from logical downstream table refs, so the adapter can resolve the physical Databricks or AWS table name from the project environment.

Review checklist​

Before deployment, review:

  1. AI_REVIEW.html or PROJECT_REVIEW.html.
  2. project_validation.html.
  3. project.yaml execution order and schedule.
  4. environments/*.environment.yaml artifact and evidence destinations.
  5. connections/*.yaml secret references.
  6. Merge keys and hash column policy.
  7. Adapter warnings.
  8. Any extensions.<adapter> blocks.

Then deploy with the adapter CLI:

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

The adapters execute or deploy. ContractForge AI only plans, generates, validates and explains.

What not to do​

  • Do not paste raw secrets into generated YAML.
  • Do not let provider text override planner status.
  • Do not move adapter deployment settings into ingestion contracts.
  • Do not use separate Databricks/AWS contracts unless a real adapter extension or reviewed semantic difference requires it.
  • Do not treat READY_WITH_WARNINGS as invisible success; keep warnings in the approval report.