from __future__ import annotations

"""Core parsing interfaces for neuraparse.

Each parser is responsible for turning a :class:`RawDocument` into a
:class:`DocumentTree`. Parsers are fully decoupled from ingestion so that
support for new formats (PDF, HTML, DOCX, etc.) can be added without
changing higher-level code.
"""

from typing import Protocol

from ..core.models import DocumentTree, RawDocument


class ParseError(RuntimeError):
    """Raised when a document cannot be parsed by any available parser."""


class BaseParser(Protocol):
    """Protocol for all document parsers."""

    def supports(self, raw: RawDocument) -> bool:  # pragma: no cover - simple predicate
        """Return ``True`` if this parser knows how to handle ``raw``."""

    def parse(self, raw: RawDocument) -> DocumentTree:
        """Convert ``raw`` into a structured :class:`DocumentTree`."""

