"""Type stubs for the hallucinator native module."""

from typing import Callable, Optional

class Reference:
    """A parsed reference extracted from a PDF."""

    @property
    def raw_citation(self) -> str: ...
    @property
    def title(self) -> Optional[str]: ...
    @property
    def authors(self) -> list[str]: ...
    @property
    def doi(self) -> Optional[str]: ...
    @property
    def arxiv_id(self) -> Optional[str]: ...

class SkipStats:
    """Statistics about references that were skipped during extraction."""

    @property
    def url_only(self) -> int: ...
    @property
    def short_title(self) -> int: ...
    @property
    def no_title(self) -> int: ...
    @property
    def no_authors(self) -> int: ...
    @property
    def total_raw(self) -> int: ...

class ExtractionResult:
    """Result of extracting references from a PDF."""

    @property
    def references(self) -> list[Reference]: ...
    @property
    def skip_stats(self) -> SkipStats: ...
    def __len__(self) -> int: ...
    @staticmethod
    def _from_parts(
        refs: list[Reference],
        total_raw: int,
        url_only: int,
        short_title: int,
        no_title: int,
        no_authors: int,
    ) -> "ExtractionResult": ...

class NativePdfExtractor:
    """The native Rust PDF reference extractor.

    Prefer using ``hallucinator.PdfExtractor`` which wraps this class
    and adds support for custom Python segmentation strategies.
    """

    def __init__(self) -> None: ...

    # Config setters
    section_header_regex: str
    section_end_regex: str
    fallback_fraction: float
    ieee_segment_regex: str
    numbered_segment_regex: str
    fallback_segment_regex: str
    min_title_words: int
    max_authors: int

    def add_venue_cutoff_pattern(self, pattern: str) -> None: ...
    def set_venue_cutoff_patterns(self, patterns: list[str]) -> None: ...
    def add_quote_pattern(self, pattern: str) -> None: ...
    def set_quote_patterns(self, patterns: list[str]) -> None: ...
    def add_compound_suffix(self, suffix: str) -> None: ...
    def set_compound_suffixes(self, suffixes: list[str]) -> None: ...

    # Extraction methods
    def extract(self, path: str) -> ExtractionResult: ...
    def extract_text(self, path: str) -> str: ...
    def find_section(self, text: str) -> Optional[str]: ...
    def segment(self, text: str) -> list[str]: ...
    def parse_reference(
        self, text: str, prev_authors: Optional[list[str]] = None
    ) -> Optional[Reference]: ...
    def parse_reference_detailed(
        self, text: str, prev_authors: Optional[list[str]] = None
    ) -> tuple[Optional[Reference], Optional[str]]: ...
    def extract_from_text(self, text: str) -> ExtractionResult: ...

# ── Validation pipeline ──

class ValidatorConfig:
    """Configuration for the reference validator."""

    def __init__(self) -> None: ...

    openalex_key: Optional[str]
    s2_api_key: Optional[str]
    dblp_offline_path: Optional[str]
    acl_offline_path: Optional[str]
    max_concurrent_refs: int
    db_timeout_secs: int
    db_timeout_short_secs: int
    disabled_dbs: list[str]
    check_openalex_authors: bool
    crossref_mailto: Optional[str]

class Validator:
    """Validates references against academic databases."""

    def __init__(self, config: ValidatorConfig) -> None: ...
    def check(
        self,
        references: list[Reference],
        progress: Optional[Callable[["ProgressEvent"], None]] = None,
    ) -> list["ValidationResult"]: ...
    def cancel(self) -> None: ...
    @staticmethod
    def stats(results: list["ValidationResult"]) -> "CheckStats": ...

class ValidationResult:
    """The result of validating a single reference."""

    @property
    def title(self) -> str: ...
    @property
    def raw_citation(self) -> str: ...
    @property
    def ref_authors(self) -> list[str]: ...
    @property
    def status(self) -> str: ...
    @property
    def source(self) -> Optional[str]: ...
    @property
    def found_authors(self) -> list[str]: ...
    @property
    def paper_url(self) -> Optional[str]: ...
    @property
    def failed_dbs(self) -> list[str]: ...
    @property
    def db_results(self) -> list["DbResult"]: ...
    @property
    def doi_info(self) -> Optional["DoiInfo"]: ...
    @property
    def arxiv_info(self) -> Optional["ArxivInfo"]: ...
    @property
    def retraction_info(self) -> Optional["RetractionInfo"]: ...

class DbResult:
    """Result from querying a single database backend."""

    @property
    def db_name(self) -> str: ...
    @property
    def status(self) -> str: ...
    @property
    def elapsed_ms(self) -> Optional[float]: ...
    @property
    def found_authors(self) -> list[str]: ...
    @property
    def paper_url(self) -> Optional[str]: ...

class DoiInfo:
    """Information about a DOI lookup."""

    @property
    def doi(self) -> str: ...
    @property
    def valid(self) -> bool: ...
    @property
    def title(self) -> Optional[str]: ...

class ArxivInfo:
    """Information about an arXiv lookup."""

    @property
    def arxiv_id(self) -> str: ...
    @property
    def valid(self) -> bool: ...
    @property
    def title(self) -> Optional[str]: ...

class RetractionInfo:
    """Information about a retraction check."""

    @property
    def is_retracted(self) -> bool: ...
    @property
    def retraction_doi(self) -> Optional[str]: ...
    @property
    def retraction_source(self) -> Optional[str]: ...

class ProgressEvent:
    """A progress event emitted during validation."""

    @property
    def event_type(self) -> str: ...
    @property
    def index(self) -> Optional[int]: ...
    @property
    def total(self) -> Optional[int]: ...
    @property
    def title(self) -> Optional[str]: ...
    @property
    def result(self) -> Optional[ValidationResult]: ...
    @property
    def failed_dbs(self) -> Optional[list[str]]: ...
    @property
    def message(self) -> Optional[str]: ...
    @property
    def count(self) -> Optional[int]: ...
    @property
    def paper_index(self) -> Optional[int]: ...
    @property
    def ref_index(self) -> Optional[int]: ...
    @property
    def db_name(self) -> Optional[str]: ...
    @property
    def db_status(self) -> Optional[str]: ...
    @property
    def elapsed_ms(self) -> Optional[float]: ...

class CheckStats:
    """Summary statistics for a validation run."""

    @property
    def total(self) -> int: ...
    @property
    def verified(self) -> int: ...
    @property
    def not_found(self) -> int: ...
    @property
    def author_mismatch(self) -> int: ...
    @property
    def retracted(self) -> int: ...
    @property
    def skipped(self) -> int: ...
