ContractForge AI overview

ContractForge AI helps teams turn natural-language intent, schema evidence and existing project context into reviewable ContractForge projects. It is not a separate runtime and it does not replace ContractForge Core or the platform adapters.

Use it when you want to:

• create a complete project from a prompt and schema evidence;
• review whether generated contracts are canonical before a deploy;
• compare Databricks, AWS and Snowflake planner output without running the platforms;
• produce AI_REVIEW.html, PROJECT_REVIEW.html or project_validation.html for approval;
• explain adapter warnings without letting a model change deterministic status.

The operating rule is simple:

1. Interpret user intent deterministically.
2. Generate canonical ContractForge project files.
3. Validate the project with ContractForge Core.
4. Validate platform fit through adapter public planners.
5. Use model providers only to enrich, explain or propose reviewable drafts.

Provider output never invents support status. The source of truth remains the deterministic planner and adapter validation result.

Install

Install the AI package with the provider extras you need:

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

Local development in this repository normally uses:

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

The package can run deterministic validation without a model provider. Provider configuration is only required for --with-ai enrichment or provider-backed explanations.

What ContractForge AI creates

ContractForge AI can generate a complete project scaffold:

File	Purpose
project.yaml	Project inventory, execution order, dependencies and schedule.
environments/*.environment.yaml	Runtime, evidence, artifact destination and guarded adapter settings.
connections/*.yaml	Shared connector defaults and auth references.
*.ingestion.yaml	Source, target, mode, schema policy, transform and quality intent.
*.annotations.yaml	Table and column descriptions, tags and metadata.
*.operations.yaml	Ownership, SLA, criticality and runbook metadata.
*.access.yaml	Grants, row filters and masks when requested.
AI_REVIEW.html	Approval report for guided/provider-assisted generation.
PROJECT_REVIEW.html	Approval report for deterministic project plans.
project_validation.html	Project validation report for a real project folder.

The contract model stays the same across adapters as much as possible. Platform differences belong in environment files, deployment metadata or guarded extensions.<adapter> blocks.

Operating model

The model provider is deliberately late in the flow. It can explain planner output, propose draft metadata, or translate narrative guidance. It cannot silently change connector, source path, target, layer, mode, support status, deployment credentials or adapter behavior.

CLI surface

Command	Use
plan-project	Interpret a prompt and recommend deterministic generation commands.
generate-project	Generate a project from explicit parameters.
guided-project	Plan and scaffold from guided intent, optionally with provider enrichment.
generate	Intent-first generation with richer project-state and report context.
validate-project-structure	Validate a real project folder with optional adapter planning.
compare-platforms	Compare adapter planning and minimal platform drift.
route-task	Choose a provider strategy before calling a model.
validate-artifact	Validate generated contracts, project plans or provider output.

Recommended workflow

1. Start with plan-project when intent is incomplete.
2. Generate with explicit parameters or guided-project.
3. Review AI_REVIEW.html or PROJECT_REVIEW.html.
4. Validate the folder with validate-project-structure.
5. Compare adapters when the same project targets more than one platform.
6. Deploy with contractforge-databricks or contractforge-aws.

ContractForge AI stops at generation, validation and explanation. Deployment belongs to adapters.

Statuses

ContractForge AI separates warning-only projects from blocked projects:

Status	Meaning
READY	Structure is valid and adapter planners returned supported plans without warnings.
READY_WITH_WARNINGS	Structure is valid and ready=true, but adapter warnings must stay visible.
NEEDS_DECISIONS	Human decisions remain before the project should be deployed.
INVALID	Required structure, contract loading or adapter planning failed.
UNSAFE	Inline secret-like values or unsafe project inputs were detected.

READY_WITH_WARNINGS is important for real work. A project can run successfully and still expose AWS warnings about Spark SQL quality expression portability or Iceberg hash-diff performance. ContractForge AI should report those warnings without marking the whole project invalid.

Main review artifacts

Use HTML reports for approval:

contractforge-ai guided-project \
  --intent "Create a Supabase medallion project for AWS and Databricks 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 \
  --format html > generated/supabase/project_validation.html

The reports use readable cards for long findings and adapter evidence, so planner status, warning codes, paths and recommendations remain inspectable.

Guardrails

ContractForge AI must preserve these boundaries:

• Core semantics stay in contracts.
• Adapter behavior stays in adapter packages.
• Environment and deployment fields stay out of ingestion contracts.
• Secrets are generated only as placeholders such as {{ secret:scope/key }}.
• Provider proposals that change behavior remain review-required.
• Provider output cannot override deterministic validation or adapter planning.