from abc import ABC, abstractmethod
from pathlib import Path

from quber.core.parsers.result import ParseResult


class Parser(ABC):
    """Engine-agnostic seam: a source file becomes a `ParseResult`.

    The `ParseResult` carries the canonical `DoclingDocument` (Quber's in-memory
    IR) on `.document`, plus the per-page confidence, parsed-page cells, and
    per-table OCR/native provenance docling produces alongside it. Concrete
    parsers (`DoclingParser` subclasses, `MockParser`) inherit this and implement
    `parse`.
    """

    @abstractmethod
    def parse(self, source: Path) -> ParseResult: ...