CLI and API entry points.

ContractForge exposes a small core CLI and adapter-owned CLIs. The core validates and plans semantics; adapters render or execute native behavior.

Core CLI

contractforge validate path/to/table.ingestion.yaml
contractforge validate-bundle contracts/silver/s_customers
contractforge connectors list
contractforge connectors show jdbc incremental_files

The core CLI should not require platform SDKs.

Databricks adapter CLI

contractforge-databricks render contracts/silver/s_customers
contractforge-databricks deploy-project project.yaml --target dev
contractforge-databricks deploy-project project.yaml --target dev --run
contractforge-databricks deploy-project project.yaml --render-bundle --force-render --target dev
contractforge-databricks render-project-bundle project.yaml --output databricks.yml --force
contractforge-databricks deploy-bundle databricks.yml --target dev --run

Adapter commands can require platform-specific dependencies, workspace configuration or credentials. Databricks deployment uses Databricks Asset Bundles and the Databricks CLI; the core does not deploy jobs.

AWS adapter CLI

contractforge-aws plan contracts/silver/s_customers.ingestion.yaml
contractforge-aws render contracts/silver/s_customers.ingestion.yaml --environment environments/prod.aws.yaml
contractforge-aws publish-s3 contracts/silver/s_customers.ingestion.yaml --environment environments/prod.aws.yaml
contractforge-aws deploy contracts/silver/s_customers.ingestion.yaml --environment environments/prod.aws.yaml
contractforge-aws deploy-project project.yaml --dry-run --summary-only
contractforge-aws deploy-project project.yaml --run --wait --audit-evidence --athena-output-location s3://bucket/athena-results/
contractforge-aws deploy-project project.yaml --dry-run --render-orchestration --summary-only
contractforge-aws deploy-project project.yaml --deploy-orchestration --summary-only
contractforge-aws deploy-project project.yaml --deploy-orchestration --wait-orchestration --summary-only
contractforge-aws deploy-project project.yaml --deploy-orchestration --wait-orchestration --record-cost-evidence --athena-output-location s3://bucket/athena-results/

AWS deployment publishes contracts/runtime artifacts to S3 and creates or updates Glue jobs. The Glue job is a generic bootstrap that loads the contractforge-aws runtime library and the contract YAML at runtime; the default path is not per-contract generated ingestion code.

Use deploy-project for repository-style ingestion projects with project.yaml.execution_order. It deploys each AWS contract in order and can start/wait Glue runs. Use --dry-run to validate planning/rendering locally and compile generated Glue Python without AWS API calls. Steps with expected_result: failed can be accepted with --accept-expected-failures for failure-observability tests. --audit-evidence runs the standard Athena control-table audit after waited Glue runs.

Use --render-orchestration or --deploy-orchestration when the project should also have a persistent AWS-native project DAG. The adapter renders Step Functions plus optional EventBridge Scheduler from project.yaml; the core does not know those services. Use --wait-orchestration to start and wait the Step Functions execution instead of running each Glue job directly.

ContractForge AI CLI

contractforge-ai plan-project \
  --intent "Create an AWS Glue bronze ingestion project from s3://landing/orders into analytics.bronze.b_orders using append." \
  --schema schemas/orders.json \
  --format markdown

contractforge-ai generate-project \
  --target aws-glue-iceberg \
  --schema schemas/orders.json \
  --project-name orders_aws \
  --connector s3 \
  --source-path s3://landing/orders \
  --target-catalog analytics \
  --target-schema bronze \
  --target-table b_orders \
  --output-dir generated/orders-aws

contractforge-ai validate-project-structure generated/orders-aws --adapter aws --format html > project_validation.html

contractforge-ai route-task \
  --intent "Summarize low-risk metadata improvements for this connector" \
  --knowledge-index .contractforge-ai/knowledge.json \
  --prefer-http-only \
  --format markdown

Project generation targets include contractforge-yaml, contractforge-python, databricks-dab, aws-glue-iceberg, dbt and classic-pyspark. The aws-glue-iceberg target generates a contract-first AWS project: project.yaml, environments/aws.environment.yaml, connections/source.yaml and split contracts under contracts/aws/....

Planner platform hints come from explicit platform or platform-service wording, not storage locations alone. s3://... selects the s3 connector but does not force AWS; iceberg can describe table format without forcing the AWS adapter. If no platform is named and multiple adapters support the connector, planning can recommend multiple adapter targets for the same contract intent. Explicit generation targets are also deterministic platform hints: --target aws-glue-iceberg adds the AWS environment scaffold, and --target databricks-dab adds the Databricks environment scaffold, while the ingestion contracts remain canonical.

The generated AWS environment uses syntactically valid review placeholders for planner-validated fields, such as s3://review-required-contractforge-artifacts/project/. Replace those with real artifact, warehouse, IAM role and wheel locations before deployment. The adapter still owns deployment through contractforge-aws; AI generation does not put AWS behavior into the core or into per-contract generated ingestion logic.

route-task --prefer-http-only can reduce SDK dependency pressure for low-risk advisory workflows. It is not a downgrade mechanism: project planning, contract generation and deployable-artifact workflows still require strict structured-output support because their output can affect real ingestion behavior.

validate-project-structure --format html is the preferred review output for complete project folders. It renders findings and adapter-planning evidence as readable cards and uses READY_WITH_WARNINGS for warning-only projects that remain ready=true.

Core Python API

Function or type	Use
validate_contract	Validate one ingestion contract mapping.
load_contract_bundle	Load split ingestion, annotations, operations, access and environment files.
semantic_contract_from_mapping	Normalize a validated contract into immutable semantic intent.
PlatformCapabilities	Declare what a platform can preserve.
plan_contract	Match semantic requirements against capabilities.
PlanningResult	Return status, plan, blockers and warnings.

from contractforge_core.contracts import validate_contract, semantic_contract_from_mapping
from contractforge_core.capabilities import PlatformCapabilities
from contractforge_core.planner import plan_contract

contract = validate_contract({
    "source": {"type": "table", "table": "main.raw.orders"},
    "target": {"catalog": "main", "schema": "bronze", "table": "b_orders"},
    "mode": "append",
})

semantic = semantic_contract_from_mapping(contract)
result = plan_contract(
    semantic,
    PlatformCapabilities(platform="example", supports_append=True, evidence_stores=("audit",)),
)
print(result.status)

Databricks Python API

Function or type	Use
plan_databricks_contract	Plan a contract against Databricks capabilities.
render_databricks_contract	Produce native Databricks artifacts.
ingest_databricks_bundle	Execute a split-contract bundle in Databricks.
deploy_databricks_project	Validate/deploy/run the Databricks Asset Bundle declared by project.yaml.
deploy_databricks_bundle	Validate/deploy/run a Databricks Asset Bundle directory or databricks.yml.
render_databricks_project_bundle	Render a Databricks Asset Bundle object from project.yaml scheduling/dependency metadata.
render_databricks_project_bundle_file	Render and write databricks.yml from a project file.
DatabricksEnvironment	Describe Databricks runtime and deployment hints.
DatabricksIngestOptions	Pass runtime options such as evidence catalog/schema.

from contractforge_databricks import deploy_databricks_project, render_databricks_contract

artifacts = render_databricks_contract("contracts/bronze/b_orders.ingestion.yaml")
print(artifacts.status)

deployment = deploy_databricks_project("project.yaml", profile="dbc-dev", target="dev", run=True)
print(deployment["status"])

AWS Python API

Function or type	Use
plan_aws_contract	Plan a contract against AWS Glue/Iceberg capabilities.
render_aws_contract	Produce AWS review artifacts, Glue scripts and deployment payloads.
publish_aws_contract_artifacts_to_s3	Publish rendered artifacts to S3.
deploy_aws_contract_to_glue	Render, publish and create or update a Glue job.
AWSEnvironment	Interpret AWS environment settings such as evidence database and artifact URI.

from contractforge_aws import deploy_aws_contract_to_glue

deployment = deploy_aws_contract_to_glue(contract, environment=environment)
print(deployment.job_name)

Common contract fields

Field	Meaning
source	Source intent, connection reference, table/query/path or connector-specific options.
source.system	Source system label recorded in evidence.
source.ref / source.table_ref	Logical layer.table reference to another ContractForge-managed table.
target	Canonical physical catalog/schema/table identity.
layer	Logical layer used for classification and observability.
mode	Write semantics such as append, overwrite, upsert, hash diff, historical or snapshot.
schema_policy	Target schema handling.
quality_rules	Validation and quarantine rules.
transform / shape	Portable preparation before write.
extensions.<adapter>	Adapter-owned options that are not portable core semantics.

Use nested target fields and adapter extension blocks in documentation and examples. Top-level legacy target or platform fields are intentionally not part of the canonical contract.