Verification Functions

from penquify.generators.verify import (
    extract_fields,
    compare_against_ground_truth,
    build_occlusion_manifest,
    verify_ground_truth,
    generate_verified_photo,
    generate_verified_dataset,
)

async def extract_fields(
    image_path: str,                    # Path to the photo
    field_names: list[str],             # Field names to look for
    api_key: Optional[str] = None,
) -> dict

{
    "extractions": {
        "field_name": {
            "value": str | None,       # What the model read
            "confidence": float,        # 0.0 - 1.0
            "reason": str | None,       # null, "blurry", "cropped", "occluded", "not_in_frame"
        }
    }
}

def compare_against_ground_truth(
    extractions: dict,    # Output from extract_fields()
    schema: dict,         # field_name -> expected_value
) -> dict

{
    "fields": {
        "field_name": {
            "source_value": str,
            "extracted_value": str | None,
            "status": "match" | "mismatch" | "illegible" | "not_visible",
            "confidence": float,
            "extraction_reason": str | None,
        }
    },
    "summary": {
        "total_fields": int,
        "matched": int,
        "mismatched": int,
        "illegible": int,
        "not_visible": int,
    }
}

def build_occlusion_manifest(
    verification: dict,         # Output from compare_against_ground_truth()
    variation: PhotoVariation,  # The variation config used to generate the photo
) -> dict

{
    "status": "not_visible" | "illegible" | "mismatch",
    "extracted": str | None,
    "expected": str,
    "confidence": float,
    "reasons": ["occluded_by_crop(header)", ...],
}

async def verify_ground_truth(
    image_path: str,
    schema: dict,               # field_name -> expected_value
    api_key: Optional[str] = None,
) -> dict