Upload Functions

from penquify.generators.upload import (
    detect_schema_from_image,
    pdf_to_image,
    schema_to_flat,
    upload_and_generate,
)

async def detect_schema_from_image(
    image_path: str,
    api_key: Optional[str] = None,
) -> dict

{
    "document_type": "dispatch_guide" | "invoice" | "purchase_order" | "bill_of_lading" | "credit_note" | "other",
    "header": {
        "doc_number": "...",
        "date": "...",
        "emitter_name": "...",
        ...
    },
    "items": [
        {"pos": 1, "code": "...", "description": "...", "qty": float, "unit": "...", "unit_price": float, "total": float}
    ],
    "totals": {
        "subtotal": float,
        "tax": float,
        "total": float,
    },
    "observations": "...",
    "confidence": float,  # 0.0 - 1.0
}

async def pdf_to_image(pdf_path: str, output_path: str) -> str

def schema_to_flat(detected: dict) -> dict

detected = {
    "header": {"doc_number": "00054321", "emitter_name": "ACME"},
    "items": [{"pos": 1, "description": "HARINA", "qty": 40, "unit": "UN"}],
    "totals": {"subtotal": 500000, "total": 595000},
}

flat = schema_to_flat(detected)
# {
#     "doc_number": "00054321",
#     "emitter_name": "ACME",
#     "item_1_pos": "1",
#     "item_1_description": "HARINA",
#     "item_1_qty": "40",
#     "item_1_unit": "UN",
#     "subtotal": "500000",
#     "total": "595000",
# }

async def upload_and_generate(
    input_path: str,                        # Path to PDF or image
    output_dir: str = "output/uploaded",
    preset_names: list[str] = None,         # Default: full_picture, folded_skewed, blurry
    max_retries: int = 2,
    api_key: Optional[str] = None,
) -> dict

{
    "detected_schema": dict,   # Full detected schema
    "ground_truth": dict,      # Flat field -> value dict
    "photos": [                # List of verified photo results
        {
            "image_path": str,
            "verified": bool,
            "attempts": int,
            "verification": dict,
            "occlusion_manifest": dict,
        }
    ],
}