agent_graph.py

"""LangGraph agent definition for the autonomous presentation pipeline.

Unlike graph.py (workflow mode), this module builds a ReAct agent that
autonomously decides which tools to call and in what order. The LLM
controls the flow — not the developer.

Comparison:
    graph.py (WORKFLOW):
        developer defines: START → researcher → writer → validator → publisher → END
        LLM has NO choice — it executes within each node, but the route is fixed

    agent_graph.py (AGENT):
        developer provides: 5 tools + a system prompt
        LLM decides: which tool to call, in what order, how many times, when to stop
        The route is DYNAMIC — different topics may produce different execution paths

Patterns demonstrated:
    - Orchestrator-Workers: the ReAct agent IS the orchestrator, tools are workers
    - Tool Use: search_web (Tavily API), publish_to_gamma (Gamma MCP)
    - Routing: classify_topic determines writing strategies based on topic type
    - Parallelization: generate_variants runs 2-3 writers concurrently
    - Voting: evaluate_and_select picks the best variant from parallel outputs

Safeguards:
    - recursion_limit: caps the total agent think→act→observe cycles (default 40)
    - MAX_SEARCHES in agent_tools.py: caps web search calls (default 8)
    - Gamma timeout: 120s per MCP call
"""

from pathlib import Path

from langgraph.checkpoint.memory import MemorySaver
from langgraph.prebuilt import create_react_agent

from agents.llm import get_llm
from tools.agent_tools import (
    classify_topic,
    evaluate_and_select,
    generate_variants,
    publish_to_gamma,
    request_human_approval,
    search_web,
)

PROMPT_DIR = Path(__file__).parent / "prompts"

# Maximum agent loop iterations (think → act → observe cycles).
# Each tool call counts as ~2 steps (call + response).
# 60 steps ≈ 30 tool calls — enough for pipeline + one HITL feedback cycle.
DEFAULT_RECURSION_LIMIT = 60


def build_agent_graph(recursion_limit: int = DEFAULT_RECURSION_LIMIT):
    """Build and compile the ReAct agent graph.

    This is the KEY difference from workflow mode:
        workflow: build_graph() in graph.py creates a StateGraph with
                  explicit edges (add_edge, add_conditional_edges)
        agent:   build_agent_graph() creates a ReAct loop where the
                  LLM autonomously picks tools from the list below

    The ReAct loop:
        1. LLM reads system prompt + conversation history
        2. LLM decides which tool to call (or to stop)
        3. Tool executes, result goes back to LLM
        4. Repeat from step 1 until LLM stops or recursion_limit hit

    Args:
        recursion_limit: Max iterations before forced stop.

    Returns:
        A compiled LangGraph application ready for .astream().
    """
    system_prompt = (PROMPT_DIR / "orchestrator.md").read_text()

    llm = get_llm(temperature=0.4)

    # These 5 tools are the agent's entire "toolkit".
    # The agent sees their docstrings and decides which to call.
    tools = [
        search_web,              # Pattern: Tool Use (Tavily API)
        classify_topic,          # Pattern: Routing
        generate_variants,       # Pattern: Parallelization (3 writers concurrently)
        evaluate_and_select,     # Pattern: Voting (Evaluator-Optimizer)
        request_human_approval,  # Pattern: Human-in-the-Loop (interrupt)
        publish_to_gamma,        # Pattern: Tool Use (Gamma MCP)
    ]

    agent = create_react_agent(
        model=llm,
        tools=tools,
        prompt=system_prompt,
        checkpointer=MemorySaver(),
    )

    return agent