Metadata-Version: 2.5
Name: riveter-sdk
Version: 0.1.0
Summary: Official Python SDK for the Riveter API — enrich data, build datasets, scrape pages, and run web searches
Project-URL: Homepage, https://docs.riveterhq.com
Project-URL: Documentation, https://docs.riveterhq.com
Author-email: Riveter <support@riveterhq.com>
License-Expression: MIT
License-File: LICENSE
Keywords: api,dataset,enrichment,riveter,scraping,sdk,web-search
Requires-Python: >=3.9
Requires-Dist: httpx<1,>=0.24
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == 'dev'
Description-Content-Type: text/markdown

# riveter-sdk

Official Python SDK for the [Riveter API](https://docs.riveterhq.com) — enrich data,
build datasets, scrape pages, and run web searches.

Requires Python 3.9+. The import name is `riveter`.

## Install

```bash
pip install riveter-sdk
```

## Quickstart

```python
from riveter import Riveter

# Reads RIVETER_API_KEY from the environment when api_key is not passed.
# Get a key at https://app.riveterhq.com/settings/api
riveter = Riveter(api_key="YOUR_API_KEY")

run = riveter.enrich(
    prompt="Research each company",
    attributes=["CEO", "Employee Count"],
    input={"Company": ["Apple", "Google"]},
)

result = riveter.runs.wait_for_result(run.id)
print(result.output)
```

## The run lifecycle

Every async kickoff (`enrich`, `datasets.build`, `extractions.run`, ...) returns a run.

```python
riveter.runs.get(run.id)                          # status + progress
riveter.runs.result(run.id, wait=50)              # output (long-polls up to 50s)
riveter.runs.wait_for_result(run.id, timeout=600) # poll until finished
riveter.runs.stop(run.id)                         # stop early
```

List runs with automatic pagination:

```python
for run in riveter.runs.list(status="success").auto_paging_iter():
    print(run.id)
```

## Surface

- `riveter.enrich(...)`, `riveter.quick_search(...)`, `riveter.scrape(...)`, `riveter.account()`
- `riveter.runs` — `get`, `result`, `stop`, `list`, `summary`, `wait_for_result`
- `riveter.enrichments` — `list`, `create`, `get`, `update`, `build_dataset`
- `riveter.datasets` — `build`, `extend`
- `riveter.configured_datasets` — `build`
- `riveter.extractions` — `create`, `get`, `run`
- `riveter.monitors` — `create`, `list`, `get`, `update`, `runs`

Responses are lightweight dataclasses; fields the SDK does not know yet stay reachable
via `.raw`.

## Errors and retries

API failures raise `riveter.APIError` with `status`, `type` (`not_found`,
`insufficient_credits`, ...), `message`, and optional `details`. Network failures raise
`APIConnectionError` / `APITimeoutError`. 429s are retried automatically using the
`X-RateLimit-Reset` header; 5xx and network failures are retried for GETs. Configure with
`max_retries` and `timeout`.

## Options

```python
Riveter(
    api_key="...",                            # default: env RIVETER_API_KEY
    base_url="https://api.riveterhq.com/v1",  # default: env RIVETER_BASE_URL, then this
    timeout=60.0,                             # keep above 50 for `wait` long-polls
    max_retries=2,
)
```
