Metadata-Version: 2.4
Name: coval-sdk
Version: 0.3.1
Summary: Typed Python client for the Coval evaluation platform API.
Author-email: Coval <support@coval.dev>
License-Expression: MIT
Project-URL: Homepage, https://docs.coval.dev/api-reference
Project-URL: Repository, https://github.com/coval-ai/coval-examples
Project-URL: Issues, https://github.com/coval-ai/coval-examples/issues
Keywords: coval,voice-ai,evaluation,openapi,sdk
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: urllib3<3.0.0,>=2.1.0
Requires-Dist: python-dateutil>=2.8.2
Requires-Dist: pydantic>=2.11
Requires-Dist: typing-extensions>=4.7.1
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: twine>=6; extra == "dev"

# coval-sdk (Python)

Typed Python client for the [Coval](https://coval.dev) evaluation platform
API. The API classes and Pydantic v2 models are generated from the same public
OpenAPI specs that power the API reference. `CovalClient` adds authentication,
safe retries, pagination, and one entry point for every public v1 resource.

## Install

```bash
pip install coval-sdk
```

Requires Python 3.9+.

## Quick start

```python
import os

from coval_sdk import CovalClient, paginate

with CovalClient(os.environ["COVAL_API_KEY"]) as coval:
  for agent in paginate(
    coval.agents.list_agents,
    items_field="agents",
    page_size=50,
  ):
    print(agent.id, agent.display_name)
```

The client sends the required lowercase `x-api-key` header and defaults to
`https://api.coval.dev/v1`.

## Retries

`GET`, `HEAD`, and `OPTIONS` requests retry `408`, `429`, and transient `5xx`
responses up to three total attempts with exponential backoff. Mutating
requests are not retried by default, which avoids duplicating side effects.

```python
from coval_sdk import CovalClient

# Disable transport retries.
coval = CovalClient(api_key, retries=False)

# Use a custom base URL.
staging = CovalClient(api_key, base_url="https://staging.api.coval.dev/v1")
```

## Generated client

All generated API classes, models, `ApiClient`, `Configuration`, and typed
exceptions remain available for lower-level usage:

```python
from coval_sdk import AgentsApi, ApiClient, Configuration

config = Configuration(host="https://api.coval.dev/v1")
with ApiClient(config) as client:
  client.set_default_header("x-api-key", api_key)
  page = AgentsApi(client).list_agents(page_size=50)
```

## Malformed list resources

List responses validate each resource independently. If one resource does not
match the published schema, the SDK omits that item, returns the remaining
typed resources, and emits `InvalidListItemWarning`. The warning identifies the
response field and list index but does not include resource contents.

Applications that prefer strict failure can enable it on the client:

```python
from coval_sdk import CovalClient

coval = CovalClient(api_key, strict_response_validation=True)
```

Single-resource and malformed top-level responses still raise Pydantic
validation errors.

## What's included

- 25 typed API classes, including agents, conversations, runs, run templates,
  metrics, monitors, reports, tags, webhooks, and organization configuration
- Pydantic v2 request and response models
- Lowercase API-key authentication and connection pooling
- Safe retry and token-pagination helpers
- Warning-backed isolation for malformed resources in list responses

## Development

From the repository root:

```bash
COVAL_SPECS_DIR=../docs/api-reference/v1 node scripts/bundle-spec.mjs
bash scripts/generate-sdks.sh
python -m pytest python-sdk/tests
```

## License

MIT.
