Metadata-Version: 2.5
Name: helve
Version: 0.1.0
Summary: Official Python client for Helve: one key for web search, page extraction, and transcription across every provider.
Project-URL: Homepage, https://helve.dev
Project-URL: Documentation, https://docs.helve.dev
Project-URL: Repository, https://github.com/youssefarizk/tool-marketplace
License-Expression: MIT
Keywords: brave,exa,extract,helve,mcp,search,serper,tavily,transcription,web-search
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.9
Requires-Dist: httpx>=0.27
Description-Content-Type: text/markdown

# helve

The official Python client for [Helve](https://helve.dev): one key for web search, page extraction, and transcription across every provider. Sync and async, built on `httpx`.

```bash
pip install helve
```

```python
from helve import Helve

helve = Helve()  # reads HELVE_API_KEY

res = helve.search("latest research on speculative decoding", provider="fusion", max_results=5)
print(res["provider"], res["usage"]["cost_usd"])

pages = helve.extract([r["url"] for r in res["results"]], content={"max_chars": 4000})

job = helve.transcriptions.create_and_wait("https://example.com/standup.mp3", diarize=True)
if job["status"] == "completed":
    print(job["result"]["text"])
```

Async is the same API on `AsyncHelve`:

```python
from helve import AsyncHelve

async with AsyncHelve() as helve:
    res = await helve.search("who won the 2026 Abel Prize")
```

## Errors

Non-2xx responses raise `HelveError` with `.status`, a stable `.type` (`invalid_request`, `unauthorized`, `insufficient_credits`, `provider_error`, …), the message, and `.detail`. 429, 502, 503, and connection failures are retried twice with backoff; pass `max_retries=` to change that.

## Options

`Helve(api_key=None, base_url="https://helve.dev", timeout=60.0, max_retries=2, transport=None)`. Every parameter documented at [docs.helve.dev](https://docs.helve.dev) is accepted as a keyword argument.
