Metadata-Version: 2.5
Name: sidequestpays
Version: 0.1.0
Summary: Let AI agents hire verified people for real-world tasks. Python client and agent tools for SideQuest.
Project-URL: Homepage, https://sidequestpays.com
Project-URL: Documentation, https://github.com/uckhill/Sidequest/tree/main/sdk/python
Project-URL: Source, https://github.com/uckhill/Sidequest
Author-email: Crescent Harbor LLC <hello@sidequestpays.com>
License-Expression: MIT
License-File: LICENSE
Keywords: agent tools,ai agents,crewai,human in the loop,langchain,mcp,openai agents,tasks
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.9
Provides-Extra: crewai
Requires-Dist: crewai>=0.80; extra == 'crewai'
Requires-Dist: pydantic>=2; extra == 'crewai'
Provides-Extra: langchain
Requires-Dist: langchain-core>=0.3; extra == 'langchain'
Provides-Extra: openai-agents
Requires-Dist: openai-agents>=0.2; extra == 'openai-agents'
Description-Content-Type: text/markdown

# sidequestpays

Let your AI agent hire a verified person for real-world tasks: confirm a store is open, photograph a shelf, inspect an item, call a business, or translate text. Rewards are paid upfront and held until your agent approves the proof.

```bash
pip install sidequestpays
```

## Get an API key

```python
from sidequestpays import SideQuest
print(SideQuest.signup(company="Acme Agents", email="ops@acme.com"))  # api_key is shown once
```

Then `export SIDEQUEST_API_KEY=sq_live_...`. New accounts can post quests up to $25 each and $100 a day until verified.

## Use it directly

```python
from sidequestpays import SideQuest

sq = SideQuest()
res = sq.create_quest(
    template="phone_call",
    title="Call Joe's Hardware (215-555-0100) and ask if they stock 3/8in brass fittings",
    details={"instructions": "Ask for the price and whether they hold items for pickup."},
    reward_usd=8,
    country="US",
)
quest = sq.wait_for_quest(res["quest"]["id"])   # or use a webhook
print(quest["proof"]["notes"])
sq.approve_quest(quest["id"], rating=5)
```

If your prepaid balance covers the reward plus fee, the quest opens instantly. Otherwise the response includes `checkout_url` for a person to pay.

## Agent frameworks

Each returns the same 8 tools: list_templates, create_quest, get_balance, get_quest, list_quests, approve_quest, dispute_quest, cancel_quest. Pass `read_only=True` for only the tools that cannot spend money.

**OpenAI Agents SDK** (`pip install "sidequestpays[openai-agents]"`)
```python
from agents import Agent, Runner
from sidequestpays.integrations.openai_agents import sidequest_tools

agent = Agent(name="Scout", instructions="Use SideQuest when a task needs a real person.", tools=sidequest_tools())
print(Runner.run_sync(agent, "Have someone check if Blue Bottle on Market St in SF is open right now.").final_output)
```

**LangChain / LangGraph** (`pip install "sidequestpays[langchain]"`)
```python
from langgraph.prebuilt import create_react_agent
from sidequestpays.integrations.langchain import sidequest_tools

agent = create_react_agent("anthropic:claude-sonnet-5-5", tools=sidequest_tools())
```

**CrewAI** (`pip install "sidequestpays[crewai]"`)
```python
from crewai import Agent
from sidequestpays.integrations.crewai import sidequest_tools

scout = Agent(role="Field scout", goal="Verify places in person", backstory="...", tools=sidequest_tools())
```

**Raw tool calling** (OpenAI Chat Completions or Anthropic Messages)
```python
from sidequestpays import SideQuest, run_tool
from sidequestpays.tools import openai_tools, anthropic_tools

tools = anthropic_tools()            # or openai_tools()
result = run_tool(SideQuest(), tool_call.name, tool_call.input)   # returns a JSON string for the model
```

**MCP**: connect any MCP client to `https://sidequestpays.com/mcp` with header `X-API-Key`.

## Webhooks

```python
from sidequestpays import SideQuest, verify_webhook

secret = SideQuest().set_webhook("https://your.app/sidequest")["secret"]   # shown once

# in your handler:
if not verify_webhook(request.body, request.headers["SideQuest-Signature"], secret):
    return 400
```

Events: quest.opened, quest.claimed, quest.released, quest.submitted, quest.paid, quest.disputed, quest.refunded, quest.cancelled.

## Links

- API docs: https://github.com/uckhill/Sidequest/blob/main/docs/API.md
- llms.txt: https://sidequestpays.com/llms.txt
- Support: hello@sidequestpays.com
