Metadata-Version: 2.4
Name: sdvm
Version: 0.1.0
Summary: Python SDK for the Synthetic Data Vending Machine (SDVM) API
Project-URL: Homepage, https://sdvm.dev
Project-URL: Repository, https://github.com/philippds/sdvm-python
Project-URL: Bug Tracker, https://github.com/philippds/sdvm-python/issues
Author-email: SDVM <hello@sdvm.dev>
License: MIT
Keywords: ai,llm,nlp,synthetic-data,training-data
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: httpx>=0.27.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: python-dotenv>=1.0; extra == 'dev'
Requires-Dist: respx>=0.21; extra == 'dev'
Description-Content-Type: text/markdown

# sdvm-python

Official Python SDK for the [Synthetic Data Vending Machine (SDVM)](https://sdvm.dev) API.

## Installation

```bash
pip install sdvm
```

Or install from source:

```bash
pip install -e .
```

## Quick Start

```python
from sdvm import Refinery
from sdvm.types import RawText

refinery = Refinery(api_key="sdvm_...")

result = refinery.run([
    RawText(text="the mitochondria is the powerhouse of the cell"),
    RawText(text="water boils at 100 degrees"),
])

for item in result:
    print(item.text)
```

## Async Support

```python
import asyncio
from sdvm import AsyncRefinery
from sdvm.types import RawText

async def main():
    refinery = AsyncRefinery(api_key="sdvm_...")
    result = await refinery.refine([
        RawText(text="the mitochondria is the powerhouse of the cell"),
        RawText(text="water boils at 100 degrees"),
    ])
    for item in result:
        print(item.text)

asyncio.run(main())
```

## Configuration

| Parameter  | Default                | Description                           |
| ---------- | ---------------------- | ------------------------------------- |
| `api_key`  | required               | Your `sdvm_` API key                  |
| `base_url` | `https://api.sdvm.dev` | Override for self-hosted or local dev |
| `timeout`  | `120.0`                | Request timeout in seconds            |

```python
refinery = Refinery(api_key="sdvm_...", base_url="http://localhost:8000")
```

## Error Handling

```python
from sdvm import Refinery, AuthenticationError, InsufficientCreditsError, RateLimitError, APIError
from sdvm.types import RawText

refinery = Refinery(api_key="sdvm_...")

try:
    result = refinery.run([RawText(text="hello")])
except AuthenticationError:
    print("Invalid or revoked API key.")
except InsufficientCreditsError:
    print("Not enough credits — purchase more at https://sdvm.dev.")
except RateLimitError:
    print("Slow down — rate limit hit.")
except APIError as e:
    print(f"Unexpected error {e.status_code}: {e}")
```

## API Reference

### `Refinery`

#### `run(data: list[RawText]) -> list[RawText]`

Refine a list of raw text samples via the API (max 100 per request).

### `AsyncRefinery`

#### `refine(data: list[RawText]) -> list[RawText]`

Same as `Refinery.run()` but async.

### Data Types

#### `RawText`

A dataclass with a single field:

- `text: str` — the raw text sample to refine.

### Exceptions

| Exception                  | HTTP | Description             |
| -------------------------- | ---- | ----------------------- |
| `AuthenticationError`      | 401  | Invalid or revoked key  |
| `InsufficientCreditsError` | 402  | Not enough credits      |
| `RateLimitError`           | 429  | Too many requests       |
| `APIError`                 | any  | Unexpected server error |

All inherit from `SDVMError`.
