letsping 0.1.0__tar.gz

letsping-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cordia Labs
+
+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.

letsping-0.1.0/MANIFEST.in

@@ -0,0 +1,4 @@
+include README.md
+include LICENSE
+include py.typed
+global-exclude *.py[cod]

letsping-0.1.0/PKG-INFO

@@ -0,0 +1,133 @@
+Metadata-Version: 2.4
+Name: letsping
+Version: 0.1.0
+Summary: The Control Plane for Autonomous Agents. Add Human-in-the-Loop approval with one line of code.
+Author-email: Cordia Labs <security@letsping.co>
+License: MIT
+Project-URL: Homepage, https://letsping.co
+Project-URL: Documentation, https://letsping.co/docs
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.23.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Requires-Dist: respx>=0.20.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: mypy>=1.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Dynamic: license-file
+
+# LetsPing Python SDK
+
+The official state management infrastructure for Human-in-the-Loop (HITL) AI agents.
+
+LetsPing provides a durable "pause button" for autonomous agents, decoupling the agent's execution logic from the human's response time. It handles state serialization, secure polling, and notification routing (Slack, Email) automatically.
+
+## Installation
+
+```bash
+pip install letsping
+
+```
+
+## Configuration
+
+Set your API key as an environment variable (recommended) or pass it directly.
+
+```bash
+export LETSPING_API_KEY="lp_live_..."
+
+```
+
+## Usage
+
+### 1. The "Ask" Primitive (Blocking)
+
+Use this when you want to pause a script until a human approves.
+
+```python
+from letsping import LetsPing
+
+client = LetsPing()
+
+# Pauses here for up to 24 hours (default)
+decision = client.ask(
+    service="payments-agent",
+    action="transfer_funds",
+    payload={
+        "amount": 5000,
+        "currency": "USD",
+        "recipient": "acct_99"
+    },
+    priority="critical"
+)
+
+# Execution resumes only after approval
+print(f"Transfer approved by {decision['metadata']['actor_id']}")
+
+```
+
+### 2. Async / Non-Blocking (FastAPI/LangGraph)
+
+For high-concurrency environments or event loops.
+
+```python
+import asyncio
+from letsping import LetsPing
+
+async def main():
+    client = LetsPing()
+    
+    # Non-blocking wait
+    decision = await client.aask(
+        service="github-agent",
+        action="merge_pr",
+        payload={"pr_id": 42},
+        timeout=3600 # 1 hour timeout
+    )
+
+asyncio.run(main())
+
+```
+
+### 3. LangChain / Agent Integration
+
+LetsPing provides a compliant tool interface that can be injected directly into LLM agent toolkits (LangChain, CrewAI, etc). This allows the LLM to *decide* when to ask for help.
+
+```python
+from letsping import LetsPing
+
+client = LetsPing()
+
+tools = [
+    # ... your other tools (search, calculator) ...
+    
+    # Inject the human as a tool
+    client.tool(
+        service="research-agent",
+        action="review_draft",
+        priority="high"
+    )
+]
+
+```
+
+## Error Handling
+
+The SDK uses typed exceptions for control flow.
+
+* `ApprovalRejectedError`: Raised when the human explicitly clicks "Reject".
+* `TimeoutError`: Raised when the duration (default 24h) expires without a decision.
+* `LetsPingError`: Base class for API or network failures.
+
+## License
+
+MIT

letsping-0.1.0/README.md

@@ -0,0 +1,106 @@
+# LetsPing Python SDK
+
+The official state management infrastructure for Human-in-the-Loop (HITL) AI agents.
+
+LetsPing provides a durable "pause button" for autonomous agents, decoupling the agent's execution logic from the human's response time. It handles state serialization, secure polling, and notification routing (Slack, Email) automatically.
+
+## Installation
+
+```bash
+pip install letsping
+
+```
+
+## Configuration
+
+Set your API key as an environment variable (recommended) or pass it directly.
+
+```bash
+export LETSPING_API_KEY="lp_live_..."
+
+```
+
+## Usage
+
+### 1. The "Ask" Primitive (Blocking)
+
+Use this when you want to pause a script until a human approves.
+
+```python
+from letsping import LetsPing
+
+client = LetsPing()
+
+# Pauses here for up to 24 hours (default)
+decision = client.ask(
+    service="payments-agent",
+    action="transfer_funds",
+    payload={
+        "amount": 5000,
+        "currency": "USD",
+        "recipient": "acct_99"
+    },
+    priority="critical"
+)
+
+# Execution resumes only after approval
+print(f"Transfer approved by {decision['metadata']['actor_id']}")
+
+```
+
+### 2. Async / Non-Blocking (FastAPI/LangGraph)
+
+For high-concurrency environments or event loops.
+
+```python
+import asyncio
+from letsping import LetsPing
+
+async def main():
+    client = LetsPing()
+    
+    # Non-blocking wait
+    decision = await client.aask(
+        service="github-agent",
+        action="merge_pr",
+        payload={"pr_id": 42},
+        timeout=3600 # 1 hour timeout
+    )
+
+asyncio.run(main())
+
+```
+
+### 3. LangChain / Agent Integration
+
+LetsPing provides a compliant tool interface that can be injected directly into LLM agent toolkits (LangChain, CrewAI, etc). This allows the LLM to *decide* when to ask for help.
+
+```python
+from letsping import LetsPing
+
+client = LetsPing()
+
+tools = [
+    # ... your other tools (search, calculator) ...
+    
+    # Inject the human as a tool
+    client.tool(
+        service="research-agent",
+        action="review_draft",
+        priority="high"
+    )
+]
+
+```
+
+## Error Handling
+
+The SDK uses typed exceptions for control flow.
+
+* `ApprovalRejectedError`: Raised when the human explicitly clicks "Reject".
+* `TimeoutError`: Raised when the duration (default 24h) expires without a decision.
+* `LetsPingError`: Base class for API or network failures.
+
+## License
+
+MIT

letsping-0.1.0/letsping.egg-info/PKG-INFO

@@ -0,0 +1,133 @@
+Metadata-Version: 2.4
+Name: letsping
+Version: 0.1.0
+Summary: The Control Plane for Autonomous Agents. Add Human-in-the-Loop approval with one line of code.
+Author-email: Cordia Labs <security@letsping.co>
+License: MIT
+Project-URL: Homepage, https://letsping.co
+Project-URL: Documentation, https://letsping.co/docs
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.23.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Requires-Dist: respx>=0.20.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: mypy>=1.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Dynamic: license-file
+
+# LetsPing Python SDK
+
+The official state management infrastructure for Human-in-the-Loop (HITL) AI agents.
+
+LetsPing provides a durable "pause button" for autonomous agents, decoupling the agent's execution logic from the human's response time. It handles state serialization, secure polling, and notification routing (Slack, Email) automatically.
+
+## Installation
+
+```bash
+pip install letsping
+
+```
+
+## Configuration
+
+Set your API key as an environment variable (recommended) or pass it directly.
+
+```bash
+export LETSPING_API_KEY="lp_live_..."
+
+```
+
+## Usage
+
+### 1. The "Ask" Primitive (Blocking)
+
+Use this when you want to pause a script until a human approves.
+
+```python
+from letsping import LetsPing
+
+client = LetsPing()
+
+# Pauses here for up to 24 hours (default)
+decision = client.ask(
+    service="payments-agent",
+    action="transfer_funds",
+    payload={
+        "amount": 5000,
+        "currency": "USD",
+        "recipient": "acct_99"
+    },
+    priority="critical"
+)
+
+# Execution resumes only after approval
+print(f"Transfer approved by {decision['metadata']['actor_id']}")
+
+```
+
+### 2. Async / Non-Blocking (FastAPI/LangGraph)
+
+For high-concurrency environments or event loops.
+
+```python
+import asyncio
+from letsping import LetsPing
+
+async def main():
+    client = LetsPing()
+    
+    # Non-blocking wait
+    decision = await client.aask(
+        service="github-agent",
+        action="merge_pr",
+        payload={"pr_id": 42},
+        timeout=3600 # 1 hour timeout
+    )
+
+asyncio.run(main())
+
+```
+
+### 3. LangChain / Agent Integration
+
+LetsPing provides a compliant tool interface that can be injected directly into LLM agent toolkits (LangChain, CrewAI, etc). This allows the LLM to *decide* when to ask for help.
+
+```python
+from letsping import LetsPing
+
+client = LetsPing()
+
+tools = [
+    # ... your other tools (search, calculator) ...
+    
+    # Inject the human as a tool
+    client.tool(
+        service="research-agent",
+        action="review_draft",
+        priority="high"
+    )
+]
+
+```
+
+## Error Handling
+
+The SDK uses typed exceptions for control flow.
+
+* `ApprovalRejectedError`: Raised when the human explicitly clicks "Reject".
+* `TimeoutError`: Raised when the duration (default 24h) expires without a decision.
+* `LetsPingError`: Base class for API or network failures.
+
+## License
+
+MIT

letsping-0.1.0/letsping.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+LICENSE
+MANIFEST.in
+README.md
+letsping.py
+py.typed
+pyproject.toml
+letsping.egg-info/PKG-INFO
+letsping.egg-info/SOURCES.txt
+letsping.egg-info/dependency_links.txt
+letsping.egg-info/requires.txt
+letsping.egg-info/top_level.txt
+tests/test_core.py

letsping-0.1.0/letsping.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

letsping-0.1.0/letsping.egg-info/requires.txt

@@ -0,0 +1,9 @@
+httpx>=0.23.0
+
+[dev]
+pytest>=7.0
+pytest-asyncio>=0.21.0
+respx>=0.20.0
+pytest-cov>=4.0
+mypy>=1.0
+ruff>=0.1.0

letsping-0.1.0/letsping.egg-info/top_level.txt

@@ -0,0 +1 @@
+letsping

letsping-0.1.0/letsping.py

@@ -0,0 +1,217 @@
+import os
+import time
+import json
+import logging
+import asyncio
+from typing import Optional, Dict, Any, Literal, TypedDict, Callable
+
+import httpx
+
+logger = logging.getLogger("letsping")
+
+DEFAULT_BASE_URL = "https://letsping.co/api"
+VERSION = "0.1.0"
+
+Priority = Literal["low", "medium", "high", "critical"]
+Status = Literal["APPROVED", "REJECTED", "PENDING"]
+
+class Decision(TypedDict):
+    status: Status
+    payload: Dict[str, Any]
+    patched_payload: Optional[Dict[str, Any]]
+    metadata: Dict[str, Any]
+
+class LetsPingError(Exception):
+    """Base class for all LetsPing SDK errors."""
+    pass
+
+class AuthenticationError(LetsPingError):
+    pass
+
+class ApprovalRejectedError(LetsPingError):
+    def __init__(self, reason: str):
+        super().__init__(f"Request rejected: {reason}")
+        self.reason = reason
+
+class TimeoutError(LetsPingError):
+    pass
+
+class LetsPing:
+    """
+    The official state management client for Human-in-the-Loop AI agents.
+    Thread-safe and async-native.
+    """
+
+    def __init__(
+        self, 
+        api_key: Optional[str] = None, 
+        base_url: Optional[str] = None,
+        timeout: float = 30.0
+    ):
+        self._api_key = api_key or os.getenv("LETSPING_API_KEY")
+        if not self._api_key:
+            raise ValueError("LetsPing API Key must be provided via arg or LETSPING_API_KEY env var.")
+        
+        self._base_url = (base_url or os.getenv("LETSPING_BASE_URL", DEFAULT_BASE_URL)).rstrip('/')
+        self._timeout = timeout
+        self._headers = {
+            "Authorization": f"Bearer {self._api_key}",
+            "Content-Type": "application/json",
+            "User-Agent": f"letsping-python/{VERSION}",
+            "Accept": "application/json"
+        }
+
+    def ask(
+        self, 
+        service: str, 
+        action: str, 
+        payload: Dict[str, Any], 
+        priority: Priority = "medium", 
+        timeout: int = 86400
+    ) -> Decision:
+        """Blocking call: Pauses execution until a human decision is rendered."""
+        request_id = self.defer(service, action, payload, priority)
+        return self.wait(request_id, timeout=timeout)
+
+    def defer(
+        self, 
+        service: str, 
+        action: str, 
+        payload: Dict[str, Any], 
+        priority: Priority = "medium",
+        callback_url: Optional[str] = None
+    ) -> str:
+        """Non-blocking: Registers the request and returns the Request ID immediately."""
+        body = {
+            "service": service,
+            "action": action,
+            "payload": payload,
+            "priority": priority,
+            "metadata": {"sdk": "python", "callback_url": callback_url} if callback_url else {"sdk": "python"}
+        }
+        
+        with httpx.Client(base_url=self._base_url, headers=self._headers, timeout=self._timeout) as client:
+            resp = self._handle_response(client.post("/ingest", json=body))
+            return resp["id"]
+
+    def wait(self, request_id: str, timeout: int = 86400) -> Decision:
+        """Resumes waiting for an existing request ID."""
+        start_time = time.time()
+        attempt = 0
+        
+        with httpx.Client(base_url=self._base_url, headers=self._headers, timeout=self._timeout) as client:
+            while time.time() - start_time < timeout:
+                attempt += 1
+                try:
+                    resp = client.get(f"/status/{request_id}")
+                    if resp.status_code == 200:
+                        decision = resp.json()
+                        if decision["status"] in ("APPROVED", "REJECTED"):
+                            return self._parse_decision(decision)
+                    elif resp.status_code not in (404, 429):
+                        self._handle_response(resp)
+                except (httpx.RequestError, json.JSONDecodeError) as e:
+                    logger.warning(f"LetsPing polling transient error: {e}")
+
+                sleep_time = min(1.0 * (1.5 ** attempt), 10.0)
+                time.sleep(sleep_time)
+
+        raise TimeoutError(f"Wait timed out after {timeout}s for request {request_id}")
+
+    async def aask(
+        self, 
+        service: str, 
+        action: str, 
+        payload: Dict[str, Any], 
+        priority: Priority = "medium", 
+        timeout: int = 86400
+    ) -> Decision:
+        """Async non-blocking wait. Compatible with asyncio event loops."""
+        request_id = await self.adefer(service, action, payload, priority)
+        return await self.await_(request_id, timeout=timeout)
+
+    async def adefer(
+        self, 
+        service: str, 
+        action: str, 
+        payload: Dict[str, Any], 
+        priority: Priority = "medium"
+    ) -> str:
+        body = {
+            "service": service,
+            "action": action,
+            "payload": payload,
+            "priority": priority,
+            "metadata": {"sdk": "python"}
+        }
+        async with httpx.AsyncClient(base_url=self._base_url, headers=self._headers, timeout=self._timeout) as client:
+            resp = await client.post("/ingest", json=body)
+            data = self._handle_response(resp)
+            return data["id"]
+
+    async def await_(self, request_id: str, timeout: int = 86400) -> Decision:
+        start_time = time.time()
+        attempt = 0
+        
+        async with httpx.AsyncClient(base_url=self._base_url, headers=self._headers, timeout=self._timeout) as client:
+            while time.time() - start_time < timeout:
+                attempt += 1
+                try:
+                    resp = await client.get(f"/status/{request_id}")
+                    if resp.status_code == 200:
+                        decision = resp.json()
+                        if decision["status"] in ("APPROVED", "REJECTED"):
+                            return self._parse_decision(decision)
+                except (httpx.RequestError, json.JSONDecodeError):
+                    pass 
+
+                sleep_time = min(1.0 * (1.5 ** attempt), 10.0)
+                await asyncio.sleep(sleep_time)
+
+        raise TimeoutError(f"Async wait timed out after {timeout}s for request {request_id}")
+
+    def tool(self, service: str, action: str, priority: Priority = "medium") -> Callable:
+        """Returns a callable 'Tool' compatible with LangChain/CrewAI."""
+        def human_approval_tool(context: str) -> str:
+            try:
+                payload = json.loads(context)
+            except json.JSONDecodeError:
+                payload = {"raw_context": context}
+            
+            try:
+                result = self.ask(service, action, payload, priority)
+                return json.dumps(result["approved_payload"])
+            except ApprovalRejectedError as e:
+                return f"ACTION_REJECTED: {e.reason}"
+            except Exception as e:
+                return f"ERROR: {str(e)}"
+                
+        return human_approval_tool
+
+    def _handle_response(self, response: httpx.Response) -> Dict[str, Any]:
+        if response.status_code == 401 or response.status_code == 403:
+            raise AuthenticationError("Invalid API Key or unauthorized access.")
+        
+        try:
+            response.raise_for_status()
+            return response.json()
+        except httpx.HTTPStatusError as e:
+            error_msg = response.text
+            try:
+                error_data = response.json()
+                error_msg = error_data.get("message", response.text)
+            except:
+                pass
+            raise LetsPingError(f"API Error {response.status_code}: {error_msg}") from e
+
+    def _parse_decision(self, data: Dict[str, Any]) -> Decision:
+        status = data.get("status")
+        if status == "REJECTED":
+            raise ApprovalRejectedError(data.get("reason", "No reason provided"))
+        
+        return {
+            "status": "APPROVED",
+            "payload": data.get("payload", {}),
+            "patched_payload": data.get("patched_payload"),
+            "metadata": data.get("metadata", {})
+        }

letsping-0.1.0/pyproject.toml

@@ -0,0 +1,43 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "letsping"
+version = "0.1.0"
+description = "The Control Plane for Autonomous Agents. Add Human-in-the-Loop approval with one line of code."
+readme = "README.md"
+authors = [{ name = "Cordia Labs", email = "security@letsping.co" }]
+license = { text = "MIT" }
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+requires-python = ">=3.8"
+dependencies = [
+    "httpx>=0.23.0"
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "pytest-asyncio>=0.21.0",
+    "respx>=0.20.0",
+    "pytest-cov>=4.0",
+    "mypy>=1.0",
+    "ruff>=0.1.0"
+]
+
+[project.urls]
+"Homepage" = "https://letsping.co"
+"Documentation" = "https://letsping.co/docs"
+
+[tool.setuptools]
+py-modules = ["letsping"]
+
+[tool.setuptools.package-data]
+"*" = ["py.typed"]

letsping-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

letsping-0.1.0/tests/test_core.py

@@ -0,0 +1,66 @@
+import pytest
+import respx
+from httpx import Response
+from letsping import LetsPing, ApprovalRejectedError, DEFAULT_BASE_URL
+
+MOCK_API_KEY = "lp_test_mock_key"
+
+@pytest.fixture
+def client():
+    return LetsPing(api_key=MOCK_API_KEY)
+
+@respx.mock
+def test_ask_approval_flow(client):
+    """Verifies the standard approval lifecycle (Ingest -> Pending -> Approved)."""
+    ingest_route = respx.post(f"{DEFAULT_BASE_URL}/ingest")
+    ingest_route.mock(return_value=Response(200, json={"id": "req_123"}))
+    
+    status_route = respx.get(f"{DEFAULT_BASE_URL}/status/req_123")
+    status_route.side_effect = [
+        Response(200, json={"status": "PENDING"}),
+        Response(200, json={
+            "status": "APPROVED",
+            "payload": {"amount": 100},
+            "patched_payload": {"amount": 100},
+            "metadata": {"actor_id": "user_1", "resolved_at": "2024-01-01"}
+        })
+    ]
+
+    result = client.ask("test-service", "test-action", {"amount": 100}, timeout=2)
+
+    assert result["status"] == "APPROVED"
+    assert result["metadata"]["actor_id"] == "user_1"
+    assert ingest_route.called
+    assert status_route.call_count == 2
+
+@respx.mock
+def test_rejection_error(client):
+    """Verifies that human rejection raises the specific exception."""
+    respx.post(f"{DEFAULT_BASE_URL}/ingest").mock(return_value=Response(200, json={"id": "req_999"}))
+    
+    respx.get(f"{DEFAULT_BASE_URL}/status/req_999").mock(return_value=Response(200, json={
+        "status": "REJECTED",
+        "reason": "Risk score too high",
+        "metadata": {}
+    }))
+
+    with pytest.raises(ApprovalRejectedError) as exc:
+        client.ask("test", "test", {}, timeout=2)
+    
+    assert "Risk score too high" in str(exc.value)
+
+@respx.mock
+@pytest.mark.asyncio
+async def test_async_flow():
+    """Verifies the async/await implementation works correctly."""
+    client = LetsPing(api_key=MOCK_API_KEY)
+    
+    respx.post(f"{DEFAULT_BASE_URL}/ingest").mock(return_value=Response(200, json={"id": "req_async"}))
+    respx.get(f"{DEFAULT_BASE_URL}/status/req_async").mock(return_value=Response(200, json={
+        "status": "APPROVED", 
+        "payload": {},
+        "metadata": {}
+    }))
+
+    result = await client.aask("async-service", "run", {})
+    assert result["status"] == "APPROVED"