Interrupts: human-in-the-loop

from tenxgraph.utils import interrupt

# issue_refund is your own function that performs the refund.
async def refund_tool(amount: float) -> str:
    """A tool that asks for approval before issuing a refund."""
    decision = interrupt(
        value={"amount": amount},
        message=f"Approve a refund of ${amount}?",
        reason="tool_approval",
        response_schema={
            "type": "object",
            "properties": {"approved": {"type": "boolean"}}
        },
    )
    if not decision or not decision.get("approved"):
        return "Refund declined"
    return issue_refund(amount)

from tenxgraph import Message
from tenxgraph.utils import ResponseGranularity

# First run: pauses at interrupt()
config = {"thread_id": "refund-123"}
result = await graph.ainvoke(
    {"messages": [Message.text_message("Please refund my order")]},
    config=config,
    response_granularity=ResponseGranularity.FULL,  # include "state" in the result
)

# The thread is paused; inspect what it's waiting for
from tenxgraph.utils import pending_interrupt
request = pending_interrupt(result["state"])
print(request.message)  # "Approve a refund of $150?"
print(request.value)    # {"amount": 150}

# Resume with the answer
result = await graph.ainvoke(
    {"resume": {"approved": True}},
    config=config
)
# The refund_tool runs again; interrupt() now returns {"approved": True}

async def refund_tool(amount: float) -> str:
    # This code runs twice
    audit_log(f"Refund requested for ${amount}")  # WRONG: runs twice
    
    decision = interrupt({"amount": amount}, message=f"Approve ${amount}?")
    
    # This code runs only after resume
    if decision and decision.get("approved"):
        issue_refund(amount)  # CORRECT: only after approval
    return "refund complete"

async def complex_approval() -> str:
    step1 = interrupt({"step": 1}, message="Approve step 1?")
    # Run pauses. Resume with an answer.
    # The node re-runs from the top, step1 now has the answer.
    
    if step1:
        step2 = interrupt({"step": 2}, message="Approve step 2?")
        # Run pauses again. Resume with the next answer.

# Pause on first run
result = await graph.ainvoke(
    {"messages": [Message.text_message("Refund?")]},
    config={"thread_id": "order-42"}
)

# Resume on second run
result = await graph.ainvoke(
    {"resume": {"approved": True}},
    config={"thread_id": "order-42"}
)

# This raises ValueError
await graph.ainvoke(
    {"messages": [Message.text_message("Actually, never mind")]},
    config={"thread_id": "order-42"}  # order-42 is paused at interrupt()
)

graph = StateGraph(AgentState)
# ... add nodes and edges ...
compiled = graph.compile(
    interrupt_before=["approval_node", "user_input_node"],
    interrupt_after=["agent", "tool_node"],
)

from tenxgraph.utils import Interrupt

# You typically do not construct Interrupt directly; the interrupt() function does.
# But you may inspect it:
request = pending_interrupt(state)
print(request.id)            # Unique pause id
print(request.node)          # Node that paused
print(request.message)       # Human prompt
print(request.reason)        # Machine-readable reason
print(request.value)         # Payload passed to interrupt()
print(request.response_schema)  # JSON Schema for validation
print(request.tool_call_id)  # Set if interrupt() ran inside a tool

from tenxgraph.utils import GraphInterrupt

# You normally do not catch it; the graph engine handles it.
# But if you need to suppress it for testing, it is an exception:
try:
    await my_node()
except GraphInterrupt as e:
    # e.interrupt is the Interrupt object
    print(e.interrupt.message)

# First request pauses at interrupt()
curl -X POST http://localhost:8000/v1/graph/invoke \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [{"role": "user", "content": [{"type": "text", "text": "Refund my order"}]}],
    "config": {"thread_id": "order-42"},
    "response_granularity": "full"
  }'

# With "response_granularity": "full", the response "state" carries the pause
{
  "messages": [...],
  "state": {
    "execution_meta": {
      "interrupt_reason": "interrupt",
      "interrupt_data": {
        "interrupt": {
          "id": "int_abc123...",
          "node": "refund_tool",
          "message": "Approve a refund of $150?",
          "reason": "tool_approval",
          "value": {"amount": 150},
          "response_schema": {...},
          "tool_call_id": null
        }
      }
    }
  },
  ...
}

# Resume with the approval
curl -X POST http://localhost:8000/v1/graph/invoke \
  -H "Content-Type: application/json" \
  -d '{
    "resume": {"approved": true},
    "config": {"thread_id": "order-42"}
  }'

{"event": "updates", "data": {"status": "interrupted", "node": "refund_tool", "interrupt": {...}}}

async def sensitive_tool(query: str) -> str:
    decision = interrupt(
        {"query": query},
        message=f"Run sensitive query: {query}?",
        reason="tool_approval",
    )
    if not decision:
        return "Query cancelled"
    return run_query(query)

async def complex_task() -> str:
    plan = interrupt(
        {"options": ["A", "B", "C"]},
        message="Which approach?",
        reason="choice",
        response_schema={
            "type": "object",
            "properties": {"choice": {"type": "string", "enum": ["A", "B", "C"]}}
        }
    )
    approach = plan["choice"]
    
    result = execute(approach)
    
    if result["needs_review"]:
        approval = interrupt(
            {"result": result},
            message="Approve the result?",
            reason="approval"
        )
        if not approval:
            return "Result rejected"
    
    return "Task complete"

if situation == "unusual":
    human_input = interrupt(
        {"situation": situation_details},
        message="Escalated to human review. Please provide guidance.",
        reason="escalation"
    )