Metadata-Version: 2.4
Name: claritylift
Version: 0.1.0
Summary: Official Python SDK for the ClarityLift public API.
Author: Startvest LLC
License: Apache-2.0
Project-URL: Homepage, https://claritylift.ai
Project-URL: Source, https://github.com/Startvest-LLC/claritylift/tree/master/packages/sdk-python
Keywords: claritylift,team-health,organizational-health-intelligence
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
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: httpx>=0.25.0
Provides-Extra: test
Requires-Dist: pytest>=7.0; extra == "test"

# claritylift

Official Python SDK for the [ClarityLift](https://claritylift.ai) public API.

## Install

```bash
pip install claritylift
```

## Quickstart

```python
import os
from claritylift import ClarityLiftClient

with ClarityLiftClient(token=os.environ["CLARITYLIFT_API_TOKEN"]) as client:
    teams = client.list_teams()
    for team in teams:
        if team.get("kind") == "scored":
            print(team["name"], team["score"], team.get("deviationLabel"))

    trends = client.trending_topics(window="30d")

    topic = client.query_topics(q="benefits plan", window="30d")
    if topic.get("belowFloor"):
        print("Insufficient volume for this query.")
    else:
        print(topic.get("synthesis"))
```

## Scopes

Create tokens at `/dashboard/settings/api-tokens`. Minimum scope per call:

| Method | Scope |
|---|---|
| `list_teams / list_team_signals / team_scores_timeseries` | `read:teams` / `read:signals` / `read:scores` |
| `trending_topics / query_topics` | `read:topics` |
| `create_intervention` | `write:interventions` |
| `create_goal / update_goal / archive_goal` | `write:goals` |
| `create_webhook / list_webhooks / delete_webhook` | `write:webhooks` |

## Idempotency

Every write accepts an optional `idempotency_key`:

```python
client.create_intervention(
    signal_id=signal_id,
    notes="1:1 scheduled",
    confidence="medium",
    idempotency_key="action-2026-04-22-abc",
)
```

Replays within 24 hours return the original response.

## Rate limits

Per-token default: 600 requests/hour. On 429 the client waits for the
`Retry-After` seconds (capped at 60s) and retries once. Subsequent
429s raise `ApiError` — let the caller back off.

## Error handling

```python
from claritylift import ApiError

try:
    client.create_goal(name="Ship Q2 rollout")
except ApiError as err:
    print(err.status, err.code, err.message)
```

## Spec

The OpenAPI definition lives at
[`/api/public/v1/openapi.json`](https://claritylift-app.azurewebsites.net/api/public/v1/openapi.json).
