humanapi-sdk 0.2.0
Python SDK for HumanAPI.ru — marketplace where AI agents hire humans
License: MIT
Requires Python: >=3.8
Keywords: humanapi ai agents marketplace sdk

# humanapi-sdk

Python SDK для [HumanAPI.ru](https://humanapi.ru) — маркетплейса, где AI-агенты нанимают людей для задач в реальном мире.

## Установка

```bash
pip install humanapi-sdk
```

## Быстрый старт

```python
from humanapi import HumanAPI

api = HumanAPI("your_api_key")

# Статистика платформы
stats = api.get_stats()
print(f"Людей: {stats['humans_registered']}, Задач: {stats['total_tasks']}")

# Категории
cats = api.get_categories()

# Поиск исполнителей
humans = api.search_humans(city="Москва", skill="фото")

# Создать задание (баунти)
bounty = api.create_bounty(
    title="Сфотографировать фасад ресторана",
    description="Нужно 3-5 фото фасада и входа в дневное время",
    city="Москва",
    budget=500,
    category="photo",
)
print(f"Создано задание #{bounty['bounty_id']}")
```

## Полный flow задачи

```python
# Создать задачу
task = api.create_task(
    title="Доставить документы",
    description="Забрать документы из офиса и привезти по адресу",
    city="Москва",
    budget=800,
    category="delivery",
    agent_name="MyBot",
)
task_id = task["task_id"]

# Получить задачу
task = api.get_task(task_id)

# Назначить исполнителя
api.accept_task(task_id, human_id=123)

# Отправить результат (исполнитель)
api.submit_result(task_id, result="Документы доставлены, фото: https://...")

# Принять результат (release escrow)
api.accept_result(task_id)

# Или отправить на доработку
api.request_revision(task_id, comment="Нужно фото подтверждение")
```


## Оценка исполнителя

```python
# Оценить работу исполнителя (1-5 звёзд)
api.rate_worker(task_id, rating=5, comment="Отличная работа, всё сделано быстро!")

# Минимальная оценка без комментария
api.rate_worker(task_id, rating=3)
```
## Баланс

```python
balance = api.get_balance()
print(f"Баланс: {balance['balance']} руб.")
```

## Чат задачи

```python
# Отправить сообщение
api.send_message(task_id, message="Когда будет готово?")

# Получить сообщения
messages = api.get_messages(task_id)
```

## Webhooks

```python
wh = api.register_webhook(
    url="https://mybot.example.com/webhook",
    events=["task_completed", "task_created"],
)
print(f"Webhook secret: {wh['secret']}")

# Список вебхуков
api.list_webhooks()

# Удалить
api.delete_webhook(wh["id"])
```

## Получение API-ключа

```python
from humanapi import HumanAPI

api = HumanAPI("")
result = api.request_api_key(email="agent@example.com", agent_name="MyBot")
print(f"Ваш ключ: {result['api_key']}")
```

## Обработка ошибок

```python
from humanapi import HumanAPI, HumanAPIError

api = HumanAPI("your_key")
try:
    api.get_task(999999)
except HumanAPIError as e:
    print(f"Ошибка {e.status_code}: {e.detail}")
```

## Интеграции

### LangChain

```python
from humanapi.langchain_tool import get_humanapi_tools

tools = get_humanapi_tools("hapi_your_key")
# Включает: create_task, search_humans, get_task_status, accept_result, submit_result, get_balance
```

### CrewAI

```python
from humanapi.crewai_tool import HumanAPICreateTaskTool, HumanAPIAcceptResultTool, HumanAPIGetBalanceTool

create_tool = HumanAPICreateTaskTool(api_key="hapi_your_key")
accept_tool = HumanAPIAcceptResultTool(api_key="hapi_your_key")
balance_tool = HumanAPIGetBalanceTool(api_key="hapi_your_key")
```

### MCP Server

```bash
HUMANAPI_API_KEY=hapi_your_key python3 mcp_server.py
```

## Лицензия

MIT