noxy-langgraph 1.0.0__tar.gz

noxy_langgraph-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Noxy Network (noxy.network)
+
+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.

noxy_langgraph-1.0.0/PKG-INFO

@@ -0,0 +1,243 @@
+Metadata-Version: 2.4
+Name: noxy-langgraph
+Version: 1.0.0
+Summary: LangGraph connector for Noxy human-in-the-loop decisions via interrupt/resume and webhooks.
+Author: Noxy Network
+License-Expression: MIT
+Project-URL: Homepage, https://noxy.network
+Project-URL: Documentation, https://docs.noxy.network
+Project-URL: Repository, https://github.com/noxy-network/langgraph-connector
+Project-URL: Issues, https://github.com/noxy-network/langgraph-connector/issues
+Keywords: noxy,noxy-network,langgraph,human-in-the-loop,ai-agents,interrupt,webhook
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+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 :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: noxy-sdk>=2.1.0
+Requires-Dist: langgraph>=0.2.0
+Requires-Dist: langgraph-checkpoint>=2.0.0
+Provides-Extra: examples
+Requires-Dist: fastapi>=0.110.0; extra == "examples"
+Requires-Dist: uvicorn>=0.27.0; extra == "examples"
+Provides-Extra: dev
+Requires-Dist: build>=1.0.0; extra == "dev"
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Requires-Dist: twine>=5.0.0; extra == "dev"
+Dynamic: license-file
+
+# Noxy LangGraph Connector
+
+[![PyPI version](https://img.shields.io/pypi/v/noxy-langgraph.svg)](https://pypi.org/project/noxy-langgraph/)
+[![Python versions](https://img.shields.io/pypi/pyversions/noxy-langgraph.svg)](https://pypi.org/project/noxy-langgraph/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+LangGraph connector for [Noxy](https://noxy.network) **human-in-the-loop** guardrails. Pauses agent graphs with `interrupt()`, delivers encrypted approval prompts to user devices, and resumes execution when Noxy fires a webhook.
+
+## Flow
+
+```mermaid
+sequenceDiagram
+    participant G as LangGraph
+    participant N as Noxy Relay
+    participant P as User Phone
+    participant S as Your Server
+
+    G->>N: send_decision (push payload)
+    N->>P: Push notification
+    G->>G: interrupt() — state saved to checkpointer
+    Note over G: Graph suspended
+
+    alt User responds
+        P->>N: Approve / Reject
+        N->>S: Webhook (outcome)
+        S->>G: Command(resume=decision)
+        G->>G: Continue with decision in state
+    else Timeout
+        N->>S: Webhook (timeout / expired)
+        S->>G: Command(resume=timeout)
+        G->>G: Continue with default behaviour
+    end
+```
+
+1. Graph reaches the HITL node.
+2. Noxy routes an encrypted actionable to the user's device (push).
+3. The node calls `interrupt()` — LangGraph suspends and persists state via a checkpointer.
+4. User responds on mobile **or** the decision TTL expires.
+5. Noxy fires a webhook to your server.
+6. Your server calls `NoxyGraphResumeHandler.resume_from_webhook()` → `Command(resume=...)`.
+7. The graph continues with the human decision (or timeout default) in state.
+
+## Requirements
+
+- Python **>= 3.10**
+- A LangGraph graph compiled **with a checkpointer** (required for `interrupt()`)
+- [noxy-sdk](https://pypi.org/project/noxy-sdk/) credentials (`NOXY_APP_TOKEN`, target identity)
+
+Target identity can be a **phone number**, **email**, **user id**, or **wallet address** (`0x…`).
+
+## Installation
+
+```bash
+pip install noxy-langgraph
+```
+
+For the FastAPI webhook example:
+
+```bash
+pip install "noxy-langgraph[examples]"
+```
+
+Local development against the monorepo SDK:
+
+```bash
+pip install -e ../../sdks/python-sdk
+pip install -e ".[dev,examples]"
+```
+
+## Quick start
+
+```python
+import uuid
+from typing import Optional, TypedDict
+
+from langgraph.checkpoint.memory import InMemorySaver
+from langgraph.constants import END, START
+from langgraph.graph import StateGraph
+from noxy import NoxyConfig, init_noxy_agent_client
+
+from noxy_langgraph import NoxyLangGraphBridge, build_tool_call_actionable
+
+
+class State(TypedDict, total=False):
+    task: str
+    noxy_decision: Optional[dict]
+    _noxy_sent_decision_id: Optional[str]
+
+
+def build_actionable(state: State) -> dict:
+    return build_tool_call_actionable(
+        tool="run_task",
+        args={"task": state["task"]},
+        title="Approve task?",
+        summary=state["task"],
+    )
+
+
+client = init_noxy_agent_client(
+    NoxyConfig(
+        endpoint="https://relay.noxy.network",
+        auth_token="your-app-token",
+        decision_ttl_seconds=3600,
+    )
+)
+# Phone, email, user id, or wallet address
+bridge = NoxyLangGraphBridge(client, "user@example.com")
+
+builder = StateGraph(State)
+builder.add_node("noxy_hitl", bridge.create_hitl_node(build_actionable))
+builder.add_edge(START, "noxy_hitl")
+builder.add_edge("noxy_hitl", END)
+
+graph = builder.compile(checkpointer=InMemorySaver())
+resume_handler = bridge.create_resume_handler(graph)
+
+config = {"configurable": {"thread_id": str(uuid.uuid4())}}
+paused = graph.invoke({"task": "Send 1 wei"}, config)
+# paused["__interrupt__"] contains the pending decision_id
+
+# Later, in your webhook handler:
+final = resume_handler.resume_from_webhook({
+    "decisionId": "<decisionId>",
+    "identityId": "user@example.com",
+    "outcome": "approved",  # or "rejected", "expired"
+})
+```
+
+## Graph state
+
+Include optional `_noxy_sent_decision_id` in your state schema. The resume handler sets it via `Command(update=...)` so the HITL node does not re-send the push when LangGraph re-executes the node after resume (LangGraph always re-runs the node body from the top).
+
+```python
+from noxy_langgraph import NOXY_SENT_DECISION_ID_KEY
+
+class State(TypedDict, total=False):
+    ...
+    _noxy_sent_decision_id: Optional[str]  # or use NOXY_SENT_DECISION_ID_KEY
+```
+
+## Webhook payload
+
+Noxy delivers JSON to your registered webhook URL:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `decisionId` | `str` | Decision to resume (snake_case `decision_id` also accepted) |
+| `identityId` | `str` | Identity that took the decision (phone, email, user id, or wallet) |
+| `outcome` | `str` | `approved`, `rejected`, `expired`, or `timeout` |
+| `receivedAt` | `str` | Optional ISO timestamp |
+
+On **timeout/expired**, pass an `on_timeout` callback to `create_hitl_node` to apply default behaviour:
+
+```python
+def on_timeout(state, resume):
+    return {"noxy_decision": resume.to_state(), "approved": False}
+
+bridge.create_hitl_node(build_actionable, on_timeout=on_timeout)
+```
+
+## API
+
+| Symbol | Description |
+|--------|-------------|
+| `NoxyLangGraphBridge` | Wires client, registry, HITL node factory, and resume handler |
+| `create_noxy_hitl_node(...)` | Low-level HITL node factory |
+| `NoxyGraphResumeHandler` | Resume paused graphs from webhook payloads |
+| `PendingInterruptRegistry` | Maps `decision_id` → `thread_id` for resume |
+| `build_tool_call_actionable(...)` | Standard `propose_tool_call` payload builder |
+| `parse_webhook_payload(...)` | Parse raw webhook JSON |
+
+## Examples
+
+- `examples/basic.py` — end-to-end demo with a mock Noxy client
+- `examples/webhook_server.py` — FastAPI server with `/runs` and `/webhooks/noxy`
+
+```bash
+python examples/basic.py
+```
+
+Configure the webhook server:
+
+```bash
+export NOXY_APP_TOKEN="your-app-token"
+export NOXY_IDENTITY_ID="user@example.com"   # or phone, user id, 0x…
+uvicorn examples.webhook_server:app --reload
+```
+
+## Development
+
+```bash
+make dev      # editable install with dev + examples extras
+make test     # run pytest
+make build    # build sdist + wheel
+make publish-check  # build and validate with twine
+```
+
+## Publishing
+
+1. Bump version in `pyproject.toml` and `noxy_langgraph/_version.py`.
+2. Update `CHANGELOG.md`.
+3. Merge to `main` — the GitHub Actions publish workflow uploads to PyPI when `PYPI_API_TOKEN` is configured.
+
+## License
+
+MIT

noxy_langgraph-1.0.0/README.md

@@ -0,0 +1,206 @@
+# Noxy LangGraph Connector
+
+[![PyPI version](https://img.shields.io/pypi/v/noxy-langgraph.svg)](https://pypi.org/project/noxy-langgraph/)
+[![Python versions](https://img.shields.io/pypi/pyversions/noxy-langgraph.svg)](https://pypi.org/project/noxy-langgraph/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+LangGraph connector for [Noxy](https://noxy.network) **human-in-the-loop** guardrails. Pauses agent graphs with `interrupt()`, delivers encrypted approval prompts to user devices, and resumes execution when Noxy fires a webhook.
+
+## Flow
+
+```mermaid
+sequenceDiagram
+    participant G as LangGraph
+    participant N as Noxy Relay
+    participant P as User Phone
+    participant S as Your Server
+
+    G->>N: send_decision (push payload)
+    N->>P: Push notification
+    G->>G: interrupt() — state saved to checkpointer
+    Note over G: Graph suspended
+
+    alt User responds
+        P->>N: Approve / Reject
+        N->>S: Webhook (outcome)
+        S->>G: Command(resume=decision)
+        G->>G: Continue with decision in state
+    else Timeout
+        N->>S: Webhook (timeout / expired)
+        S->>G: Command(resume=timeout)
+        G->>G: Continue with default behaviour
+    end
+```
+
+1. Graph reaches the HITL node.
+2. Noxy routes an encrypted actionable to the user's device (push).
+3. The node calls `interrupt()` — LangGraph suspends and persists state via a checkpointer.
+4. User responds on mobile **or** the decision TTL expires.
+5. Noxy fires a webhook to your server.
+6. Your server calls `NoxyGraphResumeHandler.resume_from_webhook()` → `Command(resume=...)`.
+7. The graph continues with the human decision (or timeout default) in state.
+
+## Requirements
+
+- Python **>= 3.10**
+- A LangGraph graph compiled **with a checkpointer** (required for `interrupt()`)
+- [noxy-sdk](https://pypi.org/project/noxy-sdk/) credentials (`NOXY_APP_TOKEN`, target identity)
+
+Target identity can be a **phone number**, **email**, **user id**, or **wallet address** (`0x…`).
+
+## Installation
+
+```bash
+pip install noxy-langgraph
+```
+
+For the FastAPI webhook example:
+
+```bash
+pip install "noxy-langgraph[examples]"
+```
+
+Local development against the monorepo SDK:
+
+```bash
+pip install -e ../../sdks/python-sdk
+pip install -e ".[dev,examples]"
+```
+
+## Quick start
+
+```python
+import uuid
+from typing import Optional, TypedDict
+
+from langgraph.checkpoint.memory import InMemorySaver
+from langgraph.constants import END, START
+from langgraph.graph import StateGraph
+from noxy import NoxyConfig, init_noxy_agent_client
+
+from noxy_langgraph import NoxyLangGraphBridge, build_tool_call_actionable
+
+
+class State(TypedDict, total=False):
+    task: str
+    noxy_decision: Optional[dict]
+    _noxy_sent_decision_id: Optional[str]
+
+
+def build_actionable(state: State) -> dict:
+    return build_tool_call_actionable(
+        tool="run_task",
+        args={"task": state["task"]},
+        title="Approve task?",
+        summary=state["task"],
+    )
+
+
+client = init_noxy_agent_client(
+    NoxyConfig(
+        endpoint="https://relay.noxy.network",
+        auth_token="your-app-token",
+        decision_ttl_seconds=3600,
+    )
+)
+# Phone, email, user id, or wallet address
+bridge = NoxyLangGraphBridge(client, "user@example.com")
+
+builder = StateGraph(State)
+builder.add_node("noxy_hitl", bridge.create_hitl_node(build_actionable))
+builder.add_edge(START, "noxy_hitl")
+builder.add_edge("noxy_hitl", END)
+
+graph = builder.compile(checkpointer=InMemorySaver())
+resume_handler = bridge.create_resume_handler(graph)
+
+config = {"configurable": {"thread_id": str(uuid.uuid4())}}
+paused = graph.invoke({"task": "Send 1 wei"}, config)
+# paused["__interrupt__"] contains the pending decision_id
+
+# Later, in your webhook handler:
+final = resume_handler.resume_from_webhook({
+    "decisionId": "<decisionId>",
+    "identityId": "user@example.com",
+    "outcome": "approved",  # or "rejected", "expired"
+})
+```
+
+## Graph state
+
+Include optional `_noxy_sent_decision_id` in your state schema. The resume handler sets it via `Command(update=...)` so the HITL node does not re-send the push when LangGraph re-executes the node after resume (LangGraph always re-runs the node body from the top).
+
+```python
+from noxy_langgraph import NOXY_SENT_DECISION_ID_KEY
+
+class State(TypedDict, total=False):
+    ...
+    _noxy_sent_decision_id: Optional[str]  # or use NOXY_SENT_DECISION_ID_KEY
+```
+
+## Webhook payload
+
+Noxy delivers JSON to your registered webhook URL:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `decisionId` | `str` | Decision to resume (snake_case `decision_id` also accepted) |
+| `identityId` | `str` | Identity that took the decision (phone, email, user id, or wallet) |
+| `outcome` | `str` | `approved`, `rejected`, `expired`, or `timeout` |
+| `receivedAt` | `str` | Optional ISO timestamp |
+
+On **timeout/expired**, pass an `on_timeout` callback to `create_hitl_node` to apply default behaviour:
+
+```python
+def on_timeout(state, resume):
+    return {"noxy_decision": resume.to_state(), "approved": False}
+
+bridge.create_hitl_node(build_actionable, on_timeout=on_timeout)
+```
+
+## API
+
+| Symbol | Description |
+|--------|-------------|
+| `NoxyLangGraphBridge` | Wires client, registry, HITL node factory, and resume handler |
+| `create_noxy_hitl_node(...)` | Low-level HITL node factory |
+| `NoxyGraphResumeHandler` | Resume paused graphs from webhook payloads |
+| `PendingInterruptRegistry` | Maps `decision_id` → `thread_id` for resume |
+| `build_tool_call_actionable(...)` | Standard `propose_tool_call` payload builder |
+| `parse_webhook_payload(...)` | Parse raw webhook JSON |
+
+## Examples
+
+- `examples/basic.py` — end-to-end demo with a mock Noxy client
+- `examples/webhook_server.py` — FastAPI server with `/runs` and `/webhooks/noxy`
+
+```bash
+python examples/basic.py
+```
+
+Configure the webhook server:
+
+```bash
+export NOXY_APP_TOKEN="your-app-token"
+export NOXY_IDENTITY_ID="user@example.com"   # or phone, user id, 0x…
+uvicorn examples.webhook_server:app --reload
+```
+
+## Development
+
+```bash
+make dev      # editable install with dev + examples extras
+make test     # run pytest
+make build    # build sdist + wheel
+make publish-check  # build and validate with twine
+```
+
+## Publishing
+
+1. Bump version in `pyproject.toml` and `noxy_langgraph/_version.py`.
+2. Update `CHANGELOG.md`.
+3. Merge to `main` — the GitHub Actions publish workflow uploads to PyPI when `PYPI_API_TOKEN` is configured.
+
+## License
+
+MIT

noxy_langgraph-1.0.0/noxy_langgraph/__init__.py

@@ -0,0 +1,32 @@
+"""Noxy LangGraph connector — webhook-driven human-in-the-loop via interrupt/resume."""
+
+from noxy_langgraph._version import __version__
+from noxy_langgraph.actionable import build_tool_call_actionable
+from noxy_langgraph.bridge import NoxyLangGraphBridge
+from noxy_langgraph.errors import (
+    NoxyLangGraphError,
+    SendDecisionFailedError,
+    UnknownDecisionError,
+)
+from noxy_langgraph.hitl import create_noxy_hitl_node
+from noxy_langgraph.registry import PendingInterrupt, PendingInterruptRegistry
+from noxy_langgraph.resume import NoxyGraphResumeHandler, parse_webhook_payload
+from noxy_langgraph.types import NoxyDecisionOutcome, NoxyDecisionResume, NoxyWebhookEvent, NOXY_SENT_DECISION_ID_KEY
+
+__all__ = [
+    "__version__",
+    "NoxyLangGraphBridge",
+    "NoxyLangGraphError",
+    "NoxyGraphResumeHandler",
+    "NoxyDecisionOutcome",
+    "NoxyDecisionResume",
+    "NoxyWebhookEvent",
+    "NOXY_SENT_DECISION_ID_KEY",
+    "PendingInterrupt",
+    "PendingInterruptRegistry",
+    "SendDecisionFailedError",
+    "UnknownDecisionError",
+    "build_tool_call_actionable",
+    "create_noxy_hitl_node",
+    "parse_webhook_payload",
+]

noxy_langgraph-1.0.0/noxy_langgraph/_version.py

@@ -0,0 +1,3 @@
+"""Package version."""
+
+__version__ = "1.0.0"

noxy_langgraph-1.0.0/noxy_langgraph/actionable.py

@@ -0,0 +1,27 @@
+"""Build Noxy actionable payloads from LangGraph state."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def build_tool_call_actionable(
+    *,
+    tool: str,
+    args: dict[str, Any],
+    title: str,
+    summary: str,
+    kind: str = "propose_tool_call",
+    extra: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    """Build a standard ``propose_tool_call`` actionable for ``send_decision``."""
+    payload: dict[str, Any] = {
+        "kind": kind,
+        "tool": tool,
+        "args": args,
+        "title": title,
+        "summary": summary,
+    }
+    if extra:
+        payload.update(extra)
+    return payload

noxy_langgraph-1.0.0/noxy_langgraph/bridge.py

@@ -0,0 +1,47 @@
+"""Convenience wrapper wiring Noxy client, registry, HITL node, and resume handler."""
+
+from __future__ import annotations
+
+from typing import Any, Callable
+
+from langgraph.graph.state import CompiledStateGraph
+from noxy.client import NoxyAgentClient
+
+from noxy_langgraph.hitl import create_noxy_hitl_node
+from noxy_langgraph.registry import PendingInterruptRegistry
+from noxy_langgraph.resume import NoxyGraphResumeHandler
+from noxy_langgraph.types import NoxyDecisionResume
+
+
+class NoxyLangGraphBridge:
+    """Shared registry and helpers for a Noxy-backed LangGraph application."""
+
+    def __init__(
+        self,
+        client: NoxyAgentClient,
+        identity_id: str,
+        *,
+        registry: PendingInterruptRegistry | None = None,
+    ) -> None:
+        self.client = client
+        self.identity_id = identity_id
+        self.registry = registry or PendingInterruptRegistry()
+
+    def create_hitl_node(
+        self,
+        build_actionable: Callable[[Any], dict[str, Any]],
+        *,
+        state_key: str = "noxy_decision",
+        on_timeout: Callable[[Any, NoxyDecisionResume], dict[str, Any]] | None = None,
+    ):
+        return create_noxy_hitl_node(
+            self.client,
+            self.identity_id,
+            self.registry,
+            build_actionable,
+            state_key=state_key,
+            on_timeout=on_timeout,
+        )
+
+    def create_resume_handler(self, graph: CompiledStateGraph) -> NoxyGraphResumeHandler:
+        return NoxyGraphResumeHandler(graph, self.registry)

noxy_langgraph-1.0.0/noxy_langgraph/errors.py

@@ -0,0 +1,22 @@
+"""Connector-specific errors."""
+
+from __future__ import annotations
+
+
+class NoxyLangGraphError(Exception):
+    """Base error for the Noxy LangGraph connector."""
+
+
+class UnknownDecisionError(NoxyLangGraphError):
+    """Raised when a webhook references a decision that is not registered."""
+
+    def __init__(self, decision_id: str) -> None:
+        super().__init__(f"no pending LangGraph interrupt for decision_id={decision_id!r}")
+        self.decision_id = decision_id
+
+
+class SendDecisionFailedError(NoxyLangGraphError):
+    """Raised when Noxy does not return a decision_id after routing."""
+
+    def __init__(self, message: str = "send_decision returned no decision_id") -> None:
+        super().__init__(message)

noxy_langgraph-1.0.0/noxy_langgraph/hitl.py

@@ -0,0 +1,83 @@
+"""LangGraph HITL node that routes to Noxy then suspends via interrupt()."""
+
+from __future__ import annotations
+
+from typing import Any, Callable
+
+from langgraph.config import get_config
+from langgraph.types import interrupt
+from noxy.client import NoxyAgentClient
+from noxy.types import NoxyDeliveryOutcome
+
+from noxy_langgraph.errors import SendDecisionFailedError
+from noxy_langgraph.registry import PendingInterrupt, PendingInterruptRegistry
+from noxy_langgraph.types import NOXY_SENT_DECISION_ID_KEY, NoxyDecisionResume
+
+
+def _first_decision_id(deliveries: list[NoxyDeliveryOutcome]) -> str:
+    for delivery in deliveries:
+        if delivery.decision_id:
+            return delivery.decision_id
+    raise SendDecisionFailedError()
+
+
+def create_noxy_hitl_node(
+    client: NoxyAgentClient,
+    identity_id: str,
+    registry: PendingInterruptRegistry,
+    build_actionable: Callable[[Any], dict[str, Any]],
+    *,
+    state_key: str = "noxy_decision",
+    on_timeout: Callable[[Any, NoxyDecisionResume], dict[str, Any]] | None = None,
+) -> Callable[[Any], dict[str, Any]]:
+    """Create a LangGraph node that pushes to Noxy, then suspends until webhook resume.
+
+    Flow:
+      1. Build actionable payload from graph state.
+      2. ``send_decision`` — Noxy delivers push notification to the user's device.
+      3. Register ``decision_id -> thread_id`` for webhook correlation.
+      4. ``interrupt()`` — graph suspends; checkpointer persists state.
+      5. On webhook resume, node re-executes and returns the human decision in state.
+    """
+
+    def noxy_hitl_node(state: Any) -> dict[str, Any]:
+        config = get_config()
+        thread_id = config["configurable"]["thread_id"]
+
+        actionable = build_actionable(state)
+        existing_decision_id = (
+            state.get(NOXY_SENT_DECISION_ID_KEY) if isinstance(state, dict) else None
+        )
+
+        if existing_decision_id:
+            decision_id = str(existing_decision_id)
+        else:
+            deliveries = client.send_decision(identity_id, actionable)
+            decision_id = _first_decision_id(deliveries)
+            registry.register(
+                PendingInterrupt(
+                    decision_id=decision_id,
+                    thread_id=str(thread_id),
+                    identity_id=identity_id,
+                )
+            )
+
+        resume_raw = interrupt(
+            {
+                "kind": "noxy_awaiting_decision",
+                "decision_id": decision_id,
+                "identity_id": identity_id,
+                "actionable": actionable,
+            }
+        )
+
+        resume = NoxyDecisionResume.from_resume_value(resume_raw)
+        if resume.is_timeout and on_timeout is not None:
+            return on_timeout(state, resume)
+
+        return {
+            state_key: resume.to_state(),
+            NOXY_SENT_DECISION_ID_KEY: decision_id,
+        }
+
+    return noxy_hitl_node