app/graph/state.py

"""Shared state passed between LangGraph nodes."""

from typing import TypedDict, Literal, Optional


class ClaimCitation(TypedDict):
    claim: str
    citation_marker: str           # e.g. "[12]" or "(Smith et al., 2023)" — inline marker only
    reference_string: str          # resolved bibliography entry, e.g. "Smith, J. et al. 2023. Title..."
    resolved_paper_id: Optional[str]
    evidence_text: Optional[str]


class Verdict(TypedDict):
    label: Literal["SUPPORT", "NOT_ENOUGH_INFO", "CONTRADICT"]
    confidence: float
    source: Literal["deberta", "llm"]


class ClaimAudit(TypedDict):
    claim_citation: ClaimCitation
    winner_sentence: Optional[str]        # the single sentence /analyze scored
    attribution_available: bool           # False when winner label is NOT_ENOUGH_INFO
    deberta_verdict: Optional[Verdict]
    llm_verdict: Optional[Verdict]
    agreement: Optional[bool]
    escalated: bool
    escalation_trace: Optional[list]      # [{"action": ..., "input": ..., "observation": ...}, ...]
    final_verdict: Optional[Verdict]
    attribution: Optional[list]           # [{"token": ..., "score": ...}, ...] or None
    resolution_note: Optional[str]        # set when citation could not be resolved to evidence


class GraphState(TypedDict):
    """Top-level state for one full document audit run."""
    source_text: str                # raw paper/abstract text
    claims: list[ClaimCitation]
    audits: list[ClaimAudit]
    current_index: int
    report: Optional[dict]