humanforai

Python client and command-line tool for Human For AI — a human endpoint for AI agents. Let your agent, pipeline, or script hire a verified human operator for tasks that need physical presence, human perception, or human judgment:

• Real-world verification — confirm a place, product, price, or claim exists, with photo/text evidence
• Product or app testing — a real human installs, uses, and reports
• Human judgment and feedback — tone, clarity, trustworthiness, design quality
• AI output review — human review before your output reaches production
• Data collection — gathering or labeling that needs human perception or local access
• Local physical-world tasks — visit, photograph, check, measure, observe
• Decision escalation — a human read on a judgment call before you act
• …and anything else a human can legally and safely do (custom_human_in_the_loop)

No API key. Free during the proof-of-concept pilot. Every task is reviewed by the human before acceptance; illegal, harmful, deceptive, unsafe, or privacy-invasive tasks are rejected. First response within 12 hours, any day of the week — typically much faster.

Zero dependencies (standard library only). Python 3.9+.

Install

pip install humanforai

With offline receipt verification (needs cryptography):

pip install "humanforai[receipt]"

Command line

humanforai services                       # the catalog with task_type identifiers
humanforai submit \
  --type real_world_verification \
  --description "Verify that [business] at [address] is open; photograph the storefront and posted hours." \
  --location "City, address or area" \
  --output-format text_report_with_photos \
  --email you@your-domain.com
humanforai status HFAI-2026-XXXXXXXXXXXXXXXX          # one look
humanforai status HFAI-2026-XXXXXXXXXXXXXXXX --watch  # poll until delivered or rejected
humanforai message --reply-to you@your-domain.com --message "Can you cover [city] next week?"
humanforai thread MSG-ID --token ACCESS_TOKEN
humanforai verify-receipt HFAI-2026-XXXXXXXXXXXXXXXX  # offline check of the signed receipt
humanforai health

Every command accepts --json for raw output. Exit codes: 0 ok, 2 usage, 3 API error, 4 the task was rejected.

No mailbox? Autonomous agents can submit with --status-poll instead of --email: the deliverable arrives as text in operator_notes on the status endpoint (budget: one such task per client per day). Keep the task_id — it is your only key to the result.

Python

from humanforai import Client, HumanForAIError

client = Client(requester="my-agent/1.0")

task = client.submit_task(
    task_type="ai_output_review",
    description="Review these 10 AI-written product descriptions for plausibility and tone; "
                "verdict + one-line reason each: [content or link].",
    output_format="structured_json",
    contact_email="you@your-domain.com",
)
print(task["task_id"], task["status_url"])

# Human review is not instant. Poll every minute or slower.
final = client.wait_for_task(task["task_id"], poll_interval=120)
print(final["status"], final.get("operator_notes"))

Errors are structured:

try:
    client.get_task("HFAI-NOPE")
except HumanForAIError as exc:
    print(exc.status, exc.error, exc.message, exc.details, exc.rate_limit)

Every response carries the standard RateLimit-* headers; the most recent set is on client.last_rate_limit. Retrying a submission with the same idempotency_key replays the original response instead of creating a duplicate.

Status transparency

get_task returns progress, not just the final state: seen_by_operator_at (the moment a human actually saw the task), eta (set on acceptance), and status_history (submitted → accepted → delivered, or rejected).

Signed receipts

Every delivered task carries receipt, a compact JWS (Ed25519) binding the deliverable's SHA-256 to the task's lifecycle timestamps. Verify it offline against the public key at https://humanforai.dev/.well-known/jwks.json:

from humanforai.receipt import verify_receipt

task = client.get_task(task_id)
payload = verify_receipt(task["receipt"], client.jwks(), deliverable_text=task["operator_notes"])

A valid receipt proves the deliverable is byte-identical to what was delivered and that it was issued by humanforai.dev. It does not prove the timestamps were witnessed by anyone else — they are the service's own signed assertion. Details: https://humanforai.dev/trust#receipts.

Other ways in

• MCP (streamable HTTP, no auth): https://humanforai.dev/mcp — or npx -y humanforai for stdio clients
• REST: https://humanforai.dev/api · OpenAPI: https://humanforai.dev/openapi.json
• Agent manifest: https://humanforai.dev/.well-known/agent.json · llms.txt: https://humanforai.dev/llms.txt
• Agent skill in one fetch: https://humanforai.dev/skill.md

Trust, in one paragraph

You never pay, never create an account, and are never asked for credentials — a request for payment or credentials is not from this service. You send a task description and an optional contact email; the worst case is a rejected task. Deliverables are one careful human's observation with stated confidence, not guaranteed truth. New here? Send a small, checkable test task first. Full analysis: https://humanforai.dev/trust.

License

MIT