Python SDK Guide
The official Python SDK for HumanPing. Give your AI agent access to real humans with 3 lines of code.
Installation
bash
pip install humanping
Requires Python 3.8+.
Quick Start
python
from humanping import HumanPing
hp = HumanPing(api_key="hp_live_...")
result = hp.verify("Is this restaurant still open?", location="123 Main St", budget=5.00)
print(result.answer)
Available Methods
hp.verify() — Reality Check
Ask a human to verify something in the real world.
python
result = hp.verify(
"Is this coffee shop still in business?",
location="456 Oak Ave",
budget=5.00
)
hp.call() — Voice Proxy
Have a human make a phone call on your agent's behalf.
python
result = hp.call(
number="+1-514-555-1234",
script="Reserve a table for 2, Friday 7 PM",
fallback_instructions="If unavailable, try Saturday",
budget=8.00
)
print(result.transcript)
hp.gut_check() — Human Intuition
Get a human's gut feeling — subjective judgments AI can't reliably make.
python
result = hp.gut_check(
content="Check out this dating profile bio...",
question="Does this person seem trustworthy?",
scale="1-10",
budget=2.00
)
print(f"Trust score: {result.score}/10")
hp.field() — Field Mission
Send a human to a physical location.
python
result = hp.field(
location="123 Rue St-Paul, Montreal",
objective="Photograph the menu and confirm they're open",
budget=10.00
)
hp.escalate() — Empathy Escalation
Hand off to a real human when your agent recognizes it's not enough.
python
result = hp.escalate(
context=conversation_history,
reason="User is grieving, needs real human support",
budget=20.00
)
hp.vibe() — Vibe Read
Get a human to read the mood of a place, event, or community.
python
result = hp.vibe(
target="Bitcoin Twitter Spaces",
duration="15m",
budget=15.00
)
Generic Task API
All sugar methods are built on hp.task() — use it for full control:
python
from humanping import HumanPing, TaskType, Urgency
hp = HumanPing(api_key="hp_live_...")
task = hp.task(
description="Verify this business exists at 123 Main St",
type=TaskType.VERIFICATION,
budget=5.00,
deadline="30m",
urgency=Urgency.URGENT,
proof="photo"
)
# Wait for result (blocking)
result = task.wait(timeout="30m")
Async Support
Every method has an async counterpart:
python
async with HumanPing(api_key="hp_live_...") as hp:
result = await hp.async_verify("Is this place open?", budget=5.00)
result = await hp.async_call(number="+1-514-555-1234", script="Reserve table for 2")
result = await hp.async_gut_check("Does this email seem legit?")
Wallet Management
python
balance = hp.wallet.balance()
print(f"Available: ${balance.available:.2f}")
hp.wallet.deposit(amount=100.00) # Add $100
LangChain Integration
python
from langchain.tools import StructuredTool
from humanping import HumanPing
hp = HumanPing(api_key="hp_...")
def human_verify(question: str, location: str = None) -> str:
result = hp.verify(question, location=location, budget=5.0)
return f"Human says: {result.answer}"
tool = StructuredTool.from_function(
func=human_verify,
name="human_verify",
description="Ask a real human to verify something."
)
Error Handling
python
from humanping.exceptions import (
AuthenticationError,
InsufficientFundsError,
TaskTimeoutError,
RateLimitError,
)
try:
result = hp.verify("Check this place", budget=5.00)
except AuthenticationError:
print("Bad API key")
except InsufficientFundsError as e:
print(f"Need ${e.required:.2f}, have ${e.available:.2f}")
except TaskTimeoutError:
print("No human picked this up in time")
except RateLimitError as e:
print(f"Retry in {e.retry_after}s")
Configuration
python
# From environment variable
import os
os.environ["HUMANPING_API_KEY"] = "hp_..."
hp = HumanPing()
# Custom base URL (self-hosted / testing)
hp = HumanPing(api_key="hp_...", base_url="http://localhost:3737/api/v1")
# Custom timeout
hp = HumanPing(api_key="hp_...", timeout=60.0)