riveter-sdk 0.1.0__tar.gz

riveter_sdk-0.1.0/.gitignore

@@ -0,0 +1,180 @@
+# Ruby/Rails
+*.gem
+*.rbc
+/.config
+/coverage/
+/InstalledFiles
+/pkg/
+/spec/reports/
+/spec/examples.txt
+/test/tmp/
+/test/version_tmp/
+/tmp/
+/.bundle/
+/vendor/bundle
+/lib/bundler/man/
+.ruby-version
+.ruby-gemset
+.rvmrc
+.rbenv-version
+
+# Rails specific
+*.sqlite3
+*.sqlite3-journal
+*.sqlite3-shm
+*.sqlite3-wal
+/db/*.sqlite3
+/db/*.sqlite3-journal
+/db/*.sqlite3-shm
+/db/*.sqlite3-wal
+/log/*
+!/log/.keep
+/storage/*
+!/storage/.keep
+/tmp/*
+!/tmp/.keep
+/public/assets
+/public/packs
+/public/packs-test
+/node_modules
+/yarn-error.log
+yarn-debug.log*
+.yarn-integrity
+.byebug_history
+config/master.key
+config/credentials/*.key
+
+# Node.js/React
+node_modules/
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.pnpm-debug.log*
+lerna-debug.log*
+dist/
+build/
+# code-executor Lambda packaging artifacts (built in CI, see deploy-code-executor-aws.yml)
+service-code-executor-js/lambda-pkg/
+service-code-executor-js/function.zip
+.env.*
+.env.local
+.env.development.local
+.env.development
+.env.test.local
+.env.production.local
+.cache/
+.vite/
+*.tsbuildinfo
+
+# Vite
+ public/vite-dev/
+ public/vite-dev/*
+ public/vite-dev*
+ public/vite/
+ public/vite/*
+ public/vite*
+public/vite-dev/assets/
+vite.config.mts*
+
+# Package managers
+package-lock.json
+yarn.lock
+pnpm-lock.yaml
+
+# IDE/Editor files
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db
+
+# Environment variables
+.env
+.env.example
+.envrc
+# MCP registry publish tokens (mcp-server)
+.mcpregistry_*
+
+# Logs
+*.log
+logs/
+
+# Coverage
+coverage/
+.nyc_output
+.coverage/
+
+# Dependency directories
+jspm_packages/
+
+# Optional npm cache directory
+.npm
+
+# Optional eslint cache
+.eslintcache
+
+# Microbundle cache
+.rpt2_cache/
+.rts2_cache_cjs/
+.rts2_cache_es/
+.rts2_cache_umd/
+
+# Optional REPL history
+.node_repl_history
+
+# Output of 'npm pack'
+*.tgz
+
+# Yarn Integrity file
+.yarn-integrity
+
+# dotenv environment variables file
+.env.test
+
+# parcel-bundler cache (https://parceljs.org/)
+.parcel-cache
+
+# Next.js build output
+.next
+
+# Nuxt.js build / generate output
+.nuxt
+dist
+
+# Gatsby files
+.cache/
+
+# Storybook build outputs
+.out
+.storybook-out
+
+# Temporary folders
+tmp/
+# Local agent/human scratch dumps (payload dumps, ad-hoc JSON, etc.)
+tmp/scratch/
+payload.json
+temp/
+script/dummy_data/
+
+# SDKs (sdk/) — per-language build/test artifacts
+sdk/python/.venv/
+sdk/python/*.egg-info/
+sdk/python/.pytest_cache/
+__pycache__/
+sdk/ruby/.bundle/
+sdk/ruby/Gemfile.lock
+
+# Vite Ruby
+/public/vite*
+node_modules
+# Vite uses dotenv and suggests to ignore local-only env files. See
+# https://vitejs.dev/guide/env-and-mode.html#env-files
+*.local
+

riveter_sdk-0.1.0/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.

riveter_sdk-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,81 @@
+# 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/pyproject.toml

@@ -0,0 +1,28 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "riveter-sdk"
+version = "0.1.0"
+description = "Official Python SDK for the Riveter API — enrich data, build datasets, scrape pages, and run web searches"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.9"
+authors = [{ name = "Riveter", email = "support@riveterhq.com" }]
+dependencies = ["httpx>=0.24,<1"]
+keywords = ["riveter", "sdk", "api", "enrichment", "dataset", "scraping", "web-search"]
+
+[project.urls]
+Homepage = "https://docs.riveterhq.com"
+Documentation = "https://docs.riveterhq.com"
+
+[project.optional-dependencies]
+dev = ["pytest>=7"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["riveter"]
+
+[tool.hatch.build.targets.sdist]
+include = ["riveter", "README.md", "LICENSE"]

riveter_sdk-0.1.0/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_sdk-0.1.0/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