looppause 0.1.0__tar.gz

looppause-0.1.0/.gitignore

@@ -0,0 +1,17 @@
+node_modules
+dist
+.next
+.turbo
+*.env
+.env.local
+.env.production
+.env.development
+!.env.example
+coverage
+.DS_Store
+*.log
+/prisma/migrations
+.env
+# Database backup files — never commit dumps
+*.dump
+looppause_backup.sql

looppause-0.1.0/PKG-INFO

@@ -0,0 +1,73 @@
+Metadata-Version: 2.4
+Name: looppause
+Version: 0.1.0
+Summary: Human-in-the-loop API client for LoopPause. Includes LangGraph and CrewAI integrations.
+Project-URL: Homepage, https://looppause.com
+Project-URL: Documentation, https://looppause.com/docs
+Project-URL: Repository, https://github.com/looppause/looppause
+Project-URL: Bug Tracker, https://github.com/looppause/looppause/issues
+License: MIT
+Keywords: ai-agents,crewai,hitl,human-in-the-loop,langgraph,looppause
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.25
+Provides-Extra: all
+Requires-Dist: crewai>=0.28; extra == 'all'
+Requires-Dist: langgraph>=0.2; extra == 'all'
+Provides-Extra: crewai
+Requires-Dist: crewai>=0.28; extra == 'crewai'
+Provides-Extra: dev
+Requires-Dist: mypy>=1.8; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: ruff>=0.3; extra == 'dev'
+Provides-Extra: langgraph
+Requires-Dist: langgraph>=0.2; extra == 'langgraph'
+Description-Content-Type: text/markdown
+
+# looppause
+
+Python client for the [LoopPause](https://looppause.com) human-in-the-loop API.
+
+Pause any agent action, route approval to Slack or email, and resume with an HMAC-SHA256 signed proof.
+
+## Install
+
+```bash
+pip install looppause                    # base client
+pip install looppause[langgraph]         # + LangGraph integration
+pip install looppause[crewai]            # + CrewAI integration
+pip install looppause[langgraph,crewai]  # everything
+```
+
+## Quick start
+
+```python
+from looppause_client import LoopPauseClient
+
+client = LoopPauseClient()  # reads LOOPPAUSE_API_KEY + LOOPPAUSE_SIGNING_SECRET
+
+pause_id = client.create_pause(
+    agent_id="billing-agent",
+    action={"type": "payment", "description": "Pay Acme Corp $12,450"},
+    recipients=[{"channel": "slack", "target": "#finance-approvals"}],
+    idempotency_key="idem_abc123",
+)
+
+proof = client.wait_for_proof(pause_id)
+
+if proof.human_authorized:
+    # proceed
+    pass
+```
+
+## Early access
+
+LoopPause is in early access. Request access: hello@looppause.com

looppause-0.1.0/README.md

@@ -0,0 +1,39 @@
+# looppause
+
+Python client for the [LoopPause](https://looppause.com) human-in-the-loop API.
+
+Pause any agent action, route approval to Slack or email, and resume with an HMAC-SHA256 signed proof.
+
+## Install
+
+```bash
+pip install looppause                    # base client
+pip install looppause[langgraph]         # + LangGraph integration
+pip install looppause[crewai]            # + CrewAI integration
+pip install looppause[langgraph,crewai]  # everything
+```
+
+## Quick start
+
+```python
+from looppause_client import LoopPauseClient
+
+client = LoopPauseClient()  # reads LOOPPAUSE_API_KEY + LOOPPAUSE_SIGNING_SECRET
+
+pause_id = client.create_pause(
+    agent_id="billing-agent",
+    action={"type": "payment", "description": "Pay Acme Corp $12,450"},
+    recipients=[{"channel": "slack", "target": "#finance-approvals"}],
+    idempotency_key="idem_abc123",
+)
+
+proof = client.wait_for_proof(pause_id)
+
+if proof.human_authorized:
+    # proceed
+    pass
+```
+
+## Early access
+
+LoopPause is in early access. Request access: hello@looppause.com

looppause-0.1.0/looppause_client.py

@@ -0,0 +1,229 @@
+"""
+looppause_client — shared Python client for the LoopPause HITL API.
+
+Used by both the LangGraph integration and the CrewAI tool.
+
+Server-side requirement assumed by this client:
+  * GET /v1/pauses/:id returns the full signed proof (including `signature`)
+    once status == "responded".
+  * POST /v1/pauses honors an `Idempotency-Key` header: the same key returns
+    the existing pause_id instead of creating a duplicate. This is what makes
+    the LangGraph interrupt() pattern correct, since the node re-executes on
+    resume and would otherwise create a second pause.
+
+Signing contract (must match the server's signer):
+  HMAC-SHA256 over the canonical JSON of the proof with the `signature` field
+  removed, keys sorted recursively, compact separators, UTF-8, hex digest.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+import os
+import time
+from dataclasses import dataclass, field
+from typing import Any, Optional
+
+import httpx  # pip install httpx
+
+
+# --------------------------------------------------------------------------- #
+# Errors
+# --------------------------------------------------------------------------- #
+class LoopPauseError(Exception):
+    """Base error."""
+
+
+class LoopPauseUnavailable(LoopPauseError):
+    """LoopPause is unreachable or returned 503. Callers MUST fail closed."""
+
+
+class LoopPauseDenied(LoopPauseError):
+    """A terminal non-approval: rejected, timed out, expired, unverifiable,
+    or a system_fallback where a human decision was required."""
+
+
+# --------------------------------------------------------------------------- #
+# Signing
+# --------------------------------------------------------------------------- #
+def _canonical(payload: dict) -> bytes:
+    body = {k: v for k, v in payload.items() if k != "signature"}
+    return json.dumps(body, sort_keys=True, separators=(",", ":")).encode("utf-8")
+
+
+def verify_signature(proof: dict, signing_secret: str) -> bool:
+    provided = proof.get("signature", "")
+    expected = hmac.new(
+        signing_secret.encode("utf-8"), _canonical(proof), hashlib.sha256
+    ).hexdigest()
+    return hmac.compare_digest(provided, expected)
+
+
+def stable_idempotency_key(*parts: Any) -> str:
+    """Deterministic key so a retried/re-executed create does not duplicate."""
+    blob = json.dumps(parts, sort_keys=True, separators=(",", ":"), default=str)
+    return "idem_" + hashlib.sha256(blob.encode("utf-8")).hexdigest()[:32]
+
+
+# --------------------------------------------------------------------------- #
+# Proof
+# --------------------------------------------------------------------------- #
+@dataclass
+class Proof:
+    pause_id: str
+    decision: str               # "approved" | "rejected"
+    authorization_type: str     # "human" | "system_fallback"
+    human_response: bool
+    responder: str
+    responded_at: str
+    channel: Optional[str] = None
+    comment: Optional[str] = None
+    fields: Optional[dict] = None
+    raw: dict = field(default_factory=dict)
+
+    @property
+    def human_authorized(self) -> bool:
+        """True only for a genuine human approval. system_fallback is False."""
+        return (
+            self.authorization_type == "human"
+            and self.human_response is True
+            and self.decision == "approved"
+        )
+
+    @classmethod
+    def from_payload(cls, p: dict) -> "Proof":
+        return cls(
+            pause_id=p["pause_id"],
+            decision=p["decision"],
+            authorization_type=p["authorization_type"],
+            human_response=bool(p.get("human_response", False)),
+            responder=p.get("responder", ""),
+            responded_at=p.get("responded_at", ""),
+            channel=p.get("channel"),
+            comment=p.get("comment"),
+            fields=p.get("fields"),
+            raw=p,
+        )
+
+
+# --------------------------------------------------------------------------- #
+# Client
+# --------------------------------------------------------------------------- #
+class LoopPauseClient:
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        signing_secret: Optional[str] = None,
+        base_url: str = "https://api.looppause.com",
+        request_timeout: float = 10.0,
+    ) -> None:
+        self.api_key = api_key or os.environ["LOOPPAUSE_API_KEY"]
+        self.signing_secret = signing_secret or os.environ["LOOPPAUSE_SIGNING_SECRET"]
+        self.base_url = base_url.rstrip("/")
+        self._http = httpx.Client(timeout=request_timeout)
+
+    def _headers(self, idempotency_key: Optional[str] = None) -> dict:
+        h = {
+            "Authorization": f"Bearer {self.api_key}",
+            "Content-Type": "application/json",
+        }
+        if idempotency_key:
+            h["Idempotency-Key"] = idempotency_key
+        return h
+
+    def create_pause(
+        self,
+        *,
+        agent_id: str,
+        action: dict,
+        recipients: list[dict],
+        idempotency_key: str,
+        webhook_url: Optional[str] = None,
+        form: Optional[dict] = None,
+        timeout_hours: int = 24,
+        escalation: Optional[dict] = None,
+    ) -> str:
+        body: dict[str, Any] = {
+            "agent_id": agent_id,
+            "action": action,
+            "recipients": recipients,
+            "timeout_hours": timeout_hours,
+        }
+        if webhook_url:
+            body["webhook_url"] = webhook_url
+        if form:
+            body["form"] = form
+        if escalation:
+            body["escalation"] = escalation
+
+        try:
+            r = self._http.post(
+                f"{self.base_url}/v1/pauses",
+                json=body,
+                headers=self._headers(idempotency_key),
+            )
+        except httpx.RequestError as exc:
+            raise LoopPauseUnavailable(f"create_pause transport error: {exc}") from exc
+
+        if r.status_code == 503:
+            raise LoopPauseUnavailable("LoopPause returned 503 on create — failing closed")
+        r.raise_for_status()
+        return r.json()["pause_id"]
+
+    def wait_for_proof(
+        self,
+        pause_id: str,
+        *,
+        poll_interval: float = 2.0,
+        max_interval: float = 30.0,
+        deadline_seconds: int = 24 * 3600,
+    ) -> Proof:
+        """Poll until responded. Verifies the HMAC signature before returning.
+
+        Raises LoopPauseUnavailable on persistent unreachability (fail closed),
+        LoopPauseDenied on timeout/expiry/unverifiable signature.
+        """
+        start = time.monotonic()
+        interval = poll_interval
+
+        while True:
+            if time.monotonic() - start > deadline_seconds:
+                raise LoopPauseDenied(f"client deadline exceeded for {pause_id} — failing closed")
+
+            try:
+                r = self._http.get(
+                    f"{self.base_url}/v1/pauses/{pause_id}", headers=self._headers()
+                )
+            except httpx.RequestError:
+                time.sleep(interval)
+                interval = min(interval * 2, max_interval)
+                continue
+
+            if r.status_code == 503:
+                # transient; back off. The deadline above bounds total wait.
+                time.sleep(interval)
+                interval = min(interval * 2, max_interval)
+                continue
+
+            r.raise_for_status()
+            data = r.json()
+            status = data.get("status")
+
+            if status == "responded":
+                if not verify_signature(data, self.signing_secret):
+                    raise LoopPauseDenied(f"signature verification failed for {pause_id} — failing closed")
+                return Proof.from_payload(data)
+
+            if status in ("timed_out", "expired"):
+                raise LoopPauseDenied(f"pause {pause_id} {status} — failing closed")
+
+            time.sleep(interval)
+            interval = min(interval * 2, max_interval)
+
+    def parse_resume_proof(self, payload: dict) -> Proof:
+        """Verify a proof handed in via Command(resume=...) (webhook path)."""
+        if not verify_signature(payload, self.signing_secret):
+            raise LoopPauseDenied("resume proof signature verification failed — failing closed")
+        return Proof.from_payload(payload)

looppause-0.1.0/looppause_crewai.py

@@ -0,0 +1,135 @@
+"""
+looppause_crewai — a CrewAI tool that gates an agent action on human approval
+via the LoopPause API.
+
+Install (PyPI):  pip install looppause-crewai
+Usage:
+    from looppause_crewai import HumanApprovalTool
+    tool = HumanApprovalTool(slack_channel="#approvals", fallback_email="x@acme.eu")
+    agent = Agent(role="Procurement", goal="...", tools=[tool])
+
+The tool BLOCKS until a human responds (or the pause times out). It fails CLOSED:
+  * LoopPause 503 / unreachable  -> raises (the crew stops; it never silently proceeds)
+  * timeout / expiry / bad signature -> raises
+  * system_fallback when require_human=True -> raises (a configured default is not a sign-off)
+  * human rejection -> returns a clear "DENIED" string the agent must honor
+Only a genuine human approval returns an "APPROVED" result.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from typing import Any, List, Optional, Type
+
+from crewai.tools import BaseTool
+from pydantic import BaseModel, Field
+
+from looppause_client import (
+    LoopPauseClient,
+    LoopPauseDenied,
+    LoopPauseUnavailable,
+    stable_idempotency_key,
+)
+
+
+class HumanApprovalInput(BaseModel):
+    """Input schema for the human approval gate."""
+
+    action_description: str = Field(
+        ..., description="A clear, human-readable description of the action awaiting approval."
+    )
+    action_details: dict = Field(
+        default_factory=dict,
+        description="Structured details of the action (amounts, targets, identifiers).",
+    )
+    action_type: str = Field(
+        default="agent_action", description="Short machine label for the action type."
+    )
+
+
+class HumanApprovalTool(BaseTool):
+    name: str = "request_human_approval"
+    description: str = (
+        "Request human approval before performing a sensitive or irreversible action. "
+        "Blocks until a person approves or rejects and returns a signed decision. "
+        "Call this BEFORE any irreversible action (payments, deletions, external "
+        "communications). If the result is not an explicit human APPROVED, do not proceed."
+    )
+    args_schema: Type[BaseModel] = HumanApprovalInput
+
+    # Configuration (set at construction; not exposed to the LLM)
+    agent_id: str = "crewai-agent"
+    slack_channel: Optional[str] = None
+    fallback_email: Optional[str] = None
+    require_human: bool = True
+    timeout_hours: int = 24
+
+    # Lazily constructed client
+    _client: Optional[LoopPauseClient] = None
+
+    def __init__(self, **kwargs: Any) -> None:
+        super().__init__(**kwargs)
+        if not (self.slack_channel or self.fallback_email):
+            raise ValueError("HumanApprovalTool needs a slack_channel and/or fallback_email.")
+        # Surface missing credentials early and clearly.
+        if "LOOPPAUSE_API_KEY" not in os.environ or "LOOPPAUSE_SIGNING_SECRET" not in os.environ:
+            raise EnvironmentError(
+                "Set LOOPPAUSE_API_KEY and LOOPPAUSE_SIGNING_SECRET before using HumanApprovalTool."
+            )
+        self._client = LoopPauseClient()
+
+    def _recipients(self) -> List[dict]:
+        rcpt: dict[str, Any] = {}
+        if self.slack_channel:
+            rcpt = {"channel": "slack", "target": self.slack_channel}
+            if self.fallback_email:
+                rcpt["fallback_email"] = self.fallback_email
+        else:
+            rcpt = {"channel": "email", "target": self.fallback_email}
+        return [rcpt]
+
+    def _run(self, action_description: str, action_details: dict, action_type: str = "agent_action") -> str:
+        action = {"type": action_type, "description": action_description, "details": action_details}
+        idem = stable_idempotency_key(self.agent_id, action)
+
+        try:
+            pause_id = self._client.create_pause(
+                agent_id=self.agent_id,
+                action=action,
+                recipients=self._recipients(),
+                idempotency_key=idem,
+                timeout_hours=self.timeout_hours,
+                escalation={"after_hours": max(1, self.timeout_hours // 4),
+                            "fallback_action": "auto_reject"},
+            )
+            proof = self._client.wait_for_proof(pause_id)
+        except LoopPauseUnavailable as exc:
+            # Fail closed hard: stop the crew rather than let it proceed unapproved.
+            raise RuntimeError(f"Human approval could not be obtained (LoopPause unavailable): {exc}")
+        except LoopPauseDenied as exc:
+            raise RuntimeError(f"Action not approved (no valid human decision): {exc}")
+
+        if self.require_human and not proof.human_authorized:
+            # e.g. system_fallback auto-approval — not a human sign-off for irreversible work.
+            raise RuntimeError(
+                f"Action not human-approved (authorization_type={proof.authorization_type}); refusing to proceed."
+            )
+
+        if proof.decision == "approved":
+            return json.dumps({
+                "result": "APPROVED",
+                "responder": proof.responder,
+                "authorization_type": proof.authorization_type,
+                "comment": proof.comment,
+                "fields": proof.fields,
+                "pause_id": proof.pause_id,
+            })
+
+        return json.dumps({
+            "result": "DENIED",
+            "responder": proof.responder,
+            "comment": proof.comment,
+            "pause_id": proof.pause_id,
+            "instruction": "Do not perform the action. A human rejected it.",
+        })

looppause-0.1.0/looppause_langgraph.py

@@ -0,0 +1,232 @@
+"""
+looppause_langgraph — native LoopPause human-in-the-loop nodes for LangGraph.
+
+Two patterns are provided:
+
+  1. make_polling_gate(...)   — a node that creates a pause and BLOCKS, polling
+     GET /v1/pauses/:id until responded. Universally compatible (no checkpointer
+     or inbound webhook required) but holds a graph worker for the whole wait.
+
+  2. make_interrupt_gate(...) — the durable, graph-native pattern. The node
+     creates a pause and calls interrupt(); the graph hibernates in the
+     checkpointer. When LoopPause's webhook fires, your app resumes the thread
+     with Command(resume=<signed_proof>). Recommended for production.
+
+Both write a structured result into state and fail CLOSED: any outcome that is
+not a genuine human approval routes away from the protected action.
+
+    pip install langgraph httpx
+"""
+
+from __future__ import annotations
+
+from typing import Any, Callable, Optional, TypedDict
+
+from langgraph.types import interrupt
+
+from looppause_client import (
+    LoopPauseClient,
+    LoopPauseDenied,
+    LoopPauseUnavailable,
+    Proof,
+    stable_idempotency_key,
+)
+
+
+class GateResult(TypedDict):
+    approved: bool
+    authorization_type: Optional[str]
+    responder: Optional[str]
+    comment: Optional[str]
+    pause_id: Optional[str]
+    halt_reason: Optional[str]
+
+
+def _result_from_proof(proof: Proof, *, require_human: bool) -> GateResult:
+    approved = proof.human_authorized if require_human else (proof.decision == "approved")
+    return GateResult(
+        approved=approved,
+        authorization_type=proof.authorization_type,
+        responder=proof.responder,
+        comment=proof.comment,
+        pause_id=proof.pause_id,
+        halt_reason=None if approved else f"decision={proof.decision},auth={proof.authorization_type}",
+    )
+
+
+def _halt(reason: str, pause_id: Optional[str] = None) -> GateResult:
+    return GateResult(
+        approved=False,
+        authorization_type=None,
+        responder=None,
+        comment=None,
+        pause_id=pause_id,
+        halt_reason=reason,
+    )
+
+
+# --------------------------------------------------------------------------- #
+# Pattern 1: blocking polling gate
+# --------------------------------------------------------------------------- #
+def make_polling_gate(
+    client: LoopPauseClient,
+    *,
+    agent_id: str,
+    action_builder: Callable[[dict], dict],
+    recipients: list[dict],
+    state_key: str = "looppause",
+    require_human: bool = True,
+    timeout_hours: int = 24,
+    escalation: Optional[dict] = None,
+) -> Callable[[dict], dict]:
+    """Returns a node that creates a pause and blocks until a decision."""
+
+    def node(state: dict) -> dict:
+        action = action_builder(state)
+        idem = stable_idempotency_key(agent_id, "polling_gate", action)
+        try:
+            pause_id = client.create_pause(
+                agent_id=agent_id,
+                action=action,
+                recipients=recipients,
+                idempotency_key=idem,
+                timeout_hours=timeout_hours,
+                escalation=escalation,
+            )
+            proof = client.wait_for_proof(pause_id)
+            return {state_key: _result_from_proof(proof, require_human=require_human)}
+        except LoopPauseUnavailable as exc:
+            return {state_key: _halt(f"looppause_unavailable: {exc}")}
+        except LoopPauseDenied as exc:
+            return {state_key: _halt(f"denied: {exc}")}
+
+    return node
+
+
+# --------------------------------------------------------------------------- #
+# Pattern 2: durable interrupt() gate (recommended)
+# --------------------------------------------------------------------------- #
+def make_interrupt_gate(
+    client: LoopPauseClient,
+    *,
+    agent_id: str,
+    action_builder: Callable[[dict], dict],
+    recipients: list[dict],
+    webhook_url: str,
+    state_key: str = "looppause",
+    require_human: bool = True,
+    timeout_hours: int = 24,
+    escalation: Optional[dict] = None,
+) -> Callable[..., dict]:
+    """Returns a node that hibernates the graph via interrupt().
+
+    IMPORTANT — re-execution semantics: on resume, LangGraph re-runs this node
+    from the top, so create_pause() is called a SECOND time. The deterministic
+    idempotency key makes that second call return the SAME pause_id rather than
+    opening a duplicate pause. Do not remove it.
+
+    Resume the thread elsewhere with Command(resume=<signed_proof_dict>) when
+    LoopPause delivers the webhook (see resume_thread below). Pass thread_id in
+    the pause metadata so your webhook knows which thread to wake.
+    """
+
+    def node(state: dict, config: dict) -> dict:
+        thread_id = config["configurable"]["thread_id"]
+        action = action_builder(state)
+        idem = stable_idempotency_key(thread_id, "interrupt_gate", action)
+
+        try:
+            pause_id = client.create_pause(
+                agent_id=agent_id,
+                action=action,
+                recipients=recipients,
+                idempotency_key=idem,
+                webhook_url=webhook_url,
+                timeout_hours=timeout_hours,
+                escalation=escalation,
+            )
+        except LoopPauseUnavailable as exc:
+            # Do not suspend if we could not even create the pause — fail closed now.
+            return {state_key: _halt(f"looppause_unavailable: {exc}")}
+
+        # Graph suspends here. The resume value is the signed proof delivered by
+        # the external resumer. On resume the node re-runs; create_pause above is
+        # idempotent, and interrupt() returns the resume value instead of pausing.
+        resume_value: Any = interrupt({"pause_id": pause_id, "action": action})
+
+        try:
+            proof = client.parse_resume_proof(resume_value)
+            return {state_key: _result_from_proof(proof, require_human=require_human)}
+        except LoopPauseDenied as exc:
+            return {state_key: _halt(f"denied: {exc}", pause_id=pause_id)}
+
+    return node
+
+
+def route_on_gate(state_key: str = "looppause") -> Callable[[dict], str]:
+    """Conditional-edge function: 'approved' or 'halt'. Default deny."""
+
+    def router(state: dict) -> str:
+        return "approved" if state.get(state_key, {}).get("approved") else "halt"
+
+    return router
+
+
+# --------------------------------------------------------------------------- #
+# External resumer (call this from your webhook handler)
+# --------------------------------------------------------------------------- #
+def resume_thread(graph, thread_id: str, signed_proof: dict) -> None:
+    """Wake a hibernating graph with the signed proof from a LoopPause webhook."""
+    from langgraph.types import Command
+
+    graph.invoke(Command(resume=signed_proof), config={"configurable": {"thread_id": thread_id}})
+
+
+# --------------------------------------------------------------------------- #
+# Example wiring
+# --------------------------------------------------------------------------- #
+if __name__ == "__main__":
+    from langgraph.graph import StateGraph, START, END
+    from langgraph.checkpoint.memory import MemorySaver
+
+    class S(TypedDict, total=False):
+        invoice: dict
+        looppause: GateResult
+        result: str
+
+    client = LoopPauseClient()  # reads LOOPPAUSE_API_KEY / LOOPPAUSE_SIGNING_SECRET
+
+    gate = make_interrupt_gate(
+        client,
+        agent_id="procurement-agent",
+        action_builder=lambda s: {
+            "type": "payment_approval",
+            "description": f"Approve payment of {s['invoice']['amount']} {s['invoice']['currency']}",
+            "details": s["invoice"],
+        },
+        recipients=[{"channel": "slack", "target": "#procurement-approvals",
+                     "fallback_email": "approvers@acme.eu"}],
+        webhook_url="https://acme.eu/webhooks/looppause",
+        require_human=True,  # irreversible action: system_fallback will NOT pass
+        escalation={"after_hours": 4, "escalate_to": "manager@acme.eu",
+                    "fallback_action": "auto_reject"},
+    )
+
+    def execute_payment(state: S) -> dict:
+        return {"result": f"PAID — approved by {state['looppause']['responder']}"}
+
+    def halted(state: S) -> dict:
+        return {"result": f"BLOCKED — {state['looppause']['halt_reason']}"}
+
+    g = StateGraph(S)
+    g.add_node("approval_gate", gate)
+    g.add_node("execute_payment", execute_payment)
+    g.add_node("halted", halted)
+    g.add_edge(START, "approval_gate")
+    g.add_conditional_edges("approval_gate", route_on_gate(),
+                            {"approved": "execute_payment", "halt": "halted"})
+    g.add_edge("execute_payment", END)
+    g.add_edge("halted", END)
+
+    app = g.compile(checkpointer=MemorySaver())
+    # First run suspends at the gate; resume_thread(app, thread_id, proof) continues it.

looppause-0.1.0/pyproject.toml

@@ -0,0 +1,94 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+# ── Base package: looppause ──────────────────────────────────────────────────
+# pip install looppause
+# pip install looppause[langgraph]    -- adds langgraph
+# pip install looppause[crewai]       -- adds crewai
+# pip install looppause[langgraph,crewai]
+
+[project]
+name = "looppause"
+version = "0.1.0"
+description = "Human-in-the-loop API client for LoopPause. Includes LangGraph and CrewAI integrations."
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.10"
+keywords = ["hitl", "human-in-the-loop", "ai-agents", "langgraph", "crewai", "looppause"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+]
+
+# Core dependencies (base client only)
+dependencies = [
+  "httpx>=0.25",
+]
+
+[project.optional-dependencies]
+# pip install looppause[langgraph]
+langgraph = [
+  "langgraph>=0.2",
+]
+# pip install looppause[crewai]
+crewai = [
+  "crewai>=0.28",
+]
+# pip install looppause[all]
+all = [
+  "langgraph>=0.2",
+  "crewai>=0.28",
+]
+# Development extras
+dev = [
+  "pytest>=7",
+  "pytest-asyncio>=0.23",
+  "mypy>=1.8",
+  "ruff>=0.3",
+]
+
+[project.urls]
+Homepage = "https://looppause.com"
+Documentation = "https://looppause.com/docs"
+Repository = "https://github.com/looppause/looppause"
+"Bug Tracker" = "https://github.com/looppause/looppause/issues"
+
+# ── Build configuration ───────────────────────────────────────────────────────
+# Flat layout: looppause_client.py, looppause_langgraph.py, looppause_crewai.py
+# are installed as top-level modules so `from looppause_client import ...` works.
+[tool.hatch.build.targets.wheel]
+include = [
+  "looppause_client.py",
+  "looppause_langgraph.py",
+  "looppause_crewai.py",
+]
+
+[tool.hatch.build.targets.sdist]
+include = [
+  "looppause_client.py",
+  "looppause_langgraph.py",
+  "looppause_crewai.py",
+  "pyproject.toml",
+  "README.md",
+]
+
+# ── Linting ───────────────────────────────────────────────────────────────────
+[tool.ruff]
+target-version = "py310"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP"]
+
+# ── Type checking ─────────────────────────────────────────────────────────────
+[tool.mypy]
+python_version = "3.10"
+strict = true
+ignore_missing_imports = true