Providers and guardrails

ContractForge AI can use model providers, but provider output is advisory until it passes deterministic validation. The goal is to improve productivity without letting the model invent ContractForge APIs or platform support.

Deterministic before provider

Every provider-backed workflow follows this order:

1. Deterministic intent extraction.
2. Deterministic project planning.
3. Core contract validation.
4. Adapter planning validation when adapters are requested.
5. Optional provider explanation or enrichment.
6. Deterministic validation of provider output.

The provider never owns support status.

Routing providers

Use route-task before choosing a model:

contractforge-ai route-task \
  --intent "Explain adapter warnings for this generated Supabase project." \
  --prefer-http-only \
  --format markdown

Low-risk advisory tasks can prefer HTTP-only providers to reduce dependency and runtime cost. Higher-risk tasks, such as project generation and structured contract enrichment, should require strict structured-output support.

Enrichment rules

Provider output may suggest:

• descriptions and annotations;
• quality rule drafts;
• transform and shape drafts;
• operations metadata drafts;
• review questions;
• explanatory summaries.

Provider output may not silently change:

• connector;
• source path;
• target catalog/schema/table;
• layer;
• write mode;
• merge keys or hash policy;
• schedule;
• environment artifact destinations;
• secret values;
• platform support status.

If a provider proposes a behavior-changing field, ContractForge AI can preserve the draft for review, but it records the field as review-required.

Example guarded enrichment

contractforge-ai guided-project \
  --intent "Create a USGS GeoJSON medallion project. Extract event_id, magnitude, place and coordinates. Add quality checks." \
  --schema schemas/usgs-events.json \
  --target contractforge-yaml \
  --with-ai \
  --provider openai \
  --allow-review-required \
  --output-dir generated/usgs

If the provider suggests shape.parse_json or a quality expression, the report shows it as draft behavior. The reviewer must approve it before treating the project as production-ready.

Rejecting unsafe output

ContractForge AI rejects or flags provider output when it:

• includes raw secrets;
• changes deterministic identity fields;
• writes adapter deployment settings into ingestion contracts;
• claims unsupported semantics are supported;
• removes required decisions;
• invents fields outside the public ContractForge contract model.

Rejected proposals are recorded in the review report instead of being silently discarded.

Cost-aware usage

Use smaller or cheaper providers only for tasks that do not reduce quality:

Task	Provider strategy
Summarize validation output	Low-cost provider is acceptable.
Translate report prose	Low-cost provider is acceptable if labels and identifiers stay unchanged.
Generate project spec	Use strongest available structured-output model.
Security, architecture or release decisions	Use strongest available model and deterministic tests.
Adapter support status	Do not ask the provider; use adapter planners.

The provider is an assistant to deterministic systems, not the system of record.