src/pubguard/errors.py

"""
PubVerse Error Code System
==========================

Structured error codes for the entire PubVerse pipeline.
PubGuard codes (PV-0XXX) encode classifier predictions directly
into the code digits.

Error code format:  PV-SXNN
    S  = Step number (0-8)
    X  = Sub-category
    NN = Detail

PubGuard composite encoding (Step 0):
    PV-0 [doc_type] [ai_detect] [toxicity]
         0=paper     0=human     0=clean
         1=poster    1=ai        1=toxic
         2=abstract
         3=junk
"""

from dataclasses import dataclass
from typing import Dict, Any, Optional

# ── PubGuard (Step 0) error messages ─────────────────────────────

# Snarky messages keyed by doc_type classification
DOC_TYPE_MESSAGES = {
    "scientific_paper": "Welcome to the lab.",
    "poster": (
        "That's a poster, not a paper. We appreciate the aesthetic effort, "
        "but we need Methods, not bullet points on a corkboard."
    ),
    "abstract_only": (
        "We got the trailer but not the movie. "
        "Where's the rest of the paper?"
    ),
    "junk": (
        "That's not a paper, that's a cry for help. Pool party invitations, "
        "invoices, and fantasy football drafts do not constitute peer-reviewed research."
    ),
}

AI_DETECT_MESSAGES = {
    "human": None,  # No message needed
    "ai_generated": (
        "Our classifier thinks a robot wrote this. "
        "The Turing test starts at the Introduction."
    ),
}

TOXICITY_MESSAGES = {
    "clean": None,
    "toxic": (
        "Content flagged as potentially toxic. "
        "Science should be provocative, not offensive."
    ),
}

# Special composite messages for particularly entertaining combos
COMBO_MESSAGES = {
    (3, 1, 0): "AI-generated junk. Congratulations, you've automated mediocrity.",
    (3, 0, 1): "Toxic junk. This is somehow worse than a pool party flyer.",
    (3, 1, 1): "The trifecta. AI-generated toxic junk. We'd be impressed if we weren't horrified.",
    (1, 1, 0): "An AI-generated poster. The future is here and it's making conference posters.",
    (2, 1, 0): "An AI-generated abstract with no paper attached. Peak efficiency.",
}

# Class label → index mapping (matches config.py label order)
DOC_TYPE_INDEX = {"scientific_paper": 0, "poster": 1, "abstract_only": 2, "junk": 3}
AI_DETECT_INDEX = {"human": 0, "ai_generated": 1}
TOXICITY_INDEX = {"clean": 0, "toxic": 1}


@dataclass
class PubVerseError:
    """Structured pipeline error code."""
    code: str           # e.g. "PV-0300"
    name: str           # e.g. "JUNK_DETECTED"
    message: str        # Human-readable (snarky) description
    step: int           # Pipeline step number
    fatal: bool         # Whether this should halt the pipeline
    details: Optional[Dict[str, Any]] = None  # Optional scores, labels, etc.

    def __str__(self) -> str:
        return f"{self.code} | {self.name} | {self.message}"

    def to_dict(self) -> Dict[str, Any]:
        d = {
            "code": self.code,
            "name": self.name,
            "message": self.message,
            "step": self.step,
            "fatal": self.fatal,
        }
        if self.details:
            d["details"] = self.details
        return d


def build_pubguard_error(verdict: Dict[str, Any]) -> PubVerseError:
    """
    Build a PubGuard error code from a screening verdict.

    The code encodes the classifier predictions:
        PV-0[doc_type_idx][ai_detect_idx][toxicity_idx]

    Returns PV-0000 (ALL_CLEAR) if the paper passes.
    """
    dt_label = verdict["doc_type"]["label"]
    ai_label = verdict["ai_generated"]["label"]
    tx_label = verdict["toxicity"]["label"]

    dt_idx = DOC_TYPE_INDEX.get(dt_label, 9)
    ai_idx = AI_DETECT_INDEX.get(ai_label, 9)
    tx_idx = TOXICITY_INDEX.get(tx_label, 9)

    code = f"PV-0{dt_idx}{ai_idx}{tx_idx}"

    # Build name
    if verdict["pass"]:
        name = "ALL_CLEAR"
    else:
        parts = []
        if dt_idx > 0:
            parts.append(dt_label.upper())
        if ai_idx > 0:
            parts.append("AI_GENERATED")
        if tx_idx > 0:
            parts.append("TOXIC")
        name = "_AND_".join(parts) if parts else "REJECTED"

    # Build message — check combo messages first, then individual
    combo_key = (dt_idx, ai_idx, tx_idx)
    if combo_key in COMBO_MESSAGES:
        message = COMBO_MESSAGES[combo_key]
    elif dt_idx > 0:
        message = DOC_TYPE_MESSAGES.get(dt_label, "Unknown document type.")
    elif ai_idx > 0:
        message = AI_DETECT_MESSAGES.get(ai_label, "AI content detected.")
    elif tx_idx > 0:
        message = TOXICITY_MESSAGES.get(tx_label, "Toxic content detected.")
    else:
        message = "Welcome to the lab."

    # Add scores to message
    score_parts = []
    if dt_idx > 0:
        score_parts.append(f"doc_type={dt_label}:{verdict['doc_type']['score']:.3f}")
    if ai_idx > 0:
        score_parts.append(f"ai={verdict['ai_generated']['score']:.3f}")
    if tx_idx > 0:
        score_parts.append(f"toxicity={verdict['toxicity']['score']:.3f}")

    if score_parts:
        message += f" ({', '.join(score_parts)})"

    # Fatal = doc_type is not scientific_paper (hard gate)
    fatal = dt_idx > 0

    details = {
        "doc_type": verdict["doc_type"],
        "ai_generated": verdict["ai_generated"],
        "toxicity": verdict["toxicity"],
    }

    return PubVerseError(
        code=code,
        name=name,
        message=message,
        step=0,
        fatal=fatal,
        details=details,
    )


# ── Special PubGuard errors ──────────────────────────────────────

def empty_input_error() -> PubVerseError:
    return PubVerseError(
        code="PV-0900",
        name="EMPTY_INPUT",
        message=(
            "You sent us nothing. Literally nothing. "
            "The void does not require peer review."
        ),
        step=0,
        fatal=True,
    )


def unreadable_pdf_error(filename: str = "") -> PubVerseError:
    return PubVerseError(
        code="PV-0901",
        name="UNREADABLE_PDF",
        message=(
            f"We can't read this PDF{f' ({filename})' if filename else ''}. "
            "If your PDF parser can't parse it, maybe it's not a PDF."
        ),
        step=0,
        fatal=True,
    )


def models_missing_error() -> PubVerseError:
    return PubVerseError(
        code="PV-0902",
        name="MODELS_MISSING",
        message=(
            "PubGuard models not found. "
            "Run: cd pub_check && python scripts/train_pubguard.py"
        ),
        step=0,
        fatal=False,  # Pipeline can continue without PubGuard
    )


def gate_bypassed() -> PubVerseError:
    return PubVerseError(
        code="PV-0999",
        name="GATE_BYPASSED",
        message="PubGuard screening bypassed (PUBGUARD_STRICT=0). Proceeding on faith. Good luck.",
        step=0,
        fatal=False,
    )


# ── Pipeline step errors (Steps 1-8) ────────────────────────────

def pipeline_error(step: int, sub: int, detail: int,
                   name: str, message: str, fatal: bool = True) -> PubVerseError:
    """Create a pipeline error for steps 1-8."""
    code = f"PV-{step}{sub}{detail:02d}"
    return PubVerseError(code=code, name=name, message=message, step=step, fatal=fatal)


# Pre-built pipeline errors for bash scripts to reference by name
PIPELINE_ERRORS = {
    # Step 1 — Feature Extraction
    "PV-1100": ("EXTRACTION_FAILED", "VLM feature extraction failed. Your PDF defeated a 7-billion parameter model. Impressive, actually.", True),
    "PV-1101": ("NO_TSV_OUTPUT", "Extraction ran but produced no output file. The VLM started reading and apparently gave up.", True),
    "PV-1200": ("VLM_NOT_FOUND", "Feature extraction script not found. Did someone move it?", True),
    # Step 2 — PubVerse Analysis
    "PV-2100": ("ANALYSIS_FAILED", "PubVerse analysis crashed. This is the big one — check the logs.", True),
    # Step 3 — Artifact Verification
    "PV-3100": ("MATRIX_MISSING", "Unified adjacency matrix not found. Something went sideways in clustering.", True),
    "PV-3101": ("PICKLE_MISSING", "Impact analysis pickle not found. The most important intermediate file is AWOL.", True),
    # Step 4 — Graph Construction
    "PV-4100": ("GRAPH_FAILED", "Graph construction failed. The nodes existed briefly, like a postdoc's optimism.", True),
    # Step 5 — 42DeepThought Scoring
    "PV-5100": ("SCORING_FAILED", "GNN scoring crashed. Check CUDA, check the graph, check your assumptions.", True),
    "PV-5101": ("NO_GRAPH_PICKLE", "Graph pickle not found for scoring. Step 4 must have failed silently.", True),
    "PV-5102": ("NO_SCORES_OUTPUT", "Scoring ran but produced no TSV. The GNN had nothing to say about your paper.", False),
    "PV-5200": ("DEEPTHOUGHT_MISSING", "42DeepThought directory not found. The entire scoring engine is missing.", False),
    # Step 6 — Cluster Analysis
    "PV-6100": ("CLUSTER_FAILED", "Cluster analysis crashed. Your paper is a loner — or the code is.", False),
    "PV-6102": ("DB_TIMEOUT", "Cluster database population timed out (>1 hour). The LLM is still thinking.", False),
    "PV-6103": ("NO_QUERY_ID", "Could not extract query paper ID from TSV. Who are you, even?", True),
    # Step 7 — Enrichment
    "PV-7100": ("ENRICH_FAILED", "Enrichment script crashed. The data refused to be unified.", False),
    # Step 8 — Visualization
    "PV-8100": ("VIZ_FAILED", "Visualization generation failed. You'll have to imagine the graph.", False),
}


def format_error_line(code: str, name: str = None, message: str = None) -> str:
    """Format a single error line for stdout output."""
    if name is None or message is None:
        if code in PIPELINE_ERRORS:
            name, message, _ = PIPELINE_ERRORS[code]
        else:
            name = name or "UNKNOWN"
            message = message or "An error occurred."
    return f"{code} | {name} | {message}"