pushary-langgraph 0.1.0__py3-none-any.whl

pushary_langgraph/__init__.py

@@ -0,0 +1,191 @@
+"""Human-in-the-loop for LangGraph and LangChain, powered by Pushary.
+
+Two seams over the durable two-call contract (``enroll`` + ``decisions.ask``):
+
+- ``ask_human`` / ``pushary_interrupt`` without a callback: a blocking approval you
+  call from inside a node. It polls durably and fails closed.
+- ``pushary_interrupt`` with a ``callback_url``: parks the graph with LangGraph's
+  native ``interrupt()`` and resumes on Pushary's signed webhook, so an hour-long
+  wait holds no compute and survives a restart.
+
+Zero framework import at module load: LangGraph is imported lazily, only on the
+durable path, so the blocking helpers work (and test) without it installed.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any, Dict, List, Optional
+
+from pushary import (
+    PusharyServer,
+    SIGNATURE_HEADER,
+    deterministic_key,
+    is_approved,
+    parse_decision_callback,
+    verify_webhook_signature,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "connect",
+    "ask_human",
+    "pushary_interrupt",
+    "describe_answer",
+    "resolve_pushary_callback",
+    "is_affirmative",
+    "deterministic_key",
+    "SIGNATURE_HEADER",
+    "__version__",
+]
+
+
+def _client(api_key: Optional[str] = None, base_url: Optional[str] = None) -> PusharyServer:
+    key = api_key or os.environ.get("PUSHARY_API_KEY")
+    if not key:
+        raise ValueError("Pushary: set PUSHARY_API_KEY or pass api_key=... to the LangGraph helpers.")
+    return PusharyServer(api_key=key, base_url=base_url)
+
+
+def _idempotency_key(external_id: str, node: str, question: str) -> str:
+    return deterministic_key([external_id, node, question])
+
+
+def is_affirmative(answer: Optional[str]) -> bool:
+    """Fail-closed yes/no check for a confirm answer."""
+    return is_approved("answered", "confirm", answer)
+
+
+def connect(external_id: str, *, api_key: Optional[str] = None, base_url: Optional[str] = None) -> str:
+    """Connect one end-user's phone (keyless). Returns a single-use link to show them."""
+    return _client(api_key, base_url).enroll(external_id)["universalLink"]
+
+
+def ask_human(
+    question: str,
+    *,
+    external_id: str,
+    type: str = "confirm",
+    options: Optional[List[str]] = None,
+    node: str = "ask-human",
+    context: Optional[str] = None,
+    agent_name: Optional[str] = None,
+    timeout_seconds: Optional[float] = None,
+    api_key: Optional[str] = None,
+    base_url: Optional[str] = None,
+) -> Dict[str, Any]:
+    """Blocking ask (Pattern A): create a decision and poll durably until answered.
+
+    Returns the decision dict (``decisionId``, ``status``, ``answered``, ``value``,
+    ``type``, fail-closed ``approved``). The idempotency key is derived from
+    external_id + node + question, so a node that re-runs on resume hits the same
+    decision instead of paging the human twice.
+    """
+    return _client(api_key, base_url).decisions.ask(
+        question,
+        type=type,
+        options=options,
+        external_id=external_id,
+        context=context,
+        agent_name=agent_name,
+        timeout_seconds=timeout_seconds,
+        idempotency_key=_idempotency_key(external_id, node, question),
+    )
+
+
+def describe_answer(type: str, result: Dict[str, Any]) -> str:
+    """Turn a decision outcome into an unambiguous instruction for the model."""
+    if not result.get("answered"):
+        return (
+            f"No answer (status: {result.get('status')}). "
+            "Treat this as NOT approved and do not proceed."
+        )
+    if type == "confirm":
+        return (
+            "The human approved. You may proceed."
+            if result.get("approved")
+            else "The human declined. Do not proceed."
+        )
+    return f"The human answered: {result.get('value') or ''}"
+
+
+def resolve_pushary_callback(
+    raw_body: Any, signature: Optional[str], secret: str
+) -> Optional[Dict[str, Any]]:
+    """Verify a callback signature and parse it, or return None.
+
+    Feed ``answer`` into ``graph.invoke(Command(resume=answer), config)``.
+    """
+    if not verify_webhook_signature(raw_body, signature, secret):
+        return None
+    cb = parse_decision_callback(raw_body)
+    if not cb:
+        return None
+    return {
+        "correlationId": cb.get("correlationId"),
+        "answer": cb.get("answer"),
+        "value": cb.get("value"),
+        "approved": is_affirmative(cb.get("answer")),
+        "context": cb.get("context"),
+        "answeredAt": cb.get("answeredAt"),
+    }
+
+
+def pushary_interrupt(
+    question: str,
+    *,
+    external_id: str,
+    node: str = "hitl",
+    type: str = "confirm",
+    options: Optional[List[str]] = None,
+    callback_url: Optional[str] = None,
+    context: Optional[str] = None,
+    agent_name: Optional[str] = None,
+    timeout_seconds: Optional[float] = None,
+    api_key: Optional[str] = None,
+    base_url: Optional[str] = None,
+) -> Optional[str]:
+    """Ask a human from inside a LangGraph node.
+
+    - ``callback_url`` omitted (Pattern A): blocks, polls durably, returns the answer
+      (or None if fail-closed). Zero extra infra, holds the run open for the wait.
+    - ``callback_url`` set (Pattern B): opens the decision, then calls LangGraph's
+      ``interrupt()`` to park the graph in your checkpointer. Resume with
+      ``Command(resume=answer)`` from the signed webhook. Holds no idle compute.
+
+    The whole node re-runs on resume, so keep code before this call idempotent. The
+    decision's idempotency key is derived from external_id + node + question, so the
+    re-run lands on the same decision.
+    """
+    idem = _idempotency_key(external_id, node, question)
+    px = _client(api_key, base_url)
+
+    if not callback_url:
+        d = px.decisions.ask(
+            question,
+            type=type,
+            options=options,
+            external_id=external_id,
+            context=context,
+            agent_name=agent_name,
+            timeout_seconds=timeout_seconds,
+            idempotency_key=idem,
+        )
+        return d.get("value") if d.get("answered") else None
+
+    px.decisions.create(
+        question,
+        type=type,
+        options=options,
+        external_id=external_id,
+        context=context,
+        agent_name=agent_name,
+        callback_url=callback_url,
+        idempotency_key=idem,
+        wait=False,
+    )
+    # Lazy import: only the durable path needs LangGraph installed.
+    from langgraph.types import interrupt
+
+    return interrupt({"pushary": "decision", "question": question, "external_id": external_id})

pushary_langgraph-0.1.0.dist-info/METADATA

@@ -0,0 +1,115 @@
+Metadata-Version: 2.4
+Name: pushary-langgraph
+Version: 0.1.0
+Summary: Human-in-the-loop for LangGraph and LangChain: a blocking ask_human, plus a durable interrupt()/Command resume that reaches your user on their phone.
+Project-URL: Homepage, https://pushary.com
+Project-URL: Documentation, https://pushary.com/docs/agents/adapters
+Author-email: Pushary <business@pushary.com>
+License: MIT
+License-File: LICENSE
+Keywords: ai-agents,approvals,human-in-the-loop,interrupt,langchain,langgraph
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: langgraph<2,>=1.0
+Requires-Dist: pushary>=1.3.2
+Description-Content-Type: text/markdown
+
+# pushary-langgraph
+
+Human-in-the-loop for [LangGraph](https://langchain-ai.github.io/langgraph/) and
+LangChain. Ask a real human to approve, and get the answer on their phone. Two seams:
+
+- **A blocking `ask_human`** you call from inside a node.
+- **A durable `pushary_interrupt`** that parks the graph with LangGraph's native
+  `interrupt()` and resumes on a signed webhook, so a long wait holds no compute and
+  survives a restart.
+
+Requires the Pushary [Partner plan](https://pushary.com/agent-notifications-integration).
+
+## Install
+
+```bash
+pip install pushary-langgraph
+```
+
+Set `PUSHARY_API_KEY` (get it in your [dashboard](https://pushary.com/dashboard/settings)).
+
+## Connect a phone once
+
+```python
+from pushary_langgraph import connect
+
+link = connect("user_123")  # show this to your end-user; one tap connects their phone
+```
+
+## Ask a human inside a node
+
+```python
+from pushary_langgraph import ask_human
+
+def approval_node(state):
+    d = ask_human("Approve this transfer?", external_id=state["user_id"], node="approval")
+    return {"approved": d["approved"]}
+```
+
+`ask_human` blocks, polls durably, and fails closed. The idempotency key is derived
+from `external_id + node + question`, so a node that re-runs on resume hits the same
+decision instead of paging the human twice.
+
+## Durable interrupt
+
+```python
+from pushary_langgraph import pushary_interrupt
+
+def approval_node(state):
+    answer = pushary_interrupt(
+        "Approve this transfer?",
+        external_id=state["user_id"],
+        node="approval",
+        callback_url=os.environ["PUSHARY_CALLBACK_URL"],  # omit to block instead of park
+    )
+    return {"approved": answer == "yes"}
+```
+
+With a `callback_url`, the node opens the decision and calls LangGraph's `interrupt()`
+to park the graph (a checkpointer is required). Keep any code before the call
+idempotent, the whole node re-runs on resume.
+
+### Resume from the webhook
+
+```python
+from pushary_langgraph import resolve_pushary_callback, SIGNATURE_HEADER
+from langgraph.types import Command
+
+# POST /pushary/callback
+def callback(request):
+    raw = request.body
+    cb = resolve_pushary_callback(raw, request.headers.get(SIGNATURE_HEADER), os.environ["PUSHARY_WEBHOOK_SECRET"])
+    if not cb:
+        return ("bad signature", 401)
+    thread_id = lookup_thread(cb["correlationId"])  # your own correlationId -> thread_id map
+    graph.invoke(Command(resume=cb["answer"]), {"configurable": {"thread_id": thread_id}})
+    return ("ok", 200)
+```
+
+## API
+
+- `connect(external_id, *, api_key=None, base_url=None)` — enroll an end-user's phone, returns the link.
+- `ask_human(question, *, external_id, type="confirm", options=None, node=..., ...)` — blocking, returns the decision dict.
+- `pushary_interrupt(question, *, external_id, node=..., callback_url=None, ...)` — blocking, or durable when `callback_url` is set.
+- `resolve_pushary_callback(raw_body, signature, secret)` — verify + parse a callback into `{correlationId, answer, approved, ...}`.
+- `describe_answer(type, result)`, `is_affirmative(answer)`, `deterministic_key(parts)`, `SIGNATURE_HEADER`.
+
+## License
+
+MIT

pushary_langgraph-0.1.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+pushary_langgraph/__init__.py,sha256=5c391ElHkVmHruEwiry3_iiGT0Hg2Pzoo7Sep1y_WPo,6474
+pushary_langgraph/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pushary_langgraph-0.1.0.dist-info/METADATA,sha256=6ONicjz8gXSANE9624xqH0hgAvgWLZdsBjvJ2brmQio,4282
+pushary_langgraph-0.1.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+pushary_langgraph-0.1.0.dist-info/licenses/LICENSE,sha256=dbAOXev8njZg4qMsS4LS9tZq8cVgKYPZ1iTeOux9UBE,1064
+pushary_langgraph-0.1.0.dist-info/RECORD,,

pushary_langgraph-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any

pushary_langgraph-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pushary
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.