API and result payload | ContractForge

Public entry points

API	Use when
`ingest(**kwargs)`	You call the framework from notebooks or Python code.
`ingest_plan(plan)`	You already normalized an `IngestionPlan`.
`ingest_stream_plan(plan)`	You run Auto Loader available-now ingestion.
`ingest_bundle(bundle)`	You load split contracts and want ingestion plus governance metadata.
`validate_plan_shape(contract)`	You validate YAML/JSON structure without starting Spark.
`yaml_schema()`	You generate a JSON Schema for editor validation.

Failure behavior

By default, ingest, ingest_plan, ingest_stream_plan and ingest_bundle raise ContractForgeExecutionError for final FAILED or ABORTED status. The result payload is still written to control tables first.

from contractforge import ContractForgeExecutionError, ingest

try:
    result = ingest(**contract)
except ContractForgeExecutionError as exc:
    print(exc.run_id)
    print(exc.target_table)
    print(exc.result["error_message"])

Important result fields

Field	Meaning
`status`	`SUCCESS`, `FAILED`, `SKIPPED`, `DRY_RUN` or another final status.
`run_id`	Primary execution identifier used across control tables.
`source`	Redacted connector metadata and source metrics.
`rows_read`, `rows_written`	Logical row metrics computed by the framework.
`rows_inserted`, `rows_updated`, `rows_deleted`	Mode-specific write metrics when available.
`rows_quarantined`	Rows isolated by quarantine-capable quality rules.
`stage_durations`	Seconds spent in read, schema, quality, write, state, lineage and governance stages.
`watermark_previous`, `watermark_current`	State transition used for incremental processing.
`framework_version`, `ctrl_schema_version`	Version evidence for support and migrations.