cheqpoint 0.1.3

Human-in-the-loop approval SDK for AI agents

cheqpoint

Official Python SDK for Cheqpoint — human-in-the-loop approval queues for AI agents.

python3 -m pip install cheqpoint

Verify installation

python3 -c "import cheqpoint; print(cheqpoint.__version__)"

[!TIP] macOS / Linux Troubleshooting: If you see ModuleNotFoundError after installing, ensure you are using python3 -m pip install to target the correct Python environment.

Quick start

import os
from cheqpoint import CheqpointClient

client = CheqpointClient(api_key=os.environ["CHEQPOINT_CONNECTION_KEY"])

# Your agent calls this instead of executing directly.
# checkpoint() submits the request and waits for a human decision.
result = client.checkpoint(
    action="refund",
    risk_score=0.9,
    summary="Refund $149 to [e-mail]",
    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

CheqpointClient(
    api_key: str,                          # Required. Your workspace Connection 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
action	str	required	Action type (e.g. "refund", "send_email", "deploy_code")
risk_score	float | None	None	Risk score 0.0–1.0 shown to reviewers (0.9 = high, 0.5 = medium, 0.2 = low)
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.

@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.

@dataclass
class RequestStatus:
    id: str
    status: str                          # "PENDING" | "APPROVED" | "REJECTED"
    details: dict
    modified_details: dict | None
    response_notes: str | None
    decision_reason_code: str | None
    decision_note: str | None
    auto_decided: bool
    auto_decision_rule_name: str | None
    decided_at: str | None

Error handling

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)

result = client.create_request(
    action="db-write",
    risk_score=0.5,
    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

result = client.create_request(action="send_email", risk_score=0.2, ...)
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

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(
        action="refund",
        risk_score=0.9,
        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

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(
            action=action_type,
            risk_score=0.9,
            summary=summary,
            details=details,
        )
        return f"Approved. Effective details: {result.effective_details}"

Flask webhook handler

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