API and result payload.

ContractForge APIs return structured operational evidence. Failed executions raise by default, after control-table records are persisted.

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 the broader YAML contract schema for editor validation.
contract_model_schemas()	You generate JSON Schema fragments from the Pydantic boundary models for source, governance, shape and transform contracts.

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.