Metadata-Version: 2.4
Name: clavis-sinica
Version: 0.1.0
Summary: Official Python client for the Clavis Sinica API — Chinese idiom, sentence, passage, classical Chinese and lesson decomposition.
Author: Clavis Sinica
License: MIT
Project-URL: Homepage, https://clavissinica.org
Project-URL: Documentation, https://clavissinica.org/docs
Project-URL: API Reference, https://clavissinica.org/openapi.json
Keywords: chinese,nlp,idiom,classical-chinese,hsk,api-client
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.25
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Dynamic: license-file

# clavis-sinica

Official Python client for the [Clavis Sinica](https://clavissinica.org) API —
Chinese idiom, sentence, passage, classical Chinese and lesson decomposition.

```bash
pip install clavis-sinica
```

```python
from clavis_sinica import Clavis

c = Clavis("ck-live_...")

c.run("decompose.idiom", {"idiom": "守株待兔"})
c.run("convert.script", {"text": "汉字", "direction": "s2t"})

# Async services poll automatically until done
c.run("decompose.lesson", {"text": "...", "title": "第一课"})
```

## What it handles for you

- `Authorization: Bearer` auth — the only accepted scheme
- The `payload` request shape, which works for every service code
- Fetches the field spec from `GET /v1/chinese/services` at startup instead of
  hardcoding a local copy
- Retries `429` honouring `Retry-After`, and `502`/`503` with exponential
  backoff; never retries `4xx` that won't succeed on retry
- Polls async services (`decompose.lesson`, `decompose.wenyan_lesson`) to
  completion
- Logs the `warnings` array — unknown top-level request fields are dropped
  silently, and that array is the only signal

## Errors

`ClavisAuthError` (401) · `ClavisParamError` (400, has `.field` / `.expected`) ·
`ClavisNotFound` (404) · `ClavisRateLimited` (429, has `.retry_after` /
`.scope`) · `ClavisUpstreamError` (502/503, worth retrying) · `ClavisTimeout`

## Not this API

Single-character and vocabulary decomposition belong to the sister product
chinesekey.org — separate pricing, `pk_live_` keys, not interchangeable.

MIT
