cheqpoint 0.1.0__py3-none-any.whl

cheqpoint/__init__.py

@@ -0,0 +1,25 @@
+from .client import (
+    CheqpointClient,
+    CheqpointError,
+    RejectedError,
+    TimeoutError,
+    CheckpointResult,
+    RequestStatus,
+)
+
+__all__ = [
+    "CheqpointClient",
+    "CheqpointError",
+    "RejectedError",
+    "TimeoutError",
+    "CheckpointResult",
+    "RequestStatus",
+]
+
+__version__ = "0.1.0"
+
+# Framework-specific tools are importable directly but not auto-imported
+# to avoid requiring optional dependencies at package load time.
+# Usage:
+#   from cheqpoint.langchain_tool import CheqpointApprovalTool
+#   from cheqpoint.crewai_tool import CheqpointApprovalTool

cheqpoint/client.py

@@ -0,0 +1,437 @@
+"""Cheqpoint Python SDK — human-in-the-loop approval queues for AI agents."""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass
+from typing import Any, Optional
+
+import requests as _requests
+
+__version__ = "0.1.0"
+
+DEFAULT_BASE_URL = "https://app.cheqpoint.io"
+DEFAULT_POLL_INTERVAL = 3  # seconds
+DEFAULT_TIMEOUT = 300  # seconds (5 minutes)
+
+
+# ---------------------------------------------------------------------------
+# Result types
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class CheckpointResult:
+    id: str
+    status: str  # "APPROVED" | "REJECTED"
+    details: dict[str, Any]
+    modified_details: Optional[dict[str, Any]]
+    response_notes: Optional[str]
+
+    @property
+    def effective_details(self) -> dict[str, Any]:
+        """Return modified_details if set, otherwise the original details."""
+        return self.modified_details if self.modified_details is not None else self.details
+
+
+@dataclass
+class RequestStatus:
+    id: str
+    status: str  # "PENDING" | "APPROVED" | "REJECTED"
+    details: dict[str, Any]
+    modified_details: Optional[dict[str, Any]]
+    response_notes: Optional[str]
+    decision_reason_code: Optional[str]
+    decision_note: Optional[str]
+    auto_decided: bool
+    auto_decision_rule_name: Optional[str]
+    decided_at: Optional[str]
+
+
+# ---------------------------------------------------------------------------
+# Errors
+# ---------------------------------------------------------------------------
+
+
+class CheqpointError(Exception):
+    """Raised when the Cheqpoint API returns an error response."""
+
+    def __init__(self, message: str, status_code: int, response_body: Any = None) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.response_body = response_body
+
+
+class RejectedError(Exception):
+    """Raised when a checkpoint request is rejected by a reviewer."""
+
+    def __init__(self, request_id: str, response_notes: Optional[str]) -> None:
+        note = f": {response_notes}" if response_notes else ""
+        super().__init__(f"Cheqpoint request {request_id} was rejected{note}")
+        self.request_id = request_id
+        self.response_notes = response_notes
+
+
+class TimeoutError(Exception):
+    """Raised when polling exceeds the configured timeout."""
+
+    def __init__(self, request_id: str, timeout: float) -> None:
+        super().__init__(
+            f"Cheqpoint request {request_id} timed out after {timeout}s waiting for a decision"
+        )
+        self.request_id = request_id
+        self.timeout = timeout
+
+
+# ---------------------------------------------------------------------------
+# Client
+# ---------------------------------------------------------------------------
+
+
+class CheqpointClient:
+    """Client for the Cheqpoint human-in-the-loop approval API."""
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+    ) -> None:
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.default_timeout = timeout
+        self._session = _requests.Session()
+        self._session.headers.update(
+            {
+                "Content-Type": "application/json",
+                "User-Agent": f"cheqpoint-python/{__version__}",
+            }
+        )
+
+    # ------------------------------------------------------------------
+    # Public methods
+    # ------------------------------------------------------------------
+
+    def checkpoint(
+        self,
+        *,
+        action: str,
+        risk_score: Optional[float] = None,
+        summary: str,
+        details: dict[str, Any],
+        justification: Optional[str] = None,
+        webhook_url: Optional[str] = None,
+        trace: Optional[dict[str, Any]] = None,
+        poll_interval: float = DEFAULT_POLL_INTERVAL,
+        timeout: Optional[float] = None,
+    ) -> CheckpointResult:
+        """Submit an action for review and block until a human decides.
+
+        Args:
+            action: Action type (e.g. "send_email", "process_refund", "deploy_code").
+            risk_score: Optional float 0.0–1.0. Default: 0.5 (medium).
+            summary: One-sentence description shown to reviewers.
+            details: Structured payload for the action.
+            justification: Optional agent reasoning shown to reviewers.
+            webhook_url: URL for Cheqpoint to POST the decision to.
+            poll_interval: Seconds between status polls. Default 3.
+            timeout: Max seconds to wait. Default is client-level default (300).
+
+        Returns:
+            CheckpointResult with status "APPROVED".
+
+        Raises:
+            RejectedError: If the request is rejected.
+            TimeoutError: If no decision within `timeout` seconds.
+            CheqpointError: On API errors.
+        """
+        effective_timeout = timeout if timeout is not None else self.default_timeout
+
+        result = self.create_request(
+            action=action,
+            risk_score=risk_score,
+            summary=summary,
+            details=details,
+            justification=justification,
+            webhook_url=webhook_url,
+            trace=trace,
+        )
+        request_id = result["id"]
+        deadline = time.monotonic() + effective_timeout
+
+        while time.monotonic() < deadline:
+            status = self.get_request(request_id)
+
+            if status.status == "APPROVED":
+                return CheckpointResult(
+                    id=status.id,
+                    status="APPROVED",
+                    details=status.details,
+                    modified_details=status.modified_details,
+                    response_notes=status.response_notes,
+                )
+
+            if status.status == "REJECTED":
+                raise RejectedError(request_id, status.response_notes)
+
+            remaining = deadline - time.monotonic()
+            if remaining <= 0:
+                break
+            time.sleep(min(poll_interval, remaining))
+
+        raise TimeoutError(request_id, effective_timeout)
+
+    def create_request(
+        self,
+        *,
+        action: str,
+        risk_score: Optional[float] = None,
+        summary: str,
+        details: dict[str, Any],
+        justification: Optional[str] = None,
+        webhook_url: Optional[str] = None,
+        trace: Optional[dict[str, Any]] = None,
+    ) -> dict[str, str]:
+        """Fire-and-forget: submit a request and return immediately with its ID.
+
+        Returns:
+            dict with "id" key containing the request ID.
+        """
+        body: dict[str, Any] = {
+            "apiKey": self.api_key,
+            "action": action,
+            "riskScore": risk_score,
+            "summary": summary,
+            "details": details,
+        }
+        if justification is not None:
+            body["justification"] = justification
+        if webhook_url is not None:
+            body["webhookUrl"] = webhook_url
+        if trace is not None:
+            body["trace"] = trace
+
+        data = self._post("/api/approvals/request", body)
+        return {"id": data["id"]}
+
+    def get_request(self, request_id: str) -> RequestStatus:
+        """Fetch the current status of a request by its ID."""
+        data = self._get(f"/api/approvals/{request_id}")
+        return RequestStatus(
+            id=data["id"],
+            status=data["status"],
+            details=data["details"],
+            modified_details=data.get("modifiedDetails"),
+            response_notes=data.get("responseNotes"),
+            decision_reason_code=data.get("decisionReasonCode"),
+            decision_note=data.get("decisionNote"),
+            auto_decided=data.get("autoDecided", False),
+            auto_decision_rule_name=data.get("autoDecisionRuleName"),
+            decided_at=data.get("decidedAt"),
+        )
+
+    # ------------------------------------------------------------------
+    # Instrumentation wrappers
+    # ------------------------------------------------------------------
+
+    def wrap_openai(self, openai_client: Any) -> tuple[Any, "TraceCollector"]:
+        """Wrap an OpenAI client to auto-capture traces.
+
+        Usage::
+
+            client, collector = cheq.wrap_openai(OpenAI(api_key=...))
+            response = client.chat.completions.create(model="gpt-4o", messages=[...])
+            cheq.checkpoint(..., trace=collector.get_trace())
+        """
+        return _wrap_openai(openai_client)
+
+    def wrap_anthropic(self, anthropic_client: Any) -> tuple[Any, "TraceCollector"]:
+        """Wrap an Anthropic client to auto-capture traces.
+
+        Usage::
+
+            client, collector = cheq.wrap_anthropic(Anthropic(api_key=...))
+            response = client.messages.create(model="claude-opus-4-6", messages=[...])
+            cheq.checkpoint(..., trace=collector.get_trace())
+        """
+        return _wrap_anthropic(anthropic_client)
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    def _post(self, path: str, body: dict[str, Any]) -> Any:
+        url = f"{self.base_url}{path}"
+        resp = self._session.post(url, json=body)
+        return self._handle_response(resp)
+
+    def _get(self, path: str) -> Any:
+        url = f"{self.base_url}{path}"
+        resp = self._session.get(url)
+        return self._handle_response(resp)
+
+    def _handle_response(self, resp: _requests.Response) -> Any:
+        if not resp.ok:
+            body: Any = None
+            message = f"HTTP {resp.status_code}"
+            try:
+                body = resp.json()
+                if isinstance(body, dict) and "error" in body:
+                    message = body["error"]
+            except Exception:
+                pass
+            raise CheqpointError(message, resp.status_code, body)
+        return resp.json()
+
+
+# ---------------------------------------------------------------------------
+# Trace instrumentation helpers
+# ---------------------------------------------------------------------------
+
+
+from datetime import datetime, timezone
+
+
+class TraceCollector:
+    """Accumulates trace steps; call get_trace() to build the TraceData dict."""
+
+    def __init__(self) -> None:
+        self._steps: list[dict[str, str]] = []
+        self._model: str = ""
+        self._total_tokens: int = 0
+
+    def _now(self) -> str:
+        return datetime.now(tz=timezone.utc).isoformat()
+
+    def add_step(self, type: str, content: str) -> None:
+        self._steps.append({"type": type, "content": content, "timestamp": self._now()})
+
+    def get_trace(self) -> dict[str, Any]:
+        trace: dict[str, Any] = {"steps": list(self._steps)}
+        if self._model:
+            trace["model"] = self._model
+        if self._total_tokens:
+            trace["totalTokens"] = self._total_tokens
+        return trace
+
+
+class _OpenAIWrapper:
+    """Thin proxy around an OpenAI client that records chat completions."""
+
+    def __init__(self, client: Any, collector: TraceCollector) -> None:
+        self._client = client
+        self._collector = collector
+
+    def __getattr__(self, name: str) -> Any:
+        if name == "chat":
+            return _OpenAIChatProxy(self._client.chat, self._collector)
+        return getattr(self._client, name)
+
+
+class _OpenAIChatProxy:
+    def __init__(self, chat: Any, collector: TraceCollector) -> None:
+        self._chat = chat
+        self._collector = collector
+
+    @property
+    def completions(self) -> "_OpenAICompletionsProxy":
+        return _OpenAICompletionsProxy(self._chat.completions, self._collector)
+
+
+class _OpenAICompletionsProxy:
+    def __init__(self, completions: Any, collector: TraceCollector) -> None:
+        self._completions = completions
+        self._collector = collector
+
+    def create(self, **kwargs: Any) -> Any:
+        if "model" in kwargs:
+            self._collector._model = kwargs["model"]
+        for msg in kwargs.get("messages", []):
+            role = msg.get("role", "")
+            content = msg.get("content", "")
+            if role == "assistant":
+                self._collector.add_step("thought", str(content))
+            elif role == "tool":
+                self._collector.add_step("observation", str(content))
+        if "tools" in kwargs:
+            self._collector.add_step("tool_call", str(kwargs["tools"])[:200])
+
+        result = self._completions.create(**kwargs)
+
+        usage = getattr(result, "usage", None)
+        if usage and hasattr(usage, "total_tokens") and usage.total_tokens:
+            self._collector._total_tokens += usage.total_tokens
+
+        choices = getattr(result, "choices", []) or []
+        if choices:
+            msg = getattr(choices[0], "message", None)
+            if msg:
+                if getattr(msg, "content", None):
+                    self._collector.add_step("thought", msg.content)
+                tool_calls = getattr(msg, "tool_calls", None) or []
+                for tc in tool_calls:
+                    fn = getattr(tc, "function", None)
+                    name = getattr(fn, "name", "tool") if fn else "tool"
+                    args = getattr(fn, "arguments", "") if fn else ""
+                    self._collector.add_step("tool_call", f"{name}({args})")
+
+        return result
+
+
+class _AnthropicWrapper:
+    """Thin proxy around an Anthropic client that records message calls."""
+
+    def __init__(self, client: Any, collector: TraceCollector) -> None:
+        self._client = client
+        self._collector = collector
+
+    def __getattr__(self, name: str) -> Any:
+        if name == "messages":
+            return _AnthropicMessagesProxy(self._client.messages, self._collector)
+        return getattr(self._client, name)
+
+
+class _AnthropicMessagesProxy:
+    def __init__(self, messages: Any, collector: TraceCollector) -> None:
+        self._messages = messages
+        self._collector = collector
+
+    def create(self, **kwargs: Any) -> Any:
+        if "model" in kwargs:
+            self._collector._model = kwargs["model"]
+        for msg in kwargs.get("messages", []):
+            role = msg.get("role", "")
+            content = msg.get("content", "")
+            if role == "assistant":
+                self._collector.add_step("thought", str(content))
+            elif role == "user":
+                self._collector.add_step("observation", str(content))
+
+        result = self._messages.create(**kwargs)
+
+        usage = getattr(result, "usage", None)
+        if usage:
+            inp = getattr(usage, "input_tokens", 0) or 0
+            out = getattr(usage, "output_tokens", 0) or 0
+            self._collector._total_tokens += inp + out
+
+        for block in getattr(result, "content", []) or []:
+            btype = getattr(block, "type", "")
+            if btype == "text":
+                self._collector.add_step("thought", getattr(block, "text", ""))
+            elif btype == "tool_use":
+                name = getattr(block, "name", "tool")
+                inp = getattr(block, "input", {})
+                self._collector.add_step("tool_call", f"{name}({inp})")
+
+        return result
+
+
+def _wrap_openai(client: Any) -> tuple[Any, TraceCollector]:
+    collector = TraceCollector()
+    return _OpenAIWrapper(client, collector), collector
+
+
+def _wrap_anthropic(client: Any) -> tuple[Any, TraceCollector]:
+    collector = TraceCollector()
+    return _AnthropicWrapper(client, collector), collector

cheqpoint/crewai_tool.py

@@ -0,0 +1,86 @@
+"""Cheqpoint CrewAI integration — human-in-the-loop approval tool."""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from .client import CheqpointClient
+
+try:
+    from crewai.tools import BaseTool
+    from pydantic import BaseModel, Field
+except ImportError as e:  # pragma: no cover
+    raise ImportError(
+        "crewai is required for CheqpointApprovalTool. "
+        "Install it with: pip install cheqpoint[crewai]"
+    ) from e
+
+
+class _ApprovalInput(BaseModel):
+    action: str = Field(
+        description="Category of the action (e.g. 'send_email', 'process_refund', 'deploy_code')"
+    )
+    summary: str = Field(description="One-sentence description shown to the reviewer")
+    details: dict[str, Any] = Field(description="Full structured payload for the action")
+    risk_score: float = Field(
+        default=0.5, ge=0.0, le=1.0, description="Risk score 0.0–1.0"
+    )
+    justification: Optional[str] = Field(
+        default=None, description="Optional agent reasoning for the reviewer"
+    )
+
+
+class CheqpointApprovalTool(BaseTool):
+    """CrewAI tool that pauses agent execution and waits for human approval.
+
+    Usage::
+
+        from crewai import Agent, Task, Crew
+        from cheqpoint.crewai_tool import CheqpointApprovalTool
+
+        approval_tool = CheqpointApprovalTool(api_key="ck_...")
+
+        agent = Agent(
+            role="Financial Analyst",
+            goal="Process refunds with human oversight",
+            backstory="You process refunds and escalate risky ones for approval.",
+            tools=[approval_tool],
+        )
+    """
+
+    name: str = "request_human_approval"
+    description: str = (
+        "Request human approval before taking a consequential action. "
+        "Call this tool when an action needs human review before execution. "
+        "Provide action type, a clear summary, and full details. "
+        "The tool blocks until a human approves or rejects the request."
+    )
+    args_schema: type[BaseModel] = _ApprovalInput
+
+    _client: CheqpointClient
+
+    def __init__(self, api_key: str, base_url: str = "https://app.cheqpoint.io", **kwargs: Any) -> None:
+        super().__init__(**kwargs)
+        object.__setattr__(self, "_client", CheqpointClient(api_key=api_key, base_url=base_url))
+
+    def _run(
+        self,
+        action: str,
+        summary: str,
+        details: dict[str, Any],
+        risk_score: float = 0.5,
+        justification: Optional[str] = None,
+    ) -> str:
+        """Execute the approval request and return the decision as a string."""
+        try:
+            result = self._client.checkpoint(
+                action=action,
+                summary=summary,
+                details=details,
+                risk_score=risk_score,
+                justification=justification,
+            )
+            notes = result.response_notes or "Approved by reviewer"
+            return f"APPROVED: {notes}"
+        except Exception as exc:
+            return f"REJECTED: {exc}"

cheqpoint/langchain_tool.py

@@ -0,0 +1,109 @@
+"""Cheqpoint LangChain integration — human-in-the-loop approval tool."""
+
+from __future__ import annotations
+
+from typing import Any, Optional, Type
+
+from .client import CheqpointClient
+
+try:
+    from langchain.tools import BaseTool
+    from pydantic import BaseModel, Field
+except ImportError as e:  # pragma: no cover
+    raise ImportError(
+        "langchain is required for CheqpointApprovalTool. "
+        "Install it with: pip install cheqpoint[langchain]"
+    ) from e
+
+
+class _CheqpointInput(BaseModel):
+    action: str = Field(
+        description="Category of the action requiring approval (e.g. 'send_email', 'process_refund', 'deploy_code')"
+    )
+    summary: str = Field(
+        description="One-sentence description shown to the human reviewer"
+    )
+    details: dict[str, Any] = Field(
+        description="Structured payload describing the action in detail"
+    )
+    risk_score: float = Field(
+        default=0.5,
+        ge=0.0,
+        le=1.0,
+        description="Risk score from 0.0 (low) to 1.0 (critical). Default: 0.5",
+    )
+    justification: Optional[str] = Field(
+        default=None,
+        description="Optional agent reasoning shown to the reviewer",
+    )
+
+
+class CheqpointApprovalTool(BaseTool):
+    """LangChain tool that pauses agent execution and waits for human approval.
+
+    Usage::
+
+        from langchain_openai import ChatOpenAI
+        from langchain.agents import create_tool_calling_agent, AgentExecutor
+        from cheqpoint.langchain_tool import CheqpointApprovalTool
+
+        tool = CheqpointApprovalTool(api_key="ck_...")
+        llm = ChatOpenAI(model="gpt-4o")
+        agent = create_tool_calling_agent(llm, [tool], prompt)
+        executor = AgentExecutor(agent=agent, tools=[tool])
+    """
+
+    name: str = "request_human_approval"
+    description: str = (
+        "Request human approval before taking a consequential action. "
+        "Use this tool when the action could have significant impact and requires "
+        "a human reviewer to approve before you proceed. "
+        "The tool blocks until a decision is made."
+    )
+    args_schema: Type[BaseModel] = _CheqpointInput
+
+    # Pydantic excludes the client field from serialisation
+    _client: CheqpointClient
+
+    def __init__(self, api_key: str, base_url: str = "https://app.cheqpoint.io", **kwargs: Any) -> None:
+        super().__init__(**kwargs)
+        object.__setattr__(self, "_client", CheqpointClient(api_key=api_key, base_url=base_url))
+
+    def _run(
+        self,
+        action: str,
+        summary: str,
+        details: dict[str, Any],
+        risk_score: float = 0.5,
+        justification: Optional[str] = None,
+    ) -> str:
+        """Synchronous execution — submits the request and polls for decision."""
+        try:
+            result = self._client.checkpoint(
+                action=action,
+                summary=summary,
+                details=details,
+                risk_score=risk_score,
+                justification=justification,
+            )
+            notes = result.response_notes or "Approved by reviewer"
+            return f"APPROVED: {notes}"
+        except Exception as exc:
+            return f"REJECTED: {exc}"
+
+    async def _arun(
+        self,
+        action: str,
+        summary: str,
+        details: dict[str, Any],
+        risk_score: float = 0.5,
+        justification: Optional[str] = None,
+    ) -> str:
+        """Async execution delegates to the sync implementation (polling is blocking)."""
+        return self._run(
+            action=action,
+            summary=summary,
+            details=details,
+            risk_score=risk_score,
+            justification=justification,
+        )

cheqpoint-0.1.0.dist-info/METADATA

@@ -0,0 +1,237 @@
+Metadata-Version: 2.4
+Name: cheqpoint
+Version: 0.1.0
+Summary: Human-in-the-loop approval SDK for AI agents
+Home-page: https://cheqpoint.io
+Author: Cheqpoint
+Keywords: cheqpoint,human-in-the-loop,ai,agents,approval
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+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.9
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.28.0
+Dynamic: author
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# cheqpoint
+
+Official Python SDK for [Cheqpoint](https://cheqpoint.co) — human-in-the-loop approval queues for AI agents.
+
+## Installation
+
+```bash
+pip install cheqpoint
+```
+
+## Quick start
+
+```python
+import os
+from cheqpoint import CheqpointClient
+
+client = CheqpointClient(api_key=os.environ["CHEQPOINT_API_KEY"])
+
+# Your agent calls this instead of executing directly.
+# checkpoint() submits the request and waits for a human decision.
+result = client.checkpoint(
+    type="refund",
+    risk_level="high",
+    summary="Refund $149 to sarah@example.com",
+    details={"userId": "usr_123", "amount": 149, "currency": "USD"},
+    justification="Double-charged on invoice #1821",
+)
+
+# effective_details returns modifiedDetails if set, else original details
+stripe.refunds.create(**result.effective_details)
+```
+
+## Constructor
+
+```python
+CheqpointClient(
+    api_key: str,                          # Required. Your workspace API key.
+    base_url: str = "https://app.cheqpoint.co",
+    timeout: float = 300,                  # Default poll timeout in seconds
+)
+```
+
+## Methods
+
+### `checkpoint(...)` → `CheckpointResult`
+
+Submit an action for review and **block** until a human decides.
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `type` | `str` | required | Short label for the action (e.g. `"refund"`, `"email"`) |
+| `risk_level` | `"low" \| "medium" \| "high"` | required | Risk level of the action |
+| `summary` | `str` | required | One-sentence description shown to reviewers |
+| `details` | `dict` | required | Structured payload. Returned as-is (or modified) on approval |
+| `justification` | `str \| None` | `None` | Agent's reasoning shown to reviewers |
+| `webhook_url` | `str \| None` | `None` | URL for Cheqpoint to POST the decision to |
+| `poll_interval` | `float` | `3` | Seconds between status polls |
+| `timeout` | `float \| None` | client default | Max seconds to wait |
+
+**Returns** `CheckpointResult` when approved.
+**Raises** `RejectedError` if rejected.
+**Raises** `TimeoutError` if no decision within timeout.
+
+```python
+@dataclass
+class CheckpointResult:
+    id: str
+    status: str                        # "APPROVED"
+    details: dict                      # original payload
+    modified_details: dict | None      # reviewer edits, if any
+    response_notes: str | None         # reviewer's note
+
+    def effective_details(self) -> dict:
+        """Returns modified_details if set, else original details."""
+```
+
+### `create_request(...)` → `dict`
+
+Fire-and-forget. Submits the request and returns immediately with `{"id": "..."}`. Pair with a `webhook_url` or poll manually with `get_request`.
+
+### `get_request(request_id)` → `RequestStatus`
+
+Fetch the current status of a request.
+
+```python
+@dataclass
+class RequestStatus:
+    id: str
+    status: str             # "PENDING" | "APPROVED" | "REJECTED"
+    type: str
+    risk_level: str
+    summary: str
+    details: dict
+    modified_details: dict | None
+    response_notes: str | None
+    webhook_delivered: bool
+    created_at: str
+    decided_at: str | None
+```
+
+## Error handling
+
+```python
+from cheqpoint import CheqpointClient, CheqpointError, RejectedError, TimeoutError
+
+try:
+    result = client.checkpoint(...)
+except RejectedError as e:
+    print(f"Rejected: {e.response_notes}")
+except TimeoutError as e:
+    print(f"Timed out for request {e.request_id}")
+except CheqpointError as e:
+    print(f"API error {e.status_code}: {e}")
+```
+
+## Examples
+
+### With webhook (recommended for production)
+
+```python
+result = client.create_request(
+    type="db-write",
+    risk_level="medium",
+    summary="Delete user account usr_456",
+    details={"userId": "usr_456", "reason": "GDPR deletion request"},
+    webhook_url="https://yourapp.com/webhook/cheqpoint",
+)
+request_id = result["id"]
+# Store request_id — your Flask/Django webhook handler receives the decision
+```
+
+### Manual polling
+
+```python
+result = client.create_request(type="email", risk_level="low", ...)
+request_id = result["id"]
+
+# Check later
+status = client.get_request(request_id)
+if status.status == "APPROVED":
+    payload = status.modified_details or status.details
+    send_email(**payload)
+```
+
+### LangChain agent tool
+
+```python
+from langchain_core.tools import tool
+
+@tool
+def issue_refund(user_id: str, amount: float, reason: str) -> str:
+    """Issue a refund to a customer. Requires human approval."""
+    result = client.checkpoint(
+        type="refund",
+        risk_level="high",
+        summary=f"Refund ${amount} to user {user_id}",
+        details={"userId": user_id, "amount": amount, "reason": reason},
+    )
+    payload = result.effective_details
+    return f"Refund approved for ${payload['amount']}"
+```
+
+### CrewAI tool
+
+```python
+from crewai_tools import BaseTool
+
+class CheqpointApprovalTool(BaseTool):
+    name: str = "Request Human Approval"
+    description: str = "Submit a risky action for human approval before executing."
+
+    def _run(self, action_type: str, summary: str, details: dict) -> str:
+        result = client.checkpoint(
+            type=action_type,
+            risk_level="high",
+            summary=summary,
+            details=details,
+        )
+        return f"Approved. Effective details: {result.effective_details}"
+```
+
+### Flask webhook handler
+
+```python
+from flask import Flask, request, jsonify
+
+app = Flask(__name__)
+
+@app.route("/webhook/cheqpoint", methods=["POST"])
+def cheqpoint_webhook():
+    data = request.get_json()
+    status = data["status"]
+    payload = data.get("modifiedDetails") or data["details"]
+
+    if status == "APPROVED":
+        process_action(payload)
+
+    return jsonify({"ok": True}), 200
+```
+
+## Requirements
+
+- Python 3.9+
+- `requests` library
+
+## License
+
+MIT

cheqpoint-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+cheqpoint/__init__.py,sha256=GfWwQ84iw4v7hpzLvpJPr6TnTxlr3EPzDWxtBe7yicE,583
+cheqpoint/client.py,sha256=vaHhkCb7M4TnRs2MKeRYrUTkUWRQUJLQarOW4tu3nQU,15457
+cheqpoint/crewai_tool.py,sha256=0h73Uo-OAz7fhDYLJfgYKDRBDN0irI2jf7SdLzncETQ,2988
+cheqpoint/langchain_tool.py,sha256=IHFd8-uMbUQIpMtwi9MivynFFKcCsVSNsF4wI6g2XbU,3676
+cheqpoint-0.1.0.dist-info/METADATA,sha256=l2h-6yv1ekmgWvxTh5TRUcX1gNw8CR4SqmQPH3VsZTc,6693
+cheqpoint-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+cheqpoint-0.1.0.dist-info/top_level.txt,sha256=V5bGw0B5vcbbkuBwrokEG1qt7clJRlIZewSLdDYaysk,10
+cheqpoint-0.1.0.dist-info/RECORD,,

cheqpoint-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

cheqpoint-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+cheqpoint