riveter-sdk 0.1.0__py3-none-any.whl

riveter/__init__.py

@@ -0,0 +1,48 @@
+"""Official Python SDK for the Riveter API. https://docs.riveterhq.com"""
+
+from ._client import Riveter
+from ._errors import APIConnectionError, APIError, APITimeoutError, RiveterError
+from ._models import (
+    Account,
+    AccountInfo,
+    AccountUser,
+    ApiKeyInfo,
+    Credit,
+    Enrichment,
+    EnrichmentSummary,
+    Extraction,
+    Monitor,
+    Pagination,
+    Run,
+    RunListItem,
+    RunProgress,
+    RunsSummary,
+    ScrapeResult,
+)
+from ._pagination import RunsPage
+from ._version import __version__
+
+__all__ = [
+    "Riveter",
+    "RiveterError",
+    "APIError",
+    "APIConnectionError",
+    "APITimeoutError",
+    "Run",
+    "RunProgress",
+    "RunListItem",
+    "RunsPage",
+    "RunsSummary",
+    "Pagination",
+    "Enrichment",
+    "EnrichmentSummary",
+    "Extraction",
+    "Monitor",
+    "ScrapeResult",
+    "Account",
+    "AccountInfo",
+    "AccountUser",
+    "ApiKeyInfo",
+    "Credit",
+    "__version__",
+]

riveter/_client.py

@@ -0,0 +1,205 @@
+from __future__ import annotations
+
+import os
+import time
+from typing import Any, Dict, List, Optional
+
+import httpx
+
+from ._errors import APIConnectionError, APIError, APITimeoutError, RiveterError
+from ._models import AccountInfo, Run, ScrapeResult
+from ._resources import ConfiguredDatasets, Datasets, Enrichments, Extractions, Monitors, Runs
+from ._version import __version__
+
+DEFAULT_BASE_URL = "https://api.riveterhq.com/v1"
+
+
+def _drop_none(mapping: Dict[str, Any]) -> Dict[str, Any]:
+    return {key: value for key, value in mapping.items() if value is not None}
+
+
+class Riveter:
+    """Client for the Riveter API. https://docs.riveterhq.com
+
+    Args:
+        api_key: Falls back to the ``RIVETER_API_KEY`` environment variable.
+        base_url: Falls back to ``RIVETER_BASE_URL``, then the production URL.
+        timeout: Per-request timeout in seconds; must exceed the 50s ``wait``
+            long-poll. Default 60.
+        max_retries: Extra attempts after a 429 (any method) or a 5xx/network
+            failure (GETs only). Default 2.
+        http_client: Custom ``httpx.Client`` (proxies, mock transports, ...).
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        base_url: Optional[str] = None,
+        timeout: float = 60.0,
+        max_retries: int = 2,
+        http_client: Optional[httpx.Client] = None,
+    ):
+        self.api_key = api_key or os.environ.get("RIVETER_API_KEY")
+        if not self.api_key:
+            raise RiveterError(
+                "Missing API key: pass api_key or set RIVETER_API_KEY "
+                "(get one at https://app.riveterhq.com/settings/api)"
+            )
+        self.base_url = (base_url or os.environ.get("RIVETER_BASE_URL") or DEFAULT_BASE_URL).rstrip("/")
+        self.timeout = timeout
+        self.max_retries = max_retries
+        self._http = http_client or httpx.Client(timeout=timeout)
+        self.runs = Runs(self)
+        self.enrichments = Enrichments(self)
+        self.datasets = Datasets(self)
+        self.configured_datasets = ConfiguredDatasets(self)
+        self.extractions = Extractions(self)
+        self.monitors = Monitors(self)
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> "Riveter":
+        return self
+
+    def __exit__(self, *exc_info: Any) -> None:
+        self.close()
+
+    # ----- top-level operations -----
+
+    def enrich(
+        self,
+        *,
+        enrichment_id: Optional[str] = None,
+        output: Optional[Dict[str, Any]] = None,
+        prompt: Optional[str] = None,
+        attributes: Optional[List[str]] = None,
+        input: Optional[Dict[str, List[str]]] = None,
+        dataset_id: Optional[str] = None,
+        run_key: Optional[str] = None,
+        webhook_url: Optional[str] = None,
+        allow_duplicate_input: Optional[bool] = None,
+    ) -> Run:
+        """Start an enrichment run on rows of input data. (operationId: enrich)"""
+        body = _drop_none(
+            {
+                "enrichment_id": enrichment_id,
+                "output": output,
+                "prompt": prompt,
+                "attributes": attributes,
+                "input": input,
+                "dataset_id": dataset_id,
+                "run_key": run_key,
+                "webhook_url": webhook_url,
+                "allow_duplicate_input": allow_duplicate_input,
+            }
+        )
+        return Run.from_dict(self.request("POST", "/enrich", json=body))
+
+    def quick_search(
+        self,
+        query: str,
+        *,
+        date_start: Optional[str] = None,
+        date_end: Optional[str] = None,
+        run_key: Optional[str] = None,
+    ) -> Run:
+        """Run one web search synchronously; results are already in ``output``.
+        (operationId: quickSearch)"""
+        body = _drop_none(
+            {"query": query, "date_start": date_start, "date_end": date_end, "run_key": run_key}
+        )
+        return Run.from_dict(self.request("POST", "/quick_search", json=body))
+
+    def scrape(
+        self,
+        url: str,
+        *,
+        proxy_country_code: Optional[str] = None,
+        skip_cache: Optional[bool] = None,
+    ) -> ScrapeResult:
+        """Scrape a webpage and return its text synchronously. (operationId: scrape)"""
+        body = _drop_none(
+            {"url": url, "proxy_country_code": proxy_country_code, "skip_cache": skip_cache}
+        )
+        return ScrapeResult.from_dict(self.request("POST", "/scrape", json=body))
+
+    def account(self) -> AccountInfo:
+        """Account, plan, and credit info for the API key. (operationId: getAccount)"""
+        return AccountInfo.from_dict(self.request("GET", "/account"))
+
+    # ----- transport -----
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Optional[Dict[str, Any]] = None,
+        json: Optional[Dict[str, Any]] = None,
+        timeout: Optional[float] = None,
+    ) -> Any:
+        url = self.base_url + path
+        headers = {
+            "Authorization": f"Bearer {self.api_key}",
+            "User-Agent": f"riveter-sdk-python/{__version__}",
+        }
+        retry_on_failure = method == "GET"
+        attempt = 0
+        while True:
+            try:
+                response = self._http.request(
+                    method,
+                    url,
+                    params=_drop_none(params or {}) or None,
+                    json=json,
+                    headers=headers,
+                    timeout=timeout if timeout is not None else self.timeout,
+                )
+            except httpx.TimeoutException as exc:
+                if retry_on_failure and attempt < self.max_retries:
+                    time.sleep(_backoff_seconds(attempt))
+                    attempt += 1
+                    continue
+                raise APITimeoutError(f"Request timed out: {method} {path}") from exc
+            except httpx.HTTPError as exc:
+                if retry_on_failure and attempt < self.max_retries:
+                    time.sleep(_backoff_seconds(attempt))
+                    attempt += 1
+                    continue
+                raise APIConnectionError(f"Request failed: {method} {path}: {exc}") from exc
+
+            if response.is_success:
+                return response.json() if response.content else None
+
+            if response.status_code == 429 and attempt < self.max_retries:
+                time.sleep(_rate_limit_delay_seconds(response, attempt))
+                attempt += 1
+                continue
+            if response.status_code >= 500 and retry_on_failure and attempt < self.max_retries:
+                time.sleep(_backoff_seconds(attempt))
+                attempt += 1
+                continue
+
+            raise APIError.from_response(response.status_code, _parse_body(response))
+
+
+def _backoff_seconds(attempt: int) -> float:
+    return min(0.5 * (2**attempt), 8.0)
+
+
+def _rate_limit_delay_seconds(response: httpx.Response, attempt: int) -> float:
+    try:
+        reset = float(response.headers.get("X-RateLimit-Reset", ""))
+    except ValueError:
+        return _backoff_seconds(attempt)
+    if reset <= 0:
+        return _backoff_seconds(attempt)
+    return min(max(reset - time.time(), 0.0), 30.0)
+
+
+def _parse_body(response: httpx.Response) -> Any:
+    try:
+        return response.json()
+    except ValueError:
+        return response.text

riveter/_errors.py

@@ -0,0 +1,63 @@
+from __future__ import annotations
+
+from typing import Any, Optional
+
+_FALLBACK_TYPES = {
+    400: "bad_request",
+    401: "unauthorized",
+    403: "forbidden",
+    404: "not_found",
+    409: "conflict",
+    422: "validation",
+    429: "rate_limited",
+}
+
+
+class RiveterError(Exception):
+    """Base class for every error raised by this SDK."""
+
+
+class APIConnectionError(RiveterError):
+    """Network-level failure: the request never produced an HTTP response."""
+
+
+class APITimeoutError(APIConnectionError):
+    """A request or wait helper exceeded its time budget."""
+
+
+class APIError(RiveterError):
+    """A non-2xx HTTP response, normalized across both error body dialects."""
+
+    def __init__(self, status: int, type: str, message: str, details: Any = None):
+        super().__init__(message)
+        self.status = status
+        self.type = type
+        self.message = message
+        self.details = details
+
+    @classmethod
+    def from_response(cls, status: int, body: Any) -> "APIError":
+        """Builds an APIError from either the clean ``{"error": {...}}`` envelope
+        or the legacy ``{"request_status": "error"}`` shape (401s)."""
+        if isinstance(body, dict):
+            error = body.get("error")
+            if isinstance(error, dict) and isinstance(error.get("type"), str):
+                return cls(
+                    status=status,
+                    type=error["type"],
+                    message=error.get("message") or f"HTTP {status}",
+                    details=error.get("details"),
+                )
+            if body.get("request_status") == "error":
+                return cls(
+                    status=status,
+                    type=body.get("error_type") or "error",
+                    message=body.get("message") or f"HTTP {status}",
+                    details=body.get("errors"),
+                )
+        message: Optional[str] = body[:200] if isinstance(body, str) and body else None
+        return cls(
+            status=status,
+            type=_FALLBACK_TYPES.get(status, f"http_{status}"),
+            message=message or f"HTTP {status}",
+        )

riveter/_models.py

@@ -0,0 +1,285 @@
+"""Typed views over API response dicts.
+
+Models keep the full response in ``.raw``, so fields added to the API later
+stay reachable without an SDK update.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field, fields
+from typing import Any, Callable, Dict, List, Optional
+
+
+def _build(cls, data: Optional[Dict[str, Any]], **nested: Callable[[Any], Any]):
+    data = dict(data or {})
+    known = {f.name: data.get(f.name) for f in fields(cls) if f.name != "raw"}
+    for name, builder in nested.items():
+        value = data.get(name)
+        known[name] = builder(value) if value is not None else None
+    return cls(**known, raw=data)
+
+
+@dataclass
+class RunProgress:
+    percent_complete: Optional[float] = None
+    estimated_seconds_remaining: Optional[float] = None
+    elapsed_seconds: Optional[float] = None
+    completed_cells: Optional[int] = None
+    total_cells_expected: Optional[int] = None
+    not_found_cells: Optional[int] = None
+    raw: Dict[str, Any] = field(default_factory=dict, repr=False)
+
+    @classmethod
+    def from_dict(cls, data: Optional[Dict[str, Any]]) -> "RunProgress":
+        return _build(cls, data)
+
+
+@dataclass
+class Run:
+    """The uniform run envelope returned by kickoffs and every /runs endpoint.
+
+    Endpoint-specific kickoff extras (``dataset_id``, ``credits_charged``, ...)
+    are optional fields; ``output`` is ``None`` until the run finishes.
+    """
+
+    id: Optional[str] = None
+    type: Optional[str] = None
+    status: Optional[str] = None
+    progress: Optional[RunProgress] = None
+    credits_used: Optional[float] = None
+    app_url: Optional[str] = None
+    result_url: Optional[str] = None
+    started_at: Optional[str] = None
+    finished_at: Optional[str] = None
+    error: Optional[Dict[str, Any]] = None
+    enrichment_id: Optional[str] = None
+    enrichment_name: Optional[str] = None
+    dataset_id: Optional[str] = None
+    extraction_id: Optional[str] = None
+    monitor_id: Optional[str] = None
+    webhook_url: Optional[str] = None
+    output: Any = None
+    max_items: Optional[int] = None
+    enrichment_run_id: Optional[str] = None
+    source_dataset_id: Optional[str] = None
+    configured_dataset_id: Optional[str] = None
+    credits_charged: Optional[float] = None
+    variables: Optional[Dict[str, Any]] = None
+    validation_warning: Optional[str] = None
+    tier: Optional[str] = None
+    raw: Dict[str, Any] = field(default_factory=dict, repr=False)
+
+    @classmethod
+    def from_dict(cls, data: Optional[Dict[str, Any]]) -> "Run":
+        return _build(cls, data, progress=RunProgress.from_dict)
+
+    @property
+    def is_finished(self) -> bool:
+        return self.status in ("success", "stopped")
+
+
+@dataclass
+class RunListItem:
+    id: Optional[str] = None
+    type: Optional[str] = None
+    status: Optional[str] = None
+    enrichment_id: Optional[str] = None
+    enrichment_name: Optional[str] = None
+    row_count: Optional[int] = None
+    credits_used: Optional[float] = None
+    error: Optional[Dict[str, Any]] = None
+    created_at: Optional[str] = None
+    started_at: Optional[str] = None
+    finished_at: Optional[str] = None
+    app_url: Optional[str] = None
+    result_url: Optional[str] = None
+    raw: Dict[str, Any] = field(default_factory=dict, repr=False)
+
+    @classmethod
+    def from_dict(cls, data: Optional[Dict[str, Any]]) -> "RunListItem":
+        return _build(cls, data)
+
+
+@dataclass
+class Pagination:
+    page: Optional[int] = None
+    per_page: Optional[int] = None
+    total_count: Optional[int] = None
+    total_pages: Optional[int] = None
+    raw: Dict[str, Any] = field(default_factory=dict, repr=False)
+
+    @classmethod
+    def from_dict(cls, data: Optional[Dict[str, Any]]) -> "Pagination":
+        return _build(cls, data)
+
+
+@dataclass
+class RunsSummary:
+    counts: Optional[Dict[str, int]] = None
+    raw: Dict[str, Any] = field(default_factory=dict, repr=False)
+
+    @classmethod
+    def from_dict(cls, data: Optional[Dict[str, Any]]) -> "RunsSummary":
+        return _build(cls, data)
+
+
+@dataclass
+class EnrichmentSummary:
+    id: Optional[str] = None
+    name: Optional[str] = None
+    status: Optional[str] = None
+    app_url: Optional[str] = None
+    columns: Optional[Dict[str, Any]] = None
+    raw: Dict[str, Any] = field(default_factory=dict, repr=False)
+
+    @classmethod
+    def from_dict(cls, data: Optional[Dict[str, Any]]) -> "EnrichmentSummary":
+        return _build(cls, data)
+
+
+@dataclass
+class Enrichment:
+    id: Optional[str] = None
+    name: Optional[str] = None
+    status: Optional[str] = None
+    app_url: Optional[str] = None
+    input: Optional[Dict[str, Any]] = None
+    output: Optional[Dict[str, Any]] = None
+    dataset_id: Optional[str] = None
+    raw: Dict[str, Any] = field(default_factory=dict, repr=False)
+
+    @classmethod
+    def from_dict(cls, data: Optional[Dict[str, Any]]) -> "Enrichment":
+        return _build(cls, data)
+
+
+@dataclass
+class Extraction:
+    id: Optional[str] = None
+    name: Optional[str] = None
+    status: Optional[str] = None
+    app_url: Optional[str] = None
+    starting_url: Optional[str] = None
+    goal_description: Optional[str] = None
+    output_record_json_schema: Any = None
+    required_keys: Optional[List[str]] = None
+    locked: Optional[bool] = None
+    validation_passing: Optional[bool] = None
+    discovered_at: Optional[str] = None
+    run_credits_required: Optional[float] = None
+    credits_charged: Optional[float] = None
+    raw: Dict[str, Any] = field(default_factory=dict, repr=False)
+
+    @classmethod
+    def from_dict(cls, data: Optional[Dict[str, Any]]) -> "Extraction":
+        return _build(cls, data)
+
+
+@dataclass
+class Monitor:
+    id: Optional[str] = None
+    name: Optional[str] = None
+    enabled: Optional[bool] = None
+    cadence: Optional[str] = None
+    minute: Optional[int] = None
+    hour: Optional[int] = None
+    day_of_week: Optional[int] = None
+    day_of_month: Optional[int] = None
+    timezone: Optional[str] = None
+    webhook_url: Optional[str] = None
+    alert_rule: Optional[str] = None
+    output_format: Optional[str] = None
+    next_run_at: Optional[str] = None
+    schedule_summary: Optional[str] = None
+    enrichment_id: Optional[str] = None
+    enrichment_name: Optional[str] = None
+    created_at: Optional[str] = None
+    has_input: Optional[bool] = None
+    raw: Dict[str, Any] = field(default_factory=dict, repr=False)
+
+    @classmethod
+    def from_dict(cls, data: Optional[Dict[str, Any]]) -> "Monitor":
+        return _build(cls, data)
+
+
+@dataclass
+class ScrapeResult:
+    """Synchronous scrape result (legacy request_status format, per the spec)."""
+
+    request_status: Optional[str] = None
+    text: Optional[str] = None
+    url: Optional[str] = None
+    base_url_for_links: Optional[str] = None
+    status_code: Optional[int] = None
+    possibly_blocked: Optional[bool] = None
+    credit_used: Optional[float] = None
+    riveter_app_link: Optional[str] = None
+    raw: Dict[str, Any] = field(default_factory=dict, repr=False)
+
+    @classmethod
+    def from_dict(cls, data: Optional[Dict[str, Any]]) -> "ScrapeResult":
+        return _build(cls, data)
+
+
+@dataclass
+class Credit:
+    count: Optional[int] = None
+    max: Optional[int] = None
+    balance: Optional[int] = None
+    raw: Dict[str, Any] = field(default_factory=dict, repr=False)
+
+    @classmethod
+    def from_dict(cls, data: Optional[Dict[str, Any]]) -> "Credit":
+        return _build(cls, data)
+
+
+@dataclass
+class Account:
+    uuid: Optional[str] = None
+    name: Optional[str] = None
+    plan: Optional[str] = None
+    credit: Optional[Credit] = None
+    raw: Dict[str, Any] = field(default_factory=dict, repr=False)
+
+    @classmethod
+    def from_dict(cls, data: Optional[Dict[str, Any]]) -> "Account":
+        return _build(cls, data, credit=Credit.from_dict)
+
+
+@dataclass
+class AccountUser:
+    uuid: Optional[str] = None
+    name: Optional[str] = None
+    email: Optional[str] = None
+    raw: Dict[str, Any] = field(default_factory=dict, repr=False)
+
+    @classmethod
+    def from_dict(cls, data: Optional[Dict[str, Any]]) -> "AccountUser":
+        return _build(cls, data)
+
+
+@dataclass
+class ApiKeyInfo:
+    name: Optional[str] = None
+    last_used_at: Optional[str] = None
+    created_by: Optional[AccountUser] = None
+    raw: Dict[str, Any] = field(default_factory=dict, repr=False)
+
+    @classmethod
+    def from_dict(cls, data: Optional[Dict[str, Any]]) -> "ApiKeyInfo":
+        return _build(cls, data, created_by=AccountUser.from_dict)
+
+
+@dataclass
+class AccountInfo:
+    """Account info (legacy request_status format, per the spec)."""
+
+    request_status: Optional[str] = None
+    message: Optional[str] = None
+    account: Optional[Account] = None
+    api_key_info: Optional[ApiKeyInfo] = None
+    raw: Dict[str, Any] = field(default_factory=dict, repr=False)
+
+    @classmethod
+    def from_dict(cls, data: Optional[Dict[str, Any]]) -> "AccountInfo":
+        return _build(cls, data, account=Account.from_dict, api_key_info=ApiKeyInfo.from_dict)

riveter/_pagination.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+from typing import Any, Callable, Dict, Iterator, Optional
+
+from ._models import Pagination, RunListItem
+
+
+class RunsPage:
+    """One page of runs. Iterate the page directly, or use
+    :meth:`auto_paging_iter` to walk every following page."""
+
+    def __init__(self, data: Optional[Dict[str, Any]], fetch_page: Callable[[int], Dict[str, Any]]):
+        data = data or {}
+        self.runs = [RunListItem.from_dict(item) for item in data.get("runs") or []]
+        self.pagination = Pagination.from_dict(data.get("pagination"))
+        self.monitor_id = data.get("monitor_id")
+        self._fetch_page = fetch_page
+
+    def __iter__(self) -> Iterator[RunListItem]:
+        return iter(self.runs)
+
+    def __len__(self) -> int:
+        return len(self.runs)
+
+    @property
+    def has_next_page(self) -> bool:
+        return (self.pagination.page or 1) < (self.pagination.total_pages or 1)
+
+    def next_page(self) -> "RunsPage":
+        return RunsPage(self._fetch_page((self.pagination.page or 1) + 1), self._fetch_page)
+
+    def auto_paging_iter(self) -> Iterator[RunListItem]:
+        page = self
+        while True:
+            for run in page.runs:
+                yield run
+            if not page.has_next_page:
+                return
+            page = page.next_page()

riveter/_resources.py

@@ -0,0 +1,349 @@
+from __future__ import annotations
+
+import time
+from typing import TYPE_CHECKING, Any, Dict, List, Optional
+
+from ._errors import APITimeoutError
+from ._models import Enrichment, EnrichmentSummary, Extraction, Monitor, Run, RunsSummary
+from ._pagination import RunsPage
+
+if TYPE_CHECKING:
+    from ._client import Riveter
+
+
+def _drop_none(mapping: Dict[str, Any]) -> Dict[str, Any]:
+    return {key: value for key, value in mapping.items() if value is not None}
+
+
+class Runs:
+    """The uniform lifecycle for every async operation — status, results, stop."""
+
+    def __init__(self, client: "Riveter"):
+        self._client = client
+
+    def get(self, run_id: str) -> Run:
+        """Status and progress of a run. (operationId: getRun)"""
+        return Run.from_dict(self._client.request("GET", f"/runs/{run_id}"))
+
+    def result(self, run_id: str, *, wait: Optional[int] = None) -> Run:
+        """The run plus its ``output`` (None until finished). ``wait``
+        long-polls up to 50 seconds server-side. (operationId: getRunResult)"""
+        timeout = max(self._client.timeout, wait + 10) if wait else None
+        data = self._client.request(
+            "GET", f"/runs/{run_id}/result", params={"wait": wait}, timeout=timeout
+        )
+        return Run.from_dict(data)
+
+    def stop(self, run_id: str) -> Run:
+        """Stop a run early. (operationId: stopRun)"""
+        return Run.from_dict(self._client.request("POST", f"/runs/{run_id}/stop"))
+
+    def list(
+        self,
+        *,
+        type: Optional[str] = None,
+        status: Optional[str] = None,
+        enrichment_id: Optional[str] = None,
+        monitor_id: Optional[str] = None,
+        created_after: Optional[str] = None,
+        created_before: Optional[str] = None,
+        page: Optional[int] = None,
+        per_page: Optional[int] = None,
+    ) -> RunsPage:
+        """List the account's runs, newest first. (operationId: listRuns)"""
+        params = _drop_none(
+            {
+                "type": type,
+                "status": status,
+                "enrichment_id": enrichment_id,
+                "monitor_id": monitor_id,
+                "created_after": created_after,
+                "created_before": created_before,
+                "per_page": per_page,
+            }
+        )
+
+        def fetch_page(page_number: int) -> Dict[str, Any]:
+            return self._client.request("GET", "/runs", params={**params, "page": page_number})
+
+        return RunsPage(fetch_page(page or 1), fetch_page)
+
+    def summary(self) -> RunsSummary:
+        """All-time run counts by status. (operationId: runsSummary)"""
+        return RunsSummary.from_dict(self._client.request("GET", "/runs/summary"))
+
+    def wait_for_result(self, run_id: str, *, timeout: float = 600.0, poll_wait: int = 50) -> Run:
+        """Polls :meth:`result` with 50s long-polls until the run reaches
+        ``success`` or ``stopped``; raises APITimeoutError past ``timeout``."""
+        deadline = time.monotonic() + timeout
+        while True:
+            run = self.result(run_id, wait=poll_wait)
+            if run.is_finished:
+                return run
+            if time.monotonic() >= deadline:
+                raise APITimeoutError(f"Run {run_id} did not finish within {timeout}s")
+
+
+class Enrichments:
+    """Saved enrichment configurations."""
+
+    def __init__(self, client: "Riveter"):
+        self._client = client
+
+    def list(self) -> List[EnrichmentSummary]:
+        """List enrichments with their output column configuration. (operationId: listEnrichments)"""
+        response = self._client.request("GET", "/enrichments")
+        return [EnrichmentSummary.from_dict(item) for item in response.get("enrichments") or []]
+
+    def create(self, *, dataset_id: str) -> Enrichment:
+        """Create an enrichment (no run) from a completed dataset build. (operationId: createEnrichment)"""
+        return Enrichment.from_dict(
+            self._client.request("POST", "/enrichments", json={"dataset_id": dataset_id})
+        )
+
+    def get(self, enrichment_id: str) -> Enrichment:
+        """The enrichment's input columns and output column configuration. (operationId: getEnrichment)"""
+        return Enrichment.from_dict(self._client.request("GET", f"/enrichments/{enrichment_id}"))
+
+    def update(
+        self,
+        enrichment_id: str,
+        *,
+        output: Optional[Dict[str, Any]] = None,
+        column_order: Optional[List[str]] = None,
+    ) -> Dict[str, Any]:
+        """Add, update, rename, delete, or reorder output columns. (operationId: updateEnrichment)"""
+        body = _drop_none({"output": output, "column_order": column_order})
+        return self._client.request("PATCH", f"/enrichments/{enrichment_id}", json=body)
+
+    def build_dataset(
+        self,
+        enrichment_id: str,
+        *,
+        prompt: str,
+        qualifiers: Optional[List[str]] = None,
+        max_items: Optional[int] = None,
+        dataset_webhook_url: Optional[str] = None,
+        auto_run_enrichment: Optional[bool] = None,
+        auto_run_enrichment_webhook_url: Optional[str] = None,
+    ) -> Run:
+        """Build a dataset shaped for this enrichment. (operationId: buildDatasetForEnrichment)"""
+        body = _drop_none(
+            {
+                "prompt": prompt,
+                "qualifiers": qualifiers,
+                "max_items": max_items,
+                "dataset_webhook_url": dataset_webhook_url,
+                "auto_run_enrichment": auto_run_enrichment,
+                "auto_run_enrichment_webhook_url": auto_run_enrichment_webhook_url,
+            }
+        )
+        return Run.from_dict(
+            self._client.request("POST", f"/enrichments/{enrichment_id}/datasets", json=body)
+        )
+
+
+class Datasets:
+    """Dataset builds — generate rows from prompts or structured specs."""
+
+    def __init__(self, client: "Riveter"):
+        self._client = client
+
+    def build(
+        self,
+        *,
+        prompt: Optional[str] = None,
+        identifiers: Optional[List[str]] = None,
+        qualifiers: Optional[List[str]] = None,
+        attributes: Optional[List[str]] = None,
+        max_items: Optional[int] = None,
+        dataset_webhook_url: Optional[str] = None,
+        auto_run_enrichment: Optional[bool] = None,
+        auto_run_enrichment_webhook_url: Optional[str] = None,
+    ) -> Run:
+        """Build a dataset from a prompt, a structured spec, or both. (operationId: buildDataset)"""
+        body = _drop_none(
+            {
+                "prompt": prompt,
+                "identifiers": identifiers,
+                "qualifiers": qualifiers,
+                "attributes": attributes,
+                "max_items": max_items,
+                "dataset_webhook_url": dataset_webhook_url,
+                "auto_run_enrichment": auto_run_enrichment,
+                "auto_run_enrichment_webhook_url": auto_run_enrichment_webhook_url,
+            }
+        )
+        return Run.from_dict(self._client.request("POST", "/datasets", json=body))
+
+    def extend(
+        self,
+        dataset_id: str,
+        *,
+        prompt: Optional[str] = None,
+        qualifiers: Optional[List[str]] = None,
+        max_items: Optional[int] = None,
+        dataset_webhook_url: Optional[str] = None,
+        auto_run_enrichment: Optional[bool] = None,
+        auto_run_enrichment_webhook_url: Optional[str] = None,
+    ) -> Run:
+        """Generate new deduplicated rows for a completed dataset build. (operationId: extendDataset)"""
+        body = _drop_none(
+            {
+                "prompt": prompt,
+                "qualifiers": qualifiers,
+                "max_items": max_items,
+                "dataset_webhook_url": dataset_webhook_url,
+                "auto_run_enrichment": auto_run_enrichment,
+                "auto_run_enrichment_webhook_url": auto_run_enrichment_webhook_url,
+            }
+        )
+        return Run.from_dict(self._client.request("POST", f"/datasets/{dataset_id}/extend", json=body))
+
+
+class ConfiguredDatasets:
+    """Reusable, pre-configured dataset templates (cds_...)."""
+
+    def __init__(self, client: "Riveter"):
+        self._client = client
+
+    def build(
+        self,
+        configured_dataset_id: str,
+        *,
+        parameters: Optional[Dict[str, str]] = None,
+        tier: Optional[str] = None,
+        dataset_webhook_url: Optional[str] = None,
+    ) -> Run:
+        """Run a configured dataset template. (operationId: buildConfiguredDataset)"""
+        body = _drop_none(
+            {"parameters": parameters, "tier": tier, "dataset_webhook_url": dataset_webhook_url}
+        )
+        return Run.from_dict(
+            self._client.request("POST", f"/configured_datasets/{configured_dataset_id}/build", json=body)
+        )
+
+
+class Extractions:
+    """Reusable site scrape/extract recipes and their runs."""
+
+    def __init__(self, client: "Riveter"):
+        self._client = client
+
+    def create(
+        self,
+        *,
+        starting_url: str,
+        goal_description: str,
+        output_record_json_schema: Dict[str, Any],
+        name: Optional[str] = None,
+        required_keys: Optional[List[str]] = None,
+    ) -> Extraction:
+        """Create an extraction and start its agent discovery. (operationId: createExtraction)"""
+        body = _drop_none(
+            {
+                "starting_url": starting_url,
+                "goal_description": goal_description,
+                "output_record_json_schema": output_record_json_schema,
+                "name": name,
+                "required_keys": required_keys,
+            }
+        )
+        return Extraction.from_dict(self._client.request("POST", "/extractions", json=body))
+
+    def get(self, extraction_id: str) -> Extraction:
+        """The extraction's status and definition. (operationId: getExtraction)"""
+        return Extraction.from_dict(self._client.request("GET", f"/extractions/{extraction_id}"))
+
+    def run(
+        self,
+        extraction_id: str,
+        *,
+        variables: Optional[Dict[str, str]] = None,
+        webhook_url: Optional[str] = None,
+    ) -> Run:
+        """Execute a ready extraction. (operationId: runExtraction)"""
+        body = _drop_none({"variables": variables, "webhook_url": webhook_url})
+        return Run.from_dict(
+            self._client.request("POST", f"/extractions/{extraction_id}/runs", json=body)
+        )
+
+
+class Monitors:
+    """Scheduled enrichment runs with webhooks."""
+
+    def __init__(self, client: "Riveter"):
+        self._client = client
+
+    def create(
+        self,
+        *,
+        enrichment_id: str,
+        cadence: str,
+        minute: int,
+        hour: int,
+        timezone: str,
+        day_of_week: Optional[int] = None,
+        day_of_month: Optional[int] = None,
+        webhook_url: Optional[str] = None,
+        alert_rule: Optional[str] = None,
+        output_format: Optional[str] = None,
+        run_immediately: Optional[bool] = None,
+        input: Optional[Dict[str, List[str]]] = None,
+    ) -> Monitor:
+        """Create a monitor that re-runs an enrichment on a schedule. (operationId: createMonitor)"""
+        body = _drop_none(
+            {
+                "enrichment_id": enrichment_id,
+                "cadence": cadence,
+                "minute": minute,
+                "hour": hour,
+                "timezone": timezone,
+                "day_of_week": day_of_week,
+                "day_of_month": day_of_month,
+                "webhook_url": webhook_url,
+                "alert_rule": alert_rule,
+                "output_format": output_format,
+                "run_immediately": run_immediately,
+                "input": input,
+            }
+        )
+        return Monitor.from_dict(self._client.request("POST", "/monitors", json=body))
+
+    def list(self) -> List[Monitor]:
+        """List the account's monitors, newest first. (operationId: listMonitors)"""
+        response = self._client.request("GET", "/monitors")
+        return [Monitor.from_dict(item) for item in response.get("monitors") or []]
+
+    def get(self, monitor_id: str) -> Monitor:
+        """The monitor's schedule, webhook, and next run time. (operationId: getMonitor)"""
+        return Monitor.from_dict(self._client.request("GET", f"/monitors/{monitor_id}"))
+
+    def update(
+        self,
+        monitor_id: str,
+        *,
+        enabled: Optional[bool] = None,
+        webhook_url: Optional[str] = None,
+    ) -> Monitor:
+        """Pause, resume, or repoint a monitor. (operationId: updateMonitor)"""
+        body = _drop_none({"enabled": enabled, "webhook_url": webhook_url})
+        return Monitor.from_dict(self._client.request("PATCH", f"/monitors/{monitor_id}", json=body))
+
+    def runs(
+        self,
+        monitor_id: str,
+        *,
+        status: Optional[str] = None,
+        page: Optional[int] = None,
+        per_page: Optional[int] = None,
+    ) -> RunsPage:
+        """The monitor's run history, newest first. (operationId: listMonitorRuns)"""
+        params = _drop_none({"status": status, "per_page": per_page})
+
+        def fetch_page(page_number: int) -> Dict[str, Any]:
+            return self._client.request(
+                "GET", f"/monitors/{monitor_id}/runs", params={**params, "page": page_number}
+            )
+
+        return RunsPage(fetch_page(page or 1), fetch_page)

riveter/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

riveter_sdk-0.1.0.dist-info/METADATA

@@ -0,0 +1,97 @@
+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,
+)
+```

riveter_sdk-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+riveter/__init__.py,sha256=f-5XD35dUyigGg_j3Et-s5chUg2fkdgxGB18D2AxRVM,932
+riveter/_client.py,sha256=IiLkvikos9fRoKB3AMfQk9RVlivhOs12kW0N2CLkxcg,7339
+riveter/_errors.py,sha256=70LmavK_KQPWNN676GoMwmWMSGZF9TFFRDj31omWIXM,2115
+riveter/_models.py,sha256=pcgKh3bNCifdVSFUJeW1g59vpLSaoz795JDtscPSs6M,9005
+riveter/_pagination.py,sha256=nLpIparrYeIHpUZHS5i0S3lfrBTQ8BvqotENsixItEg,1314
+riveter/_resources.py,sha256=Xe0h9VxZDxGfME7bonVw5z-P7iX0S7RXCV-Yi44HlZs,13260
+riveter/_version.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+riveter_sdk-0.1.0.dist-info/METADATA,sha256=7_TFxJmWEeA7LzQlkAV1ur77vpQhEXUOPT0ppVDC2AM,3111
+riveter_sdk-0.1.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+riveter_sdk-0.1.0.dist-info/licenses/LICENSE,sha256=l5XLfEkWWQz-81JmUa3lW5rsVOqT8RD1Rc36yCC9oQU,1061
+riveter_sdk-0.1.0.dist-info/RECORD,,

riveter_sdk-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

riveter_sdk-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cody
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.