Metadata-Version: 2.4
Name: serva
Version: 0.2.0
Summary: Official Python client for the Serva encode/decode API
Author: Servamind
License: Proprietary - All Rights Reserved
Project-URL: Homepage, https://serva.servamind.com
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.27
Requires-Dist: huggingface_hub>=0.20
Provides-Extra: dev
Requires-Dist: pytest>=7.4; extra == "dev"
Dynamic: license-file

# serva

Official Python client for the Serva encode/decode API.

## Install

```bash
pip install serva
```

## Usage

Generate an API key from [serva.servamind.com](https://serva.servamind.com), then:

```python
from serva import Serva

client = Serva(api_key="sk_live_...")   # or set SERVA_API_KEY

# Encode a file to the .serva format
result = client.encode("photo.raw", password="my-secret")
print(result.output_path, result.savings_percent)

# Decode it back
client.decode("photo.serva", password="my-secret", output="photo.raw")
```

## Hugging Face

Push encoded `.serva` datasets to the Hugging Face Hub and pull them back. Set your Hugging Face token as `HF_TOKEN`, or pass `hf_token=...` to `Serva`. Nothing extra to install, the Hugging Face support ships with serva.

```python
from serva import Serva

client = Serva(api_key="sk_live_...")   # HF_TOKEN read from the environment

# Encode, then push to a dataset repo
result = client.encode("photo.raw", password="my-secret")
client.hub.push(result, repo_id="your-name/my-dataset")

# Pull it back and decode
path = client.hub.pull("your-name/my-dataset", "photo.serva")
client.decode(path, password="my-secret", output="photo.raw")
```

Pushing the encode result writes a dataset card with the size and savings. A plain file path works too, and the card simply leaves the savings out.

## Configuration

| Setting | How | Default |
|---|---|---|
| API key | `Serva(api_key=...)` or `SERVA_API_KEY` | — (required) |



## Errors

All failures raise a subclass of `ServaError`: `AuthError` (401),
`PaymentRequiredError` (403), `FileTooLargeError` (413), `RateLimitError` (429).
A Hugging Face Hub operation that fails raises `HubError`, for example a missing
token, a repo that does not exist, or no access.

## Versioning

Semantic versioning. The current version is available as `serva.__version__`.
 
