pip install langgraph==0.2.0 langchain==0.3.0 langchain-openai==0.2.0 \
    fastapi==0.115.0 uvicorn==0.30.6 python-dotenv==1.0.1 \
    langgraph-checkpoint-sqlite==0.1.0

# state.py
from typing import TypedDict, Optional, Literal

class ProposedAction(TypedDict):
    action_type: str       # e.g., "send_email", "database_write"
    description: str       # human-readable summary
    parameters: dict       # actual parameters for the action
    risk_level: Literal["low", "medium", "high"]

class AgentState(TypedDict):
    user_request: str
    proposed_action: Optional[ProposedAction]
    approval_status: Optional[Literal["pending", "approved", "rejected", "modified"]]
    human_feedback: Optional[str]
    modified_parameters: Optional[dict]
    final_result: Optional[str]
    error: Optional[str]

# nodes.py
from langchain_openai import ChatOpenAI
from langchain_core.prompts import ChatPromptTemplate
from pydantic import BaseModel, Field
from state import AgentState, ProposedAction
import json

class ActionProposal(BaseModel):
    action_type: str = Field(description="Type of action: send_email, write_file, api_call, database_write")
    description: str = Field(description="Human-readable description of what will happen")
    parameters: dict = Field(description="Parameters needed to execute the action")
    risk_level: str = Field(description="Risk level: low, medium, or high")

planner_llm = ChatOpenAI(model="gpt-4o", temperature=0)
planner_chain = ChatPromptTemplate.from_messages([
    ("system", """You are a planning agent. Given a user request, propose a specific action.
Be precise about what you will do and what parameters are needed.
Risk levels: low=read-only, medium=creates data, high=modifies/deletes/sends externally."""),
    ("human", "User request: {request}"),
]) | planner_llm.with_structured_output(ActionProposal)

def planner_node(state: AgentState) -> AgentState:
    proposal = planner_chain.invoke({"request": state["user_request"]})
    return {
        **state,
        "proposed_action": {
            "action_type": proposal.action_type,
            "description": proposal.description,
            "parameters": proposal.parameters,
            "risk_level": proposal.risk_level,
        },
        "approval_status": "pending",
    }

# nodes.py (continued)
from langgraph.types import interrupt, Command

def approval_gate_node(state: AgentState) -> AgentState:
    """
    Pause execution and wait for human approval.
    The interrupt payload is what gets surfaced to the reviewer.
    """
    action = state["proposed_action"]

    # Only interrupt for medium or high risk actions
    if action["risk_level"] == "low":
        return {**state, "approval_status": "approved"}

    # This pauses the graph and returns the payload to whoever called invoke()
    human_decision = interrupt({
        "type": "approval_request",
        "proposed_action": action,
        "message": f"Agent wants to: {action['description']}. Approve?",
    })

    # human_decision is provided when the graph is resumed via Command(resume=...)
    return {
        **state,
        "approval_status": human_decision.get("decision", "rejected"),
        "human_feedback": human_decision.get("feedback", ""),
        "modified_parameters": human_decision.get("modified_parameters"),
    }

# nodes.py (continued)
import smtplib
from email.message import EmailMessage

def executor_node(state: AgentState) -> AgentState:
    """Execute the action only if approved."""
    if state["approval_status"] != "approved":
        return {
            **state,
            "final_result": f"Action cancelled. Reason: {state.get('human_feedback', 'Rejected by reviewer')}",
        }

    action = state["proposed_action"]
    params = state.get("modified_parameters") or action["parameters"]

    try:
        if action["action_type"] == "send_email":
            result = _send_email(params)
        elif action["action_type"] == "write_file":
            result = _write_file(params)
        else:
            result = f"Action '{action['action_type']}' executed with params: {params}"

        return {**state, "final_result": result}
    except Exception as e:
        return {**state, "error": str(e), "final_result": f"Execution failed: {e}"}

def _send_email(params: dict) -> str:
    """Demo email sender — swap with real SMTP or Gmail API in production."""
    to = params.get("to", "")
    subject = params.get("subject", "")
    body = params.get("body", "")
    # In production: connect to SMTP server with proper auth
    return f"Email sent to {to} with subject '{subject}'"

def _write_file(params: dict) -> str:
    path = params.get("path", "/tmp/agent_output.txt")
    content = params.get("content", "")
    with open(path, "w") as f:
        f.write(content)
    return f"File written to {path} ({len(content)} chars)"

def responder_node(state: AgentState) -> AgentState:
    if state.get("error"):
        return {**state, "final_result": f"Error: {state['error']}"}
    return state

# graph.py
from langgraph.graph import StateGraph, END
from langgraph.checkpoint.sqlite import SqliteSaver
from nodes import planner_node, approval_gate_node, executor_node, responder_node
from state import AgentState

def build_graph():
    graph = StateGraph(AgentState)
    graph.add_node("planner", planner_node)
    graph.add_node("approval_gate", approval_gate_node)
    graph.add_node("executor", executor_node)
    graph.add_node("responder", responder_node)

    graph.set_entry_point("planner")
    graph.add_edge("planner", "approval_gate")
    graph.add_edge("approval_gate", "executor")
    graph.add_edge("executor", "responder")
    graph.add_edge("responder", END)

    # Persistent checkpointer — state survives process restarts
    checkpointer = SqliteSaver.from_conn_string("./hitl_checkpoints.db")
    return graph.compile(checkpointer=checkpointer, interrupt_before=["approval_gate"])

app_graph = build_graph()

# api.py
import uuid
from fastapi import FastAPI, HTTPException
from pydantic import BaseModel
from langgraph.types import Command
from graph import app_graph

api = FastAPI(title="HITL Agent API")

class StartRequest(BaseModel):
    user_request: str
    user_id: str = "anonymous"

class ApprovalRequest(BaseModel):
    thread_id: str
    decision: str  # "approved" | "rejected"
    feedback: str = ""
    modified_parameters: dict = {}

@api.post("/start")
async def start_workflow(req: StartRequest):
    thread_id = str(uuid.uuid4())
    config = {"configurable": {"thread_id": thread_id}}

    # Run until the interrupt
    result = app_graph.invoke(
        {"user_request": req.user_request, "approval_status": None},
        config=config,
    )
    # result will contain the interrupt payload
    pending = app_graph.get_state(config)
    interrupt_data = None
    for task in pending.tasks:
        if task.interrupts:
            interrupt_data = task.interrupts[0].value

    return {
        "thread_id": thread_id,
        "status": "pending_approval",
        "proposed_action": interrupt_data,
    }

@api.post("/approve")
async def approve_action(req: ApprovalRequest):
    config = {"configurable": {"thread_id": req.thread_id}}

    # Resume the graph with the human's decision
    result = app_graph.invoke(
        Command(resume={
            "decision": req.decision,
            "feedback": req.feedback,
            "modified_parameters": req.modified_parameters or None,
        }),
        config=config,
    )
    return {
        "status": "completed",
        "result": result.get("final_result"),
        "approval_status": result.get("approval_status"),
    }

@api.get("/status/{thread_id}")
async def get_status(thread_id: str):
    config = {"configurable": {"thread_id": thread_id}}
    state = app_graph.get_state(config)
    return {"thread_id": thread_id, "state": state.values}

# Start a workflow
curl -X POST http://localhost:8000/start \
  -H "Content-Type: application/json" \
  -d '{"user_request": "Send an email to team@example.com about the Q1 report"}'

# Approve it (use the thread_id from the previous response)
curl -X POST http://localhost:8000/approve \
  -H "Content-Type: application/json" \
  -d '{"thread_id": "THREAD_ID", "decision": "approved", "feedback": "Looks good"}'