state.py

"""Shared state definition for the presentation generation pipeline.

Defines PresentationState, the single TypedDict that flows through every node
in the LangGraph graph. Every agent reads from and writes to this state — it is
the contract between all pipeline components.

State lifecycle:
    main.py initialises the dict → graph.astream() passes it through each
    node → each node returns a partial dict that LangGraph merges back.
"""

from typing import TypedDict, Annotated
from langgraph.graph.message import add_messages


class PresentationState(TypedDict):
    """Shared state object flowing through every node in the LangGraph graph.

    Attributes:
        topic: Raw presentation topic from the user.
        expanded_topic: Researcher's enriched description with subtopics.
        research_results: List of dicts with 'title', 'summary', 'source_url'.
        slide_outline: Parsed slide structure from Writer's markdown.
        slide_content: Full markdown for all slides (sent to Gamma).
        num_slides: Target slide count (--slides flag, default 10).
        validation_feedback: Validator's feedback on why content failed.
        validation_passed: True if Validator scored >= 7/10.
        revision_count: How many revision cycles completed so far.
        max_revisions: Max allowed revisions before force-publish (--max-revisions).
        gamma_url: Published Gamma URL, or sentinel: DRY_RUN/FALLBACK_MARKDOWN/TIMEOUT.
        gamma_generation_id: Gamma generation ID from MCP response.
        messages: LangChain message history (appended via add_messages reducer).
        current_agent: Name of the most recently active agent.
        status: Human-readable pipeline phase string.
        dry_run: When True, skip Gamma and print markdown to stdout.
    """
    # Input
    topic: str
    expanded_topic: str
    # Research
    research_results: list[dict]
    # Content
    slide_outline: list[dict]
    slide_content: str
    num_slides: int
    # Validation
    validation_feedback: str
    validation_passed: bool
    revision_count: int
    max_revisions: int
    # Publishing
    gamma_url: str
    gamma_generation_id: str
    # Metadata
    messages: Annotated[list, add_messages]
    current_agent: str
    status: str
    # Runtime flags
    dry_run: bool