Metadata-Version: 2.4
Name: coval-sdk
Version: 0.2.0
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
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

# coval-sdk (Python)

Generated Python client for the [Coval](https://coval.dev) evaluation
platform API. Built from the public OpenAPI specs via
[openapi-generator](https://openapi-generator.tech/docs/generators/python).

This package is currently **demo-grade**: it's the generated client without a
hand-written ergonomic wrapper layer. The TypeScript SDK (`@coval/sdk`)
ships with auth/retry/pagination helpers — those are still in flight on the
Python side and will follow in a subsequent release.

## Install

```bash
pip install coval-sdk

# For latest main before the next PyPI release:
# pip install "git+https://github.com/coval-ai/coval-examples.git#subdirectory=python-sdk"

# For local SDK development from the coval-examples repo:
# pip install -e ./python-sdk
```

Requires Python 3.9+.

## Usage

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

config = Configuration(host="https://api.coval.dev")
with ApiClient(config) as client:
    # Coval's gateway requires lowercase x-api-key. The bundled spec splits
    # the auth scheme per tag, so the cleanest pattern is to set the header
    # directly on the client:
    client.set_default_header("x-api-key", os.environ["COVAL_API_KEY"])

    agents_api = AgentsApi(client)
    page = agents_api.list_agents(page_size=50)
    for a in page.agents:
        print(a.id, a.display_name)
```

## Run the example

```bash
COVAL_API_KEY=... python examples/list_agents.py
COVAL_API_KEY=... python examples/list_agents.py --raw   # bypass pydantic validation
```

### Why `--raw` exists

The generated models enforce strict pydantic validation on responses
(including regex patterns on IDs). If your org has any historical data that
predates the current spec — for instance, an `agent_id` that doesn't match
the `^[A-Za-z0-9]{22}$` regex — pydantic will raise a `ValidationError`
mid-stream. The `--raw` flag falls back to
`list_agents_without_preload_content()` which returns the raw HTTP response,
so you can parse it manually.

For production use, prefer the typed call. If you hit ValidationErrors,
file a docs/spec issue so we can either fix the data or relax the
constraint.

## What's in the box

- 21 typed API classes (`AgentsApi`, `ConversationsApi`, `MetricsApi`, …)
- Pydantic v2 models for every request and response shape
- `urllib3`-based transport

## Regenerating

From the repo root:

```bash
node scripts/bundle-spec.mjs
bash scripts/generate-sdks.sh
```

## License

MIT.
